Метрики удобочитаемости¶

ReadabilityStats(source, sents_extractor=None, words_extractor=None, preset='plainrussian')

Метрики удобочитаемости текста по его базовым статистикам: средней длине предложения в словах, средней длине слова в слогах или буквах, доле сложных и длинных слов и вариативности длины слова. Источник данных - текст, объект Doc библиотеки spaCy или готовые базовые статистики, которые берутся как есть; экстракторы передаются базовым статистикам текста или Doc. Формулы считают только буквы учтенных слов, поэтому экстрактор слов, который отбрасывает слова, не удлиняет среднее слово.

Метрики - свойства, которые вычисляются при каждом обращении, поэтому изменение coefficients объекта действует сразу.

Исключения:

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

Класс расширяет ReadabilityStats ядра anyTS для русского языка: базовые статистики ruTS с русскими SentsExtractor и WordsExtractor по умолчанию, пресеты коэффициентов, русские формулы, шкалы и скорости чтения. Таблица print_stats и сообщения об ошибках - по-русски.

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

from ruts import ReadabilityStats

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

                Метрика                 | Значение
---------------------------------------------------
Тест Флеша-Кинкайда                     |  -2.06
Индекс удобочитаемости Флеша            |  87.17
Индекс Колман-Лиау                      |   1.17
Индекс SMOG                             |   0.05
Автоматический индекс удобочитаемости   |   0.29
Индекс удобочитаемости LIX              |  28.33
Индекс удобочитаемости RIX              |   2.00
Формула Соловьёва, Иванова, Солнышкиной |   1.52
Формула Мацковского                     |   9.35
Формула Тулдавы                         |   1.96
Индекс Дейла-Чейла                      |   4.10
Индекс Ганнинга                         |   6.00
Сводный класс                           |   1.50
Время чтения (мин.)                     |   0.08

Параметры¶

Параметр	Тип	По умолчанию	Описание
`source`	`str` / `Doc` / `BasicStats`	-	Источник данных (строка, объект Doc или готовые базовые статистики)
`sents_extractor`	`SentsExtractor`	`None`	Инструмент для извлечения предложений
`words_extractor`	`WordsExtractor`	`None`	Инструмент для извлечения слов
`preset`	`str`	`'plainrussian'`	Пресет коэффициентов: `plainrussian`, `fiction` или `academic`

Объект хранит базовые статистики текста в bs, название пресета - в preset (только для чтения), коэффициенты пресета - в coefficients, копии, которую можно менять для отдельного объекта. Базовые статистики можно передать объекту другого пресета: ReadabilityStats(rs.bs, preset="fiction").

Пресеты коэффициентов¶

Пресеты различаются коэффициентами теста Флеша-Кинкайда и индекса Флеша; коэффициенты индексов Колман-Лиау, SMOG и ARI во всех пресетах - из проекта plainrussian, остальные формулы от пресета не зависят.

Пресет	Источник	Корпус	Тест Флеша-Кинкайда	Индекс Флеша
`plainrussian`	Plain Russian Language (Бегтин)	68 текстов с метками класса	`0.318·ASL + 14.2·ASW − 30.5`	`206.835 − 1.3·ASL − 60.1·ASW` (Оборнева, вариант А)
`fiction`	Оборнева (2005/2006)	около 6 млн слов художественных текстов	`0.5·ASL + 8.4·ASW − 15.59`	`206.835 − 1.3·ASL − 60.1·ASW` (вариант А)
`academic`	Соловьёв, Иванов, Солнышкина (2018); Солнышкина и Кисельников (2015)	14 учебников обществознания для 5-11 классов	`0.36·ASL + 5.76·ASW − 11.97` (FKG_SIS)	`206.836 − 1.52·ASL − 65.14·ASW` (Оборнева, вариант Б)

Здесь ASL - среднее число слов в предложении, ASW - среднее число слогов в слове. Справочник всех коэффициентов - ruts.constants.READABILITY_PRESETS.

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

ReadabilityStats(text).flesch_kincaid_grade
ReadabilityStats(text, preset="fiction").flesch_kincaid_grade
ReadabilityStats(text, preset="academic").flesch_kincaid_grade

-2.0633333333333326
5.91
3.0299999999999994

На наборе TextsByGrade, на котором подбирались коэффициенты plainrussian, пресеты одинаково согласуются с меткой класса - корреляция Спирмена теста Флеша-Кинкайда у plainrussian 0.80, у fiction и academic 0.79, - но дают разную шкалу, медианы теста по группам меток:

Метка	Текстов	`plainrussian`	`fiction`	`academic`
1	11	2.6	6.9	3.6
3-4	10	4.1	8.6	4.8
5-9	12	4.4	8.6	4.8
10-11	18	6.9	11.9	7.2
12-17	17	23.7	24.4	15.9
1 (`SovChLit`)	179	1.3	6.0	3.0

На школьных текстах (метки 1-11) тест с пресетом fiction выше метки примерно на четыре класса (медиана отклонения +3.7 против −1.0 у plainrussian и −0.1 у academic). Для класса читателя подходят plainrussian и academic, а fiction - для сравнения с работами на коэффициентах Оборневой. Сводный класс зависит от пресета меньше: его медиана на TextsByGrade 7.75 у fiction и 6.75 у plainrussian.

Метрики¶

Формулу считает функция из ее карточки по количествам bs. Формулы ядра берут коэффициенты из coefficients, а формулы Соловьёва, Иванова, Солнышкиной, Мацковского и Дейла-Чейла - из своих функций, и coefficients на них не действует. Формула дает nan, если количество слов или предложений, на которое она делит, равно нулю. Формулы других языков с исходными коэффициентами считает класс UnadaptedReadabilityStats.

Метрика	Что измеряет	Диапазон	Чем больше, тем
`flesch_kincaid_grade`	Класс по длине предложения и слогам на слово	годы обучения, ниже 0 у простейших текстов	сложнее текст
`flesch_reading_easy`	Легкость чтения по длине предложения и слогам на слово	номинально 0-100, выше 100 у простейших текстов и ниже 0 у сложнейших	легче текст
`coleman_liau_index`	Класс по буквам и предложениям на 100 слов	годы обучения, ниже 0 у простейших текстов	сложнее текст
`smog_index`	Класс по сложным словам на предложение	годы обучения	сложнее текст
`automated_readability_index`	Класс по буквам на слово и длине предложения	годы обучения, ниже 0 у простейших текстов	сложнее текст
`lix`	Длина предложения и доля длинных слов	от 0	сложнее текст
`rix`	Длинные слова на предложение	от 0	сложнее текст
`sis_grade`	Класс по длине предложения и буквам на слово	класс школы, ниже 0 у простейших текстов	сложнее текст
`matskovsky_index`	Длина предложения и доля сложных слов	от 0	сложнее текст
`tuldava`	Слоги на слово и логарифм длины предложения	от 0	сложнее текст
`dale_chall_index`	Класс по доле сложных слов и длине предложения	годы обучения	сложнее текст
`gunning_fog_index`	Класс по длине предложения и доле сложных слов	годы обучения	сложнее текст
`consensus_grade`	Медиана формул класса и индекса Флеша как класса	годы обучения, ниже 0 у простейших текстов	сложнее текст
`reading_time`	Время чтения при скорости `reading_speed`	минуты, больше 0	длиннее текст
`mu_index`	Средняя длина слова в буквах против ее дисперсии; вне `get_stats`	больше 0, `nan` меньше чем с двумя словами или без вариативности	легче текст

Тест Флеша-Кинкайда¶

flesch_kincaid_grade · Kincaid et al., 1975

calc_flesch_kincaid_grade(n_syllables, n_words, n_sents, a=0.318, b=14.2, c=30.5)

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

\[ a \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + b \cdot \frac{\textrm{Количество слогов}}{\textrm{Количество слов}} - c \]

Коэффициенты по умолчанию - из проекта Plain Russian Language, другие дают пресеты.

Параметр	Тип	По умолчанию	Описание
`n_syllables`	`int`	-	Количество слогов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`0.318`	Коэффициент a, при средней длине предложения
`b`	`float`	`14.2`	Коэффициент b, при средней длине слова
`c`	`float`	`30.5`	Коэффициент c, свободный член

Индекс удобочитаемости Флеша¶

flesch_reading_easy · Flesch, 1948

calc_flesch_reading_easy(n_syllables, n_words, n_sents, a=1.3, b=60.1, c=206.835)

Легкость чтения текста по средней длине предложения в словах и средней длине слова в слогах.

\[ c - a \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} - b \cdot \frac{\textrm{Количество слогов}}{\textrm{Количество слов}} \]

Коэффициенты по умолчанию - Оборневой (2005/2006, вариант А), вариант Б дает пресет academic.

Параметр	Тип	По умолчанию	Описание
`n_syllables`	`int`	-	Количество слогов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`1.3`	Коэффициент a, при средней длине предложения
`b`	`float`	`60.1`	Коэффициент b, при средней длине слова
`c`	`float`	`206.835`	Коэффициент c, свободный член

Полосы describe - шкала ruts.constants.READING_EASE_LEVELS:

Значение	Прочтение
`[90; ∞)`	5-й класс
`[80; 90)`	6-й класс
`[70; 80)`	7-й класс
`[60; 70)`	8-й и 9-й класс
`[50; 60)`	10-й и 11-й класс
`[30; 50)`	университет
`(−∞; 30)`	выпускник университета

Индекс Колман-Лиау¶

coleman_liau_index · Coleman and Liau, 1975

calc_coleman_liau_index(n_letters, n_words, n_sents, a=0.055, b=0.35, c=20.33)

Число лет обучения, необходимых для чтения текста, по буквам и предложениям на 100 слов.

\[ a \cdot \frac{100 \cdot \textrm{Количество букв}}{\textrm{Количество слов}} - b \cdot \frac{100 \cdot \textrm{Количество предложений}}{\textrm{Количество слов}} - c \]

Коэффициенты по умолчанию взяты из проекта Plain Russian Language.

Параметр	Тип	По умолчанию	Описание
`n_letters`	`int`	-	Количество букв в словах
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`0.055`	Коэффициент a, при буквах на 100 слов
`b`	`float`	`0.35`	Коэффициент b, при предложениях на 100 слов
`c`	`float`	`20.33`	Коэффициент c, свободный член

Индекс SMOG¶

smog_index · McLaughlin, 1969

calc_smog_index(n_complex, n_sents, a=1.1, b=64.6, c=0.05)

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

\[ a \cdot \sqrt{b \cdot \frac{\textrm{Количество сложных слов}}{\textrm{Количество предложений}}} + c \]

Количество слов или предложений, которое не целое неотрицательное число, дает ParameterError.

Коэффициенты по умолчанию проекта Plain Russian Language получены для сложных слов от пяти слогов: ReadabilityStats передает в функцию количество таких слов (ruts.constants.SMOG_COMPLEX_SYL_FACTOR), а не n_complex_words базовых статистик.

Параметр	Тип	По умолчанию	Описание
`n_complex`	`int`	-	Количество сложных слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`1.1`	Коэффициент a, при квадратном корне
`b`	`float`	`64.6`	Коэффициент b, под квадратным корнем
`c`	`float`	`0.05`	Коэффициент c, свободный член

Автоматический индекс удобочитаемости (ARI)¶

automated_readability_index · Smith and Senter, 1967

calc_automated_readability_index(n_letters, n_words, n_sents, a=6.26, b=0.2805, c=31.04)

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

\[ a \cdot \frac{\textrm{Количество букв}}{\textrm{Количество слов}} + b \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} - c \]

Коэффициенты по умолчанию взяты из проекта Plain Russian Language.

Параметр	Тип	По умолчанию	Описание
`n_letters`	`int`	-	Количество букв в словах
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`6.26`	Коэффициент a, при буквах на слово
`b`	`float`	`0.2805`	Коэффициент b, при средней длине предложения
`c`	`float`	`31.04`	Коэффициент c, свободный член

Класс можно читать как возраст читателя:

Значение	Возраст
`1`	6-7 лет
`2`	7-8 лет
`3`	8-9 лет
`4`	9-10 лет
`5`	10-11 лет
`6`	11-12 лет
`7`	12-13 лет
`8`	13-14 лет
`9`	14-15 лет
`10`	15-16 лет
`11`	16-17 лет
`12`	17-18 лет
`13`	18-24 года
`14`	24+ года

Индекс удобочитаемости LIX¶

lix · Björnsson, 1968

calc_lix(n_long_words, n_words, n_sents)

Средняя длина предложения плюс процент длинных слов - слов длиннее шести букв; подбираемых коэффициентов нет. Значения читаются как типы текстов:

Значение	Текст
`0-30`	очень простые тексты, детские книги
`30-40`	простые тексты, художественная литература, газетные статьи
`40-50`	тексты средней сложности, журнальные статьи
`50-60`	сложные тексты, научно-популярная литература, официальные тексты
`60-100`	очень сложные тексты, законы и канцелярский язык

\[ \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + \frac{100 \cdot \textrm{Количество длинных слов}}{\textrm{Количество слов}} \]

Параметр	Тип	По умолчанию	Описание
`n_long_words`	`int`	-	Количество длинных слов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений

Эти полосы - шкала describe (ruts.constants.LIX_LEVELS), последняя открыта сверху. ReadabilityStats передает в функцию количество слов от 7 букв, а не n_long_words базовых статистик ruTS - слов от шести букв.

Индекс удобочитаемости RIX¶

rix · Anderson, 1983

calc_rix(n_long_words, n_sents)

Количество длинных слов, длиннее шести букв, на предложение; подбираемых коэффициентов нет. Значения читаются как классы:

Значение	Класс
`< 0.2`	1
`0.2-0.5`	2
`0.5-0.8`	3
`0.8-1.3`	4
`1.3-1.8`	5
`1.8-2.4`	6
`2.4-3.0`	7
`3.0-3.7`	8
`3.7-4.5`	9
`4.5-5.3`	10
`5.3-6.2`	11
`6.2-7.2`	12
`> 7.2`	университет

\[ \frac{\textrm{Количество длинных слов}}{\textrm{Количество предложений}} \]

Параметр	Тип	По умолчанию	Описание
`n_long_words`	`int`	-	Количество длинных слов
`n_sents`	`int`	-	Количество предложений

Как и для LIX, ReadabilityStats передает в функцию количество слов от 7 букв. Полосы describe (ruts.constants.RIX_LEVELS) - классы Андерсона, полоса 12-го класса входит в 11-й:

Значение	Прочтение
`[0; 0.2)`	1-й класс
`[0.2; 0.5)`	2-й класс
`[0.5; 0.8)`	3-й класс
`[0.8; 1.3)`	4-й класс
`[1.3; 1.8)`	5-й класс
`[1.8; 2.4)`	6-й класс
`[2.4; 3.0)`	7-й класс
`[3.0; 3.7)`	8-й класс
`[3.7; 4.5)`	9-й класс
`[4.5; 5.3)`	10-й класс
`[5.3; 7.2)`	11-й класс
`[7.2; ∞)`	университет и выше

Формула Соловьёва, Иванова, Солнышкиной¶

sis_grade · sis_grade_by_stage(stage) · Соловьёв, Иванов, Солнышкина, 2023

calc_sis_grade(n_letters, n_words, n_sents, a=-17.5, b=0.56, c=2.45)

Класс школы, необходимый для чтения русского академического текста, по средней длине предложения в словах и средней длине слова в буквах. Формула получена на корпусе Russian Academic Corpus из 154 учебников для 2-11 классов (5.7 млн токенов), средняя ошибка - около одного класса. Авторы считали длину предложения в токенах spaCy вместе с пунктуацией, поэтому расчет по словам ruTS дает класс чуть ниже.

\[ a + b \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + c \cdot \frac{\textrm{Количество букв}}{\textrm{Количество слов}} \]

Параметр	Тип	По умолчанию	Описание
`n_letters`	`int`	-	Количество букв в словах
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`-17.5`	Коэффициент a, свободный член
`b`	`float`	`0.56`	Коэффициент b, при средней длине предложения
`c`	`float`	`2.45`	Коэффициент c, при средней длине слова

Коэффициенты по умолчанию - общей формулы, коэффициенты ступеней обучения - в ruts.constants.SIS_GRADE_STAGES, их берет метод sis_grade_by_stage:

Ступень	a	b	c
2-4 классы	`-2.59`	`0.17`	`0.61`
5-7 классы	`-5.29`	`0.20`	`1.34`
8-11 классы	`-3.26`	`0.21`	`1.35`

Формула Соловьёва, Иванова, Солнышкиной с частотностью¶

sis_grade_by_freq(mean_ipm, stage) · Соловьёв, Иванов, Солнышкина, 2023

calc_sis_grade_freq(n_letters, n_words, n_sents, mean_ipm, a=-14.46, b=0.58, c=2.15, d=-0.0026)

Вариант общей формулы с четвертым признаком FREQ2 - средней частотностью слов текста по словарю Ляшевской и Шарова (таблица 7 статьи): чем чаще слова, тем ниже класс. Значениям FREQ2 статьи (200-1000) соответствует частотность знаменательных слов (LexicalStats.mean_ipm_content). На наборе TextsByGrade формула с частотностью коррелирует с классом не лучше формулы без нее (ρ Спирмена 0.76 против 0.78).

\[ a + b \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + c \cdot \frac{\textrm{Количество букв}}{\textrm{Количество слов}} + d \cdot \textrm{FREQ2} \]

Параметр	Тип	По умолчанию	Описание
`n_letters`	`int`	-	Количество букв в словах
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`mean_ipm`	`float`	-	Средняя частотность знаменательных слов (ipm)
`a`	`float`	`-14.46`	Коэффициент a, свободный член
`b`	`float`	`0.58`	Коэффициент b, при средней длине предложения
`c`	`float`	`2.15`	Коэффициент c, при средней длине слова
`d`	`float`	`-0.0026`	Коэффициент d, при средней частотности

Коэффициенты по умолчанию - общей формулы, коэффициенты ступеней - в ruts.constants.SIS_GRADE_FREQ_STAGES, их берет параметр stage метода sis_grade_by_freq:

Ступень	a	b	c	d
2-4 классы	`-1.21`	`0.2`	`0.56`	`-0.0025`
5-7 классы	`-5.18`	`0.17`	`1.35`	`-0.00043`
8-11 классы	`1.3`	`0.23`	`0.88`	`-0.0035`

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

from ruts import LexicalStats, ReadabilityStats

text = "Кот сидел на окне и смотрел на птиц. Птицы улетели, и кот уснул."
rs = ReadabilityStats(text)
rs.sis_grade, rs.sis_grade_by_stage("2-4")
rs.sis_grade_by_freq(LexicalStats(text).mean_ipm_content)

(-4.625384615384615, 0.8142307692307695)
-3.106298290598293

Формула Мацковского¶

matskovsky_index · Мацковский, 1976

calc_matskovsky_index(n_complex, n_words, n_sents, a=0.62, b=0.123, c=0.051)

Первая формула удобочитаемости для русского языка - по средней длине предложения и проценту сложных слов; ReadabilityStats передает в функцию количество слов от 4 слогов.

\[ a \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + b \cdot \frac{100 \cdot \textrm{Количество сложных слов}}{\textrm{Количество слов}} + c \]

Параметр	Тип	По умолчанию	Описание
`n_complex`	`int`	-	Количество сложных слов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`0.62`	Коэффициент a, при средней длине предложения
`b`	`float`	`0.123`	Коэффициент b, при доле сложных слов
`c`	`float`	`0.051`	Коэффициент c, свободный член

Формула Тулдавы¶

tuldava · Тулдава, 1975

calc_tuldava(n_syllables, n_words, n_sents)

Формула трудности текста Тулдавы («Об измерении трудности текстов», Ученые записки Тартуского университета, вып. 345, 1975, с. 102-120) в изложении Иванова, Солнышкиной и Соловьёва (2018): среднее число слогов в слове, умноженное на десятичный логарифм средней длины предложения в словах; подбираемых коэффициентов нет. Шкалы у формулы нет: в сводный класс она не входит, а describe возвращает None.

\[ \frac{\textrm{Количество слогов}}{\textrm{Количество слов}} \cdot \lg \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} \]

Параметр	Тип	По умолчанию	Описание
`n_syllables`	`int`	-	Количество слогов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений

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

from ruts import ReadabilityStats
from ruts.readability_stats import calc_tuldava

calc_tuldava(n_syllables=200, n_words=100, n_sents=10)
rs = ReadabilityStats("Кот сидел на окне и смотрел на птиц. Птицы улетели, и кот уснул.")
rs.tuldava, rs.describe("tuldava")

2.0
(1.3131677299615359, None)

Индекс Дейла-Чейла¶

dale_chall_index · Dale and Chall, 1948

calc_dale_chall_index(n_complex, n_words, n_sents, a=0.552, b=0.273)

Число лет обучения, необходимых для понимания текста, по проценту сложных слов и средней длине предложения. Это адаптация проекта Plain Russian Language: доля незнакомых слов по списку из 3000 знакомых заменена долей слов от пяти слогов, и ReadabilityStats передает в функцию их количество (ruts.constants.SMOG_COMPLEX_SYL_FACTOR). Исходные коэффициенты формулы - 0.1579 и 0.0496.

\[ a \cdot \frac{100 \cdot \textrm{Количество сложных слов}}{\textrm{Количество слов}} + b \cdot \frac{\textrm{Количество слов}}{\textrm{Количество предложений}} \]

Параметр	Тип	По умолчанию	Описание
`n_complex`	`int`	-	Количество сложных слов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`0.552`	Коэффициент a, при доле сложных слов
`b`	`float`	`0.273`	Коэффициент b, при средней длине предложения

Индекс Ганнинга¶

gunning_fog_index · Gunning, 1952

calc_gunning_fog_index(n_complex, n_words, n_sents, a=0.4)

Число лет обучения, необходимых для чтения текста, по средней длине предложения и проценту сложных слов, в исходной формуле - слов от трех слогов.

\[ a \cdot \left(\frac{\textrm{Количество слов}}{\textrm{Количество предложений}} + \frac{100 \cdot \textrm{Количество сложных слов}}{\textrm{Количество слов}}\right) \]

В адаптации проекта Plain Russian Language сложное слово - от пяти слогов: ReadabilityStats передает в функцию количество таких слов (ruts.constants.SMOG_COMPLEX_SYL_FACTOR).

Параметр	Тип	По умолчанию	Описание
`n_complex`	`int`	-	Количество сложных слов
`n_words`	`int`	-	Количество слов
`n_sents`	`int`	-	Количество предложений
`a`	`float`	`0.4`	Коэффициент a

Сводный класс¶

consensus_grade

Атрибут consensus_grade - медиана значений формул класса (grade_stats), округленных арифметически, вместе с индексом удобочитаемости Флеша, переведенным в число лет обучения (reading_ease_to_grade) без округления. Библиотека выравнивает границы reading_ease_grades и каждой шкалы preset_reading_ease_grades по своей шкале индекса Флеша, чтобы сводный класс и describe читали значение одинаково.

Формулы класса в ruTS (ruts.constants.READABILITY_GRADE_STATS) - тест Флеша-Кинкайда, индексы Колман-Лиау, SMOG, ARI, Дейла-Чейла и Ганнинга и формула Соловьёва, Иванова, Солнышкиной.

calc_consensus_grade(grades, flesch_reading_easy=None, to_grade=flesch_reading_easy_to_grade)

Медиана значений формул класса, округленных арифметически, вместе с индексом Флеша, переведенным в число лет обучения функцией to_grade без округления, - поэтому полоса с классом 8.5 голосует за 8.5.

\[ \textrm{median}\left(\lfloor g_1 + 0.5 \rfloor, \ldots, \lfloor g_k + 0.5 \rfloor, \textrm{to\_grade}(\textrm{индекс Флеша})\right) \]

Параметр	Тип	По умолчанию	Описание
`grades`	`list[float]`	-	Значения формул класса
`flesch_reading_easy`	`float`	`None`	Значение индекса удобочитаемости Флеша
`to_grade`	`Callable`	`flesch_reading_easy_to_grade`	Перевод индекса Флеша в число лет обучения

Отсутствие значений, класс или индекс Флеша, которые не конечное число, дают ParameterError; классы, которые не список, и to_grade, который нельзя вызвать, - SourceTypeError.

flesch_reading_easy_to_grade(flesch_reading_easy, grades=((90, 5), (80, 6), (70, 7), (60, 8.5), (50, 10.5), (30, 14), (0, 17)), below=17)

Перевод индекса удобочитаемости Флеша в число лет обучения для сводного класса: класс первого диапазона, нижней границы которого достигает значение, или below ниже последней границы; значения больше 100 относятся к первому диапазону. Индекс Флеша или below, которые не конечное число, дают ParameterError, как и grades, которые пусты или не состоят из пар конечных чисел с границами по убыванию.

Полосы ruTS по умолчанию (ruts.constants.READING_EASE_GRADES, атрибут reading_ease_grades) повторяют шкалу прочтения индекса; 14 и 17 - 1-3-й и 4-6-й курс вуза по таблице ступеней:

Индекс Флеша	Класс
`[90; ∞)`	5
`[80; 90)`	6
`[70; 80)`	7
`[60; 70)`	8.5
`[50; 60)`	10.5
`[30; 50)`	14
`(−∞; 30)`	17

Параметр	Тип	По умолчанию	Описание
`flesch_reading_easy`	`float`	-	Значение индекса удобочитаемости Флеша
`grades`	`list[tuple[float, float]]`	`READING_EASE_GRADES`	Нижние границы и их классы по убыванию границ
`below`	`float`	`17`	Класс ниже последней границы

Время чтения¶

reading_time · reading_time_by_speed(wpm) · reading_time_by_norm(norm) · Кузнецов и Хромов, 1991

calc_reading_time(n_words, wpm=180, *, messages=CORE_MESSAGES)

Время чтения текста в минутах: количество слов, деленное на скорость чтения.

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

Количество слов, которое не целое неотрицательное число, и скорость, которая не положительное число, дают ParameterError.

Скорость по умолчанию - верхняя граница нормы чтения про себя для взрослого. Нормы - в ruts.constants.READING_SPEED_NORMS, для начальной школы - нормы чтения вслух по ФГОС:

Норма	Слов в минуту
`adult_silent`	120-180
`grade_1`	25-40
`grade_2`	60-80
`grade_3`	80-100
`grade_4`	90-110

Параметр	Тип	По умолчанию	Описание
`n_words`	`int`	-	Количество слов
`wpm`	`float`	`180`	Скорость чтения, слов в минуту (`READING_SPEED_WPM`)
`messages`	`dict[str, str]`	`CORE_MESSAGES`	Сообщения об ошибках по ключам, ключевой аргумент

Legibilidad µ¶

mu_index · Muñoz Baquedano and Muñoz Urra, 2006

Средняя длина слова в буквах, деленная на ее выборочную дисперсию и умноженная на 100; подбираемых коэффициентов нет. Слова без букв (числа) не учитываются; меньше чем с двумя словами или без вариативности индекс не определен (nan).

\[ 100 \cdot \frac{\bar{x}}{s^2}, \quad s^2 = \frac{\sum (x_i - \bar{x})^2}{n - 1} \]

где \(x_i\) - количество букв слова, \(n\) - количество слов.

Индекс получен на испанских текстах и в get_stats ruTS не входит, но доступен как свойство mu_index; его функция - calc_mu_index ядра anyTS.

Методы¶

describe_grade(stat) возвращает ступень обучения и возраст читателя для сводного класса или формулы класса stat, по умолчанию consensus_grade; другая метрика дает ParameterError.

describe_level(stat) возвращает полосу шкалы интерпретации (level_scale) метрики stat, по умолчанию flesch_reading_easy; метрика без шкалы полос и неопределенное значение (nan) дают ParameterError.

describe(stat) возвращает прочтение любой метрики по ее шкале: для сводного класса и формулы класса - ступень обучения и возраст читателя (describe_grade), для метрики со шкалой полос (level_scale) - ее полосу, для другой метрики из grade_scales - ступень и возраст по числу лет обучения, которое дает ее шкала, и None для метрики без шкалы или с неопределенным значением (nan). Имя, которого нет ни в stats_desc, ни среди открытых свойств класса, дает UnknownStatError.

reading_time_by_speed(wpm) возвращает время чтения текста в минутах при скорости wpm, слов в минуту; скорость, которая не положительное число, дает ParameterError.

reading_time_by_norm(norm) возвращает время чтения текста в минутах при скоростях нормы norm из reading_speed_norms в их порядке; неизвестная норма дает ParameterError.

В ruTS метод возвращает время чтения при верхней и нижней границе нормы из ruts.constants.READING_SPEED_NORMS.

sis_grade_by_stage(stage) возвращает значение формулы Соловьёва, Иванова, Солнышкиной с коэффициентами ступени обучения stage: 2-4, 5-7 или 8-11; неизвестная ступень дает ParameterError.

sis_grade_by_freq(mean_ipm, stage=None) возвращает значение формулы с частотностью при средней частотности знаменательных слов mean_ipm - атрибуте mean_ipm_content класса LexicalStats - с коэффициентами ступени stage или, без нее, общей формулы. Отрицательная, бесконечная или нечисловая частотность и неизвестная ступень дают ParameterError, а nan дает nan.

get_stats() возвращает справочник метрик удобочитаемости из stats_desc.

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

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

from ruts import ReadabilityStats

text = "Ног нет, а хожу, рта нет, а скажу: когда спать, когда вставать, когда работу начинать"
rs = ReadabilityStats(text)
rs.describe_grade(), rs.describe_grade("gunning_fog_index")
rs.describe("flesch_reading_easy"), rs.describe_level("lix")
rs.describe("rix"), rs.describe("matskovsky_index")
rs.reading_time_by_speed(120), rs.reading_time_by_norm("grade_1")
rs.get_stats()

('1-3-й класс (6-8 лет)', '4-6-й класс (9-11 лет)')
('6-й класс', 'очень простые тексты, детские книги')
('6-й класс', None)
(0.125, (0.375, 0.6))
{'flesch_kincaid_grade': -2.0633333333333326,
 'flesch_reading_easy': 87.16833333333334,
 'coleman_liau_index': 1.1700000000000053,
 'smog_index': 0.05,
 'automated_readability_index': 0.2941666666666656,
 'lix': 28.333333333333336,
 'rix': 2.0,
 'sis_grade': 1.5166666666666675,
 'matskovsky_index': 9.351,
 'tuldava': 1.9601520984261356,
 'dale_chall_index': 4.095000000000001,
 'gunning_fog_index': 6.0,
 'consensus_grade': 1.5,
 'reading_time': 0.08333333333333333}

Метод to_dataframe - из интерфейса статистик ядра anyTS.

Шкалы¶

Шкалы полос индекса Флеша, LIX и RIX приведены в их карточках (ruts.constants.READABILITY_LEVEL_SCALES), а формулы класса и сводный класс describe читает по ступеням обучения grade_to_age.

Класс и возраст читателя¶

grade_to_age(grade, levels=((1, 3, '1-3-й класс', '6-8 лет'), (4, 6, '4-6-й класс', '9-11 лет'), (7, 9, '7-9-й класс', '12-14 лет'), (10, 11, '10-11-й класс', '15-16 лет'), (12, 14, '1-3-й курс вуза', '17-19 лет'), (15, 17, '4-6-й курс вуза', '20-22 года')), above=('аспирантура', 'старше 22 лет'))

Ступень обучения и возраст читателя по значению формулы класса: значение округляется арифметически и попадает в первую ступень, последний год которой оно не превышает, значения меньше 1 - в первую ступень; после последней ступени лежит above. Класс, который не конечное число, ступени, которые не четверки из двух целых лет и двух строк по возрастанию лет, и above, который не пара строк, дают ParameterError.

Ступени ruTS по умолчанию взяты из таблицы GRADE_TEXT проекта Plain Russian Language (ruts.constants.GRADE_AGE_LEVELS и POSTGRADUATE_LEVEL):

Класс	Ступень	Возраст
1-3	1-3-й класс	6-8 лет
4-6	4-6-й класс	9-11 лет
7-9	7-9-й класс	12-14 лет
10-11	10-11-й класс	15-16 лет
12-14	1-3-й курс вуза	17-19 лет
15-17	4-6-й курс вуза	20-22 года
больше 17	аспирантура	старше 22 лет

Параметр	Тип	По умолчанию	Описание
`grade`	`float`	-	Значение формулы класса
`levels`	`list[tuple[int, int, str, str]]`	`GRADE_AGE_LEVELS`	Ступени - первый и последний год, ступень и возраст - по возрастанию
`above`	`tuple[str, str]`	`POSTGRADUATE_LEVEL`	Ступень и возраст после последней ступени

Полоса шкалы¶

scale_level(value, scale)

Полоса шкалы для значения: шкала задается нижними границами полос по убыванию, значение попадает в первую полосу, границы которой достигает, а нижняя полоса открыта вниз.

Параметр	Тип	По умолчанию	Описание
`value`	`float`	-	Значение метрики
`scale`	`list[tuple[float, Any]]`	-	Нижние границы и их полосы по убыванию

Значение, которое не конечное число, и шкала, которая пуста, не является списком пар из конечной нижней границы и полосы или с границами не по убыванию, дают ParameterError.

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

from ruts.constants import READING_EASE_LEVELS
from ruts.readability_stats import calc_flesch_reading_easy, scale_level

flesch = calc_flesch_reading_easy(n_syllables=60, n_words=30, n_sents=2)
flesch, scale_level(flesch, READING_EASE_LEVELS)

(67.135, '8-й и 9-й класс')

Нормы ступеней¶

Справочник ruts.constants.LEVEL_NORMS хранит нормы признаков ступеней обучения - обычные диапазоны (квартили) длины предложения в словах, длины слова в буквах, доли слов от пяти слогов и лексического разнообразия MTLD у текстов от 100 слов с меткой ступени из наборов SovChLit и TextsByGrade. Нормы есть у школьных ступеней, где таких текстов не меньше 10:

Ступень	Текстов	Слов в предложении	Букв в слове	Доля слов от пяти слогов	MTLD
1-3-й класс	73	7.6-10.3	4.54-5.01	0.0-0.021	104-178
4-6-й класс	12	10.1-14.6	5.15-5.33	0.039-0.052	220-369
10-11-й класс	18	15.0-18.4	5.11-5.57	0.035-0.065	276-513

Нормы 1-3-го класса сняты почти целиком с текстов 1-го класса (70 из 73), так что текст для 2-3-го класса может выйти выше нормы, особенно по длине предложения. Признаки текста короче 100 слов, особенно MTLD, с нормами сравнивать не стоит.

Признаки текста¶

level_features(source)

Признаки текста, для которых есть нормы ступеней, - слов в предложении, букв в слове, доля слов от пяти слогов и MTLD; они считаются так же, как нормы. Признаки Doc считаются по его тексту, а не по границам предложений spaCy. Источник, который не строка и не Doc, дает SourceTypeError, источник без слов или предложений - SourceError.

Параметр	Тип	По умолчанию	Описание
`source`	`str` / `Doc`	-	Источник данных (строка или объект Doc)

Нормы и прочтение признака¶

level_norms(grade)

Нормы (квартили) признаков level_features ступени обучения, к которой относится класс (как в grade_to_age), или None для ступени без норм. Класс, который не конечное число, дает ParameterError.

Параметр	Тип	По умолчанию	Описание
`grade`	`float`	-	Класс читателя или сводный класс текста

describe_level_norm(stat, value, grade)

Прочтение признака текста по нормам ступени, к которой относится класс: «ниже нормы ступени», «в норме ступени» (между квартилями, включая их) или «выше нормы ступени» (ruts.constants.LEVEL_NORM_BANDS). Ступень без норм и неопределенное значение (nan) дают None, неизвестный признак - UnknownStatError, значение, которое не число, и класс, который не конечное число, - ParameterError.

Параметр	Тип	По умолчанию	Описание
`stat`	`str`	-	Название признака из `ruts.constants.LEVEL_NORMS_DESC`
`value`	`float`	-	Значение признака
`grade`	`float`	-	Класс читателя или сводный класс текста

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

from ruts.datasets import SovChLit
from ruts.readability_stats import describe_level_norm, level_features, level_norms

level_norms(2)["words_per_sent"], level_norms(8)
text = next(SovChLit().get_texts())
features = level_features(text)
{stat: describe_level_norm(stat, value, 1) for stat, value in features.items()}

((7.6, 10.3), None)
{'words_per_sent': 'выше нормы ступени',
 'letters_per_word': 'выше нормы ступени',
 'p_smog_complex_words': 'выше нормы ступени',
 'mtld': 'в норме ступени'}