Unadapted readability formulas¶

UnadaptedReadabilityStats(source, sents_extractor=None, words_extractor=None)

Readability formulas made for English, German or Italian, computed from the basic statistics of a text with the coefficients they were published with (Linsear Write in the form of textstat), without a calibration for its language. Their values compare texts of one language with each other; they are no grade levels of another language. A word without syllables (a number, a preposition of one consonant) counts as monosyllabic in FORCAST and the Wiener Sachtextformeln and as easy in Linsear Write, as in textstat. The data source is a text, a Doc object of spaCy or a ready BasicStats object, as for ReadabilityStats.

Raises:

SourceTypeError - a source that is neither a string, a Doc nor a BasicStats object, basic statistics of another class, an extractor of another type, a string or a Doc for a class without basic_stats_class;
SourceError - a source without words or without sentences.

CodeResult

import re

from anyts.basic_stats import BasicStats
from anyts.unadapted_readability_stats import UnadaptedReadabilityStats


class Basic(BasicStats):
    def count_syllables(self, word):
        return len(re.findall(r"[aeiouy]+", word, re.IGNORECASE))


class Unadapted(UnadaptedReadabilityStats):
    basic_stats_class = Basic


stats = Unadapted(
    "The cat sat on the mat. A beautiful day came, and the extraordinary dog barked!"
)
stats.print_stats()

           Metric            |  Value
----------------------------------------
FORCAST grade                |   9.00
Linsear Write grade          |   3.75
Powers-Sumner-Kearl grade    |   5.36
McAlpine EFLAW score         |  13.00
Wiener Sachtextformel 1      |   2.29
Wiener Sachtextformel 2      |   2.99
Wiener Sachtextformel 3      |   4.27
Wiener Sachtextformel 4      |   3.96
Dickes-Steiwer index         |  46.26
Gulpease index               |  87.67
Fucks index                  |  11.50
Strain index                 |   3.45
Easy listening formula (ELF) |   4.00
Wheeler-Smith index          |  20.00

Parameters¶

Parameter	Type	Default	Description
`source`	`str` / `Doc` / `BasicStats`	-	Data source
`sents_extractor`	`SentsExtractor`	`None`	Sentence extraction tool, not used for ready basic statistics
`words_extractor`	`WordsExtractor`	`None`	Word extraction tool, not used for ready basic statistics

Attributes¶

Attribute	Type	Description
`bs`	`BasicStats`	Basic statistics of the text

Metrics¶

Every metric is a property of the object, computed on each access from bs, and get_stats gives them all. A hard word has complex_syl_factor syllables or more (3), a long word long_word_letter_factor letters or more (7).

Metric	Language and readers	Range	Higher means
`forcast`	English technical texts, a grade	5-20	Harder
`linsear_write`	English, a grade	-1 and above	Harder
`powers_sumner_kearl`	English primary school texts, a grade	Any	Harder
`eflaw`	English for foreign learners	1 and above	Harder
`wiener_sachtextformel_1` ... `wiener_sachtextformel_4`	German non-fiction, a grade from 4 to 15	Any	Harder
`dickes_steiwer`	German, without syllables	Any	Easier
`gulpease`	Italian, by letters	0-100 for most texts	Easier
`fucks`	German, syllables per sentence	0 and above	Harder
`strain_index`	English	0 and above	Harder
`elf`	English texts read aloud	0 and above	Harder
`wheeler_smith`	English primary school texts	0 and above	Harder

FORCAST¶

forcast

calc_forcast(n_monosyllable_words, n_words)

The grade of Caylor et al. (1973) for technical texts: 20 minus a tenth of the monosyllabic words per 150 words, from 5 (every word monosyllabic) to 20; nan without words.

\[ \textrm{FORCAST} = 20 - \frac{150 \times \textrm{Monosyllabic words}}{10 \times \textrm{Words}} \]

Parameter	Type	Default	Description
`n_monosyllable_words`	`int`	-	Number of monosyllabic words
`n_words`	`int`	-	Number of words

A count that is not an integer or is negative, and more monosyllabic words than words, raise ParameterError.

Linsear Write¶

linsear_write

calc_linsear_write(n_easy_words, n_hard_words, n_sents)

The grade of Linsear Write in the form of textstat; the Lensear Write Formula of O'Hayre (1966) is another one, of the monosyllabic words and the sentences of a sample of 100 words. An easy word, of at most two syllables, weighs 1 and a hard one 3; their sum per sentence \(r\) is halved above 20, and otherwise loses 2 before it is halved. It is computed over the whole text rather than a sample of 100 words; nan without sentences.

\[ r = \frac{\textrm{Easy words} + 3 \times \textrm{Hard words}}{\textrm{Sentences}}, \quad \textrm{LW} = \begin{cases} r / 2 & r > 20 \\ (r - 2) / 2 & r \le 20 \end{cases} \]

Parameter	Type	Default	Description
`n_easy_words`	`int`	-	Number of the words of one or two syllables
`n_hard_words`	`int`	-	Number of the words of three syllables or more
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Powers-Sumner-Kearl¶

powers_sumner_kearl · Powers et al. 1958

calc_powers_sumner_kearl(n_syllables, n_words, n_sents)

The recalculation of the Flesch formula by Powers, Sumner and Kearl (1958) as a grade, for primary school texts; nan without words or sentences.

\[ \textrm{PSK} = 0.0778 \times \textrm{ASL} + 4.55 \times \textrm{ASW} - 2.2029 \]

Parameter	Type	Default	Description
`n_syllables`	`int`	-	Number of syllables
`n_words`	`int`	-	Number of words
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

McAlpine EFLAW¶

eflaw

calc_eflaw(n_mini_words, n_words, n_sents)

The score of McAlpine (2005) for readers of English as a foreign language: the words and the mini words, of one to three letters (mini_word_letters), per sentence; 20 and below is very easy, 30 and above confusing. nan without sentences.

\[ \textrm{EFLAW} = \frac{\textrm{Words} + \textrm{Mini words}}{\textrm{Sentences}} \]

Parameter	Type	Default	Description
`n_mini_words`	`int`	-	Number of the words of one to three letters
`n_words`	`int`	-	Number of words
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Wiener Sachtextformel¶

wiener_sachtextformel_1 · wiener_sachtextformel_2 · wiener_sachtextformel_3 · wiener_sachtextformel_4

calc_wiener_sachtextformel(n_complex, n_long_words, n_monosyllable_words, n_words, n_sents, variant=1)

The four formulas of Bamberger and Vanecek (1984) for German non-fiction, a grade from 4 to 15, over the percentages of the words of three syllables or more (MS), of more than six letters (IW) and of one syllable (ES) and the mean sentence length (SL); nan without words or sentences. A variant that is not an integer from 1 to 4 raises ParameterError.

\[ \begin{aligned} \textrm{WSTF}_1 &= 0.1935 \cdot \textrm{MS} + 0.1672 \cdot \textrm{SL} + 0.1297 \cdot \textrm{IW} - 0.0327 \cdot \textrm{ES} - 0.875 \\ \textrm{WSTF}_2 &= 0.2007 \cdot \textrm{MS} + 0.1682 \cdot \textrm{SL} + 0.1373 \cdot \textrm{IW} - 2.779 \\ \textrm{WSTF}_3 &= 0.2963 \cdot \textrm{MS} + 0.1905 \cdot \textrm{SL} - 1.1144 \\ \textrm{WSTF}_4 &= 0.2744 \cdot \textrm{MS} + 0.2656 \cdot \textrm{SL} - 1.693 \end{aligned} \]

Parameter	Type	Default	Description
`n_complex`	`int`	-	Number of the words of three syllables or more
`n_long_words`	`int`	-	Number of the words of more than six letters
`n_monosyllable_words`	`int`	-	Number of monosyllabic words
`n_words`	`int`	-	Number of words
`n_sents`	`int`	-	Number of sentences
`variant`	`int`	`1`	Variant of the formula, from 1 to 4

A count that is not an integer or is negative raises ParameterError.

Dickes-Steiwer¶

dickes_steiwer

calc_dickes_steiwer(n_letters, n_words, n_sents, n_types)

The short formula of Dickes and Steiwer (1977) for German, as Bamberger and Vanecek (1984) give it, over the letters per word, the words per sentence and the type-token ratio, without syllables; higher is easier. nan without words or sentences. The ratio falls with the length of a text, so the values compare texts of one length.

\[ \textrm{DS} = 235.95993 - 73.021 \ln\left(\frac{\textrm{Letters}}{\textrm{Words}} + 1\right) - 12.56438 \ln\left(\frac{\textrm{Words}}{\textrm{Sentences}} + 1\right) - 50.03293 \cdot \textrm{TTR} \]

Parameter	Type	Default	Description
`n_letters`	`int`	-	Number of the letters of the words
`n_words`	`int`	-	Number of words
`n_sents`	`int`	-	Number of sentences
`n_types`	`int`	-	Number of the distinct words

A count that is not an integer or is negative raises ParameterError.

Gulpease¶

gulpease

calc_gulpease(n_letters, n_words, n_sents)

The index of Lucisano and Piemontese (1988) for Italian, by letters rather than syllables: about 0 for the hardest texts and 100 for the easiest, beyond them for extreme ones; below 80 a text is hard for a reader of primary school, below 40 for a reader with a secondary education. nan without words.

\[ \textrm{Gulpease} = 89 + \frac{300 \times \textrm{Sentences} - 10 \times \textrm{Letters}}{\textrm{Words}} \]

Parameter	Type	Default	Description
`n_letters`	`int`	-	Number of the letters of the words
`n_words`	`int`	-	Number of words
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Fucks¶

fucks

calc_fucks(n_syllables, n_sents)

The style characteristic of Fucks (1955): the mean word length in syllables times the mean sentence length in words, the syllables per sentence; nan without sentences.

\[ \textrm{Fucks} = \textrm{ASW} \times \textrm{ASL} = \frac{\textrm{Syllables}}{\textrm{Sentences}} \]

Parameter	Type	Default	Description
`n_syllables`	`int`	-	Number of syllables
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Strain index¶

strain_index

calc_strain_index(n_syllables, n_sents)

The index of Nathaniel (2009): the syllables of three sentences over 10, here those of three sentences on average over the whole text, which makes it 0.3 times the index of Fucks; nan without sentences.

\[ \textrm{Strain} = \frac{3 \times \textrm{Syllables}}{10 \times \textrm{Sentences}} \]

Parameter	Type	Default	Description
`n_syllables`	`int`	-	Number of syllables
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Easy listening formula¶

elf · Fang 1966

calc_elf(n_syllables, n_syllabic_words, n_sents)

The formula of Fang (1966) for texts read aloud: the syllables above one per word, per sentence, a word without syllables (a number) adding none; 12 and below is easy to listen to. nan without sentences.

\[ \textrm{ELF} = \frac{\textrm{Syllables} - \textrm{Words of one syllable or more}}{\textrm{Sentences}} \]

Parameter	Type	Default	Description
`n_syllables`	`int`	-	Number of syllables
`n_syllabic_words`	`int`	-	Number of the words of one syllable or more
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Wheeler-Smith¶

wheeler_smith

calc_wheeler_smith(n_polysyllable_words, n_sents)

The index of Wheeler and Smith (1954) for primary school texts: the mean sentence length times the share of the words of two syllables or more, times 10, which makes 10 such words per sentence; it reads sentences where the original reads units ended by any final mark. nan without sentences.

\[ \textrm{WS} = 10 \times \textrm{ASL} \times \frac{\textrm{Words of two syllables or more}}{\textrm{Words}} \]

Parameter	Type	Default	Description
`n_polysyllable_words`	`int`	-	Number of the words of two syllables or more
`n_sents`	`int`	-	Number of sentences

A count that is not an integer or is negative raises ParameterError.

Methods¶

The methods get_stats, to_dataframe, print_stats and describe are those of the statistics interface; the formulas have no scales.

For library developers¶

Language hooks of a subclass

A language library subclasses UnadaptedReadabilityStats:

Hook	Kind	Description
`basic_stats_class`	class attribute	Basic statistics of a string or a `Doc`, the class with the syllables of the language; without it the source must be a `BasicStats` object
`complex_syl_factor`, `long_word_letter_factor`, `mini_word_letters`	class attributes	Least syllables of a hard word (3), least letters of a long word (7), most letters of a mini word of EFLAW (`EFLAW_MINI_WORD_LETTERS`, 3)
`stats_desc`, `stats_headers`	class attributes	Metrics of `get_stats` with their descriptions (`UNADAPTED_READABILITY_STATS_DESC` by default), headers of the columns for `print_stats`
`messages`	class attribute	Messages of the errors by key; `MESSAGES` by default

When a subclass is defined, a basic_stats_class that is neither a subclass of BasicStats nor None and a factor that is not an integer of at least one raise ParameterError.