pyests 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyests
-Version: 0.2.0
+Version: 0.3.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 for Spanish texts what usually requires assembling several separate tools: basic statistics, readability, lexical diversity, lexical sophistication, 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): sentences, words and character N-grams are extracted by rules, syllables and stress follow from the orthography, and only the morphological, the syntactic, the cohesion and the lexical sophistication statistics, the profile of the function words and the comparison of corpora need a trained model.
 
 * **[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,11 +78,15 @@ 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
+* **[Datasets](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 in prose, poems, drama and publicism, with the genre, the years and the country; a frequency dictionary of 83,785 lemmas by Google Books Ngram with ipm, range and dispersion
 * **[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
 * **[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.
+Style, phonostatistics, metre and rhyme come in 0.4.
 
 ## Installation
 
@@ -94,12 +102,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, the readability and the lexical diversity metrics need no spaCy model; the morphological, the syntactic, the cohesion and the lexical sophistication statistics of a string do, and so do the profile of the function words, the features of a text and the comparison of corpora, and parsing a text yourself to pass the `Doc` instead of a string:
 
 ```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; another one is passed in `data_dir` or set in the environment variable `ESTS_DATA_DIR` before the package is imported.
+
 ## Quick start
 
 ```python
@@ -446,6 +456,27 @@ More in the [documentation](https://sergeyshk.github.io/esTS/stats/cohesion_stat
 
 </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 words of the frequency bands top-1000, 2000, 5000 and 10000, the surprisal and the perplexity by the unigram model of the dictionary, the lexical density. The bands and the density work out of the box; 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>spaCy components</b></summary>
 
@@ -469,12 +500,140 @@ 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` and `ests_lexical`; the name of the pipe is free and is what the extension is called.
 
 More in the [documentation](https://sergeyshk.github.io/esTS/components/).
 
 </details>
 
+<details>
+<summary><b>Corpus measures</b></summary>
+
+<br>
+
+The library compares corpora and describes the use of a word, with the measures of corpus linguistics:
+
+*   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, checked against NLTK
+*   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 that resamples whole texts
+
+```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; 65 million characters
+*   [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 (63 billion words): 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, without title pages, notes of the transcribers and the editors, tables of contents and footnotes, 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 and verified against its SHA-256 checksum; before the download `get_texts()` and `get_records()` raise `DatasetNotFoundError` with a hint.
+
+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/) (Literature Fingerprinting)
+*   [Word tree](https://sergeyshk.github.io/esTS/visualizers/word_tree/) (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`, so they can be laid out on one figure; the network of collocations and the word tree are graphs of graphviz, whose executables render them. 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 +651,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 one of the built-in classes (`SourceError`, `ParameterError` and `DataFileError` - `ValueError`, `SourceTypeError` - `TypeError`, `UnknownStatError` - `KeyError`, `DatasetNotFoundError` - `OSError`, `DownloadError` - `RuntimeError`), 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.
 
 Before submitting changes, install the hooks that run the linters on commit and the tests on push:
 
@@ -513,7 +672,10 @@ 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, the frequency dictionary
     *   constants.py - constants of the Spanish language and of the metrics
     *   diversity_stats.py - lexical diversity metrics
     *   exceptions.py - library exceptions
@@ -523,6 +685,8 @@ Bug reports, ideas and pull requests are welcome - [issues](https://github.com/S
     *   syntax_stats.py - syntactic 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
+*   **scripts** - scripts that build the archives of the datasets
 *   **tests** - tests mirroring the package structure
 
 </details>
@@ -537,13 +701,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. 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. The Concept DOI [10.5281/zenodo.22924655](https://doi.org/10.5281/zenodo.22924655) on Zenodo 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}
 }
 ```

{pyests-0.2.0 → pyests-0.3.0}/README.es.md

@@ -24,13 +24,14 @@
   <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** calcula para textos en español lo que normalmente exige juntar varias herramientas sueltas: estadísticas básicas, legibilidad, diversidad léxica, morfología, sintaxis y cohesión, con fórmulas publicadas y con los coeficientes y las escalas de sus autores, y con las categorías y los rasgos de Universal Dependencies.
+**esTS** calcula para textos en español lo que normalmente exige juntar varias herramientas sueltas: estadísticas básicas, legibilidad, diversidad léxica, complejidad léxica, morfología, sintaxis y cohesión, con fórmulas publicadas y con los coeficientes y las escalas de sus autores, y con las categorías y los rasgos de Universal Dependencies.
 
-La biblioteca trabaja tanto con cadenas como con objetos `Doc` de [spaCy](https://github.com/explosion/spaCy): las oraciones, las palabras y los N-gramas de caracteres se extraen por reglas, las sílabas y el acento se deducen de la ortografía, y solo las estadísticas morfológicas, las sintácticas y las de cohesión necesitan un modelo entrenado.
+La biblioteca trabaja tanto con cadenas como con objetos `Doc` de [spaCy](https://github.com/explosion/spaCy): las oraciones, las palabras y los N-gramas de caracteres se extraen por reglas, las sílabas y el acento se deducen de la ortografía, y solo las estadísticas morfológicas, las sintácticas, las de cohesión y las de complejidad léxica, el perfil de las palabras funcionales y la comparación de corpus necesitan un modelo entrenado.
 
 * **[Extracción de objetos](https://sergeyshk.github.io/esTS/es/extractors/sentences/)** - tokenizadores configurables de oraciones, palabras y N-gramas de caracteres que conocen los signos de apertura, la raya de diálogo y las abreviaturas del español
 * **[Sílabas y acento](https://sergeyshk.github.io/esTS/es/syllables/)** - silabificación por reglas y sílaba tónica deducida de la escritura, sin diccionario
@@ -38,11 +39,15 @@ La biblioteca trabaja tanto con cadenas como con objetos `Doc` de [spaCy](https:
 * **[Métricas de legibilidad](https://sergeyshk.github.io/esTS/es/stats/readability_stats/)** - Fernández Huerta, Szigriszt-Pazos con la escala INFLESZ, Gutiérrez de Polini, Crawford, Legibilidad µ, SOL, LIX y RIX, con grado de consenso, etapas escolares de España y tiempo de lectura
 * **[Métricas de diversidad léxica](https://sergeyshk.github.io/esTS/es/stats/diversity_stats/)** - TTR y sus variantes, MATTR, MSTTR, MTLD, HD-D, índices de Simpson y de Yule, entropía, leyes de Zipf y de Heaps
 * **[Estadísticas morfológicas](https://sergeyshk.github.io/esTS/es/stats/morph_stats/)** - categorías gramaticales y quince rasgos morfológicos de Universal Dependencies, con los marcadores del español: los modos, las formas no personales, `ser` frente a `estar`, los adverbios en `-mente`
+* **[Medidas de corpus](https://sergeyshk.github.io/esTS/es/corpus/keyness/)** - palabras clave frente a un corpus de referencia, colocaciones, la dispersión de una palabra por las partes de un texto, una concordancia KWIC y la estilometría de autoría: la Delta de Burrows con sus variantes, Zeta, la curva de Mendenhall, el perfil de las palabras funcionales; la comparación de dos corpus por 132 rasgos de un texto con tamaños del efecto
+* **[Visualizaciones](https://sergeyshk.github.io/esTS/es/visualizers/zipf/)** - ley de Zipf, huella literaria, árbol de palabras, dispersión léxica y palabras clave, red de colocaciones, dendrograma, PCA y MDS por la Delta, crecimiento del vocabulario, longitudes de las oraciones
+* **[Conjuntos de datos](https://sergeyshk.github.io/esTS/es/datasets/spanishliterature/)** - literatura en español de dominio público: 150 obras de 33 autores de España, Hispanoamérica y Filipinas en prosa, poesía, teatro y ensayo, con el género, los años y el país; un diccionario de frecuencias de 83 785 lemas según Google Books Ngram con ipm, rango y dispersión
 * **[Componentes de spaCy](https://sergeyshk.github.io/esTS/es/components/)** - cada clase de estadísticas como componente de un pipeline, con las estadísticas puestas en el `Doc` en una sola pasada
 * **[Estadísticas de cohesión](https://sergeyshk.github.io/esTS/es/stats/cohesion_stats/)** - la repetición de sustantivos, argumentos y palabras con contenido entre oraciones, la información dada y la cohesión temporal a la manera de Coh-Metrix, con la densidad de 255 marcadores del discurso españoles
+* **[Estadísticas de complejidad léxica](https://sergeyshk.github.io/esTS/es/stats/lexical_stats/)** - cuán raras son las palabras de un texto en la lengua: la frecuencia, el rango y la dispersión de los lemas según un diccionario de Google Books Ngram, las bandas de frecuencia del top-1000 al 10000, la sorpresa, la perplejidad y la densidad léxica
 * **[Estadísticas sintácticas](https://sergeyshk.github.io/esTS/es/stats/syntax_stats/)** - el árbol de dependencias por distancias, profundidad, cláusulas y coordinación, con las construcciones del estilo administrativo: la pasiva con `ser` y con `se`, las cláusulas de participio y de gerundio, las cadenas de `de`, los predicados escindidos
 
-Las medidas de corpus y la estilometría llegan en la 0.3, el estilo, la fonoestadística, la métrica y la rima en la 0.4.
+El estilo, la fonoestadística, la métrica y la rima llegan en la 0.4.
 
 ## Instalación
 
@@ -58,12 +63,14 @@ O con [uv](https://docs.astral.sh/uv/):
 uv add pyests
 ```
 
-El distribuible en PyPI se llama `pyests` y el paquete que instala es `ests`. Las estadísticas básicas, la legibilidad y la diversidad léxica no necesitan ningún modelo de spaCy; las estadísticas morfológicas, las sintácticas y las de cohesión sí, igual que analizar un texto por su cuenta para pasar el `Doc` en lugar de una cadena:
+El distribuible en PyPI se llama `pyests` y el paquete que instala es `ests`. Las estadísticas básicas, la legibilidad y la diversidad léxica no necesitan ningún modelo de spaCy; las estadísticas morfológicas, las sintácticas, las de cohesión y las de complejidad léxica de una cadena sí, igual que el perfil de las palabras funcionales, los rasgos de un texto y la comparación de corpus, y analizar un texto por su cuenta para pasar el `Doc` en lugar de una cadena:
 
 ```bash
 python -m spacy download es_core_news_sm
 ```
 
+Las estadísticas según el diccionario de frecuencias lo necesitan descargado una vez con `FreqDict().download()`. Los conjuntos de datos van al directorio `ests_data` junto al paquete instalado; otro se pasa en `data_dir` o se define en la variable de entorno `ESTS_DATA_DIR` antes de importar el paquete.
+
 ## Primeros pasos
 
 ```python
@@ -410,6 +417,27 @@ Más en la [documentación](https://sergeyshk.github.io/esTS/es/stats/cohesion_s
 
 </details>
 
+<details>
+<summary><b>Estadísticas de complejidad léxica</b></summary>
+
+<br>
+
+Cuán raras son las palabras de un texto en la lengua, a la manera de TAALES: la frecuencia media, el rango y la dispersión de los lemas según el diccionario de frecuencias de Google Books Ngram, las proporciones de palabras de las bandas de frecuencia top-1000, 2000, 5000 y 10000, la sorpresa y la perplejidad según el modelo de unigramas del diccionario, la densidad léxica. Las bandas y la densidad funcionan sin más; las estadísticas según el diccionario lo necesitan descargado una vez.
+
+```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)
+```
+
+Más en la [documentación](https://sergeyshk.github.io/esTS/es/stats/lexical_stats/).
+
+</details>
+
 <details>
 <summary><b>Componentes de spaCy</b></summary>
 
@@ -433,12 +461,140 @@ Cada clase de estadísticas es también un componente de un pipeline, de modo qu
 (12, ('DET', 'NOUN'), 2.0)
 ```
 
-Las fábricas son `ests_basic`, `ests_readability`, `ests_diversity`, `ests_morph`, `ests_syntax` y `ests_cohesion`; el nombre del paso del pipeline es libre y es como se llama la extensión.
+Las fábricas son `ests_basic`, `ests_readability`, `ests_diversity`, `ests_morph`, `ests_syntax`, `ests_cohesion` y `ests_lexical`; el nombre del paso del pipeline es libre y es como se llama la extensión.
 
 Más en la [documentación](https://sergeyshk.github.io/esTS/es/components/).
 
 </details>
 
+<details>
+<summary><b>Medidas de corpus</b></summary>
+
+<br>
+
+La biblioteca compara corpus y describe el uso de una palabra con las medidas de la lingüística de corpus:
+
+*   palabras clave de un corpus objetivo frente a uno de referencia o frente al diccionario de frecuencias de Google Books Ngram: la razón de verosimilitud con su valor p, Log Ratio, ji cuadrado, %DIFF, BIC, ELL y la razón de momios
+*   colocaciones por logDice, MI, MI³, t-score, Dice, razón de verosimilitud, NPMI y sensibilidad mínima, contrastadas con NLTK
+*   la dispersión de una palabra por las partes de un texto: la DP de Gries, la DP normalizada, la D de Juilland, la D2 de Carroll, la S de Rosengren y la divergencia de Kullback-Leibler
+*   una concordancia KWIC por forma o por lema
+*   estilometría: las distancias entre textos por la Delta de Burrows y sus variantes, con la atribución de un texto a autores de referencia, los marcadores de palabras preferidas y evitadas por Zeta, el ji cuadrado de Kilgarriff, la curva de Mendenhall y el perfil de las palabras funcionales
+*   la comparación de dos corpus por 132 rasgos de un texto en ventanas de un tamaño parecido: la delta de Cliff, la d de Cohen y el AUC de cada rasgo, la prueba de Mann-Whitney con la corrección de Holm y un intervalo bootstrap de la diferencia de las medianas que remuestrea textos enteros
+
+```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'])
+```
+
+Las palabras se comparan tal cual, así que la caja, los lemas y las palabras vacías se eligen en la extracción.
+
+Más en la [documentación](https://sergeyshk.github.io/esTS/es/corpus/keyness/).
+
+</details>
+
+<details>
+<summary><b>Conjuntos de datos</b></summary>
+
+<br>
+
+*   [spanish_literature](https://sergeyshk.github.io/esTS/es/datasets/spanishliterature/) - literatura en español de dominio público: 150 obras de 33 autores de España, Hispanoamérica y Filipinas, de Cervantes a los años veinte, en prosa, poesía, teatro y ensayo; 65 millones de caracteres
+*   [freq_dict](https://sergeyshk.github.io/esTS/es/datasets/freqdict/) - un diccionario de frecuencias de 83 785 lemas del español a partir de los libros de Google Books Ngram de 1980-2019 (63 000 millones de palabras): ipm, rango y D de Juilland por años, número de libros y categoría gramatical (CC BY 3.0)
+
+Los textos se recortan al texto del autor, sin portadas, notas de los transcriptores y de los editores, índices ni notas al pie, y llevan el género, el autor, el título, los años de la primera publicación y el país; los registros se pueden filtrar por cualquiera de ellos y por la longitud del texto.
+
+```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
+```
+
+El archivo (19 MB) se descarga una vez con `download()` en el directorio de datos y se verifica con su suma de comprobación SHA-256; antes de la descarga `get_texts()` y `get_records()` levantan `DatasetNotFoundError` con una indicación.
+
+Más en la [documentación](https://sergeyshk.github.io/esTS/es/datasets/spanishliterature/).
+
+</details>
+
+<details>
+<summary><b>Visualizaciones</b></summary>
+
+<br>
+
+*   [Ley de Zipf](https://sergeyshk.github.io/esTS/es/visualizers/zipf/) con la curva teórica y el ajuste de Zipf-Mandelbrot
+*   [Huella literaria](https://sergeyshk.github.io/esTS/es/visualizers/fingerprinting/) (Literature Fingerprinting)
+*   [Árbol de palabras](https://sergeyshk.github.io/esTS/es/visualizers/word_tree/) (Word Tree)
+*   [Gráficos de corpus](https://sergeyshk.github.io/esTS/es/visualizers/corpus/): dispersión léxica, un diagrama de palabras clave, una red de colocaciones
+*   [Gráficos estilométricos](https://sergeyshk.github.io/esTS/es/visualizers/stylometry/): un dendrograma, las componentes principales y el escalamiento multidimensional por la Delta, las curvas de Mendenhall
+*   [Crecimiento del vocabulario y espectro de frecuencias](https://sergeyshk.github.io/esTS/es/visualizers/vocabulary/), [longitudes de las oraciones](https://sergeyshk.github.io/esTS/es/visualizers/sentences/) con una media móvil
+
+Los gráficos de matplotlib reciben los ejes `ax` y devuelven `Axes`, así que se pueden disponer en una misma figura; la red de colocaciones y el árbol de palabras son grafos de graphviz, cuyos ejecutables los dibujan. La Delta coseno separa tres novelas de Galdós de tres de 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
+
+# seis novelas de Galdós y de Unamuno del corpus de literatura
+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="Gráficos estilométricos" width="760">
+</p>
+
+Más en la [documentación](https://sergeyshk.github.io/esTS/es/visualizers/zipf/).
+
+</details>
+
 ## Desarrollo
 
 El proyecto usa [uv](https://docs.astral.sh/uv/) para gestionar las dependencias y [ruff](https://docs.astral.sh/ruff/) para el análisis y el formato del código.
@@ -456,7 +612,7 @@ Ejecute `make help` para ver la lista completa de comandos.
 
 La documentación es bilingüe: las páginas en inglés son `docs/*.md` y las españolas `docs/*.es.md` junto a ellas ([mkdocs-static-i18n](https://github.com/ultrabug/mkdocs-static-i18n)); al editar una página, actualice las dos versiones.
 
-La versión instalada está en `ests.__version__`. Todas las excepciones heredan de `ests.EstsError` y de una de las clases integradas (`SourceError` y `ParameterError` de `ValueError`, `SourceTypeError` de `TypeError`, `UnknownStatError` de `KeyError`), así que `except ValueError` sigue funcionando. La biblioteca no imprime nada por su cuenta: sus mensajes van al logger `ests` (`logging.getLogger("ests")`) y están en silencio por defecto.
+La versión instalada está en `ests.__version__`. Todas las excepciones heredan de `ests.EstsError` y de una de las clases integradas (`SourceError`, `ParameterError` y `DataFileError` de `ValueError`, `SourceTypeError` de `TypeError`, `UnknownStatError` de `KeyError`, `DatasetNotFoundError` de `OSError`, `DownloadError` de `RuntimeError`), así que `except ValueError` sigue funcionando. La biblioteca no imprime nada por su cuenta: sus mensajes van al logger `ests` (`logging.getLogger("ests")`) y están en silencio por defecto.
 
 Antes de enviar cambios, instale los hooks que ejecutan los linters al hacer commit y las pruebas al hacer push:
 
@@ -477,7 +633,10 @@ Los informes de errores, las ideas y los pull requests son bienvenidos: las [iss
 *   **ests**:
     *   basic_stats.py - estadísticas básicas del texto
     *   cohesion_stats.py - estadísticas de cohesión
+    *   lexical_stats.py - estadísticas de complejidad léxica
     *   components.py - componentes de un pipeline de spaCy
+    *   corpus - medidas de la lingüística de corpus: palabras clave, colocaciones, dispersión, concordancia, estilometría, comparación de corpus
+    *   datasets - conjuntos de datos: literatura en español, diccionario de frecuencias
     *   constants.py - constantes de la lengua española y de las métricas
     *   diversity_stats.py - métricas de diversidad léxica
     *   exceptions.py - excepciones de la biblioteca
@@ -487,6 +646,8 @@ Los informes de errores, las ideas y los pull requests son bienvenidos: las [iss
     *   syntax_stats.py - estadísticas sintácticas
     *   syllables.py - silabificación y acento
     *   utils.py - herramientas auxiliares
+    *   visualizers - gráficos: ley de Zipf, huella literaria, árbol de palabras, gráficos de corpus y estilométricos, crecimiento del vocabulario, longitudes de las oraciones
+*   **scripts** - scripts que construyen los archivos de los conjuntos de datos
 *   **tests** - pruebas que reproducen la estructura del paquete
 
 </details>
@@ -501,13 +662,14 @@ Los informes de errores, las ideas y los pull requests son bienvenidos: las [iss
 
 ## Cómo citar
 
-Si usa **esTS** en su investigación o en su software, cítelo con la siguiente entrada BibTeX. Las citas ayudan al desarrollo y al mantenimiento continuos de la biblioteca. Los mismos metadatos están en [CITATION.cff](https://github.com/SergeyShk/esTS/blob/master/CITATION.cff): GitHub los muestra bajo el botón «Cite this repository».
+Si usa **esTS** en su investigación o en su software, cítelo con la siguiente entrada BibTeX. Las citas ayudan al desarrollo y al mantenimiento continuos de la biblioteca. Los mismos metadatos están en [CITATION.cff](https://github.com/SergeyShk/esTS/blob/master/CITATION.cff): GitHub los muestra bajo el botón «Cite this repository». El Concept DOI [10.5281/zenodo.22924655](https://doi.org/10.5281/zenodo.22924655) en Zenodo apunta a todas las versiones de la biblioteca; el DOI de una versión concreta está en la página de su publicación.
 
 ```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}
 }
 ```