pyests 0.2.0__tar.gz → 0.4.0__tar.gz

{pyests-0.2.0 → pyests-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyests
-Version: 0.2.0
+Version: 0.4.0
 Summary: Spanish Texts Statistics
 Project-URL: Homepage, https://github.com/SergeyShk/esTS
 Project-URL: Repository, https://github.com/SergeyShk/esTS
@@ -28,9 +28,12 @@ Classifier: Topic :: Text Processing
 Classifier: Topic :: Text Processing :: Linguistic
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
+Requires-Dist: graphviz>=0.20.3
+Requires-Dist: matplotlib>=3.8
 Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.1
 Requires-Dist: scipy>=1.11
-Requires-Dist: simplemma>=1.0
+Requires-Dist: simplemma<3,>=2.0
 Requires-Dist: spacy>=3.7
 Description-Content-Type: text/markdown
 
@@ -60,13 +63,14 @@ Description-Content-Type: text/markdown
   <a href="https://github.com/SergeyShk/esTS/actions/workflows/ci.yml"><img src="https://github.com/SergeyShk/esTS/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
   <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
   <a href="https://github.com/SergeyShk/esTS/blob/master/LICENSE.txt"><img src="https://img.shields.io/github/license/sergeyshk/esTS.svg" alt="License"></a>
+  <a href="https://doi.org/10.5281/zenodo.22924655"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.22924655.svg" alt="DOI"></a>
 </p>
 
 ---
 
-**esTS** computes for Spanish texts what usually requires assembling several separate tools: basic statistics, readability, lexical diversity, morphology, syntax and cohesion - by published formulas with the coefficients and the scales of their authors, and by the parts of speech and the features of Universal Dependencies.
+**esTS** computes statistics of Spanish texts: basic statistics, readability, lexical diversity, lexical sophistication, style, phonostatistics, morphology, syntax and cohesion - by published formulas with the coefficients and the scales of their authors, and by the parts of speech and the features of Universal Dependencies.
 
-The library works both with raw strings and with `Doc` objects of [spaCy](https://github.com/explosion/spaCy): sentences, words and character N-grams are extracted by rules, syllables and stress follow from the orthography, and only the morphological, the syntactic and the cohesion statistics need a trained model.
+The library works both with raw strings and with `Doc` objects of [spaCy](https://github.com/explosion/spaCy); most statistics need no trained model (see Installation).
 
 * **[Object extraction](https://sergeyshk.github.io/esTS/extractors/sentences/)** - configurable sentence, word and character N-gram tokenizers that know the inverted marks, the dialogue dash and the abbreviations of Spanish
 * **[Syllables and stress](https://sergeyshk.github.io/esTS/syllables/)** - rule-based syllabification and the stressed syllable derived from the spelling, with no dictionary
@@ -74,12 +78,17 @@ The library works both with raw strings and with `Doc` objects of [spaCy](https:
 * **[Readability metrics](https://sergeyshk.github.io/esTS/stats/readability_stats/)** - Fernández Huerta, Szigriszt-Pazos with the INFLESZ scale, Gutiérrez de Polini, Crawford, Legibilidad µ, SOL, LIX and RIX, with a consensus grade, the school stages of Spain and reading time
 * **[Lexical diversity metrics](https://sergeyshk.github.io/esTS/stats/diversity_stats/)** - TTR and its variations, MATTR, MSTTR, MTLD, HD-D, Simpson's and Yule's indices, entropy, Zipf's and Heaps' laws
 * **[Morphological statistics](https://sergeyshk.github.io/esTS/stats/morph_stats/)** - parts of speech and fifteen grammatical features of Universal Dependencies, with the markers of Spanish: the moods, the non-finite forms, `ser` against `estar`, the adverbs in `-mente`
+* **[Corpus measures](https://sergeyshk.github.io/esTS/corpus/keyness/)** - keywords against a reference corpus, collocations, the dispersion of a word over the parts of a text, a KWIC concordance and the stylometry of authorship: Burrows's Delta with its variants, Zeta, the Mendenhall curve, the profile of the function words; the comparison of two corpora by 132 features of a text with effect sizes
+* **[Visualizers](https://sergeyshk.github.io/esTS/visualizers/zipf/)** - Zipf's law, literature fingerprinting, a word tree, lexical dispersion and keywords, a network of collocations, a dendrogram, PCA and MDS by Delta, vocabulary growth, sentence lengths, and the highlighting of the fragments the statistics count, such as long sentences and passives
+* **[Datasets](https://sergeyshk.github.io/esTS/datasets/spanishliterature/)** - Spanish-language literature in the public domain: 150 works by 33 authors in four genres; 4,259 sonnets of the 15th-20th centuries with the metrical pattern and the rhyme of every line; a frequency dictionary of 83,785 lemmas by Google Books Ngram
 * **[spaCy components](https://sergeyshk.github.io/esTS/components/)** - every statistics class as a component of a pipeline, the statistics attached to the `Doc` in one pass
 * **[Cohesion statistics](https://sergeyshk.github.io/esTS/stats/cohesion_stats/)** - the overlap of nouns, arguments and content words between sentences, givenness and temporal cohesion in the manner of Coh-Metrix, with the density of 255 Spanish discourse markers
+* **[Lexical sophistication statistics](https://sergeyshk.github.io/esTS/stats/lexical_stats/)** - how rare the words of a text are in the language: the frequency, range and dispersion of the lemmas by a dictionary of Google Books Ngram, the frequency bands top-1000 to 10000, surprisal, perplexity and lexical density
+* **[Style metrics](https://sergeyshk.github.io/esTS/stats/style_stats/)** - the SEO indicators of Advego and Text.ru (nausea, water content, spam score, naturalness by Zipf's law, keyword density) and the markers of the officialese style by the Spanish guides to plain language: verbal nouns, compound prepositions, parenthetical expressions and clichés
+* **[Phonostatistics](https://sergeyshk.github.io/esTS/stats/phon_stats/)** - the shares of the classes of sounds, consonant clusters, hiatuses, open syllables, hardness and the indices of alliteration and assonance, over the sounds of a rule-based transcription
+* **[Verse statistics](https://sergeyshk.github.io/esTS/stats/verse_stats/)** - the scansion of Spanish verse by its syllabic meter: the metrical syllables, the meter of a poem, the stress profile and the types of the endecasílabo, the rhyme in full and by assonance with its scheme, the strophes and the form of a poem
 * **[Syntactic statistics](https://sergeyshk.github.io/esTS/stats/syntax_stats/)** - the dependency tree by distances, depth, clauses and coordination, with the constructions of the administrative style: the passive with `ser` and with `se`, the participial and the gerund clauses, the chains of `de`, the split predicates
 
-Corpus measures and stylometry come in 0.3, style, phonostatistics, metre and rhyme in 0.4.
-
 ## Installation
 
 Requires Python 3.11 or newer.
@@ -94,12 +103,14 @@ Or with [uv](https://docs.astral.sh/uv/):
 uv add pyests
 ```
 
-The distribution on PyPI is `pyests`, the package it installs is `ests`. The basic statistics, the readability and the lexical diversity metrics need no spaCy model; the morphological, the syntactic and the cohesion statistics do, and so does parsing a text yourself to pass the `Doc` instead of a string:
+The distribution on PyPI is `pyests`, the package it installs is `ests`. The basic statistics, readability, lexical diversity, the style metrics except the verbal nouns, phonostatistics and verse statistics need no spaCy model. The morphological, syntactic, cohesion and lexical sophistication statistics of a string need one, and so do the verbal nouns, the profile of the function words, the features of a text, the comparison of corpora and parsing a `Doc` yourself:
 
 ```bash
 python -m spacy download es_core_news_sm
 ```
 
+The statistics by the frequency dictionary need it downloaded once with `FreqDict().download()`. The datasets go to the directory `ests_data` next to the installed package, or to the one passed in `data_dir` or set in `ESTS_DATA_DIR` before the package is imported.
+
 ## Quick start
 
 ```python
@@ -139,7 +150,7 @@ python -m spacy download es_core_news_sm
 
 ### Object extraction
 
-The library allows creating your own tools for sentence, word and character N-gram extraction from a text, which can be further employed for counting statistics. The sentence splitter knows the inverted marks, the dash of a line of dialogue with the remark of the narrator, the abbreviations and the initials of Spanish; the word tokenizer keeps clitics, ordinals and numbers written the Spanish way together, and lemmas come from [simplemma](https://github.com/adbar/simplemma), which needs no model.
+Configurable tools extract sentences, words and character N-grams from a text for the statistics. The sentence splitter knows the inverted marks, the dialogue dash and the abbreviations of Spanish; the word tokenizer keeps clitics, ordinals and Spanish numbers whole, and lemmas come from [simplemma](https://github.com/adbar/simplemma), which needs no model.
 
 ```python
 >>> from ests import CharNgramsExtractor, SentsExtractor, WordsExtractor
@@ -162,7 +173,7 @@ More in the [documentation](https://sergeyshk.github.io/esTS/extractors/sentence
 
 <br>
 
-Spanish spelling encodes both the syllable boundaries and the stress, so the library needs no dictionary: diphthongs, hiatuses and triphthongs, the silent `u` of `qu` and `gu`, the vocalic `y`, the `h` inside a diphthong and the consonant clusters give the syllables; the written accent, or the ending of the word when there is none, gives the stressed syllable. Adverbs in `-mente` and hyphenated compounds carry two stresses.
+The syllables and the stress follow from the Spanish spelling, with no dictionary: the written accent, or the ending of the word when there is none, gives the stressed syllable. Adverbs in `-mente` and hyphenated compounds carry two stresses.
 
 ```python
 >>> from ests.syllables import stress_type, syllabify, word_stress, word_stresses
@@ -207,7 +218,7 @@ The library allows extracting the following statistics from a text:
 *   the distribution of words by the number of letters
 *   the distribution of words by the number of syllables
 
-A complex word has three or more syllables and a long word seven or more letters, as the Spanish readability formulas count them. Any statistic can be printed in a readable form:
+A complex word has three or more syllables and a long word seven or more letters. Any statistic can be printed in a readable form:
 
 ```python
 >>> from ests import BasicStats
@@ -250,9 +261,9 @@ The library allows counting the following readability metrics:
 *   LIX readability measure
 *   RIX readability measure
 
-An interpretation layer works on top of the formulas: the band of a scale for the reading ease and for Legibilidad µ, a consensus grade as the median of the grade formulas, the school stage and the reader age of Spain, and reading time by the norms of Spanish-speaking readers.
+On top of the formulas: the band of a scale for the reading ease and for Legibilidad µ, a consensus grade (the median of the grade formulas), the school stage and the reader age in Spain, and reading time.
 
-The coefficients of the Flesch reading ease are selected by the `preset` argument: by default the *fórmula de perspicuidad* of Szigriszt-Pazos with the INFLESZ scale validated on texts for patients (`general`); the coefficients of Fernández Huerta with the bands of their author are available as `classic`.
+The coefficients of the Flesch reading ease are selected by `preset`: by default the *fórmula de perspicuidad* of Szigriszt-Pazos with the INFLESZ scale (`general`), or Fernández Huerta with the bands of its author (`classic`).
 
 ```python
 >>> from pprint import pprint
@@ -312,7 +323,7 @@ The library allows counting 32 lexical diversity metrics, among them:
 *   Shannon entropy, evenness and perplexity
 *   the slope of Zipf's law, the Zipf-Mandelbrot fit and the exponent of Heaps' law
 
-Any metric can be computed over windows of equal length, which is the standard way to compare texts of different lengths: the mean over the windows comes with a confidence interval.
+Any metric can be computed over windows of equal length, to compare texts of different lengths, with a confidence interval of the mean.
 
 ```python
 >>> from ests import DiversityStats
@@ -342,7 +353,7 @@ More in the [documentation](https://sergeyshk.github.io/esTS/stats/diversity_sta
 
 <br>
 
-The library annotates a text with the parts of speech and the grammatical features of Universal Dependencies, as the Spanish models of spaCy give them, and counts them:
+The parts of speech and the grammatical features of Universal Dependencies, as the Spanish models of spaCy give them:
 
 *   the part of speech and fifteen features: case, definiteness, degree, gender, mood, numeral type, number, person, polarity, politeness, possessive, pronoun type, reflexive, tense and verb form
 *   the distribution of the words by the values of any feature, and the parse of the text word by word
@@ -366,7 +377,7 @@ The library annotates a text with the parts of speech and the grammatical featur
 0.5
 ```
 
-The statistics need a spaCy model: a text is parsed with `es_core_news_sm`, and any other pipeline can be passed in `nlp`.
+A text is parsed with `es_core_news_sm`; another pipeline can be passed in `nlp`.
 
 More in the [documentation](https://sergeyshk.github.io/esTS/stats/morph_stats/).
 
@@ -377,7 +388,7 @@ More in the [documentation](https://sergeyshk.github.io/esTS/stats/morph_stats/)
 
 <br>
 
-The library measures the dependency tree of Universal Dependencies and the constructions that the Spanish guides to clear language warn about:
+The dependency tree of Universal Dependencies and the constructions that the Spanish guides to clear language warn about:
 
 *   the complexity of the tree: dependency distances, depth, leaves and subtrees, valency of the finite verbs, coordination chains, clauses and subordinate clauses, modifiers per noun
 *   the constructions: the passive with `ser` and with `se`, the participial and the gerund clauses, the chains of `de`, the split predicates, the impersonal `se`, the words of negation, the ratio of nouns to verbs
@@ -402,7 +413,7 @@ The library measures the dependency tree of Universal Dependencies and the const
 2.05
 ```
 
-The statistics need a parse: a text is parsed with `es_core_news_sm`, and any other pipeline can be passed in `nlp`.
+A text is parsed with `es_core_news_sm`; another pipeline with a parser can be passed in `nlp`.
 
 More in the [documentation](https://sergeyshk.github.io/esTS/stats/syntax_stats/).
 
@@ -413,7 +424,7 @@ More in the [documentation](https://sergeyshk.github.io/esTS/stats/syntax_stats/
 
 <br>
 
-The library measures referential cohesion in the manner of Coh-Metrix and of its Spanish adaptation Coh-Metrix-Esp:
+Referential cohesion in the manner of Coh-Metrix and its Spanish adaptation Coh-Metrix-Esp:
 
 *   the overlap of nouns, of arguments and of content words between adjacent sentences and between all pairs of sentences, binary and proportional
 *   givenness: pronouns, demonstratives and the content words whose lemma was already used
@@ -440,12 +451,98 @@ The library measures referential cohesion in the manner of Coh-Metrix and of its
 (86.96, 43.48)
 ```
 
-The statistics need the annotation: a text is parsed with `es_core_news_sm`, and any other pipeline can be passed in `nlp`.
+A text is parsed with `es_core_news_sm`; another pipeline can be passed in `nlp`.
 
 More in the [documentation](https://sergeyshk.github.io/esTS/stats/cohesion_stats/).
 
 </details>
 
+<details>
+<summary><b>Lexical sophistication statistics</b></summary>
+
+<br>
+
+How rare the words of a text are in the language, in the manner of TAALES: the mean frequency, range and dispersion of the lemmas by the frequency dictionary of Google Books Ngram, the shares of the frequency bands top-1000, 2000, 5000 and 10000, surprisal and perplexity, the lexical density. The statistics by the dictionary need it downloaded once.
+
+```python
+>>> from ests import LexicalStats
+>>> from ests.datasets import FreqDict
+
+>>> FreqDict().download()
+>>> ls = LexicalStats("El felinólogo examinaba al minino con parsimonia")
+>>> ls.coverage, ls.p_top1000, round(ls.surprisal, 2)
+(0.8571428571428571, 0.42857142857142855, 13.71)
+```
+
+More in the [documentation](https://sergeyshk.github.io/esTS/stats/lexical_stats/).
+
+</details>
+
+<details>
+<summary><b>Style metrics</b></summary>
+
+<br>
+
+The SEO indicators of Advego and Text.ru - nausea, water content, spam score, naturalness by Zipf's law, keyword density - and the markers of the officialese style that the Spanish guides to plain language warn about: the nouns derived from a verb, the compound prepositions of the administrative style, the parenthetical expressions and the clichés.
+
+```python
+>>> from ests import StyleStats
+
+>>> ss = StyleStats("Se procedió a la revisión del expediente en el marco del plan a la mayor brevedad.")
+>>> ss.compound_prepositions, ss.cliches, ss.verbal_nouns
+(6.25, 12.5, 20.0)
+```
+
+More in the [documentation](https://sergeyshk.github.io/esTS/stats/style_stats/).
+
+</details>
+
+<details>
+<summary><b>Phonostatistics</b></summary>
+
+<br>
+
+The shares of the classes of sounds, the consonant clusters, the hiatuses, the open syllables, the hardness and the indices of alliteration and assonance, counted over the sounds of a rule-based transcription, not over the letters: `h` is silent, `ll` and `rr` are one sound.
+
+```python
+>>> from ests import PhonStats
+
+>>> ps = PhonStats("Los suspiros se escapan de su boca de fresa")
+>>> round(ps.p_voiceless, 3), round(ps.hardness, 3), ps.sounds[-1]
+(0.371, 0.684, ('f', 'r', 'e', 's', 'a'))
+```
+
+More in the [documentation](https://sergeyshk.github.io/esTS/stats/phon_stats/).
+
+</details>
+
+<details>
+<summary><b>Verse statistics</b></summary>
+
+<br>
+
+The scansion of Spanish verse by its syllabic meter: the metrical syllables of a line with the synalepha and the law of the final stress, fitted to the meter of the poem; the meter, the stress profile and the types of the endecasílabo; the rhyme in full (consonante) and by assonance (asonante) with its scheme, the strophes and the form of a poem. No model and no dictionary are needed.
+
+```python
+>>> from ests import VerseStats
+
+>>> text = """Cuando me paro a contemplar mi estado
+... y a ver los pasos por do me han traído,
+... hallo, según por do anduve perdido,
+... que a mayor mal pudiera haber llegado."""
+>>> vs = VerseStats(text)
+>>> vs.meter, vs.patterns[0], vs.c_rhythms
+('endecasílabo', '---+---+-+-', {'4-8-10': 2, '4-7-10': 1, '3-6-10': 1})
+>>> vs.syllables[0]
+('cuan', 'do', 'me', 'pa', 'ro‿a', 'con', 'tem', 'plar', 'mi‿es', 'ta', 'do')
+>>> vs.rhyme_schemes, vs.strophes
+(('ABBA',), ('cuarteto',))
+```
+
+More in the [documentation](https://sergeyshk.github.io/esTS/stats/verse_stats/).
+
+</details>
+
 <details>
 <summary><b>spaCy components</b></summary>
 
@@ -469,12 +566,141 @@ Every statistics class is also a component of a pipeline, so a text is annotated
 (12, ('DET', 'NOUN'), 2.0)
 ```
 
-The factories are `ests_basic`, `ests_readability`, `ests_diversity`, `ests_morph`, `ests_syntax` and `ests_cohesion`; the name of the pipe is free and is what the extension is called.
+The factories are `ests_basic`, `ests_readability`, `ests_diversity`, `ests_morph`, `ests_syntax`, `ests_cohesion`, `ests_lexical`, `ests_style`, `ests_phon` and `ests_verse`; the name of the pipe is the name of the extension.
 
 More in the [documentation](https://sergeyshk.github.io/esTS/components/).
 
 </details>
 
+<details>
+<summary><b>Corpus measures</b></summary>
+
+<br>
+
+The measures of corpus linguistics that compare corpora and describe the use of a word:
+
+*   keywords of a target corpus against a reference one or against the frequency dictionary of Google Books Ngram: the log-likelihood with its p-value, Log Ratio, chi-square, %DIFF, BIC, ELL and the odds ratio
+*   collocations by logDice, MI, MI³, t-score, Dice, log-likelihood, NPMI and minimum sensitivity
+*   the dispersion of a word over the parts of a text: DP of Gries, normalized DP, Juilland's D, Carroll's D2, Rosengren's S and the Kullback-Leibler divergence
+*   a KWIC concordance by word form or by lemma
+*   stylometry: the distances between texts by Burrows's Delta and its variants, with the attribution of a text to reference authors, the markers of preferred and avoided words by Zeta, Kilgarriff's chi-square, the Mendenhall curve and the profile of the function words
+*   the comparison of two corpora by 132 features of a text over windows of about the same size: Cliff's delta, Cohen's d and the AUC of every feature, the Mann-Whitney test with Holm's correction and a bootstrap interval of the difference of the medians
+
+```python
+>>> from ests import WordsExtractor
+>>> from ests.corpus import collocations, keyness, kwic, zeta
+
+>>> we = WordsExtractor(use_lexemes=True, lowercase=True)
+>>> target = we.extract("El gato estaba en la ventana y miraba a los pájaros. Los pájaros se fueron y el gato "
+...                     "se durmió en la ventana. Mañana el gato volverá a estar en la ventana y mirará a los pájaros.")
+>>> reference = we.extract("El perro estaba en el suelo y dormía. Después el perro comió y volvió a dormir. "
+...                        "Mañana el perro saldrá a pasear.")
+
+>>> [(k.word, round(k.g2, 2)) for k in keyness(target, reference, top_n=2)]
+[('gato', 2.8), ('pájaro', 2.8)]
+
+>>> [(c.left, c.right, round(c.score, 1)) for c in collocations(target, window=2, top_n=2)]
+[('en', 'ventana', 13.0), ('estar', 'en', 12.7)]
+
+>>> [line.keyword for line in kwic("Los gatos juegan y el gato duerme.", "gato", by_lemma=True)]
+['gatos', 'gato']
+
+>>> scores = zeta(target, reference, segment_size=10)
+>>> [z.word for z in scores[:2]], [z.word for z in scores[-2:]]
+(['gato', 'ventana'], ['dormir', 'perro'])
+```
+
+Words are compared as they are, so case, lemmas and stop words are chosen at the extraction.
+
+More in the [documentation](https://sergeyshk.github.io/esTS/corpus/keyness/).
+
+</details>
+
+<details>
+<summary><b>Datasets</b></summary>
+
+<br>
+
+*   [spanish_literature](https://sergeyshk.github.io/esTS/datasets/spanishliterature/) - Spanish-language literature in the public domain: 150 works by 33 authors from Spain, Latin America and the Philippines, from Cervantes to the 1920s, in prose, poems, drama and publicism
+*   [spanish_sonnets](https://sergeyshk.github.io/esTS/datasets/spanishsonnets/) - Spanish sonnets of the Diachronic Spanish Sonnet Corpus (DISCO) in the public domain: 4,259 sonnets by 1,167 authors of the 15th-20th centuries, every line with its metrical pattern and the label of its rhyme, the automatic annotation of DISCO (CC BY 4.0)
+*   [freq_dict](https://sergeyshk.github.io/esTS/datasets/freqdict/) - a frequency dictionary of 83,785 Spanish lemmas from the books of Google Books Ngram of 1980-2019: ipm, range and Juilland's D over the years, the number of books and the part of speech (CC BY 3.0)
+
+The texts are cut to the text of the author and come with the genre, the author, the title, the years of the first publication and the country; the records can be filtered by any of them and by the length of the text.
+
+```python
+>>> from ests.datasets import SpanishLiterature
+
+>>> sl = SpanishLiterature()
+>>> sl.download()
+>>> for record in sl.get_records(author="galdos", year_from=1880, year_to=1884):
+...     print(record["title"], record["year_from"], len(record["text"]))
+La desheredada 1881 820454
+El amigo Manso 1882 521156
+La de Bringas 1884 413730
+Tormento 1884 477286
+```
+
+The archive (19 MB) is downloaded once by `download()` into the data directory; before that `get_texts()` and `get_records()` raise `DatasetNotFoundError`.
+
+More in the [documentation](https://sergeyshk.github.io/esTS/datasets/spanishliterature/).
+
+</details>
+
+<details>
+<summary><b>Visualizers</b></summary>
+
+<br>
+
+*   [Zipf's law](https://sergeyshk.github.io/esTS/visualizers/zipf/) with the theoretical curve and the Zipf-Mandelbrot fit
+*   [Literature fingerprinting](https://sergeyshk.github.io/esTS/visualizers/fingerprinting/)
+*   [Word tree](https://sergeyshk.github.io/esTS/visualizers/word_tree/)
+*   [Corpus plots](https://sergeyshk.github.io/esTS/visualizers/corpus/): lexical dispersion, a chart of keywords, a network of collocations
+*   [Stylometric plots](https://sergeyshk.github.io/esTS/visualizers/stylometry/): a dendrogram, the principal components and the multidimensional scaling by Delta, the Mendenhall curves
+*   [Vocabulary growth and frequency spectrum](https://sergeyshk.github.io/esTS/visualizers/vocabulary/), [sentence lengths](https://sergeyshk.github.io/esTS/visualizers/sentences/) with a moving average
+
+The matplotlib plots take the axes `ax` and return `Axes`; the network of collocations and the word tree are rendered by the executables of Graphviz. Cosine Delta separates three novels by Galdós from three by Unamuno:
+
+```python
+import matplotlib.pyplot as plt
+from ests import WordsExtractor
+from ests.corpus import delta
+from ests.datasets import SpanishLiterature
+from ests.visualizers import dendrogram_plot, pca_plot
+
+# six novels by Galdós and Unamuno from the corpus of literature
+titles = (
+    "Marianela",
+    "Misericordia",
+    "Torquemada en la hoguera",
+    "Niebla",
+    "Abel Sánchez",
+    "La tía Tula",
+)
+sl = SpanishLiterature()
+sl.download()
+novels = {
+    record["title"]: record["text"]
+    for author in ("galdos", "unamuno")
+    for record in sl.get_records(author=author)
+    if record["title"] in titles
+}
+we = WordsExtractor(lowercase=True)
+corpus = {title: we.extract(novels[title]) for title in titles}
+distances = delta(corpus, n_mfw=100, variant="cosine")
+
+fig, (left, right) = plt.subplots(1, 2, figsize=(13, 5))
+dendrogram_plot(distances, ax=left)
+pca_plot(corpus, n_mfw=100, ax=right)
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/SergeyShk/esTS/master/docs/img/stylometry.png" alt="Stylometric plots" width="760">
+</p>
+
+More in the [documentation](https://sergeyshk.github.io/esTS/visualizers/zipf/).
+
+</details>
+
 ## Development
 
 The project uses [uv](https://docs.astral.sh/uv/) for dependency management and [ruff](https://docs.astral.sh/ruff/) for linting and formatting.
@@ -492,7 +718,7 @@ Run `make help` for the full list of commands.
 
 The documentation is bilingual: English pages are `docs/*.md`, Spanish ones are `docs/*.es.md` next to them ([mkdocs-static-i18n](https://github.com/ultrabug/mkdocs-static-i18n)); when editing a page, update both versions.
 
-The installed version is `ests.__version__`. All exceptions inherit `ests.EstsError` and one of the built-in classes (`SourceError` and `ParameterError` - `ValueError`, `SourceTypeError` - `TypeError`, `UnknownStatError` - `KeyError`), so `except ValueError` keeps working. The library prints nothing on its own: its messages go to the `ests` logger (`logging.getLogger("ests")`) and are silent by default.
+The installed version is `ests.__version__`. All exceptions inherit `ests.EstsError` and a built-in class (`ValueError`, `TypeError`, `KeyError`, `OSError` or `RuntimeError`), so `except ValueError` keeps working. The library prints nothing on its own: its messages go to the `ests` logger and are silent by default. More in the [documentation](https://sergeyshk.github.io/esTS/exceptions/).
 
 Before submitting changes, install the hooks that run the linters on commit and the tests on push:
 
@@ -502,7 +728,7 @@ uv run pre-commit install
 
 ## Contributing
 
-Bug reports, ideas and pull requests are welcome - [issues](https://github.com/SergeyShk/esTS/issues) are open. The workflow, the checks to run before submitting a pull request and how to shape the changes are described in [CONTRIBUTING.md](https://github.com/SergeyShk/esTS/blob/master/CONTRIBUTING.md); the rules of conduct are in the [code of conduct](https://github.com/SergeyShk/esTS/blob/master/CODE_OF_CONDUCT.md).
+Bug reports, ideas and pull requests are welcome in the [issues](https://github.com/SergeyShk/esTS/issues). The workflow and the checks to run before a pull request are in [CONTRIBUTING.md](https://github.com/SergeyShk/esTS/blob/master/CONTRIBUTING.md); the rules of conduct are in the [code of conduct](https://github.com/SergeyShk/esTS/blob/master/CODE_OF_CONDUCT.md).
 
 <details>
 <summary><b>Project structure</b></summary>
@@ -513,16 +739,24 @@ Bug reports, ideas and pull requests are welcome - [issues](https://github.com/S
 *   **ests**:
     *   basic_stats.py - basic text statistics
     *   cohesion_stats.py - cohesion statistics
+    *   lexical_stats.py - lexical sophistication statistics
     *   components.py - components of a spaCy pipeline
+    *   corpus - measures of corpus linguistics: keywords, collocations, dispersion, concordance, stylometry, comparison of corpora
+    *   datasets - datasets: Spanish-language literature, Spanish sonnets, the frequency dictionary
     *   constants.py - constants of the Spanish language and of the metrics
     *   diversity_stats.py - lexical diversity metrics
     *   exceptions.py - library exceptions
     *   extractors.py - tools for object extraction from a text
     *   morph_stats.py - morphological statistics
     *   readability_stats.py - readability metrics
+    *   style_stats.py - style metrics
+    *   phon_stats.py - phonostatistics
     *   syntax_stats.py - syntactic statistics
+    *   verse_stats.py - verse statistics
     *   syllables.py - syllabification and stress
     *   utils.py - helper tools
+    *   visualizers - plots: Zipf's law, fingerprinting, word tree, corpus and stylometric plots, vocabulary growth, sentence lengths, text highlighting
+*   **scripts** - scripts that build the archives of the datasets
 *   **tests** - tests mirroring the package structure
 
 </details>
@@ -537,13 +771,14 @@ Bug reports, ideas and pull requests are welcome - [issues](https://github.com/S
 
 ## Citation
 
-Please use the following BibTeX entry for citing **esTS** if you use it in your research or software. Citations are helpful for the continued development and maintenance of this library. The same metadata is in [CITATION.cff](https://github.com/SergeyShk/esTS/blob/master/CITATION.cff) - GitHub shows it under the "Cite this repository" button.
+Please use the following BibTeX entry for citing **esTS** if you use it in your research or software. The same metadata is in [CITATION.cff](https://github.com/SergeyShk/esTS/blob/master/CITATION.cff) ("Cite this repository" on GitHub). The Concept DOI [10.5281/zenodo.22924655](https://doi.org/10.5281/zenodo.22924655) points at every version of the library; the DOI of a single version is on the page of its release.
 
 ```bibtex
 @software{esTS,
   author = {Sergey Shkarin},
   title = {{esTS, a library for statistics extraction from texts in Spanish}},
   year = 2026,
+  doi = {10.5281/zenodo.22924655},
   url = {https://github.com/SergeyShk/esTS}
 }
 ```