pycorpdiff 0.1.0a0__py3-none-any.whl

pycorpdiff/viz/forecast.py

@@ -0,0 +1,129 @@
+"""Forecast plot — solid history continues into dashed forecast.
+
+Visual grammar: the same Wilson-CI band + line + points the trajectory
+plot already uses for observed periods, then a *dashed* line + lighter
+prediction-interval band for the forecast horizon. The visual handoff
+between the two regions is what makes the chart read "this is the
+observed history, this is what we project forward".
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+def forecast_plot(
+    history: pd.DataFrame,
+    forecast: pd.DataFrame,
+    width: int = 600,
+    height: int = 320,
+) -> alt.Chart:
+    """Layered plot: observed Wilson-CI trajectory + dashed forecast band.
+
+    Parameters
+    ----------
+    history
+        The trajectory table — must carry ``period``, ``term``,
+        ``relfreq``, ``ci_lower``, ``ci_upper``.
+    forecast
+        The forecast table — must carry ``period``, ``term``,
+        ``point``, ``ci_lower``, ``ci_upper``.
+    width, height
+        Canvas dimensions.
+    """
+    import altair as alt
+
+    h = history.copy()
+    f = forecast.copy()
+    if isinstance(h["period"].iloc[0], pd.Period):
+        h["period"] = h["period"].apply(lambda p: p.to_timestamp())
+    if len(f) and isinstance(f["period"].iloc[0], pd.Period):
+        f["period"] = f["period"].apply(lambda p: p.to_timestamp())
+
+    base_h = alt.Chart(h).encode(
+        x=alt.X("period:T", title=None),
+        color=alt.Color("term:N", title=None),
+    )
+    history_band = base_h.mark_area(opacity=0.18).encode(
+        y=alt.Y("ci_lower:Q", title="Relative frequency"),
+        y2="ci_upper:Q",
+    )
+    history_line = base_h.mark_line(strokeWidth=2).encode(
+        y="relfreq:Q",
+        tooltip=[
+            "period",
+            "term",
+            "count",
+            "total",
+            alt.Tooltip("relfreq:Q", format=".5f"),
+            alt.Tooltip("ci_lower:Q", format=".5f"),
+            alt.Tooltip("ci_upper:Q", format=".5f"),
+        ],
+    )
+    history_points = base_h.mark_point(filled=True, size=50).encode(
+        y="relfreq:Q",
+    )
+
+    base_f = alt.Chart(f).encode(
+        x=alt.X("period:T", title=None),
+        color=alt.Color("term:N", title=None),
+    )
+    forecast_band = base_f.mark_area(opacity=0.12).encode(
+        y=alt.Y("ci_lower:Q"),
+        y2="ci_upper:Q",
+    )
+    forecast_line = base_f.mark_line(strokeDash=[6, 4], strokeWidth=2).encode(
+        y="point:Q",
+        tooltip=[
+            "period",
+            "term",
+            alt.Tooltip("point:Q", format=".5f"),
+            alt.Tooltip("ci_lower:Q", format=".5f"),
+            alt.Tooltip("ci_upper:Q", format=".5f"),
+        ],
+    )
+    forecast_points = base_f.mark_point(
+        filled=False, strokeWidth=2, size=50
+    ).encode(y="point:Q")
+
+    # Stitch history + forecast at the seam: a connector line from the
+    # last observed value to the first forecast point so the chart
+    # reads as a single trajectory rather than two disconnected lines.
+    if len(f) and len(h):
+        last_h = h.sort_values("period").groupby("term").tail(1)
+        first_f = f.sort_values("period").groupby("term").head(1)
+        seam = pd.concat(
+            [
+                last_h.assign(point=last_h["relfreq"])[
+                    ["period", "term", "point"]
+                ],
+                first_f[["period", "term", "point"]],
+            ]
+        )
+        seam_line = (
+            alt.Chart(seam)
+            .mark_line(strokeDash=[6, 4], strokeWidth=2, opacity=0.55)
+            .encode(
+                x="period:T",
+                y="point:Q",
+                color=alt.Color("term:N", legend=None),
+            )
+        )
+    else:
+        seam_line = alt.Chart(pd.DataFrame({"period": [], "point": [], "term": []}))
+
+    chart = (
+        history_band
+        + history_line
+        + history_points
+        + seam_line
+        + forecast_band
+        + forecast_line
+        + forecast_points
+    ).properties(width=width, height=height)
+    return chart  # type: ignore[no-any-return]

pycorpdiff/viz/keyness.py

@@ -0,0 +1,96 @@
+"""Keyness visualisations — volcano plot and top-N bar chart."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+def keyness_volcano(
+    df: pd.DataFrame,
+    width: int = 600,
+    height: int = 400,
+    n_labels: int = 15,
+) -> alt.Chart:
+    """Volcano-style scatter: effect size (x) versus significance (y).
+
+    Expects the columns produced by :meth:`Comparison.keyness`:
+    ``term``, ``log_ratio`` (or fall back to ``g2``), and ``p_value``.
+    The top ``n_labels`` rows by ``|log_ratio|`` get a text label;
+    everything else is plotted as a circle only.
+    """
+    import altair as alt
+
+    if "log_ratio" in df.columns:
+        x_col = "log_ratio"
+        x_title = "LogRatio (positive = overused in A)"
+    else:
+        x_col = "g2"
+        x_title = "Signed G² (positive = overused in A)"
+
+    # Significance axis: -log10(p), with infinities clipped at a sensible cap
+    # so a single near-zero p doesn't crush the rest of the plot vertically.
+    with np.errstate(divide="ignore"):
+        neg_log_p = -np.log10(np.clip(df["p_value"].to_numpy(), 1e-300, 1.0))
+    plot_df = df.assign(neg_log_p=neg_log_p)
+
+    base = alt.Chart(plot_df).encode(
+        x=alt.X(f"{x_col}:Q", title=x_title),
+        y=alt.Y("neg_log_p:Q", title="−log₁₀(p)"),
+        tooltip=list(df.columns),
+    )
+    points = base.mark_circle(opacity=0.55, size=60).encode(
+        color=alt.condition(
+            alt.datum[x_col] >= 0,
+            alt.value("#1f77b4"),  # A-leaning
+            alt.value("#d62728"),  # B-leaning
+        )
+    )
+    label_subset = plot_df.assign(_abs=plot_df[x_col].abs()).nlargest(n_labels, "_abs")
+    labels = alt.Chart(label_subset).mark_text(align="left", dx=6, fontSize=10).encode(
+        x=f"{x_col}:Q",
+        y="neg_log_p:Q",
+        text="term:N",
+    )
+    return (points + labels).properties(width=width, height=height)  # type: ignore[no-any-return]
+
+
+def keyness_top_n_bar(
+    df: pd.DataFrame,
+    n: int = 20,
+    width: int = 500,
+    height: int | None = None,
+) -> alt.Chart:
+    """Top-N horizontal bar chart, sorted by ``|g2|`` (signed).
+
+    Positive bars are A-leaning, negative are B-leaning. Useful when
+    you want a clean publication-ready figure rather than the
+    information-dense volcano.
+    """
+    import altair as alt
+
+    subset = df.assign(_abs=df["g2"].abs()).nlargest(n, "_abs").drop(columns="_abs")
+    if height is None:
+        height = max(200, 18 * len(subset))
+
+    chart = (
+        alt.Chart(subset)
+        .mark_bar()
+        .encode(
+            x=alt.X("g2:Q", title="Signed G²"),
+            y=alt.Y("term:N", sort="-x", title=None),
+            color=alt.condition(
+                alt.datum.g2 >= 0,
+                alt.value("#1f77b4"),
+                alt.value("#d62728"),
+            ),
+            tooltip=list(subset.columns),
+        )
+        .properties(width=width, height=height)
+    )
+    return chart  # type: ignore[no-any-return]

pycorpdiff/viz/network.py

@@ -0,0 +1,186 @@
+"""Network plot for term co-occurrence graphs.
+
+Renders a :class:`pycorpdiff.collocation.NetworkResult` as an altair
+chart with circles for nodes, rules for edges, and text labels. Node
+positions come from a spring-force layout if ``networkx`` is
+installed; otherwise the nodes fall back to a circular layout, which
+still gives a structurally faithful (if visually flatter) picture.
+
+altair is intentionally pinned at the ``[viz]`` extra to avoid pulling
+heavyweight rendering deps into the base install.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    import altair as alt
+
+    from ..collocation.network import NetworkResult
+
+
+def network_plot(
+    result: NetworkResult,
+    *,
+    width: int = 700,
+    height: int = 700,
+    max_edges: int = 100,
+    label_top_n: int = 30,
+    seed: int = 0,
+) -> alt.Chart:
+    """Plot a :class:`NetworkResult` as a force-directed-style network.
+
+    Parameters
+    ----------
+    result
+        The network to render.
+    width, height
+        Canvas dimensions in pixels. Square by default.
+    max_edges
+        Only the top ``max_edges`` edges by ``|weight|`` are drawn,
+        preventing dense networks from rendering as a black blob.
+    label_top_n
+        Inline-label budget. Only the ``label_top_n`` highest-degree
+        nodes get text labels next to their dot; the others remain
+        bare circles with hover tooltips.
+    seed
+        Random seed for the spring layout's starting configuration.
+    """
+    import altair as alt
+
+    nodes = result.nodes.copy()
+    edges = result.edges.head(max_edges).copy()
+
+    positions = _layout(nodes, edges, seed=seed)
+    nodes_xy = nodes.join(positions, how="left").reset_index(names="term")
+
+    # Edge endpoints — attach source / target coordinates.
+    edges_xy = edges.merge(
+        positions.rename(columns={"x": "x_src", "y": "y_src"}),
+        left_on="source",
+        right_index=True,
+    ).merge(
+        positions.rename(columns={"x": "x_tgt", "y": "y_tgt"}),
+        left_on="target",
+        right_index=True,
+    )
+
+    edge_layer = (
+        alt.Chart(edges_xy)
+        .mark_rule(opacity=0.35, color="#777")
+        .encode(
+            x=alt.X("x_src:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            y=alt.Y("y_src:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            x2="x_tgt:Q",
+            y2="y_tgt:Q",
+            strokeWidth=alt.Size(
+                "weight:Q",
+                scale=alt.Scale(range=[0.5, 4]),
+                legend=alt.Legend(title=f"Edge weight ({result.measure})"),
+            ),
+            tooltip=["source:N", "target:N", "cooccur_count:Q", "weight:Q"],
+        )
+    )
+
+    node_layer = (
+        alt.Chart(nodes_xy)
+        .mark_circle(opacity=0.85, color="#1f77b4")
+        .encode(
+            x=alt.X("x:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            y=alt.Y("y:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            size=alt.Size(
+                "count:Q",
+                scale=alt.Scale(range=[80, 600]),
+                legend=alt.Legend(title="Term frequency"),
+            ),
+            tooltip=["term:N", "count:Q", "degree:Q"],
+        )
+    )
+
+    labelled = nodes_xy.sort_values("degree", ascending=False).head(label_top_n)
+    label_layer = (
+        alt.Chart(labelled)
+        .mark_text(dy=-10, fontSize=11, fontWeight="bold")
+        .encode(
+            x=alt.X("x:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            y=alt.Y("y:Q", axis=None, scale=alt.Scale(domain=[-1.1, 1.1])),
+            text="term:N",
+        )
+    )
+
+    chart = (
+        (edge_layer + node_layer + label_layer)
+        .properties(width=width, height=height)
+        .configure_view(strokeWidth=0)
+        .interactive()
+    )
+    return chart  # type: ignore[no-any-return]
+
+
+def _layout(
+    nodes: pd.DataFrame,
+    edges: pd.DataFrame,
+    seed: int = 0,
+) -> pd.DataFrame:
+    """Compute ``(x, y)`` for every node.
+
+    Uses ``networkx.spring_layout`` if available; otherwise falls back
+    to a circular layout (still a valid plot, just less informative).
+    Returns a DataFrame indexed by term with ``x`` and ``y`` columns
+    rescaled to ``[-1, 1]``.
+    """
+    try:
+        import networkx as nx
+    except ImportError:
+        return _circular_layout(nodes.index.tolist())
+
+    g = nx.Graph()
+    for term in nodes.index:
+        g.add_node(term)
+    for _, row in edges.iterrows():
+        g.add_edge(row["source"], row["target"], weight=abs(float(row["weight"])))
+
+    # Kamada-Kawai produces more uniformly-spaced layouts than the
+    # default spring algorithm on densely-connected graphs, which is
+    # the common case for corpus discourse networks (every top term
+    # tends to co-occur with many others). Falls back to a high-k
+    # spring layout for disconnected graphs (KK requires connectivity).
+    n = max(1, g.number_of_nodes())
+    try:
+        if nx.is_connected(g):
+            pos = nx.kamada_kawai_layout(g)
+        else:
+            pos = nx.spring_layout(
+                g, seed=seed, k=2.5 / math.sqrt(n), iterations=200
+            )
+    except (nx.NetworkXError, ValueError):
+        pos = nx.spring_layout(
+            g, seed=seed, k=2.5 / math.sqrt(n), iterations=200
+        )
+    coords = pd.DataFrame(
+        {"x": [pos[t][0] for t in nodes.index], "y": [pos[t][1] for t in nodes.index]},
+        index=nodes.index,
+    )
+    # Rescale to a square in [-1, 1].
+    for col in ("x", "y"):
+        lo, hi = coords[col].min(), coords[col].max()
+        span = hi - lo if hi != lo else 1.0
+        coords[col] = 2.0 * (coords[col] - lo) / span - 1.0
+    return coords
+
+
+def _circular_layout(terms: list[str]) -> pd.DataFrame:
+    """Fallback layout when ``networkx`` isn't installed."""
+    n = len(terms)
+    coords = {
+        t: (math.cos(2 * math.pi * i / n), math.sin(2 * math.pi * i / n))
+        for i, t in enumerate(terms)
+    }
+    return pd.DataFrame(
+        {"x": [coords[t][0] for t in terms], "y": [coords[t][1] for t in terms]},
+        index=terms,
+    )

pycorpdiff/viz/scattertext.py

@@ -0,0 +1,160 @@
+"""Scattertext-style interactive scatter (Kessler 2017).
+
+The signature Scattertext visualisation. Each term is a point whose
+x-axis position is its rank-percentile in corpus A and whose y-axis
+position is its rank-percentile in corpus B. Words common in both
+land in the top-right corner; words common in only one side fall away
+from the diagonal into one of the two off-diagonal "distinctiveness"
+zones; words rare in both cluster near the origin.
+
+The rank-based axes are the trick that makes Scattertext readable.
+Plotting raw counts produces a plot dominated by stopwords in the
+top-right corner with everything else crushed into the bottom-left;
+rank-percentiles spread the whole vocabulary evenly across [0, 1].
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+import pandas as pd
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+def scattertext_plot(
+    df: pd.DataFrame,
+    *,
+    label_a: str = "a",
+    label_b: str = "b",
+    width: int = 600,
+    height: int = 600,
+    n_labels: int = 20,
+) -> alt.Chart:
+    """Scattertext-style interactive scatter of keyness terms.
+
+    Expects the columns produced by :meth:`Comparison.keyness`:
+    ``term``, ``count_a``, ``count_b``, and ``g2`` (the signed
+    log-likelihood used as the colour channel). ``log_ratio`` is used
+    in the tooltip when present.
+
+    The chart is pan/zoom-able and every point has a hover tooltip
+    listing the raw counts and effect sizes. The ``n_labels`` most
+    A-leaning and ``n_labels`` most B-leaning terms (by ``|g2|``) get
+    inline text labels — others remain dots.
+
+    Parameters
+    ----------
+    df
+        A KeynessResult-shaped DataFrame.
+    label_a, label_b
+        Axis titles — usually the corpus labels carried on the result.
+    width, height
+        Square by default (600×600); the rank-percentile axes deserve
+        equal visual weight.
+    n_labels
+        Per-side label budget. ``n_labels=20`` produces up to 40 text
+        labels total.
+    """
+    import altair as alt
+
+    if df.empty:
+        empty_chart = (
+            alt.Chart(df).mark_point().properties(width=width, height=height)
+        )
+        return empty_chart  # type: ignore[no-any-return]
+
+    plot = df.copy()
+    # rank() with method="average" handles ties cleanly; pct=True scales to
+    # (0, 1]. Higher percentile == more common in that corpus.
+    plot["percentile_a"] = plot["count_a"].rank(pct=True, method="average")
+    plot["percentile_b"] = plot["count_b"].rank(pct=True, method="average")
+    plot["abs_g2"] = plot["g2"].abs()
+
+    # Symmetric colour scale around zero so the colour midpoint corresponds
+    # to "equally common in both", not to the median G² of the table.
+    g2_max = float(plot["g2"].abs().max() or 1.0)
+
+    tooltip_cols: list[str] = ["term", "count_a", "count_b", "g2"]
+    for opt in ("log_ratio", "percent_diff", "p_value", "p_adjusted"):
+        if opt in plot.columns:
+            tooltip_cols.append(opt)
+
+    base = alt.Chart(plot).encode(
+        x=alt.X(
+            "percentile_a:Q",
+            title=f"Frequency rank in {label_a} (→ more common)",
+            scale=alt.Scale(domain=[0, 1]),
+        ),
+        y=alt.Y(
+            "percentile_b:Q",
+            title=f"Frequency rank in {label_b} (→ more common)",
+            scale=alt.Scale(domain=[0, 1]),
+        ),
+        tooltip=tooltip_cols,
+    )
+
+    # The diagonal x = y is the "equally distinctive" line — terms on it
+    # have the same rank in both corpora. Drawing it as a reference rule
+    # helps readers calibrate the distinctiveness zones.
+    diag = (
+        alt.Chart(pd.DataFrame({"x": [0.0, 1.0], "y": [0.0, 1.0]}))
+        .mark_line(strokeDash=[4, 4], color="#999", opacity=0.5)
+        .encode(x="x:Q", y="y:Q")
+    )
+
+    points = base.mark_circle(opacity=0.55).encode(
+        size=alt.Size(
+            "abs_g2:Q",
+            scale=alt.Scale(range=[20, 200]),
+            legend=None,
+        ),
+        color=alt.Color(
+            "g2:Q",
+            scale=alt.Scale(
+                scheme="redblue",
+                domain=[-g2_max, 0.0, g2_max],
+                reverse=True,  # blue = A-leaning, red = B-leaning
+            ),
+            title="Signed G²",
+        ),
+    )
+
+    # Pick the top-n_labels on each side by signed G².
+    a_leaning = plot.nlargest(n_labels, "g2")
+    b_leaning = plot.nsmallest(n_labels, "g2")
+    labelled = pd.concat([a_leaning, b_leaning], ignore_index=True).drop_duplicates(
+        subset="term"
+    )
+    labels = (
+        alt.Chart(labelled)
+        .mark_text(align="left", dx=5, dy=-2, fontSize=10)
+        .encode(
+            x="percentile_a:Q",
+            y="percentile_b:Q",
+            text="term:N",
+            color=alt.Color(
+                "g2:Q",
+                scale=alt.Scale(
+                    scheme="redblue",
+                    domain=[-g2_max, 0.0, g2_max],
+                    reverse=True,
+                ),
+                legend=None,
+            ),
+        )
+    )
+
+    chart = (
+        (diag + points + labels)
+        .properties(width=width, height=height)
+        .interactive()
+    )
+    return chart  # type: ignore[no-any-return]
+
+
+def _percentile_rank(series: pd.Series) -> np.ndarray:
+    """Internal helper used by tests; kept here for stability."""
+    return series.rank(pct=True, method="average").to_numpy()

pycorpdiff/viz/semantic_forecast.py

@@ -0,0 +1,114 @@
+"""Plot for :func:`pycorpdiff.forecast_semantic_drift` output.
+
+Same dashed-extension grammar as :func:`pycorpdiff.viz.forecast_plot`
+but operates on the cosine-distance scale (``distance_from_baseline``
+column on the history side, ``point`` + PI on the forecast side).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    import altair as alt
+
+
+def semantic_forecast_plot(
+    history: pd.DataFrame,
+    forecast: pd.DataFrame,
+    *,
+    width: int = 600,
+    height: int = 320,
+) -> alt.Chart:
+    """Layered plot of semantic drift with a forecast continuation.
+
+    Parameters
+    ----------
+    history
+        The DataFrame returned by :func:`pycorpdiff.semantic_trajectory`
+        — must carry ``period``, ``target``, ``distance_from_baseline``.
+    forecast
+        The DataFrame returned by
+        :func:`pycorpdiff.forecast_semantic_drift` — must carry
+        ``period``, ``target``, ``point``, ``ci_lower``, ``ci_upper``.
+    """
+    import altair as alt
+
+    h = history.copy()
+    f = forecast.copy()
+    if len(h) and isinstance(h["period"].iloc[0], pd.Period):
+        h["period"] = h["period"].apply(lambda p: p.to_timestamp())
+    if len(f) and isinstance(f["period"].iloc[0], pd.Period):
+        f["period"] = f["period"].apply(lambda p: p.to_timestamp())
+
+    base_h = alt.Chart(h).encode(
+        x=alt.X("period:T", title=None),
+        color=alt.Color("target:N", title=None),
+    )
+    history_line = base_h.mark_line(strokeWidth=2.5).encode(
+        y=alt.Y("distance_from_baseline:Q", title="cosine distance from baseline"),
+        tooltip=[
+            "period",
+            "target",
+            alt.Tooltip("distance_from_baseline:Q", format=".4f"),
+            alt.Tooltip("n_contexts:Q") if "n_contexts" in h.columns else "target:N",
+        ],
+    )
+    history_points = base_h.mark_point(filled=True, size=55).encode(
+        y="distance_from_baseline:Q",
+    )
+
+    base_f = alt.Chart(f).encode(
+        x=alt.X("period:T", title=None),
+        color=alt.Color("target:N", title=None),
+    )
+    forecast_band = base_f.mark_area(opacity=0.18).encode(
+        y=alt.Y("ci_lower:Q"),
+        y2="ci_upper:Q",
+    )
+    forecast_line = base_f.mark_line(strokeDash=[6, 4], strokeWidth=2).encode(
+        y="point:Q",
+        tooltip=[
+            "period",
+            "target",
+            alt.Tooltip("point:Q", format=".4f"),
+            alt.Tooltip("ci_lower:Q", format=".4f"),
+            alt.Tooltip("ci_upper:Q", format=".4f"),
+        ],
+    )
+    forecast_points = base_f.mark_point(filled=False, strokeWidth=2, size=55).encode(
+        y="point:Q"
+    )
+
+    if len(h) and len(f):
+        last_h = h.sort_values("period").groupby("target").tail(1)
+        first_f = f.sort_values("period").groupby("target").head(1)
+        seam = pd.concat(
+            [
+                last_h.assign(point=last_h["distance_from_baseline"])[
+                    ["period", "target", "point"]
+                ],
+                first_f[["period", "target", "point"]],
+            ]
+        )
+        seam_line = (
+            alt.Chart(seam)
+            .mark_line(strokeDash=[6, 4], strokeWidth=2, opacity=0.55)
+            .encode(
+                x="period:T",
+                y="point:Q",
+                color=alt.Color("target:N", legend=None),
+            )
+        )
+    else:
+        seam_line = alt.Chart(
+            pd.DataFrame({"period": [], "point": [], "target": []})
+        )
+
+    chart = (
+        history_line + history_points + seam_line + forecast_band
+        + forecast_line + forecast_points
+    ).properties(width=width, height=height)
+    return chart  # type: ignore[no-any-return]