Функции вычисления метрик¶

Type-Token Ratio (TTR)¶

ruts.diversity_stats.calc_ttr()

Вычисление метрики Type-Token Ratio (TTR).

Самый простой и самый критикуемый способ вычисления лексического разнообразия, не принимающий во внимание влияние эффекта длины текста.

Формула:

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

Параметры:

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

Root Type-Token Ratio (RTTR)¶

ruts.diversity_stats.calc_rttr()

Вычисление метрики Root Type-Token Ratio (RTTR).

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

Формула:

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

Параметры:

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

Corrected Type-Token Ratio (CTTR)¶

ruts.diversity_stats.calc_cttr()

Вычисление метрики Corrected Type-Token Ratio (CTTR).

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

Формула:

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

Параметры:

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

Herdan Type-Token Ratio (HTTR)¶

ruts.diversity_stats.calc_httr()

Вычисление метрики Herdan Type-Token Ratio (HTTR).

Модификация метрики TTR с использованием логарифмической функции (1960, Herdan).

Формула:

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

Параметры:

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

Summer Type-Token Ratio (STTR)¶

ruts.diversity_stats.calc_sttr()

Вычисление метрики Summer Type-Token Ratio (STTR).

Модификация метрики TTR с использованием логарифмической функции (1966, Summer).

Примечание

Значение зависит от основания логарифма: по умолчанию 10, как в koRpus и lexical-diversity, в LexicalRichness, textcomplexity и zipfR - натуральный. См. соглашения.

Формула:

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

Параметры:

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

Maas Type-Token Ratio (MTTR)¶

ruts.diversity_stats.calc_mttr()

Вычисление метрики Maas Type-Token Ratio (MTTR).

Модификация метрики TTR с использованием логарифмической функции (1972, Maas). Наиболее стабильная метрика в отношении длины текста.

Примечание

Значение зависит от основания логарифма: по умолчанию 10, как в koRpus и lexical-diversity, в LexicalRichness, textcomplexity и zipfR - натуральный. См. соглашения.

Формула:

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

Параметры:

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

Dugast Type-Token Ratio (DTTR)¶

ruts.diversity_stats.calc_dttr()

Вычисление метрики Dugast Type-Token Ratio (DTTR).

Модификация метрики TTR с использованием логарифмической функции (1978, Dugast).

Примечание

Значение зависит от основания логарифма: по умолчанию 10, как в koRpus и lexical-diversity, в LexicalRichness, textcomplexity и zipfR - натуральный. См. соглашения.

Формула:

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

Параметры:

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

Moving Average Type-Token Ratio (MATTR)¶

ruts.diversity_stats.calc_mattr()

Вычисление метрики Moving Average Type-Token Ratio (MATTR).

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

Алгоритм:

Проход по тексту окном фиксированного размера
Вычисление метрики TTR для каждого окна
Усреднение метрик

Примечание

Окно по умолчанию 50 слов, как в lexical-diversity, TAALED и textacy, quanteda и koRpus используют 100. Для текстов короче окна возвращается TTR всего текста.

Параметры:

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

Mean Segmental Type-Token Ratio (MSTTR)¶

ruts.diversity_stats.calc_msttr()

Вычисление метрики Mean Segmental Type-Token Ratio (MSTTR).

Модификация метрики TTR с использованием сегментирования (1944, Johnson). Не зависит от длины текста.

Алгоритм:

Разделение текста на сегменты фиксированного размера
Вычисление метрики TTR для каждого сегмента
Усреднение метрик

Примечание

Сегмент по умолчанию 50 слов, как в lexical-diversity, TAALED и textacy, quanteda и koRpus используют 100. Для текстов короче сегмента возвращается TTR всего текста, неполный последний сегмент отбрасывается.

Параметры:

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

Measure of Textual Lexical Diversity (MTLD)¶

ruts.diversity_stats.calc_mtld()

Вычисление метрики Measure of Textual Lexical Diversity (MTLD).

Модификация метрики MSTTR (2005, McCarthy). Не зависит от длины текста.

Алгоритм:

Текст делится на факторы - отрезки, на которых TTR опускается до порога 0.72 включительно (TTR <= 0.72; в lexical-diversity и TAALED сравнение строгое, см. соглашения)
Незавершенный фактор в конце текста учитывается частично, пропорционально тому, насколько его TTR приблизился к порогу
Количество слов делится на количество факторов

Доработанная версия алгоритма предполагает два прохода по тексту - в прямом и обратном порядке, и дальнейшее усреднение значения метрики (2010, McCarthy & Jarvis).

Примечание

Минимальная длина фактора взята из lexical-diversity Кайла и нестандартна: koRpus применяет ее только к MA-MTLD, LexicalRichness и textcomplexity не применяют вовсе. Порог 0.72 в литературе варьируется от 0.66 до 0.75. Если ни один фактор не завершен и TTR не опускается ниже 1, возвращается бесконечность.

Параметры:

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

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

ruts.diversity_stats.calc_mamtld()

Вычисление метрики Moving Average Measure of Textual Lexical Diversity (MA-MTLD).

Модификация метрики MTLD с использованием скользящего окна (koRpus MTLD-MA): фактор начинается с каждой позиции текста, значение метрики - средняя длина завершенных факторов по двум проходам, в прямом и обратном порядке. Факторы, не завершенные до конца текста, не учитываются.

Предупреждение

Если ни один фактор не завершен, функция возвращает nan. Метрика нестабильна на коротких текстах.

Факторы со всех стартов считаются по массиву предыдущих вхождений слов блоками стартов через numpy, а не перебором множеств лексем (_mtld_factor_lengths): число лексем на отрезке равно числу позиций, чье предыдущее вхождение лежит раньше начала отрезка. Время линейно по длине текста; значения совпадают с прямым перебором.

Параметры:

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

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

ruts.diversity_stats.calc_mtldw()

Вычисление метрики MTLD-W (lexical-diversity mtld_ma_wrap, TAALED).

Модификация метрики MA-MTLD: фактор начинается с каждой позиции текста, а факторы, не завершенные до конца текста, продолжаются с его начала, поэтому все позиции получают равный вес. Фактор не может быть длиннее текста.

Предупреждение

Если TTR не опускается до порога даже на всем тексте, функция возвращает nan. Метрика нестабильна на текстах короче 100 слов.

Параметры:

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

Hypergeometric Distribution D (HD-D)¶

ruts.diversity_stats.calc_hdd()

Вычисление метрики Hypergeometric Distribution D (HD-D).

Наиболее достоверная реализация алгоритма VocD (2010, McCarthy & Jarvis).

Алгоритм:

Случайный отбор из текста сегментов длиной от 32 до 50 слов
Вычисление метрики TTR для каждого сегмента
Усреднение метрик

Предупреждение

Для текстов короче 50 слов и для текстов короче размера выборки метрика не определена, функция возвращает nan.

Параметры:

Параметр	Тип	По умолчанию	Описание
`text`	list[str]	`-`	Список слов
`sample_size`	int	`42`	Длина сегмента, в литературе от 35 до 50

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

ruts.diversity_stats.calc_simpson_index()

Вычисление индекса Симпсона.

Индекс широко применяется в биологии для описания вероятности принадлежности любых двух особей, случайно отобранных из неопределенно большого сообщества, к разным видам. С определенными допущениями применим и для описания лексического разнообразия текста.

Вычисляется в классической форме без возвращения, как в quanteda, LexicalRichness и zipfR. Чем ниже показатель, тем богаче словарь текста.

Предупреждение

Для текстов короче двух слов индекс не определен, функция возвращает nan. То же относится к обратному индексу Симпсона и индексу Джини-Симпсона.

Формула:

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

где \(n\) - количество вхождений лексемы в текст.

Параметры:

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

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

ruts.diversity_stats.calc_inverse_simpson_index()

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

Чем выше показатель, тем богаче словарь текста.

Формула:

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

Предупреждение

Если все слова текста уникальны, индекс Симпсона равен 0, а обратный индекс - бесконечности.

Параметры:

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

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

ruts.diversity_stats.calc_gini_simpson_index()

Вычисление индекса Джини-Симпсона.

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

Формула:

\[ 1-D \]

Параметры:

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

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

ruts.diversity_stats.calc_hapax_index(), псевдоним ruts.diversity_stats.calc_honore_r()

Вычисление Гапакс-индекса.

Определение

Гапакс (греч. ἅπαξ λεγόμενον - «только раз названное») - слово, встретившееся в некотором корпусе текстов только один раз. Так, можно сказать, что боливар («шляпа определённого фасона») - гапакс языка Пушкина (оно встречается только в знаменитом месте из «Евгения Онегина»). Термин «гапакс» популярен в исследованиях Библии, в которой обнаружено несколько сотен подобных слов.

Гапаксы того или иного автора нередко используют для атрибуции ему некоторого другого произведения, где встречаются такие слова.

Метрика совпадает с мерой Оноре (1979). Используется натуральный логарифм, как в zipfR и textcomplexity.

Формула:

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

Предупреждение

Если все слова текста являются гапаксами, значение индекса равно бесконечности. Для текстов короче двух слов индекс не определен, функция возвращает nan.

Параметры:

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

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

ruts.diversity_stats.calc_frequency_spectrum()

Вычисление спектра частот - количества лексем \(V_i\), встретившихся в тексте ровно \(i\) раз. Основа для мер Юла, Хердана, Сишела, Мишеа, Баайена и LNRE-моделей zipfR. Все меры ниже считаются из спектра частот за линейное время; формулы сверены с Tweedie и Baayen (1998), zipfR, quanteda, koRpus, LexicalRichness и textcomplexity.

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

Параметры:

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

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

ruts.diversity_stats.calc_yule_k()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_yule_i()

Вычисление обратной характеристики Юла. Чем выше показатель, тем богаче словарь текста; если все слова текста уникальны, значение равно бесконечности.

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_herdan_vm()

Вычисление меры Хердана (1955, Herdan). Теоретически не зависит от длины текста, чем ниже показатель, тем богаче словарь.

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_sichel_s()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_michea_m()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_brunet_w()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_dugast_k()

Вычисление меры Дюга (1979, Dugast). Не путать с Dugast's U - метрикой DTTR.

Примечание

Значение зависит от основания логарифма: по умолчанию 10, как для метрик Summer, Maas и Dugast's U, в textcomplexity - натуральный. Мера не определена, если \(\log N \le 1\), то есть для текстов не длиннее основания логарифма; в этом случае функция возвращает nan.

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_baayen_p()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_hapax_ratio()

Вычисление доли гапаксов среди всех лексем текста.

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_alpha2()

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

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_entropy()

Вычисление энтропии Шеннона распределения лексем в битах. Чем выше показатель, тем богаче словарь текста. Число Хилла первого порядка равно \(2^H\) (перплексия), нулевого - \(V\), второго - обратный индекс Симпсона.

Формула:

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

Параметры:

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

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

ruts.diversity_stats.calc_evenness()

Вычисление выравненности (выравненность Пиелу) - отношения энтропии Шеннона к ее максимуму при данном количестве лексем. Лежит в пределах от 0 до 1; для текстов из одной лексемы не определена, функция возвращает nan.

Формула:

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

Параметры:

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

Перплексия¶

ruts.diversity_stats.calc_perplexity()

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

Формула:

\[ 2^H \]

Параметры:

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

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

ruts.diversity_stats.calc_zipf_alpha()

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

Примечание

Оценка по рангам методом наименьших квадратов смещена, для точной оценки используют метод максимального правдоподобия (например, библиотека powerlaw). Для текстов из одной лексемы функция возвращает nan.

Параметры:

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

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

ruts.diversity_stats.fit_zipf_mandelbrot(), ruts.diversity_stats.ZipfMandelbrot

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

Примечание

Для текстов из менее чем трех лексем, при одинаковых частотах всех лексем и при расходящейся подгонке все поля nan. На коротких текстах параметры неустойчивы: закон описывает распределение частот больших корпусов.

Параметры:

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

Пример

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)

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

ruts.diversity_stats.calc_heaps_beta(), ruts.diversity_stats.fit_heaps(), ruts.diversity_stats.vocabulary_growth()

Вычисление показателя \(\beta\) закона Хипса \(V(N) = K \cdot N^{\beta}\), описывающего рост словаря с ростом длины текста. Оценивается линейной регрессией логарифма размера словаря по логарифму длины текста вдоль кривой роста словаря (vocabulary_growth - размер словаря после каждого слова). На корпусах в миллионы слов \(\beta\) лежит в пределах 0.4-0.6; регрессия по всей кривой роста отдельного текста дает больше (0.6-0.9), так как в начале текста почти каждое слово новое, поэтому значения сравнимы только между текстами близкой длины. fit_heaps возвращает именованный кортеж HeapsFit с обоими параметрами k, beta и коэффициентом детерминации r2; по нему строится график закона Хипса.

Примечание

Значение зависит от порядка слов и требует от нескольких сотен слов. Для текстов короче двух слов функция возвращает nan.

Параметры:

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

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

ruts.diversity_stats.calc_windowed()

Оконный расчет любой метрики: значение по последовательным окнам текста одинаковой длины, среднее, выборочное стандартное отклонение и доверительный интервал среднего по распределению Стьюдента. Стандартный способ сравнения текстов разной длины (textcomplexity bootstrap, характеристические кривые koRpus); STTR Кубата и Милички - оконный расчет TTR с окном 1000 слов и 95% доверительным интервалом. Для текстов короче окна метрика считается по всему тексту как по единственному окну, окна с неопределенным значением метрики (nan) не учитываются. Если хотя бы в одном окне метрика бесконечна (например, обратный индекс Симпсона на окне из уникальных слов), среднее равно бесконечности, а стандартное отклонение и доверительный интервал не определены. Возвращает именованный кортеж WindowStats с полями mean, std, lower, upper и n_windows.

Параметры:

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