pycorpdiff 0.1.0a0__tar.gz → 0.1.0a2__tar.gz

{pycorpdiff-0.1.0a0 → pycorpdiff-0.1.0a2}/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.0a0] — initial release
+## [0.1.0a2] — initial release
 
 The initial public release of `pycorpdiff` — comparative corpus analysis
 for modern Python workflows. Three public verbs (`compare`, `track`,

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

@@ -1,11 +1,10 @@
 cff-version: 1.2.0
 message: >
-  If you use pycorpdiff in academic work, please cite both the
-  software (this entry) and the accompanying Journal of Statistical
-  Software paper once it appears. The JSS manuscript is in
-  preparation; the draft will live in this repository as paper/paper.tex.
+  If you use pycorpdiff in academic work, please cite this software
+  entry. GitHub renders a "Cite this repository" widget directly from
+  this file.
 title: "pycorpdiff: Comparative Corpus Analysis for Modern Python Workflows"
-version: 0.1.0a0
+version: 0.1.0a2
 date-released: 2026-05-22
 authors:
   - family-names: Turner
@@ -34,16 +33,10 @@ abstract: >
   computational social science, and discourse analysis research,
   emphasising interpretability, explainability, statistical rigour,
   and reproducibility.
-preferred-citation:
-  type: article
-  authors:
-    - family-names: Turner
-      given-names: Jason
-  title: "pycorpdiff: Comparative Corpus Analysis for Modern Python Workflows"
-  journal: "Journal of Statistical Software"
-  year: 2026
-  status: in-preparation
 identifiers:
   - type: url
     value: "https://github.com/jturner-uofl/pycorpdiff"
     description: Project repository
+  - type: url
+    value: "https://pypi.org/project/pycorpdiff/"
+    description: PyPI release

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycorpdiff
-Version: 0.1.0a0
+Version: 0.1.0a2
 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
@@ -30,7 +30,7 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: collocation,comparative corpus analysis,computational social science,corpus linguistics,diachronic nlp,digital humanities,discourse analysis,keyness,semantic change,temporal text analysis
-Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -95,15 +95,10 @@ Description-Content-Type: text/markdown
 
 # pycorpdiff
 
-<!--
-TODO post-publish (Phase 5 — once GitHub repo public + PyPI published + Zenodo DOI minted):
-
 [![PyPI](https://img.shields.io/pypi/v/pycorpdiff.svg)](https://pypi.org/project/pycorpdiff/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pycorpdiff.svg)](https://pypi.org/project/pycorpdiff/)
 [![CI](https://github.com/jturner-uofl/pycorpdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/jturner-uofl/pycorpdiff/actions/workflows/ci.yml)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.<RECORD>.svg)](https://doi.org/10.5281/zenodo.<RECORD>)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
--->
 
 **Comparative corpus analysis for modern Python workflows.**
 
@@ -135,8 +130,8 @@ 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: pre-release alpha (0.1.0a0).** Public API is stable for the
-> features described below; PyPI publication is the next milestone.
+> **Status: alpha (0.1.0a2).** Public API is stable for the features
+> described below; on PyPI as `pip install pycorpdiff`.
 
 ## The three-layer architecture
 
@@ -148,36 +143,53 @@ via extras.
 
 ## Quick start
 
+```bash
+pip install "pycorpdiff[viz,temporal]"
+```
+
 ```python
 import pycorpdiff as pcd
 
-news = pcd.from_dataframe(df, text_col="body", meta_cols=("outlet", "date"))
+# Bundled synthetic UK-Hansard corpus — runs offline, no data needed.
+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(news.slice(outlet="Guardian"), news.slice(outlet="Mail")).keyness()
-c = pcd.compare(a, b).collocation_shift("migrant")
-s = pcd.compare(a, b).semantic_shift("migrant", embedder=pcd.SBERTEmbedder())
+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(news, "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-06-23")   # segmented OLS
-tr.causal_impact(event_date="2016-06-23")             # Bayesian counterfactual (Brodersen 2015)
-tr.forecast(horizon=4)                                # state-space ETS
+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
 
 # Before / after a known event
-pcd.compare.before_after(news, event_date="2016-06-23").keyness()
+pcd.compare.before_after(corpus, event_date="2016-06-23").keyness()
 
-# N-way (≥ 2 corpora)
-pcd.keyness_multi([gu, ma, te, mi], labels=["Guardian", "Mail", "Telegraph", "Mirror"])
+# 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)
 
 # The discourse as a graph
-pcd.cooccurrence_network(news, top_n=50).plot()
+pcd.cooccurrence_network(immigration, top_n=30).plot()
 
 # Every Result: .to_df() · .plot() · .explain() · .summary() · .to_html() · .to_json()
 ```
 
+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
@@ -185,23 +197,28 @@ surface.
 
 ## Installation
 
-<!-- TODO post-publish: replace this block with the PyPI install commands once published. -->
+```bash
+pip install pycorpdiff                # lexical-comparative core
+pip install "pycorpdiff[viz]"         # + altair / matplotlib / networkx
+pip install "pycorpdiff[semantic]"    # + sentence-transformers
+pip install "pycorpdiff[temporal]"    # + ruptures / statsmodels
+pip install "pycorpdiff[notebooks]"   # + jupyter / vl-convert / pysofra
+pip install "pycorpdiff[all]"         # everything
+```
 
-Currently a pre-release alpha. From a local clone:
+The base install keeps a small dependency footprint (`numpy`, `pandas`,
+`scipy`, `pyarrow`); optional extras land per analytical layer so you
+only pay for what you use.
+
+To work from source:
 
 ```bash
 git clone https://github.com/jturner-uofl/pycorpdiff
 cd pycorpdiff
 pip install -e ".[dev]"
-pytest -q                          # 519 default tests, ~7s
+pytest -q
 ```
 
-Optional extras: `[viz]` (altair + matplotlib + networkx), `[semantic]`
-(sentence-transformers + scikit-learn), `[temporal]` (ruptures +
-statsmodels), `[polars]`, `[duckdb]`, `[huggingface]`, `[nlp]` (spaCy),
-`[notebooks]` (jupyter + vl-convert + pysofra, for the showcase),
-or `[all]`.
-
 ## Cross-validation receipts
 
 The math agrees with the standard tools — by automated test:

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

@@ -1,14 +1,9 @@
 # pycorpdiff
 
-<!--
-TODO post-publish (Phase 5 — once GitHub repo public + PyPI published + Zenodo DOI minted):
-
 [![PyPI](https://img.shields.io/pypi/v/pycorpdiff.svg)](https://pypi.org/project/pycorpdiff/)
 [![Python versions](https://img.shields.io/pypi/pyversions/pycorpdiff.svg)](https://pypi.org/project/pycorpdiff/)
 [![CI](https://github.com/jturner-uofl/pycorpdiff/actions/workflows/ci.yml/badge.svg)](https://github.com/jturner-uofl/pycorpdiff/actions/workflows/ci.yml)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.<RECORD>.svg)](https://doi.org/10.5281/zenodo.<RECORD>)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
--->
 
 **Comparative corpus analysis for modern Python workflows.**
 
@@ -40,8 +35,8 @@ 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: pre-release alpha (0.1.0a0).** Public API is stable for the
-> features described below; PyPI publication is the next milestone.
+> **Status: alpha (0.1.0a2).** Public API is stable for the features
+> described below; on PyPI as `pip install pycorpdiff`.
 
 ## The three-layer architecture
 
@@ -53,36 +48,53 @@ via extras.
 
 ## Quick start
 
+```bash
+pip install "pycorpdiff[viz,temporal]"
+```
+
 ```python
 import pycorpdiff as pcd
 
-news = pcd.from_dataframe(df, text_col="body", meta_cols=("outlet", "date"))
+# Bundled synthetic UK-Hansard corpus — runs offline, no data needed.
+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(news.slice(outlet="Guardian"), news.slice(outlet="Mail")).keyness()
-c = pcd.compare(a, b).collocation_shift("migrant")
-s = pcd.compare(a, b).semantic_shift("migrant", embedder=pcd.SBERTEmbedder())
+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(news, "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-06-23")   # segmented OLS
-tr.causal_impact(event_date="2016-06-23")             # Bayesian counterfactual (Brodersen 2015)
-tr.forecast(horizon=4)                                # state-space ETS
+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
 
 # Before / after a known event
-pcd.compare.before_after(news, event_date="2016-06-23").keyness()
+pcd.compare.before_after(corpus, event_date="2016-06-23").keyness()
 
-# N-way (≥ 2 corpora)
-pcd.keyness_multi([gu, ma, te, mi], labels=["Guardian", "Mail", "Telegraph", "Mirror"])
+# 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)
 
 # The discourse as a graph
-pcd.cooccurrence_network(news, top_n=50).plot()
+pcd.cooccurrence_network(immigration, top_n=30).plot()
 
 # Every Result: .to_df() · .plot() · .explain() · .summary() · .to_html() · .to_json()
 ```
 
+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
@@ -90,23 +102,28 @@ surface.
 
 ## Installation
 
-<!-- TODO post-publish: replace this block with the PyPI install commands once published. -->
+```bash
+pip install pycorpdiff                # lexical-comparative core
+pip install "pycorpdiff[viz]"         # + altair / matplotlib / networkx
+pip install "pycorpdiff[semantic]"    # + sentence-transformers
+pip install "pycorpdiff[temporal]"    # + ruptures / statsmodels
+pip install "pycorpdiff[notebooks]"   # + jupyter / vl-convert / pysofra
+pip install "pycorpdiff[all]"         # everything
+```
 
-Currently a pre-release alpha. From a local clone:
+The base install keeps a small dependency footprint (`numpy`, `pandas`,
+`scipy`, `pyarrow`); optional extras land per analytical layer so you
+only pay for what you use.
+
+To work from source:
 
 ```bash
 git clone https://github.com/jturner-uofl/pycorpdiff
 cd pycorpdiff
 pip install -e ".[dev]"
-pytest -q                          # 519 default tests, ~7s
+pytest -q
 ```
 
-Optional extras: `[viz]` (altair + matplotlib + networkx), `[semantic]`
-(sentence-transformers + scikit-learn), `[temporal]` (ruptures +
-statsmodels), `[polars]`, `[duckdb]`, `[huggingface]`, `[nlp]` (spaCy),
-`[notebooks]` (jupyter + vl-convert + pysofra, for the showcase),
-or `[all]`.
-
 ## Cross-validation receipts
 
 The math agrees with the standard tools — by automated test:

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycorpdiff"
-version = "0.1.0a0"
+version = "0.1.0a2"
 description = "Comparative corpus analysis for Python: keyness, collocations, semantic shift, temporal trajectories with changepoints + causal inference."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -23,7 +23,7 @@ keywords = [
     "temporal text analysis",
 ]
 classifiers = [
-    "Development Status :: 2 - Pre-Alpha",
+    "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
@@ -36,9 +36,9 @@ classifiers = [
 ]
 dependencies = [
     "numpy>=1.24",
-    # Capped at <3 to match the constraint pysofra discovered: pandas 3.x
-    # raises Pandas4Warning under strict warning filters via third-party
-    # DataFrame copies. Lift when the wider PyData stack catches up.
+    # Capped at <3: pandas 3.x raises Pandas4Warning under strict
+    # warning filters via third-party DataFrame copies. Lift when the
+    # wider PyData stack catches up.
     "pandas>=2.0,<3",
     "scipy>=1.11",
     "pyarrow>=14",
@@ -47,13 +47,12 @@ dependencies = [
 [project.optional-dependencies]
 # Visualisation: altair-first, matplotlib retained for paper-grade figures.
 viz = ["altair>=5", "matplotlib>=3.8", "networkx>=3.1"]
-# Embedding-based semantic shift (Phase 2). sentence-transformers pulls
-# torch transitively, which is why this is opt-in rather than a base dep.
+# Embedding-based semantic shift. sentence-transformers pulls torch
+# transitively, which is why this is opt-in rather than a base dep.
 semantic = ["sentence-transformers>=2.2", "scikit-learn>=1.3"]
 # Changepoint detection + interrupted time series.
 temporal = ["ruptures>=1.1", "statsmodels>=0.14"]
-# Optional columnar backend. polars.from_pandas() needs pyarrow at runtime
-# (mirrors pysofra's pinning).
+# Optional columnar backend. polars.from_pandas() needs pyarrow at runtime.
 polars = ["polars>=1.0", "pyarrow>=15"]
 # Out-of-core querying for large corpora.
 duckdb = ["duckdb>=0.10"]
@@ -92,9 +91,9 @@ dev = [
     "ruff>=0.4",
     "mypy>=1.8",
     "pre-commit>=3.6",
-    # pandas-stubs sharpens mypy strict typing for pandas surfaces (per
-    # pysofra). Without it, ignore_missing_imports would mask real
-    # typing regressions in pandas-mediated code paths.
+    # pandas-stubs sharpens mypy strict typing for pandas surfaces.
+    # Without it, ignore_missing_imports would mask real typing
+    # regressions in pandas-mediated code paths.
     "pandas-stubs>=2.2",
 ]
 [project.urls]
@@ -119,7 +118,6 @@ include = [
 exclude = [
     "docs",
     "examples",
-    "site",
     ".github",
     "uv.lock",
 ]

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

@@ -1,26 +1,25 @@
 """pycorpdiff — comparative corpus analysis for modern Python workflows.
 
 The package exposes three public verbs (:func:`compare`, :func:`track`,
-plus the :class:`Corpus` constructor and the I/O ``read_*`` helpers) and
-four families of result objects (:class:`KeynessResult`,
-:class:`CollocationShiftResult`, :class:`SemanticShiftResult`,
-:class:`TemporalTrajectory`).
-
-Layer-1 ingestion utilities are functional in this scaffolding release;
-Layer-2 analytical methods raise :class:`NotImplementedError` until Phase 1
-of the roadmap lands.
+:func:`compare.before_after`) and a family of frozen-dataclass
+result objects (:class:`KeynessResult`, :class:`CollocationShiftResult`,
+:class:`SemanticShiftResult`, :class:`TemporalTrajectory`,
+:class:`NetworkResult`, :class:`ForecastResult`,
+:class:`CausalImpactResult`, :class:`BocpdResult`,
+:class:`ConcordanceResult`), each implementing the same
+``.to_df / .plot / .explain / .summary / .to_html / .to_json`` contract.
 
 Example
 -------
 
 >>> import pycorpdiff as pcd
 >>> pcd.__version__
-'0.1.0a0'
+'0.1.0a2'
 """
 
 from __future__ import annotations
 
-__version__ = "0.1.0a0"
+__version__ = "0.1.0a2"
 
 from .collocation.network import NetworkResult, cooccurrence_network
 from .compare import Comparison, compare

{pycorpdiff-0.1.0a0 → pycorpdiff-0.1.0a2}/src/pycorpdiff/results.py

@@ -251,7 +251,16 @@ class SemanticShiftResult:
         return _table_to_json(self.table, path, **kw)
 
     def plot(self, **kw: Any) -> alt.Chart:
-        raise NotImplementedError("SemanticShiftResult.plot() lands in Phase 6")
+        """Plotting for SemanticShiftResult is not yet implemented.
+
+        For a forward-looking trajectory of cosine distances, use
+        :func:`pycorpdiff.semantic_trajectory` and pass the resulting
+        DataFrame to :func:`pycorpdiff.viz.semantic_forecast_plot`.
+        """
+        raise NotImplementedError(
+            "SemanticShiftResult.plot() is not yet implemented; "
+            "use .table or pcd.viz.semantic_forecast_plot() instead"
+        )
 
     def neighbors_before(
         self, target: str | None = None, n: int = 10

{pycorpdiff-0.1.0a0 → pycorpdiff-0.1.0a2}/tests/unit/test_smoke.py

@@ -1,10 +1,8 @@
-"""Smoke tests for the Phase 0 scaffolding.
+"""Smoke tests for the public surface.
 
-These exercise the parts of the package that are real in the scaffolding
-release: imports, the Corpus constructor, slicing, the regex tokenizer,
-and the CSV/parquet readers. Analytical methods are expected to raise
-NotImplementedError and are intentionally not exercised here — Phase 1
-will replace those tests with real ones.
+Quick exercises of imports, the :class:`Corpus` constructor, slicing,
+the default regex tokenizer, and the CSV/parquet readers. The deeper
+analytical surfaces have their own dedicated test modules.
 """
 
 from __future__ import annotations