goad-toolkit 0.2.8__tar.gz → 0.2.9__tar.gz

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: goad-toolkit
-Version: 0.2.8
+Version: 0.2.9
 Summary: An extensible toolkit for Goal Oriented Analysis of Data
 Project-URL: Github, https://github.com/raoulg/goad_toolkit
 Author-email: raoul grouls <Raoul.Grouls@han.nl>

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/docs/02-pipelines.md

@@ -199,9 +199,31 @@ will not warn you. Write the steps in the order you would do them by hand.
 you would want to run again on new data. A one-off `df[df.author == "Alice"]` while you are
 poking around is a notebook cell, and should stay one.
 
-**Debugging.** When a pipeline produces something surprising, add the steps back one at a
-time rather than dismantling it into cells — the moment it becomes cells again you have lost
-the record of what you did, which is the thing you were trying to keep.
+**Debugging.** When a pipeline produces something surprising, do not dismantle it into cells:
+the moment it becomes cells again you have lost the record of what you did, which is the
+thing you were trying to keep. Ask it what it did instead.
+
+```python
+result = pipeline.apply(data, keep_intermediate=True)
+pipeline.report()
+```
+
+```
+     step  rows  columns          added  removed
+ calendar  4083        9  hour, day_name
+  weekend  4083       10      is_weekend
+   window  3961       10
+```
+
+`report()` gives one row per step: how many rows survived it, how many columns the frame had
+afterwards, and which columns that step added or removed. The step where the row count falls
+off a cliff is the one filtering more than you meant it to, and a step with an empty `added`
+is a step that silently did nothing.
+
+`pipeline.intermediate` holds the frame as it stood after each step, keyed by step name, so
+you can look at the rows themselves once `report()` has told you where to look. Both are off
+by default — keeping them costs one full copy of the frame per step — and turning them on
+does not change what `apply` returns.
 
 ---
 

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/docs/03-plot-composition.md

@@ -155,6 +155,7 @@ step 3.
 | `HeatmapPlot` | `sns.heatmap`, pivoting the frame if asked | when both variables have many levels |
 | `BarbellPlot` | before and after per category, joined | the change is the message |
 | `HighlightCategory` | recolours bars: grey, plus the one that matters | a layer, and it needs no help from what drew them |
+| `Annotate` | text on the plot, with an arrow to the point | a layer; the finding, written where it is read |
 | `ScatterPlot` | `sns.scatterplot` | the first plot of any relation question |
 | `RegPlot` | `sns.regplot` — `fit_reg`, `lowess`, `order` | `scatter=False` layers it over a `ScatterPlot` |
 | `CorrelationHeatmap` | `.corr()` as a heatmap, scale pinned to [-1, 1] | where to look next, not a ranking |
@@ -168,6 +169,8 @@ step 3.
 | `QQPlot` | sample quantiles vs. a distribution's theoretical quantiles | the tails, not the bulk — see [Distributions §5.5](05-distributions.md) |
 | `ECDFPlot` | one or two empirical CDFs, bin-free | the right tool for comparing two samples |
 | `NullPlot` | a shuffled statistic, with the observed value marked | `HistogramPlot` + `VerticalLine`, see [Models and residuals §6.7](06-models-and-residuals.md) |
+| `ProjectionPlot` | already-fitted 2-D coordinates | takes an array, not a model — see [Five families §4.5](04-five-families.md) |
+| `ScreePlot` | variance explained per component, plus the running total | the figure a projection has to come with |
 
 `HistogramPlot` defaults to `sqrt(n)` bins capped at 50. That default is a starting point,
 not an answer — bin count changes what a histogram appears to say, and choosing it is part of
@@ -202,6 +205,21 @@ bars.plot_on(HighlightCategory(settings))
 about the data, but they are only defaults — pass `categories=` at the call to override.
 Naming a category that is not on the axis raises, and lists the ones that are.
 
+`Annotate` is the other layer worth reaching for by habit. A reader with thirty seconds reads
+the annotation and not the axes, so the sentence you would have said out loud belongs on the
+plot:
+
+```python
+line.plot_on(
+    Annotate(settings),
+    text="six-day gap: the logging host was down, not the channel",
+    xy=(gap_date, gap_value),          # the point being explained
+    xytext=(label_date, label_value),  # where the text sits; an arrow joins them
+)
+```
+
+Give it `xy` alone and the text lands on the point with no arrow.
+
 ## 3.7 Writing your own plot
 
 Two questions decide the shape:

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/docs/04-five-families.md

@@ -210,9 +210,14 @@ kept; a distance matrix when the items are few enough.
   space; use the projection to *look* at the result. Clustering the 2D coordinates is
   clustering an artefact.
 
-**In GOAD:** projections are computed elsewhere (sklearn) and plotted through a `BasePlot`
-subclass, so the variance-explained ends up in the `PlotSettings` title where a reader will
-see it.
+**In GOAD:** `ProjectionPlot` and `ScreePlot`. Both take arrays, not models — fitting a PCA,
+t-SNE or UMAP is sklearn's job and stays outside this library, so goad never has an opinion
+about how you got the coordinates.
+
+`ProjectionPlot` hides the tick values by default: the units of an embedding mean nothing, and
+showing them invites reading a distance off them. `ScreePlot` is the figure that has to
+accompany it — the variance-explained belongs in the title where a reader will see it, and
+two components carrying 12% make a picture of 12% of the data.
 
 ---
 

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/docs/08-api-reference.md

@@ -102,14 +102,26 @@ for the step.
 ```python
 class Pipeline:
     def add(self, transform_class: Type[T], name: Optional[str] = None, **kwargs) -> "Pipeline"
-    def apply(self, data: pd.DataFrame) -> pd.DataFrame
+    def apply(self, data: pd.DataFrame, keep_intermediate: bool = False) -> pd.DataFrame
+    def report(self) -> pd.DataFrame
     def __getitem__(self, key: str) -> Dict[str, Any]
     def __setitem__(self, key: str, params: Dict[str, Any]) -> None
+
+    intermediate: Dict[str, pd.DataFrame]    # the frame after each step, when kept
+    input_columns: List[str]                 # the columns apply was handed
 ```
 
 `add` takes the **class**, not an instance, and returns `self` so calls chain. `apply` copies
 the frame once, then instantiates and runs each step in insertion order.
 
+`keep_intermediate=True` fills `intermediate` with a **copy** of the frame after every step —
+a copy is required, since the steps mutate one frame in place and stored references would all
+show the finished columns. It does not change what `apply` returns. Both `intermediate` and
+`input_columns` are reset at the start of every `apply`, so a later plain run clears them.
+
+`report()` turns those into one row per step — `step`, `rows`, `columns`, `added`, `removed` —
+and raises if no intermediates were kept. See [Pipelines §2.7](02-pipelines.md).
+
 ---
 
 ## 8.4 `goad_toolkit.dataprocessor`
@@ -325,6 +337,9 @@ class BasePlot(ABC):
 | `HeatmapPlot` | `data, index=None, columns=None, values=None, aggfunc="mean", cmap="rocket_r", annot=True, fmt=".1f", **kwargs` |
 | `BarbellPlot` | `data, category, start, end, start_label="before", end_label="after", start_color="lightgrey", end_color="crimson", line_color="lightgrey", markersize=80, **kwargs` |
 | `HighlightCategory` | `categories=None, color=None, base_color=None, axis="x"` |
+| `Annotate` | `text, xy, xytext=None, arrow=True, color="black", fontsize=11, **kwargs` |
+| `ProjectionPlot` | `coordinates, labels=None, alpha=0.7, hide_axes=True, **kwargs` |
+| `ScreePlot` | `explained_variance_ratio, n_components=None, cumulative=True, color="steelblue", line_color="crimson", **kwargs` |
 | `BarWithDates` | `data, x, y, interval: int = 1, **kwargs` |
 | `ResidualPlot` | `data, x, y, date, datelabel, interval: int = 1` |
 | `ScatterPlot` | `data, x, y, alpha=0.6, **kwargs` → `sns.scatterplot` (`hue`, `size`, `style`) |
@@ -367,6 +382,12 @@ category that is not on the axis raises and lists the ones that are; so does app
 axis with no bars. Zero-size patches are skipped — seaborn keeps its legend proxies in
 `ax.patches`, and recolouring those would rewrite the legend's swatches.
 
+`Annotate` draws an arrow only when `xytext` is given — an arrow from a point to itself is not
+a thing — so `xy` alone places the text on the point. `ProjectionPlot` takes coordinates of
+shape `(n, 2)` and raises on anything else, or on a label count that does not match; it hides
+the tick values unless told not to. `ScreePlot` takes the ratios, not a fitted model, so
+sklearn stays out of goad.
+
 `HeatmapPlot` pivots when given both `index` and `columns` (and `values`), and draws `data`
 as a matrix when given neither; one without the other raises. Its scale is sequential,
 unlike `CorrelationHeatmap`'s. `BarbellPlot` draws rows in the frame's own order — sort by the

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/docs/09-analysis-method.md

@@ -121,7 +121,7 @@ See [The five families](04-five-families.md).
 | What is grouped visually, and does it match what is grouped conceptually? | The gestalt principles group things for the reader without asking you | the groupings, intended and accidental |
 | Which single element carries the message, and is it the only coloured thing? | Grey first, colour as a pointer, not decoration | the one element |
 | What can you delete without losing meaning? | Everything remaining should be earning its place | the list you deleted |
-| Is the finding written on the plot? | A reader with thirty seconds reads the annotation, not the axes | the annotation, and where it sits |
+| Is the finding written on the plot? (`Annotate`) | A reader with thirty seconds reads the annotation, not the axes | the annotation, and where it sits |
 
 See [Visual critique](07-visual-critique.md).
 

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "goad-toolkit"
-version = "0.2.8"
+version = "0.2.9"
 description = "An extensible toolkit for Goal Oriented Analysis of Data"
 readme = "README.md"
 authors = [

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/src/goad_toolkit/datatransforms.py

@@ -213,6 +213,8 @@ class Pipeline:
 
     def __init__(self):
         self.transforms: Dict[str, Dict[str, Any]] = {}
+        self.intermediate: Dict[str, pd.DataFrame] = {}
+        self.input_columns: List[str] = []
 
     def add(
         self, transform_class: Type[T], name: Optional[str] = None, **kwargs
@@ -229,8 +231,25 @@ class Pipeline:
         self.transforms[name] = {"class": transform_class, "params": kwargs}
         return self  # Allow method chaining
 
-    def apply(self, data: pd.DataFrame) -> pd.DataFrame:
-        """Apply all transformations in the pipeline."""
+    def apply(
+        self, data: pd.DataFrame, keep_intermediate: bool = False
+    ) -> pd.DataFrame:
+        """Apply all transformations in the pipeline.
+
+        Args:
+            data: Frame to transform. It is never modified.
+            keep_intermediate: Keep the frame as it stood after every step in
+                `self.intermediate`, and the input's columns in
+                `self.input_columns`, so `report()` can say which step did what.
+                Off by default: it holds one full copy of the frame per step.
+
+        Returns:
+            The frame after every transform, whether or not intermediates were
+            kept — turning introspection on does not change what you get back.
+        """
+        self.intermediate = {}
+        self.input_columns = list(data.columns)
+
         # Make a single copy at the pipeline level
         result = data.copy() if len(self.transforms) > 0 else data
         for name, transform_config in tqdm(
@@ -240,8 +259,46 @@ class Pipeline:
             params = transform_config["params"]
             transform = transform_class(name=name, **params)
             result = transform(result)
+            if keep_intermediate:
+                # A copy, not a reference: the steps mutate one frame in place,
+                # so a stored reference would show every step holding the final
+                # columns and nothing would look like it had done anything.
+                self.intermediate[name] = result.copy()
         return result
 
+    def report(self) -> pd.DataFrame:
+        """One row per step: how many rows survived it, and which columns it added.
+
+        The answer to "which step broke it", without dismantling the pipeline
+        back into loose cells. Needs `apply(..., keep_intermediate=True)` first.
+
+        Returns:
+            A frame with one row per step: `step`, `rows`, `columns`, `added`
+            and `removed`, in the order the steps ran.
+        """
+        if not self.intermediate:
+            raise ValueError(
+                "No intermediate frames to report on. Run "
+                "apply(data, keep_intermediate=True) first."
+            )
+
+        rows = []
+        previous = list(self.input_columns)
+        for name, frame in self.intermediate.items():
+            current = list(frame.columns)
+            rows.append(
+                {
+                    "step": name,
+                    "rows": len(frame),
+                    "columns": len(current),
+                    "added": ", ".join(c for c in current if c not in previous),
+                    "removed": ", ".join(c for c in previous if c not in current),
+                }
+            )
+            previous = current
+
+        return pd.DataFrame(rows)
+
     def __getitem__(self, key: str) -> Dict[str, Any]:
         """Get a specific transform configuration by name."""
         if key in self.transforms:

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/src/goad_toolkit/visualizer.py

@@ -365,6 +365,68 @@ class HighlightCategory(BasePlot):
         return self.fig, self.ax
 
 
+class Annotate(BasePlot):
+    """Write the finding on the plot, where a reader with thirty seconds looks.
+
+    The last question in the visual critique is whether the finding is written
+    down. Axis labels say what the numbers are; the annotation says what you
+    concluded, and it is the only part most readers will read.
+    """
+
+    def build(
+        self,
+        text: str,
+        xy: Tuple[float, float],
+        xytext: Optional[Tuple[float, float]] = None,
+        arrow: bool = True,
+        color: str = "black",
+        fontsize: float = 11,
+        **kwargs,
+    ):
+        """
+        Place `text` on the axis, optionally with an arrow to the point.
+
+        Parameters:
+        -----------
+        text : str
+            What you concluded. A sentence, not a label.
+        xy : Tuple[float, float]
+            Point in data coordinates the text is about.
+        xytext : Optional[Tuple[float, float]]
+            Where the text itself sits, in data coordinates. Defaults to `xy`,
+            which places the text on the point and draws no arrow.
+        arrow : bool
+            Draw an arrow from the text to `xy`. Ignored when `xytext` is None,
+            since an arrow from a point to itself is not a thing.
+        color : str
+            Text colour.
+        fontsize : float
+            Text size.
+        **kwargs : Additional keyword arguments passed to `ax.annotate`.
+
+        Returns:
+        --------
+        fig, ax : The created figure and axes.
+        """
+        if self.ax is None:
+            raise ValueError("No axes available for plotting")
+
+        arrowprops = None
+        if xytext is not None and arrow:
+            arrowprops = {"arrowstyle": "->", "color": color, "linewidth": 1}
+
+        self.ax.annotate(
+            text,
+            xy=xy,
+            xytext=xytext if xytext is not None else xy,
+            color=color,
+            fontsize=fontsize,
+            arrowprops=arrowprops,
+            **kwargs,
+        )
+        return self.fig, self.ax
+
+
 class ComparePlotDate(BasePlot):
     def build(
         self,
@@ -942,6 +1004,140 @@ class CorrelationHeatmap(BasePlot):
         return self.fig, self.ax
 
 
+class ProjectionPlot(BasePlot):
+    """Points in two dimensions after a projection has already been fitted.
+
+    Takes coordinates, not a model: fitting PCA, t-SNE or UMAP is sklearn's job
+    and stays outside this library. Pass the array it gave you.
+
+    The axes of a t-SNE or UMAP plot mean nothing — not distance, not direction,
+    not scale — so they are hidden by default. What survives is which points sit
+    together, and even that is a claim to check rather than a finding.
+    """
+
+    def build(
+        self,
+        coordinates: Any,
+        labels: Optional[Any] = None,
+        alpha: float = 0.7,
+        hide_axes: bool = True,
+        **kwargs,
+    ):
+        """
+        Scatter a set of two-dimensional coordinates.
+
+        Parameters:
+        -----------
+        coordinates : array-like
+            Shape (n, 2): the output of a fitted projection.
+        labels : Optional[array-like]
+            One label per point, used as colour. Length must match.
+        alpha : float
+            Point transparency; projections overplot heavily in dense regions.
+        hide_axes : bool
+            Hide the tick marks and values. The units of an embedding are not
+            interpretable, and showing them invites reading a distance off them.
+        **kwargs : Additional keyword arguments passed to `sns.scatterplot`.
+
+        Returns:
+        --------
+        fig, ax : The created figure and axes.
+        """
+        if self.ax is None:
+            raise ValueError("No axes available for plotting")
+
+        points = np.asarray(coordinates)
+        if points.ndim != 2 or points.shape[1] != 2:
+            raise ValueError(
+                f"ProjectionPlot needs coordinates of shape (n, 2), got {points.shape}"
+            )
+        if labels is not None and len(labels) != len(points):
+            raise ValueError(f"Got {len(labels)} labels for {len(points)} points")
+
+        sns.scatterplot(
+            x=points[:, 0],
+            y=points[:, 1],
+            hue=labels,
+            alpha=alpha,
+            ax=self.ax,
+            **kwargs,
+        )
+
+        if hide_axes:
+            self.ax.set_xticks([])
+            self.ax.set_yticks([])
+
+        return self.fig, self.ax
+
+
+class ScreePlot(BasePlot):
+    """How much of the variance the components you kept actually carry.
+
+    The figure that has to accompany a projection. Two components that explain
+    12% of the variance make a picture of 12% of the data, and a shape in that
+    picture is not a shape in the dataset.
+    """
+
+    def build(
+        self,
+        explained_variance_ratio: Any,
+        n_components: Optional[int] = None,
+        cumulative: bool = True,
+        color: str = "steelblue",
+        line_color: str = "crimson",
+        **kwargs,
+    ):
+        """
+        Draw the variance explained per component, and the running total.
+
+        Parameters:
+        -----------
+        explained_variance_ratio : array-like
+            One fraction per component, as `explained_variance_ratio_` gives.
+        n_components : Optional[int]
+            Show only the first this many components.
+        cumulative : bool
+            Overlay the running total, which is what "how much did I keep"
+            actually asks.
+        color : str
+            Bar colour.
+        line_color : str
+            Cumulative line colour.
+        **kwargs : Additional keyword arguments passed to `ax.bar`.
+
+        Returns:
+        --------
+        fig, ax : The created figure and axes.
+        """
+        if self.ax is None:
+            raise ValueError("No axes available for plotting")
+
+        ratios = np.asarray(explained_variance_ratio, dtype=float)
+        if ratios.ndim != 1 or len(ratios) == 0:
+            raise ValueError(
+                f"ScreePlot needs a one-dimensional, non-empty array of ratios, "
+                f"got shape {ratios.shape}"
+            )
+        if n_components is not None:
+            ratios = ratios[:n_components]
+
+        components = np.arange(1, len(ratios) + 1)
+        self.ax.bar(components, ratios, color=color, **kwargs)
+
+        if cumulative:
+            self.ax.plot(
+                components,
+                np.cumsum(ratios),
+                color=line_color,
+                marker="o",
+                label="cumulative",
+            )
+            self.ax.legend()
+
+        self.ax.set_xticks(components)
+        return self.fig, self.ax
+
+
 class HistogramPlot(BasePlot):
     """Plot a histogram using seaborn."""
 

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/tests/test_datatransforms.py

@@ -1,7 +1,12 @@
 import pandas as pd
 import pytest
 
-from goad_toolkit.datatransforms import Pipeline, RegexFeature, TimeFeatures
+from goad_toolkit.datatransforms import (
+    Pipeline,
+    RegexFeature,
+    TimeFeatures,
+    TransformBase,
+)
 
 
 @pytest.fixture
@@ -165,3 +170,88 @@ def test_feature_is_the_column_name_and_name_is_the_step(messages):
     assert "addressed_to" in result.columns
     assert "mentions" not in result.columns
     assert "mentions" in repr(pipeline)
+
+
+class KeepFirst(TransformBase):
+    """A transform that drops rows, so a report has something to report."""
+
+    def transform(self, data: pd.DataFrame, n: int) -> pd.DataFrame:
+        return data.head(n)
+
+
+def test_apply_keeps_nothing_by_default(data):
+    pipeline = Pipeline()
+    pipeline.add(TimeFeatures, column="timestamp", features=["hour"])
+
+    pipeline.apply(data)
+
+    assert pipeline.intermediate == {}
+
+
+def test_apply_keeps_a_frame_per_step_when_asked(data):
+    pipeline = Pipeline()
+    pipeline.add(TimeFeatures, name="calendar", column="timestamp", features=["hour"])
+    pipeline.add(TimeFeatures, name="naming", column="timestamp", features=["day_name"])
+
+    result = pipeline.apply(data, keep_intermediate=True)
+
+    assert list(pipeline.intermediate) == ["calendar", "naming"]
+    # Each step is kept as it stood, not as a view of the finished frame.
+    assert "hour" in pipeline.intermediate["calendar"].columns
+    assert "day_name" not in pipeline.intermediate["calendar"].columns
+    assert "day_name" in pipeline.intermediate["naming"].columns
+    assert "day_name" in result.columns
+
+
+def test_keeping_intermediates_does_not_change_the_result(data):
+    kept = Pipeline()
+    kept.add(TimeFeatures, column="timestamp", features=["hour"])
+
+    plain = Pipeline()
+    plain.add(TimeFeatures, column="timestamp", features=["hour"])
+
+    pd.testing.assert_frame_equal(
+        kept.apply(data, keep_intermediate=True), plain.apply(data)
+    )
+
+
+def test_a_second_apply_replaces_the_kept_frames(data):
+    pipeline = Pipeline()
+    pipeline.add(TimeFeatures, column="timestamp", features=["hour"])
+
+    pipeline.apply(data, keep_intermediate=True)
+    pipeline.apply(data)
+
+    assert pipeline.intermediate == {}
+
+
+def test_report_names_the_columns_each_step_added(data):
+    pipeline = Pipeline()
+    pipeline.add(TimeFeatures, name="calendar", column="timestamp", features=["hour"])
+    pipeline.add(TimeFeatures, name="naming", column="timestamp", features=["day_name"])
+
+    pipeline.apply(data, keep_intermediate=True)
+    report = pipeline.report()
+
+    assert list(report["step"]) == ["calendar", "naming"]
+    assert list(report["added"]) == ["hour", "day_name"]
+    assert list(report["removed"]) == ["", ""]
+    assert list(report["rows"]) == [len(data), len(data)]
+
+
+def test_report_shows_where_the_rows_went(data):
+    pipeline = Pipeline()
+    pipeline.add(TimeFeatures, name="calendar", column="timestamp", features=["hour"])
+    pipeline.add(KeepFirst, name="first_two", n=2)
+
+    pipeline.apply(data, keep_intermediate=True)
+    report = pipeline.report()
+
+    assert list(report["rows"]) == [len(data), 2]
+
+
+def test_report_without_intermediates_says_what_to_do():
+    pipeline = Pipeline()
+
+    with pytest.raises(ValueError, match="keep_intermediate=True"):
+        pipeline.report()

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/tests/test_visualizer.py

@@ -13,6 +13,7 @@ from scipy import stats  # noqa: E402
 from goad_toolkit.analytics import NullResult  # noqa: E402
 from goad_toolkit.visualizer import (  # noqa: E402
     ACFPlot,
+    Annotate,
     BarbellPlot,
     BarPlot,
     BarWithDates,
@@ -27,10 +28,12 @@ from goad_toolkit.visualizer import (  # noqa: E402
     LinePlot,
     NullPlot,
     PlotSettings,
+    ProjectionPlot,
     QQPlot,
     RegPlot,
     ResidualPlot,
     ScatterPlot,
+    ScreePlot,
     VerticalDate,
     VerticalLine,
 )
@@ -278,6 +281,119 @@ def facecolours(ax) -> list:
     return [patch.get_facecolor() for patch in ax.patches]
 
 
+def test_annotate_writes_the_text_on_the_axis():
+    host = LinePlot(PlotSettings())
+    host.create_figure()
+
+    host.plot_on(Annotate(PlotSettings()), text="the dip is the outage", xy=(1.0, 2.0))
+
+    assert [t.get_text() for t in host.ax.texts] == ["the dip is the outage"]
+
+
+def test_annotate_draws_an_arrow_when_the_text_sits_elsewhere():
+    host = LinePlot(PlotSettings())
+    host.create_figure()
+
+    host.plot_on(
+        Annotate(PlotSettings()), text="here", xy=(1.0, 2.0), xytext=(3.0, 4.0)
+    )
+
+    annotation = host.ax.texts[0]
+    assert annotation.arrow_patch is not None
+    assert annotation.get_position() == (3.0, 4.0)
+
+
+def test_annotate_without_a_second_point_draws_no_arrow():
+    host = LinePlot(PlotSettings())
+    host.create_figure()
+
+    host.plot_on(Annotate(PlotSettings()), text="here", xy=(1.0, 2.0), arrow=True)
+
+    assert host.ax.texts[0].arrow_patch is None
+
+
+def test_projection_plot_scatters_the_coordinates():
+    rng = np.random.default_rng(1)
+    coordinates = rng.normal(size=(30, 2))
+
+    fig, ax = ProjectionPlot(PlotSettings()).plot(coordinates=coordinates)
+
+    assert fig is not None
+    assert len(ax.collections[0].get_offsets()) == 30
+
+
+def test_projection_plot_hides_the_meaningless_axes():
+    coordinates = np.random.default_rng(1).normal(size=(10, 2))
+
+    fig, ax = ProjectionPlot(PlotSettings()).plot(coordinates=coordinates)
+
+    assert list(ax.get_xticks()) == []
+    assert list(ax.get_yticks()) == []
+
+
+def test_projection_plot_colours_by_label():
+    coordinates = np.random.default_rng(1).normal(size=(6, 2))
+    labels = ["a", "b"] * 3
+
+    fig, ax = ProjectionPlot(PlotSettings()).plot(
+        coordinates=coordinates, labels=labels
+    )
+
+    legend_labels = [t.get_text() for t in ax.get_legend().get_texts()]
+    assert legend_labels == ["a", "b"]
+
+
+def test_projection_plot_rejects_more_than_two_dimensions():
+    coordinates = np.random.default_rng(1).normal(size=(10, 3))
+
+    with pytest.raises(ValueError, match=r"shape \(n, 2\)"):
+        ProjectionPlot(PlotSettings()).plot(coordinates=coordinates)
+
+
+def test_projection_plot_rejects_a_label_count_mismatch():
+    coordinates = np.random.default_rng(1).normal(size=(10, 2))
+
+    with pytest.raises(ValueError, match="3 labels for 10 points"):
+        ProjectionPlot(PlotSettings()).plot(
+            coordinates=coordinates, labels=["a", "b", "c"]
+        )
+
+
+def test_scree_plot_draws_a_bar_per_component_and_the_running_total():
+    ratios = [0.5, 0.25, 0.15, 0.1]
+
+    fig, ax = ScreePlot(PlotSettings()).plot(explained_variance_ratio=ratios)
+
+    assert len(ax.patches) == 4
+    cumulative = ax.lines[0].get_ydata()
+    assert cumulative[-1] == pytest.approx(1.0)
+    assert list(cumulative) == pytest.approx([0.5, 0.75, 0.9, 1.0])
+
+
+def test_scree_plot_can_show_only_the_first_components():
+    ratios = [0.5, 0.25, 0.15, 0.1]
+
+    fig, ax = ScreePlot(PlotSettings()).plot(
+        explained_variance_ratio=ratios, n_components=2
+    )
+
+    assert len(ax.patches) == 2
+    assert ax.lines[0].get_ydata()[-1] == pytest.approx(0.75)
+
+
+def test_scree_plot_without_the_cumulative_line():
+    fig, ax = ScreePlot(PlotSettings()).plot(
+        explained_variance_ratio=[0.6, 0.4], cumulative=False
+    )
+
+    assert len(ax.lines) == 0
+
+
+def test_scree_plot_rejects_an_empty_array():
+    with pytest.raises(ValueError, match="non-empty"):
+        ScreePlot(PlotSettings()).plot(explained_variance_ratio=[])
+
+
 def test_bar_plot_draws_one_bar_per_category(categories):
     fig, ax = BarPlot(PlotSettings()).plot(data=categories, x="species", y="mass")
 

{goad_toolkit-0.2.8 → goad_toolkit-0.2.9}/uv.lock

@@ -383,7 +383,7 @@ wheels = [
 
 [[package]]
 name = "goad-toolkit"
-version = "0.2.8"
+version = "0.2.9"
 source = { editable = "." }
 dependencies = [
     { name = "loguru" },