Метрики лексического разнообразия¶

DiversityStats(source, words_extractor=None, window_len=50, mtld_threshold=0.72, mtld_min_len=10, hdd_sample_size=42, log_base=10)

Основные метрики лексического разнообразия текста, вычисляемые по его словам.

Исключения:

SourceTypeError - источник, который не строка и не Doc, экстрактор другого типа;
SourceError - источник без слов;
ParameterError - параметр, который отвергает check_params.

Класс расширяет DiversityStats ядра anyTS: вместо списка слов он принимает текст или объект Doc библиотеки spaCy. Слова текста извлекает русский WordsExtractor или заданный экстрактор, который для Doc применяется к его тексту; без экстрактора слова Doc берутся из его токенов без знаков ударения, а части дефисного слова, разрезанного spaCy, склеиваются (во-первых - одно слово). Слова всегда приводятся к нижнему регистру. Таблица print_stats выводится с русскими заголовками и русскими описаниями метрик из ruts.constants.DIVERSITY_STATS_DESC, а сообщения об ошибках - по-русски, из ruts.constants.CORE_MESSAGES.

КодРезультат

from ruts import DiversityStats

text = "Ног нет, а хожу, рта нет, а скажу: когда спать, когда вставать, когда работу начинать"
ds = DiversityStats(text)
ds.print_stats()

                                Метрика                                | Значение
----------------------------------------------------------------------------------
Type-Token Ratio (TTR)                                                 |   0.73
Root Type-Token Ratio (RTTR)                                           |   2.84
Corrected Type-Token Ratio (CTTR)                                      |   2.01
Herdan Type-Token Ratio (HTTR)                                         |   0.89
Summer Type-Token Ratio (STTR)                                         |   0.25
Maas Type-Token Ratio (MTTR)                                           |   0.10
Dugast Type-Token Ratio (DTTR)                                         |  10.27
Moving Average Type-Token Ratio (MATTR)                                |   0.73
Mean Segmental Type-Token Ratio (MSTTR)                                |   0.73
Measure of Textual Lexical Diversity (MTLD)                            |  15.00
Moving Average Measure of Textual Lexical Diversity (MA-MTLD)          |  12.00
Moving Average Measure of Textual Lexical Diversity with Wrap (MTLD-W) |  13.25
Hypergeometric Distribution D (HD-D)                                   |   nan
Индекс Симпсона (D)                                                    |   0.05
Обратный индекс Симпсона (1/D)                                         |  21.00
Индекс Джини-Симпсона (1-D)                                            |   0.95
Гапакс-индекс (Honoré's R)                                             |  992.95
Характеристика Юла (Yule's K)                                          |  444.44
Обратная характеристика Юла (Yule's I)                                 |   8.64
Мера Хердана (Herdan's Vm)                                             |   0.14
Мера Сишела (Sichel's S)                                               |   0.18
Мера Мишеа (Michéa's M)                                                |   5.50
Мера Брюне (Brunet's W)                                                |   6.01
Мера Дюга (Dugast's k)                                                 |  14.78
Мера Баайена (Baayen's P)                                              |   0.53
Мера Орлова (Orlov's Z, слов)                                          |   nan
Доля гапаксов                                                          |   0.73
Показатель α₂                                                          |   0.50
Энтропия Шеннона (бит)                                                 |   3.32
Выравненность                                                          |   0.96
Перплексия                                                             |  10.01
Наклон закона Ципфа (α)                                                |   0.49
Показатель закона Хипса (β)                                            |   0.84
Взрывность частых лексем                                               |   nan

Параметры¶

Параметр	Тип	По умолчанию	Описание
`source`	`str` / `Doc`	-	Источник данных
`words_extractor`	`WordsExtractor`	`None`	Инструмент для извлечения слов; для `Doc` применяется к его тексту
`window_len`	`int`	`50`	Размер окна для MATTR и сегмента для MSTTR (`MATTR_WINDOW_LEN`)
`mtld_threshold`	`float`	`0.72`	Порог TTR для MTLD, MA-MTLD и MTLD-W (`MTLD_TTR_THRESHOLD`)
`mtld_min_len`	`int`	`10`	Минимальная длина фактора для MTLD, MA-MTLD и MTLD-W (`MTLD_MIN_LEN`)
`hdd_sample_size`	`int`	`42`	Размер выборки для HD-D (`HDD_SAMPLE_SIZE`)
`log_base`	`float`	`10`	Основание логарифма для метрик Summer, Maas и Dugast (`DIVERSITY_LOG_BASE`)

Константы умолчаний в скобках, здесь и в карточках, - из anyts.constants.

Объект хранит слова в words, кортежем, и пять параметров под их именами, изменяемые у объекта. frequency_spectrum - спектр частот слов (calc_frequency_spectrum), а honore_r - псевдоним hapax_index.

check_params(window_len=50, mtld_threshold=0.72, mtld_min_len=10, hdd_sample_size=42, log_base=10, *, messages=CORE_MESSAGES)

Проверка параметров метрик: window_len или hdd_sample_size, которые не целое число не меньше единицы, mtld_min_len, который не целое неотрицательное число, mtld_threshold, который не число в интервале (0, 1), и log_base, который не конечное число больше 1, дают ParameterError. Проверка выполняется до извлечения слов, поэтому о неверном параметре она сообщает раньше, чем о пустом тексте.

Соглашения¶

Часть метрик зависит от соглашений, которые в разных библиотеках различаются. Все они, кроме сравнения с порогом MTLD, вынесены в параметры класса:

Параметр	По умолчанию	Другие библиотеки
Основание логарифма для Summer, Maas, Dugast's U и Dugast's k	`10`	LexicalRichness, textcomplexity и zipfR - натуральный
Окно MATTR и сегмент MSTTR	`50`	quanteda и koRpus - 100
Порог TTR для MTLD	`0.72`	в литературе 0.66-0.75
Сравнение с порогом MTLD	фактор закрывается при TTR ≤ 0.72 (McCarthy & Jarvis, 2010)	lexical-diversity и TAALED - строгое `<`; значения расходятся, когда TTR попадает ровно в порог
Минимальная длина фактора MTLD	`10`	koRpus - только в MTLD-MA, с отбрасыванием более коротких факторов вместо их продления; LexicalRichness и textcomplexity - не применяется
Размер выборки HD-D	`42`	в литературе 35-50

По Zenker и Kyle (2021) MATTR, MTLD и HD-D стабильны на текстах от 50-200 слов, MTLD-W, MA-MTLD и Maas нестабильны на коротких текстах, а семейство TTR не стабилизируется вовсе. Тексты разной длины сравниваются оконным расчетом с доверительными интервалами.

Метрики¶

Каждая метрика - свойство объекта, которое вычисляется при каждом обращении функцией из ее карточки с параметрами объекта, а get_stats дает их все.

Метрика	Что измеряет	Диапазон	Чем больше, тем
`ttr`	Доля лексем среди слов	0-1	богаче словарь
`rttr`	Лексемы относительно квадратного корня из числа слов	от 0	богаче словарь
`cttr`	Лексемы относительно квадратного корня из удвоенного числа слов	от 0	богаче словарь
`httr`	Лексемы относительно слов в логарифмах	0-1	богаче словарь
`sttr`	Лексемы относительно слов в двойных логарифмах	до 1, `nan` для одной лексемы или текста не длиннее основания	богаче словарь
`mttr`	Повторяемость слов в логарифмах	от 0	беднее словарь
`dttr`	Обратная величина к метрике Maas	от 0, `inf` без повторяющихся слов	богаче словарь
`mattr`	Средний TTR скользящего окна	0-1	богаче словарь
`msttr`	Средний TTR последовательных сегментов	0-1	богаче словарь
`mtld`	Слов на фактор - отрезок, на котором TTR опускается до порога	больше 0, `inf` без повторяющихся слов	богаче словарь
`mamtld`	Средняя длина факторов, начинающихся с каждого слова	до числа слов, `nan`, если ни один фактор не завершен	богаче словарь
`mtldw`	Средняя длина факторов, начинающихся с каждого слова, с заворотом текста	до числа слов, `nan`, если ни один фактор не завершен	богаче словарь
`hdd`	Ожидаемый TTR случайной выборки	0-1, `nan` для текста короче 50 слов или размера выборки	богаче словарь
`simpson_index`	Вероятность того, что два слова - одна лексема	0-1, `nan` для текста короче двух слов	беднее словарь
`inverse_simpson_index`	Эффективное число лексем второго порядка	от 1, `inf` без повторяющихся слов, `nan` для текста короче двух слов	богаче словарь
`gini_simpson_index`	Вероятность того, что два слова - разные лексемы	0-1, `nan` для текста короче двух слов	богаче словарь
`hapax_index`	Доля гапаксов среди лексем относительно длины текста	от 0, `inf` без повторяющихся слов, `nan` для текста короче двух слов	богаче словарь
`yule_k`	Повторяемость слов	0-10 000, `nan` для текста короче двух слов	беднее словарь
`yule_i`	Величина, обратная Yule's K	больше 0, `inf` без повторяющихся слов, `nan` для текста короче двух слов	богаче словарь
`herdan_vm`	Неравномерность частот	0-1, `nan` для текста короче двух слов	беднее словарь
`sichel_s`	Доля дислегоменов среди лексем	0-1	больше лексем, встретившихся дважды
`michea_m`	Лексем на дислегомен	от 1, `inf` без дислегоменов	меньше лексем, встретившихся дважды
`brunet_w`	Слова относительно лексем	от 1 до числа слов	беднее словарь
`dugast_k`	Лексемы относительно слов в логарифмах	от 0, `nan` для текста не длиннее основания	богаче словарь
`baayen_p`	Доля гапаксов среди слов	0-1	быстрее растет словарь
`orlov_z`	Длина текста в словах, при которой закон Ципфа лучше всего описывает словарь	больше 0, `nan` без решения, `inf` за пределами `float`	богаче словарь
`hapax_ratio`	Доля гапаксов среди лексем	0-1	больше лексем, встретившихся один раз
`alpha2`	Форма нижней части спектра частот	до 1, `nan` без гапаксов	больше гапаксов относительно дислегоменов
`entropy`	Информация на слово в битах	от 0	богаче словарь
`evenness`	Энтропия относительно ее максимума	0-1, `nan` для одной лексемы	равномернее частоты
`perplexity`	Эффективное число лексем	от 1 до числа лексем	богаче словарь
`zipf_alpha`	Падение частоты с рангом	от 0, `nan` для одной лексемы	быстрее падают частоты
`heaps_beta`	Рост словаря с длиной текста	от 0, `nan` для текста короче двух слов	быстрее растет словарь
`burstiness`	Средняя взрывность лексем с пятью и более вхождениями	от -1 до 1, `nan` без таких лексем	слова идут всплесками

Функции и именованные кортежи карточек импортируются из ruts.diversity_stats.

Type-Token Ratio (TTR)¶

ttr

calc_ttr(text)

Самая простая мера лексического разнообразия, без поправки на длину текста.

\[ \frac{\textrm{Количество лексем}}{\textrm{Количество слов}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Root Type-Token Ratio (RTTR)¶

rttr

calc_rttr(text)

Модификация метрики TTR (Guiraud, 1960).

\[ \frac{\textrm{Количество лексем}}{\sqrt{\textrm{(Количество слов)}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Corrected Type-Token Ratio (CTTR)¶

cttr

calc_cttr(text)

Модификация метрики TTR (Carroll, 1964).

\[ \frac{\textrm{Количество лексем}}{\sqrt{2\times\textrm{(Количество слов)}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Herdan Type-Token Ratio (HTTR)¶

httr

calc_httr(text)

Логарифмическая модификация метрики TTR (Herdan, 1960).

\[ \frac{\log_{10} {\textrm{(Количество лексем)}}}{\log_{10} {{\textrm{(Количество слов)}}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Summer Type-Token Ratio (STTR)¶

sttr

calc_sttr(text, base=10)

Логарифмическая модификация метрики TTR (Summer, 1966). Значение зависит от основания логарифма (см. соглашения). Оно равно nan для текста из одной лексемы, где числитель не определен, и для текста не длиннее основания (\(\log \log N \le 0\)), в том числе для таких окон calc_windowed.

\[ \frac{\log_{10} {\log_{10} {\textrm{(Количество лексем)}}}}{\log_{10} {\log_{10} {{\textrm{(Количество слов)}}}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`base`	`float`	`10`	Основание логарифма (`DIVERSITY_LOG_BASE`)

base, который не конечное число больше 1, дает ParameterError.

Maas Type-Token Ratio (MTTR)¶

mttr

calc_mttr(text, base=10)

Логарифмическая модификация метрики TTR (Maas, 1972). Значение зависит от основания логарифма (см. соглашения).

\[ \frac{\log_{10} {\textrm{(Количество слов)}}-\log_{10} {\textrm{(Количество лексем)}}}{\log_{10} {{\textrm{(Количество слов)}}}^2} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`base`	`float`	`10`	Основание логарифма (`DIVERSITY_LOG_BASE`)

base, который не конечное число больше 1, дает ParameterError.

Dugast Type-Token Ratio (DTTR)¶

dttr

calc_dttr(text, base=10)

Логарифмическая модификация метрики TTR (Dugast, 1978), обратная величина к метрике Maas. Значение зависит от основания логарифма (см. соглашения). У текста без повторяющихся слов значение бесконечно.

\[ \frac{\log_{10} {{\textrm{(Количество слов)}}}^2}{\log_{10} {\textrm{(Количество слов)}}-\log_{10} {\textrm{(Количество лексем)}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`base`	`float`	`10`	Основание логарифма (`DIVERSITY_LOG_BASE`)

base, который не конечное число больше 1, дает ParameterError.

Moving Average Type-Token Ratio (MATTR)¶

mattr

calc_mattr(text, window_len=50)

Модификация метрики TTR со скользящей средней (Covington & McFall, 2010), не зависящая от длины текста: окно фиксированного размера скользит по тексту, и TTR всех окон усредняется. Для текстов короче окна возвращается TTR всего текста.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`window_len`	`int`	`50`	Размер окна (`MATTR_WINDOW_LEN`)

window_len, который не целое число не меньше единицы, дает ParameterError.

Mean Segmental Type-Token Ratio (MSTTR)¶

msttr

calc_msttr(text, segment_len=50)

Модификация метрики TTR с сегментированием (Johnson, 1944), не зависящая от длины текста: текст делится на сегменты фиксированного размера, и TTR всех сегментов усредняется; неполный последний сегмент отбрасывается. Для текстов короче сегмента возвращается TTR всего текста.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`segment_len`	`int`	`50`	Размер сегмента (`MATTR_WINDOW_LEN`)

segment_len, который не целое число не меньше единицы, дает ParameterError.

Measure of Textual Lexical Diversity (MTLD)¶

mtld

calc_mtld(text, min_len=10, threshold=0.72)

Модификация метрики MSTTR (McCarthy, 2005), не зависящая от длины текста: количество слов, деленное на количество факторов - отрезков, на которых TTR опускается до порога (TTR <= threshold, см. соглашения). Незавершенный последний фактор учитывается пропорционально тому, насколько его TTR приблизился к порогу. Значение - среднее двух проходов, в прямом и обратном порядке (McCarthy & Jarvis, 2010). Минимальная длина фактора нестандартна (lexical-diversity Кайла), а min_len, равный 0, ее отключает. Если ни один фактор не завершен и TTR не опускается ниже 1, значение равно бесконечности.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`min_len`	`int`	`10`	Минимальная длина фактора (`MTLD_MIN_LEN`)
`threshold`	`float`	`0.72`	Порог TTR для завершения фактора (`MTLD_TTR_THRESHOLD`)

min_len, который не целое неотрицательное число, и threshold, который не число в интервале (0, 1), дают ParameterError.

Moving Average Measure of Textual Lexical Diversity (MA-MTLD)¶

mamtld

calc_mamtld(text, min_len=10, threshold=0.72, step=1)

Модификация метрики MTLD со скользящим окном по образцу MTLD-MA из koRpus: фактор начинается с каждой позиции текста, а значение - средняя длина завершенных факторов по двум проходам, в прямом и обратном порядке. koRpus делает только прямой проход, закрывает фактор при TTR строго ниже порога и отбрасывает факторы короче минимальной длины, а не продлевает их. С шагом step, равным k, фактор начинается с каждой k-й позиции от каждого из концов текста, как MTLDMA.steps в koRpus, и вычисляются только эти факторы: шаг 10 в несколько раз быстрее. Если ни один фактор не завершен, значение равно nan. Метрика нестабильна на коротких текстах.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`min_len`	`int`	`10`	Минимальная длина фактора (`MTLD_MIN_LEN`)
`threshold`	`float`	`0.72`	Порог TTR для завершения фактора (`MTLD_TTR_THRESHOLD`)
`step`	`int`	`1`	Расстояние между началами факторов

min_len, который не целое неотрицательное число, threshold, который не число в интервале (0, 1), и step, который не целое число больше 0, дают ParameterError.

MTLD со скользящим окном и заворотом текста (MTLD-W)¶

mtldw

calc_mtldw(text, min_len=10, threshold=0.72)

Модификация метрики MA-MTLD по образцу mtld_ma_wrap из lexical-diversity и TAALED: факторы, не завершенные до конца текста, продолжаются с его начала, поэтому все позиции получают равный вес. Фактор не может быть длиннее текста. Если ни один фактор не завершен, потому что текст короче min_len или TTR не опускается до порога ни с одного начала, значение равно nan. Метрика нестабильна на текстах короче 100 слов.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`min_len`	`int`	`10`	Минимальная длина фактора (`MTLD_MIN_LEN`)
`threshold`	`float`	`0.72`	Порог TTR для завершения фактора (`MTLD_TTR_THRESHOLD`)

min_len, который не целое неотрицательное число, и threshold, который не число в интервале (0, 1), дают ParameterError.

Hypergeometric Distribution D (HD-D)¶

hdd

calc_hdd(text, sample_size=42)

Альтернатива vocd-D (McCarthy & Jarvis, 2010): точный ожидаемый TTR случайной выборки из sample_size слов, без отбора выборок. Гипергеометрическое распределение дает вероятность того, что каждая лексема попадет в выборку хотя бы раз; HD-D - сумма этих вероятностей, деленная на размер выборки. Для текстов короче 50 слов или короче размера выборки метрика не определена, и значение равно nan.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`sample_size`	`int`	`42`	Размер выборки в словах (`HDD_SAMPLE_SIZE`)

sample_size, который не целое число не меньше единицы, дает ParameterError.

Индекс Симпсона (D)¶

simpson_index · Википедия

calc_simpson_index(text)

Вероятность того, что два слова, случайно извлеченные из текста без возвращения, окажутся одной лексемой; \(n\) - количество вхождений лексемы в текст. Для текстов короче двух слов индекс не определен, и значение равно nan; то же относится к обратному индексу Симпсона и индексу Джини-Симпсона.

\[ \frac{\sum n\times(n-1)}{\textrm{(Количество слов)}\times(\textrm{Количество слов}-1)} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Обратный индекс Симпсона (1/D)¶

inverse_simpson_index · Википедия

calc_inverse_simpson_index(text)

Оценка числа Хилла второго порядка (\(1/\sum_k p_k^2\)) по парам слов, извлеченным без возвращения. Если все слова текста уникальны, индекс Симпсона равен 0, а обратный индекс - бесконечности.

\[ \frac{1}{D} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Индекс Джини-Симпсона (1-D)¶

gini_simpson_index · Википедия

calc_gini_simpson_index(text)

Вероятность того, что два случайно выбранных слова текста окажутся разными.

\[ 1-D \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Гапакс-индекс (Honoré's R)¶

hapax_index · honore_r · Википедия

calc_hapax_index(text)

Гапакс (греч. ἅπαξ λεγόμενον - «только раз названное») - слово, встретившееся в корпусе только один раз: baciyelmo, словечко Санчо Пансы для цирюльничьего тазика, который Дон Кихот принимает за шлем, - гапакс Сервантеса (глава 44 первой части «Дон Кихота»). Индекс совпадает с мерой Оноре (1979) и использует натуральный логарифм. Если все слова текста - гапаксы, индекс равен бесконечности; для текстов короче двух слов он не определен, и значение равно nan. calc_honore_r - та же функция.

\[ 100\times\frac{\ln {\textrm{(Количество слов)}}}{1-\frac{\textrm{Количество гапаксов}}{\textrm{Количество лексем}}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Русский пример: боливар («шляпа определённого фасона») - гапакс языка Пушкина: слово встречается только в знаменитом месте из «Евгения Онегина».

Спектр частот¶

frequency_spectrum

calc_frequency_spectrum(text)

Количество лексем \(V_i\), встретившихся в тексте ровно \(i\) раз, справочником по частоте \(i\) в порядке возрастания. Из него по формулам Tweedie и Baayen (1998) вычисляются гапакс-индекс, характеристики Юла K и I, меры Хердана Vm, Сишела S, Мишеа M и Баайена P, доля гапаксов и показатель α₂.

Обозначения: \(N\) - количество слов, \(V\) - количество лексем, \(V_i\) - количество лексем с частотой \(i\), \(V_1\) - гапаксы, \(V_2\) - дислегомены, \(p_k\) - относительная частота лексемы.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Характеристика Юла (Yule's K)¶

yule_k

calc_yule_k(text)

Характеристика Юла (Yule, 1944) - одна из немногих мер, теоретически не зависящих от длины текста (Tweedie & Baayen, 1998); на практике она сходится с ростом текста. Пропорциональна индексу Симпсона: \(K \approx 10^4 \cdot D\). Для текстов короче двух слов значение равно nan.

\[ K = 10^4\times\frac{\sum_i i^2 V_i - N}{N^2} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Обратная характеристика Юла (Yule's I)¶

yule_i

calc_yule_i(text)

Обратная характеристика Юла. Если все слова текста уникальны, значение равно бесконечности; для текстов короче двух слов - nan.

\[ I = \frac{V^2}{\sum_i i^2 V_i - V} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Мера Хердана (Herdan's Vm)¶

herdan_vm

calc_herdan_vm(text)

Мера Хердана (Herdan, 1955), теоретически не зависящая от длины текста. Для текстов короче двух слов значение равно nan.

\[ V_m = \sqrt{\sum_i V_i \left(\frac{i}{N}\right)^2 - \frac{1}{V}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Мера Сишела (Sichel's S)¶

sichel_s

calc_sichel_s(text)

Мера Сишела (Sichel, 1975) - доля дислегоменов, лексем с частотой 2, среди всех лексем. Стабильна на текстах разной длины.

\[ S = \frac{V_2}{V} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Мера Мишеа (Michéa's M)¶

michea_m

calc_michea_m(text)

Мера Мишеа (Michéa, 1969) - обратная величина к мере Сишела. Если в тексте нет дислегоменов, значение равно бесконечности.

\[ M = \frac{V}{V_2} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Мера Брюне (Brunet's W)¶

brunet_w

calc_brunet_w(text, a=0.172)

Мера Брюне (Brunet, 1978). Значения для текстов обычно лежат в пределах 10-20.

\[ W = N^{V^{-a}}, \quad a = 0.172 \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`a`	`float`	`0.172`	Показатель степени (`BRUNET_W_EXPONENT`)

a, который не конечное число, дает ParameterError.

Мера Дюга (Dugast's k)¶

dugast_k

calc_dugast_k(text, base=10)

Мера Дюга (Dugast, 1979), не путать с Dugast's U - метрикой DTTR. Значение зависит от основания логарифма. Для текстов не длиннее основания (\(\log N \le 1\)) мера не определена, и значение равно nan.

\[ k = \frac{\log V}{\log \log N} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`base`	`float`	`10`	Основание логарифма (`DIVERSITY_LOG_BASE`)

base, который не конечное число больше 1, дает ParameterError.

Мера Баайена (Baayen's P)¶

baayen_p

calc_baayen_p(text)

Мера Баайена (Baayen, 1991) - доля гапаксов среди всех слов текста. Равна наклону кривой роста словаря в конце текста: вероятности того, что следующее слово окажется новым (Evert, 2004).

\[ P = \frac{V_1}{N} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Мера Орлова (Orlov's Z)¶

orlov_z · Tweedie и Baayen (1998)

calc_orlov_z(text)

Длина текста, при которой закон Ципфа лучше всего описывает словарь (Орлов, 1983): решение \(Z\) для \(N\) слов, \(V\) лексем и доли \(p\) самой частой лексемы. У правой части есть минимум по \(Z\), и \(Z\) - решение больше точки минимума; значение равно nan, если \(V\) не больше этого минимума или каждое слово - отдельная лексема, и inf, если \(V\) так близко к \(N\), что \(Z\) выходит за пределы float. Вместе с Yule's K мера Z лучше всех мер, которые сравнивали Tweedie и Baayen, различала авторов. На тексте короче примерно десяти тысяч слов Z неустойчива и растет с длиной, а ее значения различаются на порядки: сравнивают тексты одной длины или ее логарифм.

\[ V = \frac{Z}{\ln(pZ)} \cdot \frac{N}{N - Z} \cdot \ln \frac{N}{Z} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

КодРезультат

from ruts.diversity_stats import calc_orlov_z

words = "снесла курочка яичко не простое а золотое дед бил бил не разбил баба била била не разбила".split()
round(calc_orlov_z(words), 2)

279.56

Доля гапаксов¶

hapax_ratio

calc_hapax_ratio(text)

Доля гапаксов среди всех лексем текста.

\[ \frac{V_1}{V} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Показатель α₂¶

alpha2

calc_alpha2(text)

Оценка параметра Ципфа-Мандельброта по нижней части спектра частот (Evert, 2004). Если в тексте нет гапаксов, значение равно nan.

\[ \alpha_2 = 1 - \frac{2 V_2}{V_1} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Энтропия Шеннона¶

entropy · Википедия

calc_entropy(text)

Энтропия распределения лексем в битах. Число Хилла первого порядка равно \(2^H\) (перплексия), нулевого - \(V\); число второго порядка оценивает обратный индекс Симпсона.

\[ H = -\sum_k p_k \log_2 p_k \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Выравненность¶

evenness

calc_evenness(text)

Выравненность Пиелу - отношение энтропии Шеннона к ее максимуму при данном количестве лексем. Для текстов из одной лексемы она не определена, и значение равно nan.

\[ \frac{H}{\log_2 V} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Перплексия¶

perplexity

calc_perplexity(text)

Число Хилла первого порядка, эффективное количество лексем текста.

\[ 2^H \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Наклон закона Ципфа¶

zipf_alpha · Википедия

calc_zipf_alpha(text)

Показатель \(\alpha\) закона Ципфа \(f(r) \propto r^{-\alpha}\), где \(r\) - ранг лексемы по частоте, оцененный линейной регрессией логарифма частоты по логарифму ранга. Для естественных текстов \(\alpha\) близка к 1. Оценка по рангам методом наименьших квадратов смещена, метод максимального правдоподобия точнее. Для текстов из одной лексемы значение равно nan.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

Подгонка закона Ципфа-Мандельброта¶

Википедия

fit_zipf_mandelbrot(text)

Подгонка закона Ципфа-Мандельброта \(f(r) = C / (r + q)^s\) к распределению частот по рангам. При \(q = 0\) это закон Ципфа с показателем \(s\); сдвиг \(q\) передает выполаживание кривой на самых частых словах. Параметры подбираются методом наименьших квадратов в логарифмических координатах при \(q \ge 0\), \(s \ge 0\); лексемы с нулевой частотой в счетчике не учитываются. Результат - именованный кортеж ZipfMandelbrot с полями c, q, s и r2 - коэффициентом детерминации подгонки в логарифмических координатах. Все поля равны nan для текстов из менее чем трех лексем, при одинаковых частотах всех лексем или при расходящейся подгонке. На коротких текстах параметры неустойчивы: закон описывает большие корпуса.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]` / `Counter`	-	Список слов или счетчик их частот

Счетчик, слова которого не строки или частоты не числа, дает SourceTypeError, а отрицательная, nan или бесконечная частота - SourceError (check_counts).

Визуализатор закона Ципфа строит эту подгонку при show_fit=True.

КодРезультат

from ruts.diversity_stats import fit_zipf_mandelbrot

# частоты 12, 6, 4, 3 в точности следуют закону f = 12 / r
words = ["а"] * 12 + ["б"] * 6 + ["в"] * 4 + ["г"] * 3
fit = fit_zipf_mandelbrot(words)
round(fit.c, 3), round(fit.q, 3), round(fit.s, 3), round(fit.r2, 3)

(12.001, 0.0, 1.0, 1.0)

Показатель закона Хипса¶

heaps_beta · Википедия

calc_heaps_beta(text)

Показатель \(\beta\) закона Хипса \(V(N) = K \cdot N^{\beta}\) роста словаря с ростом длины текста, оцененный линейной регрессией логарифма размера словаря по логарифму длины текста вдоль кривой роста. На корпусах в миллионы слов \(\beta\) лежит в пределах 0.4-0.6, на отдельном тексте - в пределах 0.6-0.9, поэтому значения сравнимы только между текстами близкой длины. Значение зависит от порядка слов и требует от нескольких сотен слов. Для текстов короче двух слов значение равно nan.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов

vocabulary_growth(text)

Кривая роста словаря списка слов: размер словаря после каждого слова текста.

fit_heaps(text)

Подгонка закона Хипса по кривой роста словаря списка слов, как в calc_heaps_beta. Возвращает именованный кортеж HeapsFit с параметрами k, beta и коэффициентом детерминации r2, все nan для текстов короче двух слов; r2 равен nan и для текста из одной лексемы.

По fit_heaps строится график закона Хипса.

Взрывность¶

burstiness · Kim и Jo (2016)

calc_burstiness(text, min_freq=5)

Насколько лексема встречается всплесками, а не равномерно по тексту, - взрывность Kim и Jo, которая поправляет взрывность Goh и Barabási на конечное число событий \(n\), усредненная по лексемам, встретившимся не меньше min_freq раз (BURSTINESS_MIN_FREQ). Для \(n\) вхождений лексемы \(r\) - коэффициент вариации их \(n\) интервалов, включая интервал от последнего вхождения до первого через конец текста. Значение равно −1 для вхождений через равные интервалы, включая интервал через конец (a x a x a x a x a x - −1, a x a x a x a x a - около −0.69), близко к 0 для редкой лексемы в случайных местах и доходит до 1 для вхождений всплесками; без таких лексем значение - nan. На коротком тексте или окне лексемы из min_freq вхождений - в основном служебные слова, а значение растет с длиной текста.

\[ A_n = \frac{\sqrt{n + 1} \cdot r - \sqrt{n - 1}}{(\sqrt{n + 1} - 2) \cdot r + \sqrt{n - 1}} \]

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`min_freq`	`int`	`5`	Наименьшее количество вхождений измеряемой лексемы

min_freq, который не целое число не меньше 2, дает ParameterError.

КодРезультат

from ruts.diversity_stats import calc_burstiness

(
    calc_burstiness("да нет да нет да нет да нет да нет".split()),
    calc_burstiness("да да да да да нет нет нет нет нет".split()),
)

(-1.0, 0.18350341907227388)

Оконный расчет¶

windowed(stat)

calc_windowed(text, func, window_len=100, step=None, confidence=0.95, *, messages=CORE_MESSAGES)

Значения метрики по последовательным окнам одинаковой длины дают их среднее, выборочное стандартное отклонение и доверительный интервал среднего по распределению Стьюдента. Стандартный способ сравнения текстов разной длины; стандартизированный TTR Кубата и Милички (не STTR Summer) - оконный TTR с окном 1000 слов и 95% интервалом. Текст короче окна - единственное окно; окна со значением nan не учитываются. Если окон с определенным значением меньше двух, отклонение и интервал равны nan, а если таких окон нет - и среднее. Метрика, бесконечная хотя бы в одном окне (например, обратный индекс Симпсона на окне из уникальных слов), делает среднее бесконечным, а отклонение и интервал - nan. Результат - именованный кортеж WindowStats с полями mean, std, lower, upper и n_windows - числом окон с определенным значением.

Параметр	Тип	По умолчанию	Описание
`text`	`list[str]`	-	Список слов
`func`	`Callable`	-	Функция вычисления метрики по списку слов
`window_len`	`int`	`100`	Размер окна
`step`	`int`	`None`	Шаг окна; по умолчанию равен размеру окна, и окна не пересекаются
`confidence`	`float`	`0.95`	Уровень доверия
`messages`	`dict[str, str]`	`CORE_MESSAGES`	Сообщения об ошибках по ключам

func, который нельзя вызвать, дает SourceTypeError; window_len или step, которые не целое число не меньше единицы, и confidence, который не число в интервале (0, 1), дают ParameterError.

Каждая функция проверяет слова с помощью check_words: text, который является строкой, Doc, итератором, множеством или таблицей или слова которого не строки, дает SourceTypeError; fit_zipf_mandelbrot принимает и счетчик.

Методы¶

windowed(stat, window_len=100, step=None, confidence=0.95) вычисляет метрику из get_stats по ее названию в окнах: calc_windowed с функцией метрики и параметрами объекта. Остальные аргументы, результат и ошибки - как у calc_windowed; неизвестное название дает UnknownStatError.

КодРезультат

ds.windowed("ttr", window_len=5)
ds.windowed("ttr", window_len=5, step=2).n_windows

WindowStats(mean=0.9333333333333332, std=0.11547005383792512, lower=0.6464898180167025, upper=1.220176848649964, n_windows=3)
6

get_stats() возвращает справочник вычисленных метрик из stats_desc.

print_stats() выводит таблицу вычисленных метрик с их описаниями из stats_desc под заголовками из stats_headers.

КодРезультат

ds.get_stats()

{'ttr': 0.7333333333333333,
 'rttr': 2.840187787218772,
 'cttr': 2.008316044185609,
 'httr': 0.8854692840710255,
 'sttr': 0.2500605793160848,
 'mttr': 0.09738250756232528,
 'dttr': 10.268784661968118,
 'mattr': 0.7333333333333333,
 'msttr': 0.7333333333333333,
 'mtld': 15.0,
 'mamtld': 12.0,
 'mtldw': 13.25,
 'hdd': nan,
 'simpson_index': 0.047619047619047616,
 'inverse_simpson_index': 21.0,
 'gini_simpson_index': 0.9523809523809523,
 'hapax_index': 992.9517404041437,
 'yule_k': 444.44444444444446,
 'yule_i': 8.642857142857142,
 'herdan_vm': 0.1421338109037403,
 'sichel_s': 0.18181818181818182,
 'michea_m': 5.5,
 'brunet_w': 6.00637847898991,
 'dugast_k': 14.783895126869226,
 'baayen_p': 0.5333333333333333,
 'orlov_z': nan,
 'hapax_ratio': 0.7272727272727273,
 'alpha2': 0.5,
 'entropy': 3.3232314287976203,
 'evenness': 0.9606293157795304,
 'perplexity': 10.009038104159247,
 'zipf_alpha': 0.4884512334695912,
 'heaps_beta': 0.8366147342060046,
 'burstiness': nan}

Остальные методы - to_dataframe и describe - из интерфейса статистик ядра anyTS; шкал у метрик лексического разнообразия нет, поэтому describe для метрик get_stats возвращает None.