pycorpdiff 0.1.0a2__tar.gz → 0.1.0a3__tar.gz

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to `pycorpdiff` are documented in this file. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
 project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.1.0a2] — initial release
+## [0.1.0a3] — initial release
 
 The initial public release of `pycorpdiff` — comparative corpus analysis
 for modern Python workflows. Three public verbs (`compare`, `track`,

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/CITATION.cff

@@ -4,7 +4,7 @@ message: >
   entry. GitHub renders a "Cite this repository" widget directly from
   this file.
 title: "pycorpdiff: Comparative Corpus Analysis for Modern Python Workflows"
-version: 0.1.0a2
+version: 0.1.0a3
 date-released: 2026-05-22
 authors:
   - family-names: Turner

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycorpdiff
-Version: 0.1.0a2
+Version: 0.1.0a3
 Summary: Comparative corpus analysis for Python: keyness, collocations, semantic shift, temporal trajectories with changepoints + causal inference.
 Project-URL: Homepage, https://github.com/jturner-uofl/pycorpdiff
 Project-URL: Documentation, https://github.com/jturner-uofl/pycorpdiff
@@ -53,7 +53,7 @@ Requires-Dist: matplotlib>=3.8; extra == 'all'
 Requires-Dist: networkx>=3.1; extra == 'all'
 Requires-Dist: polars>=1.0; extra == 'all'
 Requires-Dist: pyarrow>=15; extra == 'all'
-Requires-Dist: pysofra>=0.1.0a2; extra == 'all'
+Requires-Dist: pysofra>=0.1.0a3; extra == 'all'
 Requires-Dist: ruptures>=1.1; extra == 'all'
 Requires-Dist: scikit-learn>=1.3; extra == 'all'
 Requires-Dist: sentence-transformers>=2.2; extra == 'all'
@@ -76,7 +76,7 @@ Provides-Extra: nlp
 Requires-Dist: spacy>=3.7; extra == 'nlp'
 Provides-Extra: notebooks
 Requires-Dist: jupyter>=1.0; extra == 'notebooks'
-Requires-Dist: pysofra>=0.1.0a2; extra == 'notebooks'
+Requires-Dist: pysofra>=0.1.0a3; extra == 'notebooks'
 Requires-Dist: vl-convert-python>=1.5; extra == 'notebooks'
 Provides-Extra: polars
 Requires-Dist: polars>=1.0; extra == 'polars'
@@ -130,7 +130,7 @@ points — one-line adapters, no plugin registry. The base install pulls
 only `numpy`, `pandas`, `scipy`, and `pyarrow`; everything else is opt-in
 via extras.
 
-> **Status: alpha (0.1.0a2).** Public API is stable for the features
+> **Status: alpha (0.1.0a3).** Public API is stable for the features
 > described below; on PyPI as `pip install pycorpdiff`.
 
 ## The three-layer architecture
@@ -144,52 +144,61 @@ via extras.
 ## Quick start
 
 ```bash
-pip install "pycorpdiff[viz,temporal]"
+pip install "pycorpdiff[viz]"
 ```
 
 ```python
 import pycorpdiff as pcd
 
-# Bundled synthetic UK-Hansard corpus — runs offline, no data needed.
+# Bundled UK-Hansard sample — runs offline, no data download.
 corpus = pcd.load_hansard_sample()
 immigration = corpus.slice(topic="immigration")
-human = immigration.slice(frame="humanising")
-criminal = immigration.slice(frame="criminalising")
-
-# Compare — three verbs
-k = pcd.compare(human, criminal).keyness()
-c = pcd.compare(human, criminal).collocation_shift("immigrant")
-# s = pcd.compare(human, criminal).semantic_shift("immigrant", embedder=pcd.SBERTEmbedder())
-#   ↑ requires `pip install "pycorpdiff[semantic]"`
-
-# Track over time
-tr = pcd.track(immigration, "criminal").over_time(freq="Y")
-tr.changepoints()                                # offline PELT
-tr.changepoints_online(hazard=1/24)              # Bayesian online (Adams & MacKay 2007)
-tr.interrupted_time_series(event_date="2016")    # segmented OLS
-tr.causal_impact(event_date="2016")              # Bayesian counterfactual (Brodersen 2015)
-tr.forecast(horizon=4)                           # state-space ETS
+
+# Which words separate the humanising and criminalising frames?
+keyness = pcd.compare(
+    immigration.slice(frame="humanising"),
+    immigration.slice(frame="criminalising"),
+).keyness(min_count=3)
+
+keyness.plot()                # volcano plot — picture the result
+# keyness.table.head(10)      # or look at the ranked table directly
+# keyness.explain("criminal") # KWIC concordances showing the textual evidence
+```
+
+That's the entire surface in five lines: load a corpus, slice it,
+compare two slices, plot the result. Every other analytical method —
+collocation shifts, semantic drift, temporal trajectories, changepoint
+detection, causal-impact analysis, forecasting, co-occurrence networks,
+N-way keyness — follows the same shape. See
+[the showcase notebook](docs/rendered/pycorpdiff_showcase.html) for the
+full feature tour, or the cheat sheet below for one-line API previews.
+
+### Cheat sheet — every analytical surface in one block
+
+```python
+# Compare verbs (returns Result objects with .plot / .to_df / .explain / .summary)
+pcd.compare(a, b).keyness()
+pcd.compare(a, b).collocation_shift("migrant")
+pcd.compare(a, b).semantic_shift("migrant", embedder=pcd.SBERTEmbedder())   # [semantic]
+
+# Track over time (requires [temporal] for the changepoint + ITS + forecast + causal_impact methods)
+tr = pcd.track(corpus, "migrant").over_time(freq="Y")
+tr.changepoints()                                  # offline PELT
+tr.changepoints_online(hazard=1/24)                # Bayesian online (Adams & MacKay 2007)
+tr.interrupted_time_series(event_date="2016")      # segmented OLS
+tr.causal_impact(event_date="2016")                # Bayesian counterfactual (Brodersen 2015)
+tr.forecast(horizon=4)                             # state-space ETS
 
 # Before / after a known event
 pcd.compare.before_after(corpus, event_date="2016-06-23").keyness()
 
-# N-way (≥ 2 corpora) — one keyness across all four parties
-parties = ["Conservative", "Labour", "Liberal Democrat", "SNP"]
-nhs = corpus.slice(topic="nhs")
-pcd.keyness_multi([nhs.slice(party=p) for p in parties], labels=parties)
+# N-way (≥ 2 corpora)
+pcd.keyness_multi([a, b, c, d], labels=["A", "B", "C", "D"])
 
 # The discourse as a graph
-pcd.cooccurrence_network(immigration, top_n=30).plot()
-
-# Every Result: .to_df() · .plot() · .explain() · .summary() · .to_html() · .to_json()
+pcd.cooccurrence_network(corpus, top_n=30).plot()
 ```
 
-Every line of the snippet above is verified end-to-end against
-`pip install "pycorpdiff[viz,temporal]"` — no data download required.
-Replace `load_hansard_sample()` with `pcd.from_dataframe(your_df, ...)`,
-`pcd.read_parquet(...)`, `pcd.fetch_hansard(...)`, or
-`pcd.from_huggingface(...)` to use your own corpus.
-
 See [`examples/pycorpdiff_showcase.ipynb`](examples/pycorpdiff_showcase.ipynb)
 ([rendered HTML](docs/rendered/pycorpdiff_showcase.html)) for a
 walkthrough on a synthetic UK Hansard corpus exercising every analytical

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/README.md

@@ -35,7 +35,7 @@ points — one-line adapters, no plugin registry. The base install pulls
 only `numpy`, `pandas`, `scipy`, and `pyarrow`; everything else is opt-in
 via extras.
 
-> **Status: alpha (0.1.0a2).** Public API is stable for the features
+> **Status: alpha (0.1.0a3).** Public API is stable for the features
 > described below; on PyPI as `pip install pycorpdiff`.
 
 ## The three-layer architecture
@@ -49,52 +49,61 @@ via extras.
 ## Quick start
 
 ```bash
-pip install "pycorpdiff[viz,temporal]"
+pip install "pycorpdiff[viz]"
 ```
 
 ```python
 import pycorpdiff as pcd
 
-# Bundled synthetic UK-Hansard corpus — runs offline, no data needed.
+# Bundled UK-Hansard sample — runs offline, no data download.
 corpus = pcd.load_hansard_sample()
 immigration = corpus.slice(topic="immigration")
-human = immigration.slice(frame="humanising")
-criminal = immigration.slice(frame="criminalising")
-
-# Compare — three verbs
-k = pcd.compare(human, criminal).keyness()
-c = pcd.compare(human, criminal).collocation_shift("immigrant")
-# s = pcd.compare(human, criminal).semantic_shift("immigrant", embedder=pcd.SBERTEmbedder())
-#   ↑ requires `pip install "pycorpdiff[semantic]"`
-
-# Track over time
-tr = pcd.track(immigration, "criminal").over_time(freq="Y")
-tr.changepoints()                                # offline PELT
-tr.changepoints_online(hazard=1/24)              # Bayesian online (Adams & MacKay 2007)
-tr.interrupted_time_series(event_date="2016")    # segmented OLS
-tr.causal_impact(event_date="2016")              # Bayesian counterfactual (Brodersen 2015)
-tr.forecast(horizon=4)                           # state-space ETS
+
+# Which words separate the humanising and criminalising frames?
+keyness = pcd.compare(
+    immigration.slice(frame="humanising"),
+    immigration.slice(frame="criminalising"),
+).keyness(min_count=3)
+
+keyness.plot()                # volcano plot — picture the result
+# keyness.table.head(10)      # or look at the ranked table directly
+# keyness.explain("criminal") # KWIC concordances showing the textual evidence
+```
+
+That's the entire surface in five lines: load a corpus, slice it,
+compare two slices, plot the result. Every other analytical method —
+collocation shifts, semantic drift, temporal trajectories, changepoint
+detection, causal-impact analysis, forecasting, co-occurrence networks,
+N-way keyness — follows the same shape. See
+[the showcase notebook](docs/rendered/pycorpdiff_showcase.html) for the
+full feature tour, or the cheat sheet below for one-line API previews.
+
+### Cheat sheet — every analytical surface in one block
+
+```python
+# Compare verbs (returns Result objects with .plot / .to_df / .explain / .summary)
+pcd.compare(a, b).keyness()
+pcd.compare(a, b).collocation_shift("migrant")
+pcd.compare(a, b).semantic_shift("migrant", embedder=pcd.SBERTEmbedder())   # [semantic]
+
+# Track over time (requires [temporal] for the changepoint + ITS + forecast + causal_impact methods)
+tr = pcd.track(corpus, "migrant").over_time(freq="Y")
+tr.changepoints()                                  # offline PELT
+tr.changepoints_online(hazard=1/24)                # Bayesian online (Adams & MacKay 2007)
+tr.interrupted_time_series(event_date="2016")      # segmented OLS
+tr.causal_impact(event_date="2016")                # Bayesian counterfactual (Brodersen 2015)
+tr.forecast(horizon=4)                             # state-space ETS
 
 # Before / after a known event
 pcd.compare.before_after(corpus, event_date="2016-06-23").keyness()
 
-# N-way (≥ 2 corpora) — one keyness across all four parties
-parties = ["Conservative", "Labour", "Liberal Democrat", "SNP"]
-nhs = corpus.slice(topic="nhs")
-pcd.keyness_multi([nhs.slice(party=p) for p in parties], labels=parties)
+# N-way (≥ 2 corpora)
+pcd.keyness_multi([a, b, c, d], labels=["A", "B", "C", "D"])
 
 # The discourse as a graph
-pcd.cooccurrence_network(immigration, top_n=30).plot()
-
-# Every Result: .to_df() · .plot() · .explain() · .summary() · .to_html() · .to_json()
+pcd.cooccurrence_network(corpus, top_n=30).plot()
 ```
 
-Every line of the snippet above is verified end-to-end against
-`pip install "pycorpdiff[viz,temporal]"` — no data download required.
-Replace `load_hansard_sample()` with `pcd.from_dataframe(your_df, ...)`,
-`pcd.read_parquet(...)`, `pcd.fetch_hansard(...)`, or
-`pcd.from_huggingface(...)` to use your own corpus.
-
 See [`examples/pycorpdiff_showcase.ipynb`](examples/pycorpdiff_showcase.ipynb)
 ([rendered HTML](docs/rendered/pycorpdiff_showcase.html)) for a
 walkthrough on a synthetic UK Hansard corpus exercising every analytical

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycorpdiff"
-version = "0.1.0a2"
+version = "0.1.0a3"
 description = "Comparative corpus analysis for Python: keyness, collocations, semantic shift, temporal trajectories with changepoints + causal inference."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -66,7 +66,7 @@ huggingface = ["datasets>=2.14"]
 # rendered HTML examples. `jupyter` runs the notebook, `vl-convert` does
 # static SVG/PNG export of altair charts, `pysofra` renders the showcase's
 # result tables in JAMA-style typography.
-notebooks = ["jupyter>=1.0", "vl-convert-python>=1.5", "pysofra>=0.1.0a2"]
+notebooks = ["jupyter>=1.0", "vl-convert-python>=1.5", "pysofra>=0.1.0a3"]
 # Meta-extra so `pycorpdiff[all]` exercises every optional code path.
 all = [
     "altair>=5",
@@ -82,7 +82,7 @@ all = [
     "duckdb>=0.10",
     "spacy>=3.7",
     "vl-convert-python>=1.5",
-    "pysofra>=0.1.0a2",
+    "pysofra>=0.1.0a3",
 ]
 dev = [
     "pytest>=8",

{pycorpdiff-0.1.0a2 → pycorpdiff-0.1.0a3}/src/pycorpdiff/__init__.py

@@ -14,12 +14,12 @@ Example
 
 >>> import pycorpdiff as pcd
 >>> pcd.__version__
-'0.1.0a2'
+'0.1.0a3'
 """
 
 from __future__ import annotations
 
-__version__ = "0.1.0a2"
+__version__ = "0.1.0a3"
 
 from .collocation.network import NetworkResult, cooccurrence_network
 from .compare import Comparison, compare