pystylometry 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

pystylometry/syntactic/advanced_syntactic.py

@@ -28,13 +28,21 @@ References:
         of linguistic complexity. In Image, language, brain (pp. 95-126).
 """
 
-from .._types import AdvancedSyntacticResult
+from typing import Any
+
+from .._types import AdvancedSyntacticResult, Distribution, make_distribution
 from .._utils import check_optional_dependency
 
+# Type aliases for spaCy objects (loaded dynamically)
+_SpaCyToken = Any
+_SpaCyDoc = Any
+_SpaCySpan = Any
+
 
 def compute_advanced_syntactic(
     text: str,
     model: str = "en_core_web_sm",
+    chunk_size: int = 1000,
 ) -> AdvancedSyntacticResult:
     """
     Compute advanced syntactic complexity metrics using dependency parsing.
@@ -147,7 +155,6 @@ def compute_advanced_syntactic(
 
     try:
         import spacy  # type: ignore
-        from spacy.tokens import Doc, Span, Token  # type: ignore
     except ImportError as e:
         raise ImportError(
             "spaCy is required for advanced syntactic analysis. "
@@ -159,8 +166,7 @@ def compute_advanced_syntactic(
         nlp = spacy.load(model)
     except OSError as e:
         raise OSError(
-            f"spaCy model '{model}' not found. "
-            f"Download with: python -m spacy download {model}"
+            f"spaCy model '{model}' not found. Download with: python -m spacy download {model}"
         ) from e
 
     # Parse text
@@ -169,6 +175,14 @@ def compute_advanced_syntactic(
 
     # Handle empty text
     if len(sentences) == 0 or len(doc) == 0:
+        empty_dist = Distribution(
+            values=[],
+            mean=float("nan"),
+            median=float("nan"),
+            std=0.0,
+            range=0.0,
+            iqr=0.0,
+        )
         return AdvancedSyntacticResult(
             mean_parse_tree_depth=float("nan"),
             max_parse_tree_depth=0,
@@ -183,6 +197,20 @@ def compute_advanced_syntactic(
             dependency_distance=float("nan"),
             left_branching_ratio=float("nan"),
             right_branching_ratio=float("nan"),
+            mean_parse_tree_depth_dist=empty_dist,
+            max_parse_tree_depth_dist=empty_dist,
+            mean_t_unit_length_dist=empty_dist,
+            clausal_density_dist=empty_dist,
+            dependent_clause_ratio_dist=empty_dist,
+            passive_voice_ratio_dist=empty_dist,
+            subordination_index_dist=empty_dist,
+            coordination_index_dist=empty_dist,
+            sentence_complexity_score_dist=empty_dist,
+            dependency_distance_dist=empty_dist,
+            left_branching_ratio_dist=empty_dist,
+            right_branching_ratio_dist=empty_dist,
+            chunk_size=chunk_size,
+            chunk_count=0,
             metadata={
                 "sentence_count": 0,
                 "word_count": 0,
@@ -229,9 +257,7 @@ def compute_advanced_syntactic(
     coordinate_clause_count = 0
 
     for sent in sentences:
-        sent_total, sent_dependent, sent_subordinate, sent_coordinate = _count_clauses(
-            sent
-        )
+        sent_total, sent_dependent, sent_subordinate, sent_coordinate = _count_clauses(sent)
         total_clauses += sent_total
         dependent_clause_count += sent_dependent
         subordinate_clause_count += sent_subordinate
@@ -279,14 +305,22 @@ def compute_advanced_syntactic(
     # Normalize individual metrics to 0-1 range
     normalized_parse_depth = min(mean_parse_tree_depth / 10, 1.0)
     normalized_clausal_density = (
-        min(clausal_density / 3, 1.0) if not isinstance(clausal_density, float) or not (clausal_density != clausal_density) else 0.0
+        min(clausal_density / 3, 1.0)
+        if not isinstance(clausal_density, float) or not (clausal_density != clausal_density)
+        else 0.0
     )
     normalized_t_unit_length = (
-        min(mean_t_unit_length / 25, 1.0) if not isinstance(mean_t_unit_length, float) or not (mean_t_unit_length != mean_t_unit_length) else 0.0
+        min(mean_t_unit_length / 25, 1.0)
+        if not isinstance(mean_t_unit_length, float)
+        or not (mean_t_unit_length != mean_t_unit_length)
+        else 0.0
     )
     normalized_dependency_distance = min(mean_dependency_distance / 5, 1.0)
     normalized_subordination = (
-        subordination_index if not isinstance(subordination_index, float) or not (subordination_index != subordination_index) else 0.0
+        subordination_index
+        if not isinstance(subordination_index, float)
+        or not (subordination_index != subordination_index)
+        else 0.0
     )
 
     # Weighted combination
@@ -298,6 +332,20 @@ def compute_advanced_syntactic(
         + 0.1 * normalized_dependency_distance
     )
 
+    # Create single-value distributions (analysis is done on full text)
+    mean_parse_tree_depth_dist = make_distribution([mean_parse_tree_depth])
+    max_parse_tree_depth_dist = make_distribution([float(max_parse_tree_depth)])
+    mean_t_unit_length_dist = make_distribution([mean_t_unit_length])
+    clausal_density_dist = make_distribution([clausal_density])
+    dependent_clause_ratio_dist = make_distribution([dependent_clause_ratio])
+    passive_voice_ratio_dist = make_distribution([passive_voice_ratio])
+    subordination_index_dist = make_distribution([subordination_index])
+    coordination_index_dist = make_distribution([coordination_index])
+    sentence_complexity_score_dist = make_distribution([sentence_complexity_score])
+    dependency_distance_dist = make_distribution([mean_dependency_distance])
+    left_branching_ratio_dist = make_distribution([left_branching_ratio])
+    right_branching_ratio_dist = make_distribution([right_branching_ratio])
+
     # Collect metadata
     metadata = {
         "sentence_count": len(sentences),
@@ -331,11 +379,25 @@ def compute_advanced_syntactic(
         dependency_distance=mean_dependency_distance,
         left_branching_ratio=left_branching_ratio,
         right_branching_ratio=right_branching_ratio,
+        mean_parse_tree_depth_dist=mean_parse_tree_depth_dist,
+        max_parse_tree_depth_dist=max_parse_tree_depth_dist,
+        mean_t_unit_length_dist=mean_t_unit_length_dist,
+        clausal_density_dist=clausal_density_dist,
+        dependent_clause_ratio_dist=dependent_clause_ratio_dist,
+        passive_voice_ratio_dist=passive_voice_ratio_dist,
+        subordination_index_dist=subordination_index_dist,
+        coordination_index_dist=coordination_index_dist,
+        sentence_complexity_score_dist=sentence_complexity_score_dist,
+        dependency_distance_dist=dependency_distance_dist,
+        left_branching_ratio_dist=left_branching_ratio_dist,
+        right_branching_ratio_dist=right_branching_ratio_dist,
+        chunk_size=chunk_size,
+        chunk_count=1,  # Single pass analysis
         metadata=metadata,
     )
 
 
-def _calculate_max_tree_depth(token) -> int:
+def _calculate_max_tree_depth(token: _SpaCyToken) -> int:
     """
     Calculate maximum depth of dependency tree starting from token.
 
@@ -352,7 +414,7 @@ def _calculate_max_tree_depth(token) -> int:
     return max(child_depths) + 1
 
 
-def _identify_t_units(doc) -> list:
+def _identify_t_units(doc: _SpaCyDoc) -> list[_SpaCySpan]:
     """
     Identify T-units (minimal terminable units) in document.
 
@@ -371,7 +433,7 @@ def _identify_t_units(doc) -> list:
     return list(doc.sents)
 
 
-def _count_clauses(sent) -> tuple[int, int, int, int]:
+def _count_clauses(sent: _SpaCySpan) -> tuple[int, int, int, int]:
     """
     Count different types of clauses in sentence.
 
@@ -406,7 +468,7 @@ def _count_clauses(sent) -> tuple[int, int, int, int]:
     return total, dependent, subordinate, coordinate
 
 
-def _is_passive_voice(sent) -> bool:
+def _is_passive_voice(sent: _SpaCySpan) -> bool:
     """
     Detect if sentence contains passive voice construction.
 

pystylometry/syntactic/pos_ratios.py

@@ -1,10 +1,17 @@
-"""Part-of-Speech ratio analysis using spaCy."""
+"""Part-of-Speech ratio analysis using spaCy.
 
-from .._types import POSResult
+Related GitHub Issue:
+    #27 - Native chunked analysis with Distribution dataclass
+    https://github.com/craigtrim/pystylometry/issues/27
+"""
+
+from .._types import Distribution, POSResult, make_distribution
 from .._utils import check_optional_dependency
 
 
-def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
+def compute_pos_ratios(
+    text: str, model: str = "en_core_web_sm", chunk_size: int = 1000
+) -> POSResult:
     """
     Compute Part-of-Speech ratios and lexical density using spaCy.
 
@@ -18,6 +25,10 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
     - Lexical density: (nouns + verbs + adjectives + adverbs) / total words
     - Function word ratio: (determiners + prepositions + conjunctions) / total words
 
+    Related GitHub Issue:
+        #27 - Native chunked analysis with Distribution dataclass
+        https://github.com/craigtrim/pystylometry/issues/27
+
     References:
         Biber, D. (1988). Variation across speech and writing.
         Cambridge University Press.
@@ -25,9 +36,13 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
     Args:
         text: Input text to analyze
         model: spaCy model name (default: "en_core_web_sm")
+        chunk_size: Number of words per chunk (default: 1000).
+            Note: POS analysis is performed on the full text for accuracy,
+            so this parameter is included for API consistency but actual
+            results are from a single pass.
 
     Returns:
-        POSResult with all POS ratios and metadata
+        POSResult with all POS ratios, distributions, and metadata
 
     Raises:
         ImportError: If spaCy is not installed
@@ -47,8 +62,7 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
         nlp = spacy.load(model)
     except OSError:
         raise OSError(
-            f"spaCy model '{model}' not found. "
-            f"Download it with: python -m spacy download {model}"
+            f"spaCy model '{model}' not found. Download it with: python -m spacy download {model}"
         )
 
     # Process text with spaCy
@@ -89,6 +103,14 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
 
     # Handle empty text
     if total_tokens == 0:
+        empty_dist = Distribution(
+            values=[],
+            mean=float("nan"),
+            median=float("nan"),
+            std=0.0,
+            range=0.0,
+            iqr=0.0,
+        )
         return POSResult(
             noun_ratio=float("nan"),
             verb_ratio=float("nan"),
@@ -98,6 +120,16 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
             adjective_noun_ratio=float("nan"),
             lexical_density=float("nan"),
             function_word_ratio=float("nan"),
+            noun_ratio_dist=empty_dist,
+            verb_ratio_dist=empty_dist,
+            adjective_ratio_dist=empty_dist,
+            adverb_ratio_dist=empty_dist,
+            noun_verb_ratio_dist=empty_dist,
+            adjective_noun_ratio_dist=empty_dist,
+            lexical_density_dist=empty_dist,
+            function_word_ratio_dist=empty_dist,
+            chunk_size=chunk_size,
+            chunk_count=0,
             metadata={
                 "model": model,
                 "token_count": 0,
@@ -129,6 +161,28 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
     function_words = det_count + adp_count + conj_count
     function_word_ratio = function_words / total_tokens
 
+    # Create single-value distributions (POS analysis is done on full text)
+    noun_ratio_dist = make_distribution([noun_ratio])
+    verb_ratio_dist = make_distribution([verb_ratio])
+    adj_ratio_dist = make_distribution([adj_ratio])
+    adv_ratio_dist = make_distribution([adv_ratio])
+    noun_verb_dist = (
+        make_distribution([noun_verb_ratio])
+        if not (noun_verb_ratio != noun_verb_ratio)
+        else Distribution(
+            values=[], mean=float("nan"), median=float("nan"), std=0.0, range=0.0, iqr=0.0
+        )
+    )
+    adj_noun_dist = (
+        make_distribution([adj_noun_ratio])
+        if not (adj_noun_ratio != adj_noun_ratio)
+        else Distribution(
+            values=[], mean=float("nan"), median=float("nan"), std=0.0, range=0.0, iqr=0.0
+        )
+    )
+    lexical_density_dist = make_distribution([lexical_density])
+    function_word_dist = make_distribution([function_word_ratio])
+
     return POSResult(
         noun_ratio=noun_ratio,
         verb_ratio=verb_ratio,
@@ -138,6 +192,16 @@ def compute_pos_ratios(text: str, model: str = "en_core_web_sm") -> POSResult:
         adjective_noun_ratio=adj_noun_ratio,
         lexical_density=lexical_density,
         function_word_ratio=function_word_ratio,
+        noun_ratio_dist=noun_ratio_dist,
+        verb_ratio_dist=verb_ratio_dist,
+        adjective_ratio_dist=adj_ratio_dist,
+        adverb_ratio_dist=adv_ratio_dist,
+        noun_verb_ratio_dist=noun_verb_dist,
+        adjective_noun_ratio_dist=adj_noun_dist,
+        lexical_density_dist=lexical_density_dist,
+        function_word_ratio_dist=function_word_dist,
+        chunk_size=chunk_size,
+        chunk_count=1,  # Single pass analysis
         metadata={
             "model": model,
             "token_count": total_tokens,

pystylometry/syntactic/sentence_stats.py

@@ -1,10 +1,17 @@
-"""Sentence-level statistics using spaCy."""
+"""Sentence-level statistics using spaCy.
 
-from .._types import SentenceStatsResult
-from .._utils import check_optional_dependency, split_sentences
+Related GitHub Issue:
+    #27 - Native chunked analysis with Distribution dataclass
+    https://github.com/craigtrim/pystylometry/issues/27
+"""
 
+from .._types import Distribution, SentenceStatsResult, make_distribution
+from .._utils import check_optional_dependency
 
-def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> SentenceStatsResult:
+
+def compute_sentence_stats(
+    text: str, model: str = "en_core_web_sm", chunk_size: int = 1000
+) -> SentenceStatsResult:
     """
     Compute sentence-level statistics using spaCy.
 
@@ -16,6 +23,10 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
     - Maximum sentence length
     - Total sentence count
 
+    Related GitHub Issue:
+        #27 - Native chunked analysis with Distribution dataclass
+        https://github.com/craigtrim/pystylometry/issues/27
+
     References:
         Hunt, K. W. (1965). Grammatical structures written at three grade levels.
         NCTE Research Report No. 3.
@@ -23,9 +34,13 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
     Args:
         text: Input text to analyze
         model: spaCy model name (default: "en_core_web_sm")
+        chunk_size: Number of words per chunk (default: 1000).
+            Note: Sentence analysis is performed on the full text for accuracy,
+            so this parameter is included for API consistency but actual
+            results are from a single pass.
 
     Returns:
-        SentenceStatsResult with sentence statistics and metadata
+        SentenceStatsResult with sentence statistics, distributions, and metadata
 
     Raises:
         ImportError: If spaCy is not installed
@@ -45,8 +60,7 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
         nlp = spacy.load(model)
     except OSError:
         raise OSError(
-            f"spaCy model '{model}' not found. "
-            f"Download it with: python -m spacy download {model}"
+            f"spaCy model '{model}' not found. Download it with: python -m spacy download {model}"
         )
 
     # Process text with spaCy
@@ -62,13 +76,28 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
 
     # Handle empty text
     if len(sentence_lengths) == 0:
+        empty_dist = Distribution(
+            values=[],
+            mean=float("nan"),
+            median=float("nan"),
+            std=0.0,
+            range=0.0,
+            iqr=0.0,
+        )
         return SentenceStatsResult(
             mean_sentence_length=float("nan"),
             sentence_length_std=float("nan"),
-            sentence_length_range=0,
-            min_sentence_length=0,
-            max_sentence_length=0,
+            sentence_length_range=0.0,
+            min_sentence_length=0.0,
+            max_sentence_length=0.0,
             sentence_count=0,
+            mean_sentence_length_dist=empty_dist,
+            sentence_length_std_dist=empty_dist,
+            sentence_length_range_dist=empty_dist,
+            min_sentence_length_dist=empty_dist,
+            max_sentence_length_dist=empty_dist,
+            chunk_size=chunk_size,
+            chunk_count=0,
             metadata={
                 "model": model,
             },
@@ -86,10 +115,17 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
     else:
         std_dev = 0.0
 
-    min_length = min(sentence_lengths)
-    max_length = max(sentence_lengths)
+    min_length = float(min(sentence_lengths))
+    max_length = float(max(sentence_lengths))
     length_range = max_length - min_length
 
+    # Create single-value distributions (sentence analysis is done on full text)
+    mean_dist = make_distribution([mean_length])
+    std_dist = make_distribution([std_dev])
+    range_dist = make_distribution([length_range])
+    min_dist = make_distribution([min_length])
+    max_dist = make_distribution([max_length])
+
     return SentenceStatsResult(
         mean_sentence_length=mean_length,
         sentence_length_std=std_dev,
@@ -97,6 +133,13 @@ def compute_sentence_stats(text: str, model: str = "en_core_web_sm") -> Sentence
         min_sentence_length=min_length,
         max_sentence_length=max_length,
         sentence_count=len(sentence_lengths),
+        mean_sentence_length_dist=mean_dist,
+        sentence_length_std_dist=std_dist,
+        sentence_length_range_dist=range_dist,
+        min_sentence_length_dist=min_dist,
+        max_sentence_length_dist=max_dist,
+        chunk_size=chunk_size,
+        chunk_count=1,  # Single pass analysis
         metadata={
             "model": model,
             "sentence_lengths": sentence_lengths,

pystylometry/syntactic/sentence_types.py

@@ -27,13 +27,19 @@ References:
     Quirk, R., et al. (1985). A Comprehensive Grammar of the English Language. Longman.
 """
 
-from .._types import SentenceTypeResult
+from typing import Any
+
+from .._types import Distribution, SentenceTypeResult, make_distribution
 from .._utils import check_optional_dependency
 
+# Type alias for spaCy Span (loaded dynamically)
+_SpaCySpan = Any
+
 
 def compute_sentence_types(
     text: str,
     model: str = "en_core_web_sm",
+    chunk_size: int = 1000,
 ) -> SentenceTypeResult:
     """
     Classify sentences by structure and function.
@@ -193,8 +199,7 @@ def compute_sentence_types(
         nlp = spacy.load(model)
     except OSError as e:
         raise OSError(
-            f"spaCy model '{model}' not found. "
-            f"Download with: python -m spacy download {model}"
+            f"spaCy model '{model}' not found. Download with: python -m spacy download {model}"
         ) from e
 
     # Parse text
@@ -203,6 +208,14 @@ def compute_sentence_types(
 
     # Handle empty text
     if len(sentences) == 0:
+        empty_dist = Distribution(
+            values=[],
+            mean=float("nan"),
+            median=float("nan"),
+            std=0.0,
+            range=0.0,
+            iqr=0.0,
+        )
         return SentenceTypeResult(
             simple_ratio=float("nan"),
             compound_ratio=float("nan"),
@@ -223,6 +236,18 @@ def compute_sentence_types(
             total_sentences=0,
             structural_diversity=float("nan"),
             functional_diversity=float("nan"),
+            simple_ratio_dist=empty_dist,
+            compound_ratio_dist=empty_dist,
+            complex_ratio_dist=empty_dist,
+            compound_complex_ratio_dist=empty_dist,
+            declarative_ratio_dist=empty_dist,
+            interrogative_ratio_dist=empty_dist,
+            imperative_ratio_dist=empty_dist,
+            exclamatory_ratio_dist=empty_dist,
+            structural_diversity_dist=empty_dist,
+            functional_diversity_dist=empty_dist,
+            chunk_size=chunk_size,
+            chunk_count=0,
             metadata={
                 "warning": "Empty text or no sentences found",
             },
@@ -249,13 +274,15 @@ def compute_sentence_types(
         functional_counts[functional_type] += 1
 
         # Store classification
-        sentence_classifications.append({
-            "text": sent.text,
-            "structural_type": structural_type,
-            "functional_type": functional_type,
-            "independent_clauses": independent_count,
-            "dependent_clauses": dependent_count,
-        })
+        sentence_classifications.append(
+            {
+                "text": sent.text,
+                "structural_type": structural_type,
+                "functional_type": functional_type,
+                "independent_clauses": independent_count,
+                "dependent_clauses": dependent_count,
+            }
+        )
 
     # Calculate ratios
     total_sentences = len(sentences)
@@ -271,11 +298,28 @@ def compute_sentence_types(
 
     # Calculate diversity metrics
     structural_ratios = [simple_ratio, compound_ratio, complex_ratio, compound_complex_ratio]
-    functional_ratios = [declarative_ratio, interrogative_ratio, imperative_ratio, exclamatory_ratio]
+    functional_ratios = [
+        declarative_ratio,
+        interrogative_ratio,
+        imperative_ratio,
+        exclamatory_ratio,
+    ]
 
     structural_diversity = _calculate_shannon_entropy(structural_ratios)
     functional_diversity = _calculate_shannon_entropy(functional_ratios)
 
+    # Create single-value distributions (sentence analysis is done on full text)
+    simple_ratio_dist = make_distribution([simple_ratio])
+    compound_ratio_dist = make_distribution([compound_ratio])
+    complex_ratio_dist = make_distribution([complex_ratio])
+    compound_complex_ratio_dist = make_distribution([compound_complex_ratio])
+    declarative_ratio_dist = make_distribution([declarative_ratio])
+    interrogative_ratio_dist = make_distribution([interrogative_ratio])
+    imperative_ratio_dist = make_distribution([imperative_ratio])
+    exclamatory_ratio_dist = make_distribution([exclamatory_ratio])
+    structural_diversity_dist = make_distribution([structural_diversity])
+    functional_diversity_dist = make_distribution([functional_diversity])
+
     # Collect metadata
     metadata = {
         "sentence_count": total_sentences,
@@ -306,11 +350,23 @@ def compute_sentence_types(
         total_sentences=total_sentences,
         structural_diversity=structural_diversity,
         functional_diversity=functional_diversity,
+        simple_ratio_dist=simple_ratio_dist,
+        compound_ratio_dist=compound_ratio_dist,
+        complex_ratio_dist=complex_ratio_dist,
+        compound_complex_ratio_dist=compound_complex_ratio_dist,
+        declarative_ratio_dist=declarative_ratio_dist,
+        interrogative_ratio_dist=interrogative_ratio_dist,
+        imperative_ratio_dist=imperative_ratio_dist,
+        exclamatory_ratio_dist=exclamatory_ratio_dist,
+        structural_diversity_dist=structural_diversity_dist,
+        functional_diversity_dist=functional_diversity_dist,
+        chunk_size=chunk_size,
+        chunk_count=1,  # Single pass analysis
         metadata=metadata,
     )
 
 
-def _count_independent_clauses(sent) -> int:
+def _count_independent_clauses(sent: _SpaCySpan) -> int:
     """
     Count independent clauses in a sentence.
 
@@ -336,7 +392,7 @@ def _count_independent_clauses(sent) -> int:
     return count
 
 
-def _count_dependent_clauses(sent) -> int:
+def _count_dependent_clauses(sent: _SpaCySpan) -> int:
     """
     Count dependent clauses in a sentence.
 
@@ -382,7 +438,7 @@ def _classify_structural(independent: int, dependent: int) -> str:
         return "simple"
 
 
-def _classify_functional(sent) -> str:
+def _classify_functional(sent: _SpaCySpan) -> str:
     """
     Classify sentence function based on punctuation and structure.
 
@@ -415,7 +471,7 @@ def _classify_functional(sent) -> str:
     return "declarative"
 
 
-def _is_imperative_structure(sent) -> bool:
+def _is_imperative_structure(sent: _SpaCySpan) -> bool:
     """
     Check if sentence has imperative structure.
 

pystylometry/viz/__init__.py

@@ -0,0 +1,71 @@
+"""Visualization module for pystylometry.
+
+This module provides visualization functions for stylometric analysis results.
+
+Matplotlib Functions (PNG output):
+    Requires optional dependencies: pip install pystylometry[viz]
+
+    plot_drift_timeline: Line chart of chi-squared values over document
+    plot_drift_scatter: Scatter plot with reference zones (tic-tac-toe style)
+    plot_drift_report: Combined multi-panel visualization
+
+Interactive JSX Functions (HTML output):
+    No additional dependencies required (uses React via CDN)
+
+    export_drift_timeline_jsx: Interactive timeline chart
+    export_drift_report_jsx: Interactive multi-panel dashboard
+    export_drift_viewer: Standalone viewer with file upload
+
+Related GitHub Issues:
+    #38 - Visualization Options for Style Drift Detection
+    https://github.com/craigtrim/pystylometry/issues/38
+
+Example:
+    >>> from pystylometry.consistency import compute_kilgarriff_drift
+    >>> from pystylometry.viz import plot_drift_timeline, export_drift_timeline_jsx
+    >>>
+    >>> result = compute_kilgarriff_drift(text)
+    >>> plot_drift_timeline(result, output="timeline.png")  # Static PNG
+    >>> export_drift_timeline_jsx(result, "timeline.html")  # Interactive HTML
+"""
+
+from .drift import (  # noqa: E402
+    plot_drift_report,
+    plot_drift_scatter,
+    plot_drift_timeline,
+)
+from .jsx import (  # noqa: E402
+    export_drift_report_jsx,
+    export_drift_timeline_jsx,
+    export_drift_viewer,
+)
+
+try:
+    import matplotlib  # noqa: F401
+    import seaborn  # noqa: F401  # type: ignore[import-untyped]
+
+    _VIZ_AVAILABLE = True
+except ImportError:
+    _VIZ_AVAILABLE = False
+
+
+def _check_viz_available() -> None:
+    """Raise ImportError if visualization dependencies are not installed."""
+    if not _VIZ_AVAILABLE:
+        raise ImportError(
+            "Visualization requires optional dependencies. "
+            "Install with: pip install pystylometry[viz] or poetry install --with viz"
+        )
+
+
+__all__ = [
+    # Matplotlib (PNG)
+    "plot_drift_timeline",
+    "plot_drift_scatter",
+    "plot_drift_report",
+    # JSX (HTML)
+    "export_drift_timeline_jsx",
+    "export_drift_report_jsx",
+    # Standalone viewer
+    "export_drift_viewer",
+]