pycorpdiff 0.1.0a0__py3-none-any.whl

pycorpdiff/temporal/forecast.py

@@ -0,0 +1,405 @@
+"""Forward prediction for :class:`TemporalTrajectory`.
+
+The other temporal modules answer *retrospective* questions —
+"when did things change", "was there a step at this known event".
+This one answers the *predictive* one: where is the trajectory
+heading, and what's the uncertainty around that?
+
+Method: state-space exponential smoothing (Hyndman et al. 2008) via
+``statsmodels.tsa.exponential_smoothing.ets.ETSModel``. Default
+``method="auto"`` selects ETS for series of length ≥ 8 and falls
+back to a Holt linear-trend model for shorter histories where ETS
+overfits. Rates are forecast on the logit scale and back-transformed
+so prediction intervals are pinned to ``[0, 1]`` instead of admitting
+nonsensical negative frequencies.
+
+Prediction intervals are the analytical PIs that come out of the
+state-space fit at the requested ``level``; for short series they
+will be appropriately wide. Honest uncertainty beats false precision.
+
+Reference
+---------
+Hyndman, R. J., Koehler, A. B., Ord, J. K., & Snyder, R. D. (2008).
+*Forecasting with Exponential Smoothing: The State Space Approach*.
+Springer.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+import numpy as np
+import pandas as pd
+
+from ..results import _table_to_html, _table_to_json
+
+if TYPE_CHECKING:
+    import altair as alt
+
+ForecastMethod = Literal["auto", "ets", "holt"]
+
+
+@dataclass(frozen=True)
+class ForecastResult:
+    """Forward prediction of a :class:`TemporalTrajectory`.
+
+    Carries both the original history (so :meth:`plot` can render the
+    solid-then-dashed continuation in a single chart) and the forecast
+    table with point estimates and prediction intervals.
+    """
+
+    history: pd.DataFrame
+    forecast: pd.DataFrame
+    targets: list[str]
+    freq: str
+    horizon: int
+    level: float
+    method: str
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_df(self) -> pd.DataFrame:
+        """Return just the forecast table (point + PI per term × period)."""
+        return self.forecast.copy()
+
+    def to_combined(self) -> pd.DataFrame:
+        """Return history + forecast stacked, with a ``kind`` column
+        distinguishing the two."""
+        h = self.history.copy()
+        h["kind"] = "observed"
+        h = h.rename(columns={"relfreq": "point"})[
+            ["period", "term", "point", "ci_lower", "ci_upper", "kind"]
+        ]
+        f = self.forecast.copy()
+        f["kind"] = "forecast"
+        return pd.concat([h, f[h.columns]], ignore_index=True)
+
+    def to_html(self, path: str | Path | None = None, **kw: Any) -> str:
+        """Render the forecast table as HTML."""
+        return _table_to_html(self.forecast, path, **kw)
+
+    def to_json(self, path: str | Path | None = None, **kw: Any) -> str:
+        """Render the forecast table as JSON."""
+        return _table_to_json(self.forecast, path, **kw)
+
+    def plot(self, **kw: Any) -> alt.Chart:
+        """Layered altair chart: solid observed + dashed forecast.
+
+        The history portion shows the existing Wilson CI band; the
+        forecast portion shows the prediction-interval band at the
+        chosen ``level``.
+        """
+        from ..viz.forecast import forecast_plot
+
+        return forecast_plot(
+            history=self.history, forecast=self.forecast, **kw
+        )
+
+    def summary(self) -> str:
+        return (
+            f"ForecastResult(targets={self.targets!r}, freq={self.freq!r}, "
+            f"horizon={self.horizon}, level={self.level}, method={self.method})"
+        )
+
+
+def forecast_trajectory(
+    trajectory_table: pd.DataFrame,
+    *,
+    targets: Sequence[str] | None = None,
+    horizon: int = 4,
+    level: float = 0.95,
+    method: ForecastMethod = "auto",
+    logit_transform: bool = True,
+) -> pd.DataFrame:
+    """Forecast every (or selected) target term's trajectory ``horizon``
+    periods forward.
+
+    Parameters
+    ----------
+    trajectory_table
+        The DataFrame attached to a :class:`TemporalTrajectory` —
+        must carry ``period``, ``term``, ``relfreq`` columns at minimum.
+    targets
+        Which terms to forecast. ``None`` (default) forecasts every
+        term present in the table.
+    horizon
+        Number of periods to extrapolate.
+    level
+        Prediction-interval level. ``0.95`` → 95% PI.
+    method
+        ``"auto"`` (default) picks ETS for series of length ≥ 8, Holt
+        otherwise. ``"ets"`` or ``"holt"`` force a specific method.
+    logit_transform
+        If ``True`` (default), forecast on the logit scale and
+        back-transform so the prediction intervals stay in ``[0, 1]``.
+        Disable only if forecasting something other than a rate.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns: ``period``, ``term``, ``point``, ``ci_lower``,
+        ``ci_upper``. One row per (target, future period). Period
+        values match the freq of the input trajectory.
+    """
+    if horizon < 1:
+        raise ValueError(f"horizon must be >= 1; got {horizon}")
+    if not 0 < level < 1:
+        raise ValueError(f"level must be in (0, 1); got {level}")
+
+    if targets is None:
+        target_list = list(trajectory_table["term"].unique())
+    else:
+        target_list = list(targets)
+        missing = set(target_list) - set(trajectory_table["term"].unique())
+        if missing:
+            raise ValueError(
+                f"unknown targets: {sorted(missing)!r}; "
+                f"trajectory carries {sorted(trajectory_table['term'].unique())!r}"
+            )
+
+    rows: list[pd.DataFrame] = []
+    for term in target_list:
+        sub = (
+            trajectory_table[trajectory_table["term"] == term]
+            .sort_values("period")
+            .set_index("period")["relfreq"]
+        )
+        if sub.isna().any():
+            sub = sub.dropna()
+        if len(sub) < 4:
+            raise ValueError(
+                f"need at least 4 observations to forecast {term!r}; "
+                f"got {len(sub)}"
+            )
+        fc = _forecast_one(
+            sub,
+            horizon=horizon,
+            level=level,
+            method=method,
+            logit_transform=logit_transform,
+        )
+        fc.insert(1, "term", term)
+        rows.append(fc)
+
+    return pd.concat(rows, ignore_index=True)
+
+
+def forecast_semantic_drift(
+    trajectory_df: pd.DataFrame,
+    *,
+    targets: Sequence[str] | None = None,
+    horizon: int = 4,
+    level: float = 0.95,
+    method: ForecastMethod = "auto",
+) -> pd.DataFrame:
+    """Forecast a :func:`pycorpdiff.semantic_trajectory` output forward.
+
+    Operates on the ``distance_from_baseline`` column — the cosine
+    displacement of each per-period contextual centroid from the
+    baseline period. Same state-space machinery as
+    :func:`forecast_trajectory`, but the logit transform is *off* by
+    default (cosine distance lives in roughly ``[0, 2]``, not
+    ``[0, 1]``) and the prediction interval is clipped to be
+    non-negative since negative cosine *distance* is nonsensical.
+
+    Parameters
+    ----------
+    trajectory_df
+        The DataFrame returned by :func:`pycorpdiff.semantic_trajectory`
+        — must carry ``period``, ``target``, ``distance_from_baseline``
+        columns.
+    targets
+        Restrict to a subset of targets. ``None`` forecasts every
+        target in the table.
+    horizon
+        Number of periods to extrapolate.
+    level
+        Prediction-interval level. ``0.95`` → 95% PI.
+    method
+        ``"auto"`` (default), ``"ets"``, or ``"holt"``.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Columns: ``period``, ``target``, ``point``, ``ci_lower``,
+        ``ci_upper``. One row per (target, future period).
+    """
+    if horizon < 1:
+        raise ValueError(f"horizon must be >= 1; got {horizon}")
+    if not 0 < level < 1:
+        raise ValueError(f"level must be in (0, 1); got {level}")
+
+    required_cols = {"period", "target", "distance_from_baseline"}
+    missing = required_cols - set(trajectory_df.columns)
+    if missing:
+        raise ValueError(
+            f"trajectory_df is missing required columns: {sorted(missing)!r}"
+        )
+
+    if targets is None:
+        target_list = list(trajectory_df["target"].unique())
+    else:
+        target_list = list(targets)
+        unknown = set(target_list) - set(trajectory_df["target"].unique())
+        if unknown:
+            raise ValueError(
+                f"unknown targets: {sorted(unknown)!r}; "
+                f"trajectory carries {sorted(trajectory_df['target'].unique())!r}"
+            )
+
+    rows: list[pd.DataFrame] = []
+    for tgt in target_list:
+        sub = (
+            trajectory_df[trajectory_df["target"] == tgt]
+            .sort_values("period")
+            .set_index("period")["distance_from_baseline"]
+        )
+        sub = sub.dropna()
+        if len(sub) < 4:
+            raise ValueError(
+                f"need at least 4 observations to forecast {tgt!r}; "
+                f"got {len(sub)}"
+            )
+        fc = _forecast_one(
+            sub,
+            horizon=horizon,
+            level=level,
+            method=method,
+            logit_transform=False,
+        )
+        # Clip lower bound at 0 — cosine distance is non-negative.
+        fc["ci_lower"] = fc["ci_lower"].clip(lower=0.0)
+        fc["point"] = fc["point"].clip(lower=0.0)
+        fc.insert(1, "target", tgt)
+        rows.append(fc)
+
+    return pd.concat(rows, ignore_index=True)
+
+
+def _forecast_one(
+    series: pd.Series,
+    *,
+    horizon: int,
+    level: float,
+    method: ForecastMethod,
+    logit_transform: bool,
+) -> pd.DataFrame:
+    """Forecast a single univariate rate series.
+
+    Returns a DataFrame with columns ``period``, ``point``,
+    ``ci_lower``, ``ci_upper``. Period values are constructed from the
+    input series's PeriodIndex.
+    """
+    try:
+        from statsmodels.tsa.exponential_smoothing.ets import ETSModel
+        from statsmodels.tsa.holtwinters import Holt
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "forecast() requires statsmodels. "
+            "Install with: pip install 'pycorpdiff[temporal]'"
+        ) from exc
+
+    # statsmodels prefers a DatetimeIndex with a known freq for ETS —
+    # convert from PeriodIndex and attach the inferred frequency so the
+    # state-space model can extrapolate cleanly.
+    ts_series = series.copy()
+    if isinstance(series.index, pd.PeriodIndex):
+        period_freq = series.index.freq
+        ts_index = series.index.to_timestamp()
+        inferred = getattr(ts_index, "inferred_freq", None)
+        ts_series.index = (
+            pd.DatetimeIndex(ts_index, freq=inferred) if inferred else ts_index
+        )
+    else:
+        period_freq = None
+
+    if logit_transform:
+        eps = 1e-6
+        y_arr = np.clip(ts_series.to_numpy(dtype=float), eps, 1.0 - eps)
+        z = pd.Series(
+            np.log(y_arr / (1.0 - y_arr)),
+            index=ts_series.index,
+            name=ts_series.name,
+        )
+    else:
+        z = ts_series.astype(float)
+
+    chosen = method
+    if chosen == "auto":
+        chosen = "ets" if len(z) >= 8 else "holt"
+
+    alpha = 1.0 - level
+
+    if chosen == "ets":
+        model = ETSModel(
+            z, error="add", trend="add", seasonal=None
+        ).fit(disp=False)
+        pred = model.get_prediction(start=len(z), end=len(z) + horizon - 1)
+        summary = pred.summary_frame(alpha=alpha)
+        z_point = summary["mean"].to_numpy(dtype=float)
+        z_lower = summary["pi_lower"].to_numpy(dtype=float)
+        z_upper = summary["pi_upper"].to_numpy(dtype=float)
+    elif chosen == "holt":
+        holt = Holt(z, initialization_method="estimated").fit()
+        # Holt has no analytical PI in older statsmodels — use
+        # forecast_int via simulate-based intervals.
+        z_point = np.asarray(holt.forecast(steps=horizon), dtype=float)
+        # Residual-based PI (Hyndman §6.4): std of fitted residuals
+        # widens with sqrt(h) under the additive-error assumption.
+        resid_std = float(np.std(holt.resid, ddof=1))
+        from scipy.stats import norm
+
+        crit = float(norm.ppf(1.0 - alpha / 2.0))
+        h_steps = np.arange(1, horizon + 1, dtype=float)
+        widening = crit * resid_std * np.sqrt(h_steps)
+        z_lower = z_point - widening
+        z_upper = z_point + widening
+    else:
+        raise ValueError(
+            f"unknown method={chosen!r}; expected 'auto', 'ets', or 'holt'"
+        )
+
+    if logit_transform:
+        point = _inv_logit(z_point)
+        lower = _inv_logit(z_lower)
+        upper = _inv_logit(z_upper)
+    else:
+        point = z_point
+        lower = z_lower
+        upper = z_upper
+
+    # Future periods — match original index type.
+    if period_freq is not None and isinstance(series.index, pd.PeriodIndex):
+        last_period = series.index[-1]
+        future_periods = pd.period_range(
+            start=last_period + 1, periods=horizon, freq=period_freq
+        )
+        future_idx: pd.Index = pd.Index(future_periods)
+    else:
+        last_ts = series.index[-1]
+        inferred = getattr(series.index, "inferred_freq", None) or "D"
+        offset = pd.tseries.frequencies.to_offset(inferred)
+        future_idx = pd.date_range(
+            start=last_ts + offset, periods=horizon, freq=offset
+        )
+
+    return pd.DataFrame(
+        {
+            "period": future_idx,
+            "point": point,
+            "ci_lower": lower,
+            "ci_upper": upper,
+        }
+    )
+
+
+def _inv_logit(x: np.ndarray) -> np.ndarray:
+    """Numerically-stable inverse logit."""
+    out: np.ndarray = np.where(
+        x >= 0,
+        1.0 / (1.0 + np.exp(-x)),
+        np.exp(x) / (1.0 + np.exp(x)),
+    )
+    return out

pycorpdiff/temporal/its.py

@@ -0,0 +1,123 @@
+"""Interrupted time-series analysis around a known event date.
+
+Implements the standard segmented-regression specification:
+
+    y_t = β₀ + β₁·t + β₂·post_t + β₃·(t − t_event)·post_t + ε
+
+where ``post_t`` is 1 when ``t ≥ t_event`` and 0 otherwise. The
+coefficients of interest:
+
+- ``β₂`` (level change): the immediate step at the intervention.
+- ``β₃`` (slope change): how the post-period trend differs from
+  the pre-period trend.
+
+Reference
+---------
+Wagner, A. K., Soumerai, S. B., Zhang, F., & Ross-Degnan, D. (2002).
+Segmented regression analysis of interrupted time series studies in
+medication use research. *Journal of Clinical Pharmacy and
+Therapeutics*, 27(4), 299-309.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+
+def interrupted_time_series(
+    series: pd.Series,
+    event_date: str | pd.Period | pd.Timestamp,
+) -> pd.DataFrame:
+    """Fit a segmented-regression ITS model around ``event_date``.
+
+    Parameters
+    ----------
+    series
+        A series indexed by period (or datetime). Index values must
+        compare against ``event_date`` to produce the pre/post split.
+    event_date
+        Where to place the intervention. Anything pandas can compare to
+        the series index — a string, a :class:`pandas.Period`, a
+        :class:`pandas.Timestamp`.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Four rows (one per coefficient), columns ``term``, ``coef``,
+        ``std_err``, ``t``, ``p_value``, ``ci_lower``, ``ci_upper``.
+        ``term`` values: ``"intercept"``, ``"time"``, ``"level_change"``,
+        ``"slope_change"``.
+    """
+    try:
+        import statsmodels.api as sm
+    except ImportError as exc:  # pragma: no cover
+        raise ImportError(
+            "interrupted_time_series requires statsmodels. "
+            "Install with: pip install 'pycorpdiff[temporal]'"
+        ) from exc
+
+    if len(series) < 4:
+        raise ValueError(f"need at least 4 observations; got {len(series)}")
+    if series.isna().any():
+        raise ValueError("series contains NaN values; impute or drop them first")
+
+    y = series.to_numpy(dtype=float)
+    # Use a 0-based time index — coefficients are then interpretable as
+    # "per period" effects without anchoring to a Unix epoch.
+    t = np.arange(len(series), dtype=float)
+
+    event_norm = _normalise_event(event_date, series)
+    # Find the first index where index value is >= event_date.
+    idx = series.index
+    post_mask = np.array([_ge(period, event_norm) for period in idx], dtype=int)
+    if post_mask.sum() == 0:
+        raise ValueError(f"event_date={event_date!r} is after the last period")
+    if post_mask.sum() == len(series):
+        raise ValueError(f"event_date={event_date!r} is before the first period")
+
+    event_t = float(t[post_mask.astype(bool)][0])
+    time_after = (t - event_t) * post_mask
+
+    x = np.column_stack([np.ones_like(t), t, post_mask.astype(float), time_after])
+    model = sm.OLS(y, x).fit()
+
+    conf_int = model.conf_int()
+    terms = ["intercept", "time", "level_change", "slope_change"]
+    return pd.DataFrame(
+        {
+            "term": terms,
+            "coef": model.params,
+            "std_err": model.bse,
+            "t": model.tvalues,
+            "p_value": model.pvalues,
+            "ci_lower": conf_int[:, 0],
+            "ci_upper": conf_int[:, 1],
+        }
+    )
+
+
+def _normalise_event(
+    event: str | pd.Period | pd.Timestamp, series: pd.Series
+) -> pd.Period | pd.Timestamp:
+    """Coerce ``event`` to the same type as the series index for comparison.
+
+    The pandas type hierarchy here is a bit fiddly: ``Period`` and
+    ``Timestamp`` aren't directly comparable, and ``Period(event,
+    freq=BaseOffset)`` isn't accepted by mypy even though it works at
+    runtime. We route through string forms where types disagree.
+    """
+    sample = series.index[0]
+    if isinstance(sample, pd.Period):
+        if isinstance(event, pd.Period):
+            return event
+        freqstr: str = str(sample.freqstr)
+        return pd.Period(str(event), freq=freqstr)
+    if isinstance(event, pd.Period):
+        return pd.Timestamp(str(event))
+    return pd.Timestamp(event)
+
+
+def _ge(period_index_value: object, event: object) -> bool:
+    """``period_index_value >= event`` with sensible coercions."""
+    return bool(period_index_value >= event)  # type: ignore[operator]

pycorpdiff/temporal/slicing.py

@@ -0,0 +1,174 @@
+"""Temporal slicing primitives — ``TemporalCorpus``, ``track``, ``Tracker``."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+import numpy as np
+import pandas as pd
+
+from ..corpus import Corpus, CorpusSlice
+from ..results import TemporalTrajectory
+from ..stats import wilson_ci
+
+
+@dataclass(frozen=True)
+class TemporalCorpus:
+    """A corpus indexed by time period for diachronic analysis.
+
+    Constructed via :meth:`pycorpdiff.Corpus.by_time`; bucketing of the
+    parent corpus's ``time_col`` follows the pandas offset alias
+    ``freq``. Periods with no documents are skipped — there's no
+    silent-zero entry in :meth:`periods` or :meth:`iter_slices`.
+    """
+
+    parent: Corpus
+    time_col: str
+    freq: str = "Y"
+
+    def __len__(self) -> int:
+        return len(self.parent)
+
+    def _period_series(self) -> pd.Series:
+        """Per-document Period values, indexed like the parent's docs frame."""
+        times = pd.to_datetime(self.parent.docs[self.time_col])
+        return times.dt.to_period(self.freq)
+
+    def periods(self) -> list[pd.Period]:
+        """Sorted list of populated periods."""
+        return sorted(self._period_series().unique())
+
+    def slice(self, period: pd.Period | str) -> CorpusSlice:
+        """Return the :class:`CorpusSlice` for one period.
+
+        ``period`` may be a :class:`pandas.Period` or any string pandas
+        can parse to one (e.g. ``"2020"``, ``"2020Q1"``, ``"2020-03"``).
+        """
+        idx = self._period_series()
+        period_obj = pd.Period(period, freq=self.freq) if isinstance(period, str) else period
+        mask = pd.Series(idx.values == period_obj, index=self.parent.docs.index)
+        return CorpusSlice(
+            parent=self.parent,
+            mask=mask,
+            filters={"period": str(period_obj)},
+        )
+
+    def iter_slices(self) -> Iterator[tuple[pd.Period, CorpusSlice]]:
+        """Yield ``(period, CorpusSlice)`` pairs in chronological order."""
+        idx = self._period_series()
+        for period in self.periods():
+            mask = pd.Series(idx.values == period, index=self.parent.docs.index)
+            yield period, CorpusSlice(
+                parent=self.parent, mask=mask, filters={"period": str(period)}
+            )
+
+
+@dataclass(frozen=True)
+class Tracker:
+    """A diachronic tracker over one or more target terms."""
+
+    corpus: Corpus | CorpusSlice
+    targets: list[str]
+
+    def over_time(
+        self,
+        freq: str = "Y",
+        time_col: str = "date",
+        confidence: float = 0.95,
+    ) -> TemporalTrajectory:
+        """Return a :class:`TemporalTrajectory` of relative frequencies.
+
+        For every populated period × target, computes the raw count,
+        period token total, relative frequency, and a Wilson score
+        interval at ``confidence`` (default 95%). The output frame has
+        one row per (period, term) pair, sorted by term then period.
+        """
+        temporal = self.corpus.by_time(time_col, freq)
+        rows: list[dict[str, object]] = []
+        for period, slice_ in temporal.iter_slices():
+            tokens_per_doc = slice_.tokens()
+            all_tokens: list[str] = [tok for doc in tokens_per_doc for tok in doc]
+            total = len(all_tokens)
+            counter = pd.Series(all_tokens).value_counts() if total else pd.Series(dtype=int)
+            for target in self.targets:
+                count = int(counter.get(target, 0))
+                relfreq = (count / total) if total > 0 else float("nan")
+                lo, hi = wilson_ci(
+                    np.array([count], dtype=np.int64),
+                    np.array([total], dtype=np.int64),
+                    confidence=confidence,
+                )
+                rows.append(
+                    {
+                        "period": period,
+                        "term": target,
+                        "count": count,
+                        "total": total,
+                        "relfreq": relfreq,
+                        "ci_lower": float(lo[0]),
+                        "ci_upper": float(hi[0]),
+                    }
+                )
+        table = (
+            pd.DataFrame(rows)
+            .sort_values(["term", "period"], kind="stable")
+            .reset_index(drop=True)
+        )
+        return TemporalTrajectory(table=table, targets=list(self.targets), freq=freq)
+
+    def trajectory(
+        self,
+        freq: str = "Y",
+        time_col: str = "date",
+        confidence: float = 0.95,
+    ) -> TemporalTrajectory:
+        """Alias for :meth:`over_time`."""
+        return self.over_time(freq=freq, time_col=time_col, confidence=confidence)
+
+    def semantic_over_time(
+        self,
+        freq: str = "Y",
+        time_col: str = "date",
+        embedder: object | None = None,
+        window: int = 5,
+        baseline_period: str | None = None,
+    ) -> pd.DataFrame:
+        """Track each target's *contextual centroid* across time periods.
+
+        Where :meth:`over_time` returns relative frequencies, this
+        returns a semantic trajectory: per-period averaged contextual
+        embeddings with cosine distance to a baseline period. With
+        SBERT this surfaces meaning shifts that pure frequency
+        analysis misses.
+
+        See :func:`pycorpdiff.semantic.semantic_trajectory` for the
+        full parameter docs.
+        """
+        from ..semantic.shift import (  # noqa: F401 — keeps the import side-effect close to the use
+            semantic_shift,
+        )
+        from ..semantic.trajectory import semantic_trajectory
+
+        return semantic_trajectory(
+            self.corpus,
+            target=self.targets if len(self.targets) > 1 else self.targets[0],
+            time_col=time_col,
+            freq=freq,
+            embedder=embedder,  # type: ignore[arg-type]
+            window=window,
+            baseline_period=baseline_period,
+        )
+
+
+def track(
+    corpus: Corpus | CorpusSlice, target: str | list[str]
+) -> Tracker:
+    """Construct a :class:`Tracker` for diachronic analysis of target term(s).
+
+    Accepts either a :class:`Corpus` or a :class:`CorpusSlice`, so
+    ``pcd.track(corpus.slice(topic="immigration"), "criminal")`` works
+    out of the box.
+    """
+    targets = [target] if isinstance(target, str) else list(target)
+    return Tracker(corpus=corpus, targets=targets)