pystylometry 0.1.0__py3-none-any.whl

pystylometry/readability/ari.py

@@ -0,0 +1,70 @@
+"""Automated Readability Index (ARI)."""
+
+from .._types import ARIResult
+from .._utils import split_sentences, tokenize
+
+
+def compute_ari(text: str) -> ARIResult:
+    """
+    Compute Automated Readability Index (ARI).
+
+    Formula:
+        ARI = 4.71 × (characters/words) + 0.5 × (words/sentences) - 21.43
+
+    The ARI is designed to gauge the understandability of a text and produces
+    an approximate representation of the US grade level needed to comprehend the text.
+
+    Grade Level to Age mapping:
+        1-5:   5-11 years
+        6-8:   11-14 years
+        9-12:  14-18 years
+        13-14: 18-22 years
+        14+:   22+ years (college level)
+
+    References:
+        Senter, R. J., & Smith, E. A. (1967). Automated readability index.
+        AMRL-TR-6620. Aerospace Medical Research Laboratories.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        ARIResult with ARI score, grade level, and age range
+
+    Example:
+        >>> result = compute_ari("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"ARI Score: {result.ari_score:.1f}")
+        >>> print(f"Grade Level: {result.grade_level}")
+        >>> print(f"Age Range: {result.age_range}")
+    """
+    sentences = split_sentences(text)
+    tokens = tokenize(text)
+
+    if len(sentences) == 0 or len(tokens) == 0:
+        return ARIResult(
+            ari_score=0.0,
+            grade_level=0,
+            age_range="Unknown",
+            metadata={"sentence_count": 0, "word_count": 0, "character_count": 0},
+        )
+
+    # Count characters (letters, numbers, excluding spaces and punctuation)
+    character_count = sum(1 for char in text if char.isalnum())
+
+    # TODO: Implement ARI formula
+    ari_score = 0.0  # Placeholder
+    grade_level = 0  # Placeholder
+    age_range = "Unknown"  # Placeholder
+
+    return ARIResult(
+        ari_score=ari_score,
+        grade_level=grade_level,
+        age_range=age_range,
+        metadata={
+            "sentence_count": len(sentences),
+            "word_count": len(tokens),
+            "character_count": character_count,
+            "characters_per_word": character_count / len(tokens) if tokens else 0,
+            "words_per_sentence": len(tokens) / len(sentences) if sentences else 0,
+        },
+    )

pystylometry/readability/coleman_liau.py

@@ -0,0 +1,67 @@
+"""Coleman-Liau Index."""
+
+from .._types import ColemanLiauResult
+from .._utils import split_sentences, tokenize
+
+
+def compute_coleman_liau(text: str) -> ColemanLiauResult:
+    """
+    Compute Coleman-Liau Index.
+
+    Formula:
+        CLI = 0.0588 × L - 0.296 × S - 15.8
+
+    Where:
+        L = average number of letters per 100 words
+        S = average number of sentences per 100 words
+
+    The Coleman-Liau index relies on characters rather than syllables,
+    making it easier to compute and potentially more language-agnostic.
+
+    References:
+        Coleman, M., & Liau, T. L. (1975). A computer readability formula
+        designed for machine scoring. Journal of Applied Psychology, 60(2), 283.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        ColemanLiauResult with CLI index and grade level
+
+    Example:
+        >>> result = compute_coleman_liau("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"CLI Index: {result.cli_index:.1f}")
+        >>> print(f"Grade Level: {result.grade_level}")
+    """
+    sentences = split_sentences(text)
+    tokens = tokenize(text)
+
+    if len(sentences) == 0 or len(tokens) == 0:
+        return ColemanLiauResult(
+            cli_index=0.0,
+            grade_level=0,
+            metadata={"sentence_count": 0, "word_count": 0, "letter_count": 0},
+        )
+
+    # Count letters (excluding spaces and punctuation)
+    letter_count = sum(1 for char in text if char.isalpha())
+
+    # Calculate per 100 words
+    L = (letter_count / len(tokens)) * 100  # noqa: N806
+    S = (len(sentences) / len(tokens)) * 100  # noqa: N806
+
+    # TODO: Implement Coleman-Liau formula
+    cli_index = 0.0  # Placeholder
+    grade_level = 0  # Placeholder
+
+    return ColemanLiauResult(
+        cli_index=cli_index,
+        grade_level=grade_level,
+        metadata={
+            "sentence_count": len(sentences),
+            "word_count": len(tokens),
+            "letter_count": letter_count,
+            "letters_per_100_words": L,
+            "sentences_per_100_words": S,
+        },
+    )

pystylometry/readability/flesch.py

@@ -0,0 +1,81 @@
+"""Flesch Reading Ease and Flesch-Kincaid Grade Level."""
+
+from .._types import FleschResult
+from .._utils import split_sentences, tokenize
+from .syllables import count_syllables
+
+
+def compute_flesch(text: str) -> FleschResult:
+    """
+    Compute Flesch Reading Ease and Flesch-Kincaid Grade Level.
+
+    Flesch Reading Ease:
+        Score = 206.835 - 1.015 × (words/sentences) - 84.6 × (syllables/words)
+        Higher scores = easier to read (0-100 scale)
+
+    Flesch-Kincaid Grade Level:
+        Grade = 0.39 × (words/sentences) + 11.8 × (syllables/words) - 15.59
+
+    Interpretation of Reading Ease:
+        90-100: Very Easy (5th grade)
+        80-89:  Easy (6th grade)
+        70-79:  Fairly Easy (7th grade)
+        60-69:  Standard (8th-9th grade)
+        50-59:  Fairly Difficult (10th-12th grade)
+        30-49:  Difficult (College)
+        0-29:   Very Difficult (College graduate)
+
+    References:
+        Flesch, R. (1948). A new readability yardstick.
+        Journal of Applied Psychology, 32(3), 221.
+
+        Kincaid, J. P., et al. (1975). Derivation of new readability formulas
+        for Navy enlisted personnel. Naval Technical Training Command.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        FleschResult with reading ease, grade level, and difficulty rating
+
+    Example:
+        >>> result = compute_flesch("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"Reading Ease: {result.reading_ease:.1f}")
+        >>> print(f"Grade Level: {result.grade_level:.1f}")
+        >>> print(f"Difficulty: {result.difficulty}")
+    """
+    sentences = split_sentences(text)
+    tokens = tokenize(text)
+
+    if len(sentences) == 0 or len(tokens) == 0:
+        return FleschResult(
+            reading_ease=0.0,
+            grade_level=0.0,
+            difficulty="Unknown",
+            metadata={"sentence_count": 0, "word_count": 0, "syllable_count": 0},
+        )
+
+    # Count syllables
+    total_syllables = sum(count_syllables(word) for word in tokens)
+
+    # Calculate metrics
+    words_per_sentence = len(tokens) / len(sentences)
+    syllables_per_word = total_syllables / len(tokens)
+
+    # TODO: Implement Flesch formulas
+    reading_ease = 0.0  # Placeholder
+    grade_level = 0.0  # Placeholder
+    difficulty = "Unknown"  # Placeholder
+
+    return FleschResult(
+        reading_ease=reading_ease,
+        grade_level=grade_level,
+        difficulty=difficulty,
+        metadata={
+            "sentence_count": len(sentences),
+            "word_count": len(tokens),
+            "syllable_count": total_syllables,
+            "words_per_sentence": words_per_sentence,
+            "syllables_per_word": syllables_per_word,
+        },
+    )

pystylometry/readability/gunning_fog.py

@@ -0,0 +1,63 @@
+"""Gunning Fog Index."""
+
+from .._types import GunningFogResult
+from .._utils import split_sentences, tokenize
+from .syllables import count_syllables
+
+
+def compute_gunning_fog(text: str) -> GunningFogResult:
+    """
+    Compute Gunning Fog Index.
+
+    Formula:
+        Fog Index = 0.4 × [(words/sentences) + 100 × (complex words/words)]
+
+    Where complex words are defined as words with 3+ syllables,
+    excluding proper nouns, compound words, and common suffixes.
+
+    The index estimates years of formal education needed to understand the text
+    on first reading.
+
+    References:
+        Gunning, R. (1952). The Technique of Clear Writing.
+        McGraw-Hill.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        GunningFogResult with fog index and grade level
+
+    Example:
+        >>> result = compute_gunning_fog("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"Fog Index: {result.fog_index:.1f}")
+        >>> print(f"Grade Level: {result.grade_level}")
+    """
+    sentences = split_sentences(text)
+    tokens = tokenize(text)
+
+    if len(sentences) == 0 or len(tokens) == 0:
+        return GunningFogResult(
+            fog_index=0.0,
+            grade_level=0,
+            metadata={"sentence_count": 0, "word_count": 0, "complex_word_count": 0},
+        )
+
+    # Count complex words (3+ syllables)
+    # TODO: Exclude proper nouns, compound words, and -es/-ed/-ing endings
+    complex_word_count = sum(1 for word in tokens if count_syllables(word) >= 3)
+
+    # TODO: Implement Gunning Fog formula
+    fog_index = 0.0  # Placeholder
+    grade_level = 0  # Placeholder
+
+    return GunningFogResult(
+        fog_index=fog_index,
+        grade_level=grade_level,
+        metadata={
+            "sentence_count": len(sentences),
+            "word_count": len(tokens),
+            "complex_word_count": complex_word_count,
+            "complex_word_percentage": (complex_word_count / len(tokens) * 100) if tokens else 0,
+        },
+    )

pystylometry/readability/smog.py

@@ -0,0 +1,71 @@
+"""SMOG (Simple Measure of Gobbledygook) Index."""
+
+from .._types import SMOGResult
+from .._utils import split_sentences, tokenize
+from .syllables import count_syllables
+
+
+def compute_smog(text: str) -> SMOGResult:
+    """
+    Compute SMOG (Simple Measure of Gobbledygook) Index.
+
+    Formula:
+        SMOG = 1.043 × √(polysyllables × 30/sentences) + 3.1291
+
+    Where polysyllables are words with 3 or more syllables.
+
+    The SMOG index estimates the years of education needed to understand the text.
+    It's particularly useful for healthcare materials.
+
+    References:
+        McLaughlin, G. H. (1969). SMOG grading: A new readability formula.
+        Journal of Reading, 12(8), 639-646.
+
+    Args:
+        text: Input text to analyze
+
+    Returns:
+        SMOGResult with SMOG index and grade level
+
+    Example:
+        >>> result = compute_smog("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"SMOG Index: {result.smog_index:.1f}")
+        >>> print(f"Grade Level: {result.grade_level}")
+    """
+    sentences = split_sentences(text)
+    tokens = tokenize(text)
+
+    if len(sentences) < 30:
+        # SMOG requires at least 30 sentences for accuracy
+        # We'll compute anyway but note in metadata
+        pass
+
+    if len(sentences) == 0 or len(tokens) == 0:
+        return SMOGResult(
+            smog_index=0.0,
+            grade_level=0,
+            metadata={
+                "sentence_count": 0,
+                "word_count": 0,
+                "polysyllable_count": 0,
+                "warning": "Insufficient text",
+            },
+        )
+
+    # Count polysyllables (words with 3+ syllables)
+    polysyllable_count = sum(1 for word in tokens if count_syllables(word) >= 3)
+
+    # TODO: Implement SMOG formula
+    smog_index = 0.0  # Placeholder
+    grade_level = 0  # Placeholder
+
+    return SMOGResult(
+        smog_index=smog_index,
+        grade_level=grade_level,
+        metadata={
+            "sentence_count": len(sentences),
+            "word_count": len(tokens),
+            "polysyllable_count": polysyllable_count,
+            "warning": "Less than 30 sentences" if len(sentences) < 30 else None,
+        },
+    )

pystylometry/readability/syllables.py

@@ -0,0 +1,54 @@
+"""Syllable counting utilities using CMU Pronouncing Dictionary."""
+
+
+def count_syllables(word: str) -> int:
+    """
+    Count syllables in a word using CMU Pronouncing Dictionary with heuristic fallback.
+
+    Args:
+        word: The word to count syllables for
+
+    Returns:
+        Number of syllables in the word
+    """
+    # TODO: Implement with pronouncing library
+    # For now, use simple heuristic fallback
+    return _heuristic_syllable_count(word)
+
+
+def _heuristic_syllable_count(word: str) -> int:
+    """
+    Simple heuristic syllable counter for fallback.
+
+    This is a basic implementation that counts vowel groups.
+    Should be replaced with CMU dict lookup when pronouncing is available.
+
+    Args:
+        word: The word to count syllables for
+
+    Returns:
+        Estimated number of syllables
+    """
+    word = word.lower().strip()
+    if len(word) == 0:
+        return 0
+
+    vowels = "aeiouy"
+    syllable_count = 0
+    previous_was_vowel = False
+
+    for char in word:
+        is_vowel = char in vowels
+        if is_vowel and not previous_was_vowel:
+            syllable_count += 1
+        previous_was_vowel = is_vowel
+
+    # Adjust for silent 'e'
+    if word.endswith("e") and syllable_count > 1:
+        syllable_count -= 1
+
+    # Ensure at least one syllable
+    if syllable_count == 0:
+        syllable_count = 1
+
+    return syllable_count

pystylometry/syntactic/__init__.py

@@ -0,0 +1,9 @@
+"""Syntactic analysis metrics (requires spaCy)."""
+
+from .pos_ratios import compute_pos_ratios
+from .sentence_stats import compute_sentence_stats
+
+__all__ = [
+    "compute_pos_ratios",
+    "compute_sentence_stats",
+]

pystylometry/syntactic/pos_ratios.py

@@ -0,0 +1,61 @@
+"""Part-of-Speech ratio analysis using spaCy."""
+
+from .._types import POSResult
+from .._utils import check_optional_dependency
+
+
+def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
+    """
+    Compute Part-of-Speech ratios and lexical density using spaCy.
+
+    Metrics computed:
+    - Noun ratio: nouns / total words
+    - Verb ratio: verbs / total words
+    - Adjective ratio: adjectives / total words
+    - Adverb ratio: adverbs / total words
+    - Noun-verb ratio: nouns / verbs
+    - Adjective-noun ratio: adjectives / nouns
+    - Lexical density: (nouns + verbs + adjectives + adverbs) / total words
+    - Function word ratio: (determiners + prepositions + conjunctions) / total words
+
+    References:
+        Biber, D. (1988). Variation across speech and writing.
+        Cambridge University Press.
+
+    Args:
+        text: Input text to analyze
+        model: spaCy model name (default: "en_core_web_sm")
+
+    Returns:
+        POSResult with all POS ratios and metadata
+
+    Raises:
+        ImportError: If spaCy is not installed
+
+    Example:
+        >>> result = compute_pos_ratios("The quick brown fox jumps over the lazy dog.")
+        >>> print(f"Noun ratio: {result.noun_ratio:.3f}")
+        >>> print(f"Verb ratio: {result.verb_ratio:.3f}")
+        >>> print(f"Lexical density: {result.lexical_density:.3f}")
+    """
+    check_optional_dependency("spacy", "syntactic")
+
+    # TODO: Implement spaCy-based POS analysis
+    # import spacy
+    # nlp = spacy.load(model)
+    # doc = nlp(text)
+
+    return POSResult(
+        noun_ratio=0.0,
+        verb_ratio=0.0,
+        adjective_ratio=0.0,
+        adverb_ratio=0.0,
+        noun_verb_ratio=0.0,
+        adjective_noun_ratio=0.0,
+        lexical_density=0.0,
+        function_word_ratio=0.0,
+        metadata={
+            "model": model,
+            "token_count": 0,
+        },
+    )

pystylometry/syntactic/sentence_stats.py

@@ -0,0 +1,60 @@
+"""Sentence-level statistics using spaCy."""
+
+from .._types import SentenceStatsResult
+from .._utils import check_optional_dependency, split_sentences
+
+
+def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> SentenceStatsResult:
+    """
+    Compute sentence-level statistics using spaCy.
+
+    Metrics computed:
+    - Mean sentence length (in words)
+    - Standard deviation of sentence lengths
+    - Range of sentence lengths (max - min)
+    - Minimum sentence length
+    - Maximum sentence length
+    - Total sentence count
+
+    References:
+        Hunt, K. W. (1965). Grammatical structures written at three grade levels.
+        NCTE Research Report No. 3.
+
+    Args:
+        text: Input text to analyze
+        model: spaCy model name (default: "en_core_web_sm")
+
+    Returns:
+        SentenceStatsResult with sentence statistics and metadata
+
+    Raises:
+        ImportError: If spaCy is not installed
+
+    Example:
+        >>> result = compute_sentence_stats("The quick brown fox. It jumps over the lazy dog.")
+        >>> print(f"Mean length: {result.mean_sentence_length:.1f} words")
+        >>> print(f"Std dev: {result.sentence_length_std:.1f}")
+        >>> print(f"Sentence count: {result.sentence_count}")
+    """
+    check_optional_dependency("spacy", "syntactic")
+
+    # TODO: Implement spaCy-based sentence analysis
+    # import spacy
+    # nlp = spacy.load(model)
+    # doc = nlp(text)
+    # sentences = list(doc.sents)
+
+    # For now, use simple fallback
+    sentences = split_sentences(text)
+
+    return SentenceStatsResult(
+        mean_sentence_length=0.0,
+        sentence_length_std=0.0,
+        sentence_length_range=0,
+        min_sentence_length=0,
+        max_sentence_length=0,
+        sentence_count=len(sentences),
+        metadata={
+            "model": model,
+        },
+    )