goad-toolkit 0.2.0__tar.gz

goad_toolkit-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.aider*
+dev/
+data/**
+.DS_Store

goad_toolkit-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12

goad_toolkit-0.2.0/MCP_SERVER.md

@@ -0,0 +1,205 @@
+# GOAD🐐 as an MCP server
+
+This repo ships a small [MCP](https://modelcontextprotocol.io) server,
+[`goad_mcp.py`](goad_mcp.py), that turns the [`docs/`](docs) chapters into coaching methods
+for a coding assistant (Claude Code, Cursor, Codex, Claude Desktop, …) — one for **analysing**
+a dataset from a question rather than from its columns, one for **critiquing** a finished
+visualisation, and one for **fitting a distribution** without deciding what an outlier is
+first.
+
+The point is to learn how to work *with* an assistant while doing data analysis, grounded in
+GOAD's own method (the question comes first, the residual is the finding, every parameter is
+part of the claim) instead of generic advice — and instead of handing the whole problem over
+and getting back twelve plots nobody can defend.
+
+## How to use it
+
+- **Analysing something:** in Claude Code, run `/goad:analyse` (optionally describe what you
+  want to find out). In any client, just say **"Coach me through analysing this with the goad
+  server."** Expect a conversation, not an answer: your assistant will work through six
+  stages, asking you questions one stage at a time and waiting for your actual answers before
+  moving on.
+- **Critiquing a plot:** `/goad:critique`, or **"Critique this plot against the goad
+  checklist."**
+- **Fitting a distribution:** `/goad:distribution`, or **"Coach me through fitting a
+  distribution to this column using the goad server."**
+- **Looking something up:** "Using the goad server, get the chapter on plot composition." /
+  "Search the goad docs for long tail." / "What does goad say about t-SNE perplexity?"
+
+The analysis and critique prompts are coaching sessions, not code generators — they are built
+to ask what you think before offering an answer, and to write code only once you have said
+what it is for. Using your assistant to answer all six stages itself in one go defeats the
+point; ask it to go back to stage one and actually wait for your answers.
+
+## What it exposes
+
+**Tools**
+
+| Tool | What it does |
+| --- | --- |
+| `goad_list_concepts` | List all 10 chapters, in reading order. |
+| `goad_get_concept` | Fetch the full markdown of one chapter. |
+| `goad_search` | Keyword search across every chapter. |
+| `goad_analysis_checklist` | A six-stage, table-driven analysis conversation — see below. |
+| `goad_critique_visual` | The visual-critique checklist, one section at a time. |
+| `goad_distribution_method` | The method for fitting and defending a distribution, in the right order. |
+
+**`goad_analysis_checklist` is the centrepiece**, and it is deliberately not a one-shot
+document dump. It walks a student through six stages **in order**, one at a time, and only
+advances once the assistant reports back what the student actually said:
+
+1. **question** — what do you want to know, what would count as an answer in both directions,
+   and who is it for?
+2. **data** — what is one row, what was measured versus derived, and what does the question
+   need that the data does not yet contain?
+3. **shape** — how is each variable distributed, is anything long-tailed, and are the extreme
+   values errors or ordinary members of a tail?
+4. **encoding** — which of the five families does the question live in, and which visual
+   channel carries the comparison you actually care about?
+5. **critique** — what does the plot say in the first 200ms, what does the eye group by
+   itself, and what exactly are you claiming?
+6. **verification** — what null would produce this too, what confounder could, and what does
+   the residual look like?
+
+Each stage returns a markdown table — question / why it matters / what a good answer names —
+plus an instruction to the assistant: ask the student, wait for a real answer, don't answer on
+their behalf, and don't fetch the next stage until this one is actually recorded. Progress is
+held in memory for the current session only. At the end it returns a recap of everything
+recorded, which is a usable first draft of the write-up.
+
+`goad_critique_visual` splits the work explicitly: sections 2 and 3 (gestalt principles, the
+five guidelines) are ones an assistant can genuinely help with, and it is told to be concrete
+there. Sections 1 and 4 (what caught your eye, what you are claiming) it is told to ask and
+wait for — it cannot see the plot the way you do, and answering section 4 for you means
+inventing a claim to fit the picture, which is backwards.
+
+**Prompts**
+
+- `analyse` — start the six-stage analysis conversation. Takes an optional `question`.
+- `critique` — walk a finished visualisation through the checklist. Takes an optional `plot`.
+- `distribution` — coach the distribution-fitting method in order. Takes an optional `variable`.
+
+**Resources**
+
+- `goad://concept/{name}` — each chapter's raw markdown, addressable by number (`5`),
+  filename (`05-distributions.md`), stem, or title.
+
+The content comes from [`docs/`](docs); no build step, no database, no embeddings.
+
+## Requirements
+
+- [`uv`](https://docs.astral.sh/uv/)
+- Python 3.10+
+
+You do **not** need `goad-toolkit` installed to run the server — it only reads markdown.
+
+## Install
+
+`uv` runs the server straight from a URL: it downloads the single script, provisions Python
+and the `fastmcp` package from the script's own [PEP 723](https://peps.python.org/pep-0723/)
+metadata, and the server fetches its docs from the repo over HTTP.
+
+You pin a version with `GOAD_REF` — a git ref (branch, tag, or commit). That one variable
+selects both the script (in the URL) and the docs it fetches (inside the script), so a whole
+cohort runs exactly the same thing and the two cannot drift apart.
+
+> **Note:** the docs and this server land in **v0.2.0**. Until that tag exists, point
+> `GOAD_REF` at the branch (`feat/docs-and-mcp`) or work from a local clone (see below).
+
+### Claude Code
+
+```bash
+claude mcp add goad -e GOAD_REF=v0.2.0 -- \
+  sh -c 'uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py'
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "goad": {
+      "command": "sh",
+      "args": ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"],
+      "env": { "GOAD_REF": "v0.2.0" }
+    }
+  }
+}
+```
+
+### Codex
+
+Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.goad]
+command = "sh"
+args = ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"]
+env = { GOAD_REF = "v0.2.0" }
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config), then restart the
+app:
+
+```json
+{
+  "mcpServers": {
+    "goad": {
+      "command": "sh",
+      "args": ["-c", "uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py"],
+      "env": { "GOAD_REF": "v0.2.0" }
+    }
+  }
+}
+```
+
+(The `sh` wrapper is for macOS/Linux; on Windows, drop `sh -c` and put the ref directly in
+the URL instead, keeping the `GOAD_REF` env value in sync.)
+
+## Working from a local clone instead
+
+If you have already cloned `goad_toolkit`, point the same command at the local file instead
+of the URL — the server then reads `docs/` straight off disk, so any edits show up without a
+restart:
+
+```bash
+claude mcp add goad -- uv run --no-project /path/to/goad_toolkit/goad_mcp.py
+```
+
+## Tracking the bleeding edge instead
+
+Set `GOAD_REF=main` to always run whatever is on `main`, including chapters or checklist
+changes not in a release yet. Fine for your own use; for a cohort of students, pin to a tag
+instead so everyone runs the exact same docs during an assignment.
+
+## Update to a new version
+
+Pick the newest tag from the [releases](https://github.com/raoulg/goad_toolkit/tags), then
+point `GOAD_REF` at it. Because the ref lives in the URL, switching it fetches the new script
+automatically — no cache clearing needed.
+
+**Claude Code** — re-running `add` errors if the server already exists, so remove first, then
+add with the new tag:
+
+```bash
+claude mcp remove goad -s user
+claude mcp add goad -s user -e GOAD_REF=v0.2.0 -- \
+  sh -c 'uv run --no-project https://raw.githubusercontent.com/raoulg/goad_toolkit/$GOAD_REF/goad_mcp.py'
+```
+
+**Cursor / Codex / Claude Desktop** — edit the `GOAD_REF` value in the config, then restart
+your assistant so it relaunches the server.
+
+## Companion servers
+
+`goad` covers "is my analysis any good". Two siblings cover the rest of the same workflow:
+
+- [`codestyle`](https://github.com/raoulg/codestyle) — is my code any good.
+- [`vectormesh`](https://github.com/raoulg/vectormesh) — is my architecture any good.
+
+All three follow the same shape: a `docs/` folder as the single source of truth, one PEP 723
+script that serves it, and a staged conversation the assistant cannot short-circuit.

goad_toolkit-0.2.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: goad-toolkit
+Version: 0.2.0
+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>
+Requires-Python: >=3.12
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: matplotlib>=3.10.1
+Requires-Dist: numpy>=2.2.4
+Requires-Dist: pandas>=2.2.3
+Requires-Dist: pydantic>=2.10.6
+Requires-Dist: requests>=2.32.3
+Requires-Dist: scipy>=1.15.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: tqdm>=4.67.1
+Description-Content-Type: text/markdown
+
+# GOAD🐐 is the GOAT - Goal Oriented Analysis of Data
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![image](https://shields.io/pypi/v/goad_toolkit.svg)](https://pypi.org/project/goad_toolkit/)
+
+<p align="center">
+  <em>GOAD🐐 - When your data analysis is so fire🔥 it's got rizz✨</em>
+</p>
+
+![GOAD🐐](img/goaded.png)
+
+GOAD🐐 is a flexible Python package for analyzing, transforming, and visualizing data with an emphasis on statistical distribution fitting and modular visualization components.
+
+> with thanks to my daughters for the genz slang!
+
+## 📊 Features
+
+- **Composable & extendable plotting system** - Build complex visualizations by combining simple components. You can extend the existing components with your own.
+- **Statistical distribution fitting** - Automatically fit and compare distributions to your data. The distribution registry is extendable with additional distributions.
+- **Extendable data transformation pipelines** - Chain and reuse data transformations into pipelines. Again, extendable with custom transformation components.
+
+> Before GOAD🐐 : mid data
+> After GOAD🐐 : data got infinity aura
+
+## 📖 Documentation
+
+Full documentation lives in [`docs/`](docs/README.md) — ten chapters covering the method, the
+pipeline and plot systems, the five families of visualisation, distribution fitting, models
+and residuals, and a visual-critique checklist.
+
+The same chapters are also available as an **MCP server**, so your coding assistant can coach
+you through an analysis instead of doing it for you. See [MCP_SERVER.md](MCP_SERVER.md).
+
+## 🚀 Quick Start
+
+### Installation
+Using [uv](https://docs.astral.sh/uv/):
+```bash
+uv add goad-toolkit
+```
+
+Or, if you prefer your dependencies to be installed 100x slower, with pip:
+```bash
+pip install goad-toolkit
+```
+
+## 📋 Demo: Linear Model Analysis
+
+GOAD🐐 includes a comprehensive [demo](demo/linear.py) that shows how to use its components together.
+
+### Main capabilities
+In the [demo/linear.py](demo/linear.py) file you can see a showcase of the main capabilities of GOAD🐐:
+- create a data processing pipeline
+- components are extendable, so you can easily add your own steps to a pipeline
+- create visualisations by stacking components. `BasePlot` will handle boilerplate.
+- the `DistributionFitter` will try to fit a few common distributions, and add statistical tests for you
+- The results work together with the `visualizer.PlotFits` class to show the results
+
+The main strenght of this module is not that these elements are there (even thought they are very useful). Its superpower is that everything is extendable: so you can use this as a start, and extend it with your own visualisations and analytics.
+
+> POV: Your data just got GOADed🐐 and now it's giving main character energy
+
+## 📚 Core Components
+
+#### 🔄 Extendable Data Transforms
+
+GOAD🐐 provides a pipeline approach to transform your data:
+
+```python
+from goad_toolkit.datatransforms import Pipeline, ShiftValues, ZScaler
+
+# Create a pipeline
+pipeline = Pipeline()
+
+# Add transformations
+pipeline.add(ShiftValues, name="shift_deaths", column="deaths", period=-14)
+pipeline.add(ZScaler, name="scale_tests", column="positivetests", rename=True)
+
+# Apply all transformations
+result = pipeline.apply(data)
+```
+
+Available transforms include:
+- `ShiftValues` - Shift values in a column by a specified period
+- `DiffValues` - Calculate the difference between consecutive values
+- `SelectDataRange` - Select rows within a specified date range
+- `RollingAvg` - Calculate rolling average of a column
+- `ZScaler` - Standardize values in a column
+
+You can extend the pipeline with your own transformations by subclassing `BaseTransform`. The Zscaler is implemented as follows:
+
+```python
+class ZScaler(TransformBase):
+    """Standardize the values in a column."""
+    def transform(
+        self, data: pd.DataFrame, column: str, rename: bool = False
+    ) -> pd.DataFrame:
+        """Standardize the values in a column."""
+        if rename:
+            colname = f"{column}_zscore"
+        else:
+            colname = column
+        data[colname] = (data[column] - data[column].mean()) / data[column].std()
+        return data
+```
+
+### 📊 Visualization System
+
+GOAD🐐 visualization system is built on a composable architecture that allows you to build complex plots by combining simpler components:
+
+```python
+from goad_toolkit.visualizer import PlotSettings, ResidualPlot
+
+# Create plot settings
+plotsettings = PlotSettings(
+        xlabel="date",
+        ylabel="normalized values",
+        title="Z-Scores of Deaths and Positive Tests",
+    )
+
+class LinePlot(BasePlot):
+    """Plot a line plot using seaborn."""
+    def build(self, data: pd.DataFrame, **kwargs):
+        sns.lineplot(data=data, ax=self.ax, **kwargs)
+        return self.fig, self.ax
+
+
+class ComparePlot(BasePlot):
+    def build(self, data: pd.DataFrame, x: str, y1: str, y2: str, **kwargs):
+        compare = LinePlot(self.settings)
+        self.plot_on(compare, data=data, x=x, y=y1, label=y1, **kwargs)
+        self.plot_on(compare, data=data, x=x, y=y2, label=y2, **kwargs)
+        plt.xticks(rotation=45)
+
+        return self.fig, self.ax
+
+compareplot = ComparePlot(plotsettings)
+compareplot.plot(
+        data=data, x="date", y1="deaths_shifted_zscore", y2="positivetests_zscore"
+    )
+```
+![zscore](img/zscores.png)
+This extendable strategy lets BasePlot handle the boilerplate, while you can focus on creating the visualizations you need.
+It is also easier to reuse components in different contexts.
+### 📈 Distribution Fitting
+
+GOAD🐐 includes tools for fitting statistical distributions to your data:
+
+```python
+from goad_toolkit.analytics import DistributionFitter
+from goad_toolkit.visualizer import PlotSettings, FitPlotSettings, PlotFits
+
+fitter = DistributionFitter()
+fits = fitter.fit(data["residual"], discrete=False) # we have to decide if the data is discrete or not
+best = fitter.best(fits)
+settings = PlotSettings(
+    figsize=(12, 6), title="Residuals", xlabel="error", ylabel="probability"
+)
+fitplotsettings = FitPlotSettings(bins=30, max_fits=3)
+fitplotter = PlotFits(settings)
+fig = fitplotter.plot(
+    data=data["residual"], fit_results=fits, fitplotsettings=fitplotsettings
+)
+```
+For the [kstest](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.kstest.html), the null hypothesis is that the two distributions are identical. In this example, the p-values are below 0.05, so we can reject the null hypothesis and conclude that the data does not follow any of these.
+
+The plots are sorted by log-likelihood, which means there is no good fit with a distribution in this case.
+![residuals](img/distribution_fit.png)
+
+### 🧩 Extending with Custom Distributions
+
+You can easily register new distributions:
+
+```python
+from goad_toolkit.distributions import DistributionRegistry
+from scipy import stats
+
+# Create registry
+registry = DistributionRegistry()
+
+# Register a new distribution
+registry.register_distribution(
+    name="negative_binomial",
+    dist=stats.nbinom,
+    is_discrete=True,
+    num_params=2
+)
+
+# Now it will be used automatically in the  DistributionFitter for discrete fits
+from goad_toolkit.analytics import DistributionFitter
+fitter = DistributionFitter()
+print(fitter.registry) # shows all registered distributions
+```
+
+
+
+## 🔧 Advanced Usage: Composing Plots
+
+GOAD🐐 has a powerful plotting system that allows you to combine plot elements:
+
+```python
+from goad_toolkit.visualizer import BasePlot, LinePlot, BarWithDates, VerticalDate
+
+# Use a base plot to create a composite
+class MyCompositePlot(BasePlot):
+    def build(self, data: pd.DataFrame, x: str, y1: str, y2: str, special_date: str):
+        # Plot the first component - a line plot
+        line_plot = LinePlot(self.settings)
+        self.plot_on(line_plot, data=data, x=x, y=y1, label=y1)
+
+        # Plot the second component - a bar chart
+        bar_plot = BarWithDates(self.settings)
+        self.plot_on(bar_plot, data=data, x=x, y=y2)
+
+        # Add a vertical line
+        vline = VerticalDate(self.settings)
+        self.plot_on(vline, date=special_date, label="Important Event")
+        return self.fig, self.ax
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+<p align="center">
+  <em>GOAD🐐 - When your data analysis is so fire🔥 it's got rizz✨</em>
+</p>

goad_toolkit-0.2.0/README.md

@@ -0,0 +1,228 @@
+# GOAD🐐 is the GOAT - Goal Oriented Analysis of Data
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![image](https://shields.io/pypi/v/goad_toolkit.svg)](https://pypi.org/project/goad_toolkit/)
+
+<p align="center">
+  <em>GOAD🐐 - When your data analysis is so fire🔥 it's got rizz✨</em>
+</p>
+
+![GOAD🐐](img/goaded.png)
+
+GOAD🐐 is a flexible Python package for analyzing, transforming, and visualizing data with an emphasis on statistical distribution fitting and modular visualization components.
+
+> with thanks to my daughters for the genz slang!
+
+## 📊 Features
+
+- **Composable & extendable plotting system** - Build complex visualizations by combining simple components. You can extend the existing components with your own.
+- **Statistical distribution fitting** - Automatically fit and compare distributions to your data. The distribution registry is extendable with additional distributions.
+- **Extendable data transformation pipelines** - Chain and reuse data transformations into pipelines. Again, extendable with custom transformation components.
+
+> Before GOAD🐐 : mid data
+> After GOAD🐐 : data got infinity aura
+
+## 📖 Documentation
+
+Full documentation lives in [`docs/`](docs/README.md) — ten chapters covering the method, the
+pipeline and plot systems, the five families of visualisation, distribution fitting, models
+and residuals, and a visual-critique checklist.
+
+The same chapters are also available as an **MCP server**, so your coding assistant can coach
+you through an analysis instead of doing it for you. See [MCP_SERVER.md](MCP_SERVER.md).
+
+## 🚀 Quick Start
+
+### Installation
+Using [uv](https://docs.astral.sh/uv/):
+```bash
+uv add goad-toolkit
+```
+
+Or, if you prefer your dependencies to be installed 100x slower, with pip:
+```bash
+pip install goad-toolkit
+```
+
+## 📋 Demo: Linear Model Analysis
+
+GOAD🐐 includes a comprehensive [demo](demo/linear.py) that shows how to use its components together.
+
+### Main capabilities
+In the [demo/linear.py](demo/linear.py) file you can see a showcase of the main capabilities of GOAD🐐:
+- create a data processing pipeline
+- components are extendable, so you can easily add your own steps to a pipeline
+- create visualisations by stacking components. `BasePlot` will handle boilerplate.
+- the `DistributionFitter` will try to fit a few common distributions, and add statistical tests for you
+- The results work together with the `visualizer.PlotFits` class to show the results
+
+The main strenght of this module is not that these elements are there (even thought they are very useful). Its superpower is that everything is extendable: so you can use this as a start, and extend it with your own visualisations and analytics.
+
+> POV: Your data just got GOADed🐐 and now it's giving main character energy
+
+## 📚 Core Components
+
+#### 🔄 Extendable Data Transforms
+
+GOAD🐐 provides a pipeline approach to transform your data:
+
+```python
+from goad_toolkit.datatransforms import Pipeline, ShiftValues, ZScaler
+
+# Create a pipeline
+pipeline = Pipeline()
+
+# Add transformations
+pipeline.add(ShiftValues, name="shift_deaths", column="deaths", period=-14)
+pipeline.add(ZScaler, name="scale_tests", column="positivetests", rename=True)
+
+# Apply all transformations
+result = pipeline.apply(data)
+```
+
+Available transforms include:
+- `ShiftValues` - Shift values in a column by a specified period
+- `DiffValues` - Calculate the difference between consecutive values
+- `SelectDataRange` - Select rows within a specified date range
+- `RollingAvg` - Calculate rolling average of a column
+- `ZScaler` - Standardize values in a column
+
+You can extend the pipeline with your own transformations by subclassing `BaseTransform`. The Zscaler is implemented as follows:
+
+```python
+class ZScaler(TransformBase):
+    """Standardize the values in a column."""
+    def transform(
+        self, data: pd.DataFrame, column: str, rename: bool = False
+    ) -> pd.DataFrame:
+        """Standardize the values in a column."""
+        if rename:
+            colname = f"{column}_zscore"
+        else:
+            colname = column
+        data[colname] = (data[column] - data[column].mean()) / data[column].std()
+        return data
+```
+
+### 📊 Visualization System
+
+GOAD🐐 visualization system is built on a composable architecture that allows you to build complex plots by combining simpler components:
+
+```python
+from goad_toolkit.visualizer import PlotSettings, ResidualPlot
+
+# Create plot settings
+plotsettings = PlotSettings(
+        xlabel="date",
+        ylabel="normalized values",
+        title="Z-Scores of Deaths and Positive Tests",
+    )
+
+class LinePlot(BasePlot):
+    """Plot a line plot using seaborn."""
+    def build(self, data: pd.DataFrame, **kwargs):
+        sns.lineplot(data=data, ax=self.ax, **kwargs)
+        return self.fig, self.ax
+
+
+class ComparePlot(BasePlot):
+    def build(self, data: pd.DataFrame, x: str, y1: str, y2: str, **kwargs):
+        compare = LinePlot(self.settings)
+        self.plot_on(compare, data=data, x=x, y=y1, label=y1, **kwargs)
+        self.plot_on(compare, data=data, x=x, y=y2, label=y2, **kwargs)
+        plt.xticks(rotation=45)
+
+        return self.fig, self.ax
+
+compareplot = ComparePlot(plotsettings)
+compareplot.plot(
+        data=data, x="date", y1="deaths_shifted_zscore", y2="positivetests_zscore"
+    )
+```
+![zscore](img/zscores.png)
+This extendable strategy lets BasePlot handle the boilerplate, while you can focus on creating the visualizations you need.
+It is also easier to reuse components in different contexts.
+### 📈 Distribution Fitting
+
+GOAD🐐 includes tools for fitting statistical distributions to your data:
+
+```python
+from goad_toolkit.analytics import DistributionFitter
+from goad_toolkit.visualizer import PlotSettings, FitPlotSettings, PlotFits
+
+fitter = DistributionFitter()
+fits = fitter.fit(data["residual"], discrete=False) # we have to decide if the data is discrete or not
+best = fitter.best(fits)
+settings = PlotSettings(
+    figsize=(12, 6), title="Residuals", xlabel="error", ylabel="probability"
+)
+fitplotsettings = FitPlotSettings(bins=30, max_fits=3)
+fitplotter = PlotFits(settings)
+fig = fitplotter.plot(
+    data=data["residual"], fit_results=fits, fitplotsettings=fitplotsettings
+)
+```
+For the [kstest](https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.kstest.html), the null hypothesis is that the two distributions are identical. In this example, the p-values are below 0.05, so we can reject the null hypothesis and conclude that the data does not follow any of these.
+
+The plots are sorted by log-likelihood, which means there is no good fit with a distribution in this case.
+![residuals](img/distribution_fit.png)
+
+### 🧩 Extending with Custom Distributions
+
+You can easily register new distributions:
+
+```python
+from goad_toolkit.distributions import DistributionRegistry
+from scipy import stats
+
+# Create registry
+registry = DistributionRegistry()
+
+# Register a new distribution
+registry.register_distribution(
+    name="negative_binomial",
+    dist=stats.nbinom,
+    is_discrete=True,
+    num_params=2
+)
+
+# Now it will be used automatically in the  DistributionFitter for discrete fits
+from goad_toolkit.analytics import DistributionFitter
+fitter = DistributionFitter()
+print(fitter.registry) # shows all registered distributions
+```
+
+
+
+## 🔧 Advanced Usage: Composing Plots
+
+GOAD🐐 has a powerful plotting system that allows you to combine plot elements:
+
+```python
+from goad_toolkit.visualizer import BasePlot, LinePlot, BarWithDates, VerticalDate
+
+# Use a base plot to create a composite
+class MyCompositePlot(BasePlot):
+    def build(self, data: pd.DataFrame, x: str, y1: str, y2: str, special_date: str):
+        # Plot the first component - a line plot
+        line_plot = LinePlot(self.settings)
+        self.plot_on(line_plot, data=data, x=x, y=y1, label=y1)
+
+        # Plot the second component - a bar chart
+        bar_plot = BarWithDates(self.settings)
+        self.plot_on(bar_plot, data=data, x=x, y=y2)
+
+        # Add a vertical line
+        vline = VerticalDate(self.settings)
+        self.plot_on(vline, date=special_date, label="Important Event")
+        return self.fig, self.ax
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
+
+<p align="center">
+  <em>GOAD🐐 - When your data analysis is so fire🔥 it's got rizz✨</em>
+</p>