iapucp-metrix 0.1.0

A comprehensive set of indicators and metrics for assessing text complexity in Spanish.

PUCP-Metrix

A comprehensive set of indicators and metrics for assessing text complexity in Spanish, developed by the Artificial Intelligence Group at PUCP (Pontificia Universidad Católica del Perú).

Overview

PUCP-Metrix is a Python library that provides an extensive collection of text complexity metrics specifically designed for Spanish texts. It implements various linguistic and psycholinguistic measures inspired by Coh-Metrix, adapted and optimized for Spanish language processing.

Features

The library calculates over 100 different text complexity metrics organized into several categories:

📊 Descriptive Indices

Basic text structure and length statistics:

• DESPC: Paragraph count
• DESPCi: Paragraph count incidence per 1000 words
• DESSC: Sentence count
• DESSCi: Sentence count incidence per 1000 words
• DESWC: Word count (alphanumeric words)
• DESWCU: Unique word count
• DESWCUi: Unique word count incidence per 1000 words
• DESPL: Average paragraph length (sentences per paragraph)
• DESPLd: Standard deviation of paragraph length
• DESSL: Average sentence length (words per sentence)
• DESSLd: Standard deviation of sentence length
• DESSNSL: Average sentence length excluding stopwords
• DESSNSLd: Standard deviation of sentence length excluding stopwords
• DESSLmax: Maximum sentence length
• DESSLmin: Minimum sentence length
• DESWLsy: Average syllables per word
• DESWLsyd: Standard deviation of syllables per word
• DESCWLsy: Average syllables per content word
• DESCWLsyd: Standard deviation of syllables per content word
• DESCWLlt: Average letters per content word
• DESCWLltd: Standard deviation of letters per content word
• DESWLlt: Average letters per word
• DESWLltd: Standard deviation of letters per word
• DESWNSLlt: Average letters per word (excluding stopwords)
• DESWNSLltd: Standard deviation of letters per word (excluding stopwords)
• DESLLlt: Average letters per lemma
• DESLLltd: Standard deviation of letters per lemma

📖 Readability Indices

Traditional readability formulas adapted for Spanish:

• RDFHGL: Fernández-Huertas Grade Level
• RDSPP: Szigriszt-Pazos Perspicuity
• RDMU: Readability µ index
• RDSMOG: SMOG index
• RDFOG: Gunning Fog index
• RDHS: Honoré Statistic
• RDBR: Brunet index

🔗 Syntactic Complexity Indices

Measures of syntactic structure complexity:

• SYNNP: Mean number of modifiers per noun phrase
• SYNLE: Mean number of words before main verb
• SYNMEDwrd: Minimal edit distance of words between adjacent sentences
• SYNMEDlem: Minimal edit distance of lemmas between adjacent sentences
• SYNMEDpos: Minimal edit distance of POS tags between adjacent sentences
• SYNCLS1: Ratio of sentences with 1 clause
• SYNCLS2: Ratio of sentences with 2 clauses
• SYNCLS3: Ratio of sentences with 3 clauses
• SYNCLS4: Ratio of sentences with 4 clauses
• SYNCLS5: Ratio of sentences with 5 clauses
• SYNCLS6: Ratio of sentences with 6 clauses
• SYNCLS7: Ratio of sentences with 7 clauses

🎯 Syntactic Pattern Density Indices

Density measures of specific syntactic patterns:

• DRNP: Noun phrase density per 1000 words
• DRNPc: Noun phrase count
• DRVP: Verb phrase density per 1000 words
• DRVPc: Verb phrase count
• DRNEG: Negation expression density per 1000 words
• DRNEGc: Negation expression count
• DRGER: Gerund form density per 1000 words
• DRGERc: Gerund count
• DRINF: Infinitive form density per 1000 words
• DRINFc: Infinitive count
• DRCCONJ: Coordinating conjunction density per 1000 words
• DRCCONJc: Coordinating conjunction count
• DRSCONJ: Subordinating conjunction density per 1000 words
• DRSCONJc: Subordinating conjunction count

🌐 Connective Indices

Analysis of discourse connectives:

• CNCAll: All connectives incidence per 1000 words
• CNCCaus: Causal connectives incidence per 1000 words
• CNCLogic: Logical connectives incidence per 1000 words
• CNCADC: Adversative connectives incidence per 1000 words
• CNCTemp: Temporal connectives incidence per 1000 words
• CNCAdd: Additive connectives incidence per 1000 words

🔗 Referential Cohesion Indices

Measures of referential overlap between sentences:

• CRFNO1: Noun overlap between adjacent sentences
• CRFAO1: Argument overlap between adjacent sentences
• CRFSO1: Stem overlap between adjacent sentences
• CRFCWO1: Content word overlap between adjacent sentences (mean)
• CRFCWO1d: Content word overlap between adjacent sentences (std dev)
• CRFANP1: Anaphore overlap between adjacent sentences
• CRFNOa: Noun overlap between all sentences
• CRFAOa: Argument overlap between all sentences
• CRFSOa: Stem overlap between all sentences
• CRFCWOa: Content word overlap between all sentences (mean)
• CRFCWOad: Content word overlap between all sentences (std dev)
• CRFANPa: Anaphore overlap between all sentences

🌊 Semantic Cohesion Indices

LSA-based semantic similarity measures:

• SECLOSadj: LSA overlap between adjacent sentences (mean)
• SECLOSadjd: LSA overlap between adjacent sentences (std dev)
• SECLOSall: LSA overlap between all sentences (mean)
• SECLOSalld: LSA overlap between all sentences (std dev)
• SECLOPadj: LSA overlap between adjacent paragraphs (mean)
• SECLOPadjd: LSA overlap between adjacent paragraphs (std dev)
• SECLOSgiv: LSA overlap between given and new sentences (mean)
• SECLOSgivd: LSA overlap between given and new sentences (std dev)

📝 Lexical Diversity Indices

Various measures of vocabulary richness:

• LDTTRa: Type-token ratio for all words
• LDTTRcw: Type-token ratio for content words
• LDTTRno: Type-token ratio for nouns
• LDTTRvb: Type-token ratio for verbs
• LDTTRadv: Type-token ratio for adverbs
• LDTTRadj: Type-token ratio for adjectives
• LDTTRLa: Type-token ratio for all lemmas
• LDTTRLno: Type-token ratio for noun lemmas
• LDTTRLvb: Type-token ratio for verb lemmas
• LDTTRLadv: Type-token ratio for adverb lemmas
• LDTTRLadj: Type-token ratio for adjective lemmas
• LDTTRLpron: Type-token ratio for pronouns
• LDTTRLrpron: Type-token ratio for relative pronouns
• LDTTRLipron: Type-token ratio for indefinite pronouns
• LDTTRLifn: Type-token ratio for functional words
• LDMLTD: Measure of Textual Lexical Diversity (MTLD)
• LDVOCd: Vocabulary Complexity Diversity (VoCD)
• LDMaas: Maas index
• LDDno: Noun density
• LDDvb: Verb density
• LDDadv: Adverb density
• LDDadj: Adjective density

📊 Word Information Indices

Incidence of different word types:

• WRDCONT: Content word incidence per 1000 words
• WRDCONTc: Content word count
• WRDNOUN: Noun incidence per 1000 words
• WRDNOUNc: Noun count
• WRDVERB: Verb incidence per 1000 words
• WRDVERBc: Verb count
• WRDADJ: Adjective incidence per 1000 words
• WRDADJc: Adjective count
• WRDADV: Adverb incidence per 1000 words
• WRDADVc: Adverb count
• WRDPRO: Personal pronoun incidence per 1000 words
• WRDPROc: Personal pronoun count
• WRDPRP1s: First person singular pronoun incidence per 1000 words
• WRDPRP1sc: First person singular pronoun count
• WRDPRP1p: First person plural pronoun incidence per 1000 words
• WRDPRP1pc: First person plural pronoun count
• WRDPRP2s: Second person singular pronoun incidence per 1000 words
• WRDPRP2sc: Second person singular pronoun count
• WRDPRP2p: Second person plural pronoun incidence per 1000 words
• WRDPRP2pc: Second person plural pronoun count
• WRDPRP3s: Third person singular pronoun incidence per 1000 words
• WRDPRP3sc: Third person singular pronoun count
• WRDPRP3p: Third person plural pronoun incidence per 1000 words
• WRDPRP3pc: Third person plural pronoun count

🎯 Textual Simplicity Indices

Measures of sentence length distribution:

• TSSRsh: Ratio of short sentences (< 11 words)
• TSSRmd: Ratio of medium sentences (11-12 words)
• TSSRlg: Ratio of long sentences (13-14 words)
• TSSRxl: Ratio of very long sentences (≥ 15 words)

📈 Word Frequency Indices

Measures based on word frequency in Spanish corpora:

• WFRCno: Rare noun count
• WFRCnoi: Rare noun incidence per 1000 words
• WFRCvb: Rare verb count
• WFRCvbi: Rare verb incidence per 1000 words
• WFRCadj: Rare adjective count
• WFRCadji: Rare adjective incidence per 1000 words
• WFRCadv: Rare adverb count
• WFRCadvi: Rare adverb incidence per 1000 words
• WFRCcw: Rare content word count
• WFRCcwi: Rare content word incidence per 1000 words
• WFRCcwd: Distinct rare content word count
• WFRCcwdi: Distinct rare content word incidence per 1000 words
• WFMcw: Mean frequency of content words
• WFMw: Mean frequency of all words
• WFMrw: Mean frequency of rarest words per sentence
• WFMrcw: Mean frequency of rarest content words per sentence

🧠 Psycholinguistic Indices

Measures based on psycholinguistic properties of words:

Concreteness measures:

• PSYC: Overall concreteness ratio
• PSYC0: Very low concreteness ratio (1-2.5)
• PSYC1: Low concreteness ratio (2.5-4)
• PSYC2: Medium concreteness ratio (4-5.5)
• PSYC3: High concreteness ratio (5.5-7)

Imageability measures:

• PSYIM: Overall imageability ratio
• PSYIM0: Very low imageability ratio (1-2.5)
• PSYIM1: Low imageability ratio (2.5-4)
• PSYIM2: Medium imageability ratio (4-5.5)
• PSYIM3: High imageability ratio (5.5-7)

Familiarity measures:

• PSYFM: Overall familiarity ratio
• PSYFM0: Very low familiarity ratio (1-2.5)
• PSYFM1: Low familiarity ratio (2.5-4)
• PSYFM2: Medium familiarity ratio (4-5.5)
• PSYFM3: High familiarity ratio (5.5-7)

Age of Acquisition measures:

• PSYAoA: Overall age of acquisition ratio
• PSYAoA0: Very early acquisition ratio (1-2.5)
• PSYAoA1: Early acquisition ratio (2.5-4)
• PSYAoA2: Medium acquisition ratio (4-5.5)
• PSYAoA3: Late acquisition ratio (5.5-7)

Arousal measures:

• PSYARO: Overall arousal ratio
• PSYARO0: Very low arousal ratio (1-3)
• PSYARO1: Low arousal ratio (3-5)
• PSYARO2: Medium arousal ratio (5-7)
• PSYARO3: High arousal ratio (7-9)

Valence measures:

• PSYVAL: Overall valence ratio
• PSYVAL0: Very negative valence ratio (1-4)
• PSYVAL1: Negative valence ratio (3-5)
• PSYVAL2: Positive valence ratio (5-7)
• PSYVAL3: Very positive valence ratio (7-9)

Installation

Prerequisites

• Python 3.12 or higher

Install the package

# Using UV (recommended)
uv add iapucp-metrix

# Or using pip
pip install iapucp-metrix

Install Spanish language model

After installing the package, you need to install the required Spanish spaCy model:

# Using the provided script
./install_es_core_news

# Or manually
uv pip install es_core_news_lg@https://github.com/explosion/spacy-models/releases/download/es_core_news_lg-3.8.0/es_core_news_lg-3.8.0-py3-none-any.whl

Quick Start

from iapucp_metrix.analyzer import Analyzer

# Initialize analyzer
analyzer = Analyzer()

# Process multiple texts efficiently
texts = [
    "Primer texto para analizar...",
    "Segundo texto con contenido diferente...",
    "Tercer texto para completar el análisis..."
]

# Compute metrics with multiprocessing
metrics_list = analyzer.compute_metrics(
    texts, 
    workers=4,     # Use 4 CPU cores
    batch_size=2   # Process 2 texts per batch
)

# Process results
for i, metrics in enumerate(metrics_list):
    print(f"Text {i+1}:")
    print(f"  Readability (Fernández-Huertas): {metrics['RDFHGL']:.2f}")

Development

Setting up the development environment

# Clone the repository
git clone https://github.com/your-org/pucp-metrix.git
cd pucp-metrix

# Install dependencies
uv sync

# Install the Spanish model
./install_es_core_news

# Run tests
uv run pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.