plotlywaterfall 0.9.3__tar.gz → 1.1.0__tar.gz

plotlywaterfall-1.1.0/CHANGELOG.md

@@ -0,0 +1,119 @@
+# Changelog
+
+## [Unreleased]
+
+## [1.1.0] - 2026-11-05
+
+### Fixed
+- **Wrong levels with groups whose rows are in a different order**: running levels were accumulated
+  in each group's own row order instead of the x-axis order, so such a group's bars started at the
+  wrong height. They now always follow the x-axis.
+- **Dates on the x-axis** were labelled `Timestamp('2026-01-31 00:00:00')`; they are now shown as
+  `Jan 2026` (dates in different months) or `2026-01-31`, in tick labels and hover.
+- **The order of a pandas `Categorical` x column** was ignored; it now sets the order of the bars
+  (and of groups and categories).
+
+### Added
+- `category_orders` (as in plotly express) to set the order of x, group and category values;
+  the colour palette is assigned in that order.
+- `x_format`: strftime pattern for date x-values or a function for any x-values.
+- `number_unit` (`"k"`, `"M"`, `"bn"` or `"auto"` = one unit for the whole chart) and
+  `negative_style="parentheses"` for accounting-style labels such as `($0.73M)`.
+
+## [1.0.0] - 2026-11-05
+
+First stable release: a one-call `waterfall()` function, mixed signs within a bar, a plotly-express
+style colour API, value labels and hover texts, type hints, and an
+[example gallery](https://docdru.github.io/plotlywaterfall/).
+
+### Upgrading from 0.9
+- **`colors` was removed.** Use `color` and `color_discrete_map`:
+
+  | 0.9 `colors=` | 1.0 |
+  |---|---|
+  | `{"one": "red", "two": "blue"}` (per category) | `color_discrete_map={"one": "red", "two": "blue"}` |
+  | `{"Group1": "red", "Group2": "blue"}` (per group) | `color="group", color_discrete_map={"Group1": "red", "Group2": "blue"}` (with your group column name) |
+  | `{"Group1": {"one": "red"}}` (per group and category) | `color_discrete_map={("Group1", "one"): "red"}` |
+
+- **Charts look different by default:** bars carry value labels (`value_labels=None` turns them
+  off), charts without category and group are coloured by direction (green / red / grey), a category
+  keeps its colour across groups, and the y-axis is titled with the y column.
+- **Mixed signs within one bar are drawn** as sub-steps instead of raising `NotImplementedError`;
+  `mixed_signs="error"` restores the old behaviour.
+- **Python 3.11 or newer** is required.
+
+### Added
+- **Type hints throughout** and a `py.typed` marker, so type checkers (mypy, pyright) use the
+  package's annotations.
+- Options with a fixed set of values (`total_type`, `mixed_signs`, `step_order`, `value_labels`) are
+  typed as `Literal`s, so editors suggest the valid values and type checkers catch typos.
+- **`waterfall(df, x=..., y=..., ...)`**: one call that returns the figure, like plotly express'
+  `px.bar`. Same arguments as `Waterfall` (keyword-only after `x` and `y`); `Waterfall` stays for
+  building subtotals step by step.
+- **New colour API in plotly-express style**: `color` (category column, group column or
+  `"direction"`), `color_discrete_map` (value → colour; `(group, category)` tuples for one group's
+  category), `color_discrete_sequence`, `pattern_shape` and `pattern_shape_map`.
+- `color="direction"` colours increases, decreases and totals (default green / red / grey) and adds
+  a legend for them.
+- Keys of `color_discrete_map` / `pattern_shape_map` that match no value raise a `UserWarning`.
+- **Value labels**: `value_labels` (`"bar"` default, `"segment"`, `"both"`, `None` / `False`), with one number
+  format for labels and hover: `number_format` (Python format spec or function), `number_prefix`,
+  `number_suffix`. Changes are signed (`+9`, `-7`), totals not.
+- **Hover texts** show the x label, the segment's category and value, the step for split bars and the
+  running total (previously plotly's default hover showed the internal numeric x-position).
+- `title` and `labels` (column display names, as in plotly express) arguments.
+- **Mixed signs within one bar**: categories of one bar (at an x-value or in a total) may now have
+  different signs. The bar is split into narrow sub-steps that walk from its start to its end level,
+  with a "net ghost" bar behind them showing the net change. New arguments `mixed_signs`
+  (`"steps"` default, `"error"` for the previous behaviour), `net_ghost` and `step_order`.
+
+### Changed
+- `import plotlywaterfall.waterfall as m` now gives the `waterfall` function (the package exports it under
+  that name). `from plotlywaterfall.waterfall import Waterfall` keeps working.
+- **Value labels are shown by default** (`value_labels=None` restores unlabelled bars) and the y-axis is
+  titled with the y column name (or its `labels` entry). The axis range leaves room for the labels.
+- **Minimum Python is now 3.11** (3.8–3.10 are end-of-life; the code never ran on 3.8/3.9).
+- `numpy` is now declared as a dependency (it was imported but not declared); dependencies are declared in
+  `pyproject.toml` and `requirements.txt` was removed.
+- **Default colours**: charts without category and group are coloured by direction. Charts with
+  categories or groups get one colour per category (or group) taken from the template's colorway,
+  so a category has the same colour in every group (previously plotly cycled colours per trace).
+- Clear `ValueError`s for invalid input: unknown column names, missing values (NaN) in `y`,
+  unknown `total_type`, and subtotal keys that are not x-values (now also checked in the constructor).
+- `Waterfall` can be imported directly: `from plotlywaterfall import Waterfall`
+  (`from plotlywaterfall.waterfall import Waterfall` keeps working); `plotlywaterfall.__version__` added.
+- Internal cleanup: removed dead code in `add_subtotal`, one helper for bar offsets and one for colors.
+
+### Removed
+- The `colors` argument, replaced by `color` / `color_discrete_map` (see "Upgrading from 0.9").
+
+### Fixed
+- `total_type="sumtotal"` with groups raised `KeyError: 'Y'` unless the value column was named `Y`.
+- Groups with opposite signs at the same x-value (or opposite-signed totals) raised
+  "mixed signed categories in totals"; the sign check now only compares stacked bars within one group.
+- The `subtotals` dict passed by the caller is no longer modified (with `total=True` it used to gain
+  the total, which added an extra bar when the dict was reused).
+- The `connector_line` default is no longer a dict shared between instances.
+
+### Development
+- mypy runs with `disallow_untyped_defs` and `disallow_incomplete_defs`; CI checks that the wheel
+  contains `py.typed`.
+- Example gallery: CI executes the example notebook and publishes it as HTML with interactive charts on
+  GitHub Pages (pull requests: `docs-site` artifact); the README image is rendered by CI as well.
+- Modern development setup: uv with `uv.lock`, PEP 735 dependency groups, ruff (lint + format), mypy, pre-commit.
+- GitHub Actions CI: lint, type check, tests on Python 3.11–3.15 (Linux/Windows/macOS), lowest-dependency and
+  pre-release dependency jobs, example-notebook execution, package build; weekly scheduled run.
+- Automated PyPI releases on version tags via Trusted Publishing with attestations; Dependabot for actions and dependencies.
+- Automated AI pull-request review (Mistral) posted as a PR comment; see README "AI pull-request review".
+
+## [0.9.3] - 2024-02-20
+- Bugfix legend groups
+
+## [0.9.2] - 2024-02-20
+- Bugfix line placement in case of empty bars at certain x in other then the first group
+
+## [0.9.1] - 2024-01-04
+- Added CHANGELOG.md and using full URLs for images in README.md
+
+## [0.9.0] - 2024-01-04
+- Initial release on pypi.org

{plotlywaterfall-0.9.3 → plotlywaterfall-1.1.0}/LICENSE

@@ -1,4 +1,6 @@
-Copyright (c) 2012-2024 Scott Chacon and others
+MIT License
+
+Copyright (c) 2023-2026 Daniel Rüffer
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

plotlywaterfall-1.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: plotlywaterfall
+Version: 1.1.0
+Summary: Plotly-express-style waterfall charts with groups, stacked categories, subtotals and custom colors.
+Project-URL: Homepage, https://github.com/docdru/plotlywaterfall
+Project-URL: Source, https://github.com/docdru/plotlywaterfall
+Project-URL: Issues, https://github.com/docdru/plotlywaterfall/issues
+Project-URL: Changelog, https://github.com/docdru/plotlywaterfall/blob/main/CHANGELOG.md
+Author-email: Daniel Rüffer <docdru.plotlywaterfall@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cashflow,chart,finance,jupyter,plotly,visualization,waterfall
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2
+Requires-Dist: plotly>=5.24
+Description-Content-Type: text/markdown
+
+# plotlywaterfall
+
+[![CI](https://github.com/docdru/plotlywaterfall/actions/workflows/ci.yml/badge.svg)](https://github.com/docdru/plotlywaterfall/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/plotlywaterfall)](https://pypi.org/project/plotlywaterfall/)
+[![Python versions](https://img.shields.io/pypi/pyversions/plotlywaterfall)](https://pypi.org/project/plotlywaterfall/)
+[![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)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Examples](https://img.shields.io/badge/examples-gallery-2a78d6)](https://docdru.github.io/plotlywaterfall/)
+
+## Description
+
+A small package adding simple waterfall plotting capabilities on top of the plotly graphing package. Waterfall graphs are useful to display e.g. financial data such as cashflow statements in an easily digestible format. 
+
+While plotly includes basic capabilities to plot waterfall graphs, it ships only limited features. The *plotlywaterfall* package provides simple, plotly-express-style waterfall graphs with grouping, multiple stacked categories and variable colors. 
+
+## Installation
+
+Requires Python 3.11 or newer.
+
+```bash
+pip install plotlywaterfall
+# or
+uv add plotlywaterfall
+```
+
+## Usage
+
+**[Example gallery](https://docdru.github.io/plotlywaterfall/)** with interactive charts for every feature (rendered from
+[`examples/examples.ipynb`](https://github.com/docdru/plotlywaterfall/blob/main/examples/examples.ipynb) by CI).
+
+`waterfall(df, x=..., y=..., ...)` returns a plotly figure, like plotly express' `px.bar`. The class
+`Waterfall` takes the same arguments (`Waterfall(...).get_fig()`) and also lets you add subtotals step by
+step with `add_subtotal`.
+
+A complete example with groups, stacked categories, a subtotal and a total:
+
+```python
+import pandas as pd
+
+from plotlywaterfall import waterfall
+
+df = pd.DataFrame(
+    {
+        "X": ["A", "B", "C"] * 4 + ["D", "D"],
+        "Y": [4, 1, 8, 7, 3, 2] + [i - 1 for i in [4, 1, 8, 7, 3, 2]] + [8, 5],
+        "category": ["one"] * 3 + ["two"] * 3 + ["one"] * 3 + ["two"] * 3 + ["two", "three"],
+        "group": ["Group1"] * 6 + ["Group2"] * 6 + ["Group2", "Group3"],
+    }
+)
+
+fig = waterfall(
+    df,
+    x="X",
+    y="Y",
+    category="category",
+    group="group",
+    total=True,
+    subtotals={"C": "Subtotal"},
+    color_discrete_map={"one": "#2a78d6", "two": "#eb6834", "three": "#1baf7a"},
+    pattern_shape="group",
+)
+fig.update_layout(template="plotly_white")
+fig
+```
+
+![Example waterfall chart with three groups, stacked categories, a subtotal and a total](https://docdru.github.io/plotlywaterfall/images/readme-example.png)
+
+### Labels, number format and hover
+
+Every bar is labelled with its change (signed, e.g. `+9`) or, for totals, its value; hovering shows
+the step, its category and the running total.
+
+| Argument | Meaning | Default |
+|---|---|---|
+| `value_labels` | `"bar"` (one label per bar, outside), `"segment"` (inside each stacked segment), `"both"`, or `None` / `False` for no labels | `"bar"` |
+| `number_format` | Python format spec for the absolute value (e.g. `",.1f"`) or a function | thousands separators, up to two decimals |
+| `number_prefix` / `number_suffix` | Units around the number; the sign stays in front (`-$5M`) | `""` |
+| `number_unit` | `"k"`, `"M"`, `"bn"` (e.g. 12500000 → `12.5M`), or `"auto"` for one unit chosen from the chart's largest value | `None` |
+| `negative_style` | `"minus"` (`-7`, changes `+9`) or `"parentheses"` (accounting: `(7)`, changes unsigned) | `"minus"` |
+| `title` | Figure title | `None` |
+| `labels` | Display names for columns, like plotly express (`{"Y": "Cashflow [MUSD]"}`); titles the axes | y-axis titled with the y column |
+| `category_orders` | Order of x, group or category values, like plotly express (`{"X": ["Revenue", "Costs"]}`) | order of a pandas `Categorical`, else of appearance |
+| `x_format` | Labels of the x-values: a strftime pattern for dates (`"%b %Y"`) or a function | dates as `Jan 2026` (one per month) or `2026-01-31` |
+
+    waterfall(df, x="X", y="Y", total=True, number_prefix="$", number_suffix="M",
+              title="Cash bridge", labels={"Y": "Cashflow [MUSD]"})
+
+For financial statements: one unit for all labels and accounting negatives,
+
+    waterfall(df, x="X", y="Y", total=True, number_unit="auto", negative_style="parentheses",
+              number_prefix="$")   # $1.25M, ($0.73M), …
+
+### Colors
+
+Colours work like in plotly express:
+
+| Argument | Meaning |
+|---|---|
+| `color` | What drives the colour: the category column, the group column, or `"direction"` (increase / decrease / total). Default: the category column if given, else the group column, else `"direction"`. |
+| `color_discrete_map` | Colour per value, e.g. `{"one": "red"}`. `(group, category)` tuples colour one group's category. With `color="direction"` the keys are `"increase"`, `"decrease"`, `"total"` (default green / red / grey). Keys that match no value raise a warning. |
+| `color_discrete_sequence` | Colours for values missing from the map, assigned in order. Default: the colorway of the active plotly template. |
+| `pattern_shape` | The group or category column, to give its values different fill patterns, e.g. colour by category and pattern by group. |
+| `pattern_shape_map` | Pattern per value, e.g. `{"Actual": "/"}`. |
+
+Colours are assigned per value, so a category has the same colour in every group:
+
+    waterfall(df, x="X", y="Y", category="category", group="group", total=True,
+              pattern_shape="group")
+
+Coming from version 0.9? The `colors` argument was replaced by `color` / `color_discrete_map`; see
+[Upgrading from 0.9](https://github.com/docdru/plotlywaterfall/blob/main/CHANGELOG.md#upgrading-from-09).
+
+### Mixed signs
+
+Categories of one bar may have different signs, e.g. a subsidy (+1) and a restructuring charge (−4)
+at the same x-value, or a total that combines positive and negative categories. Such a bar is split
+into one narrow sub-step per category that walks from the level where the bar starts to where it
+ends, with a light "net ghost" bar behind it showing the net change:
+
+    df = pd.DataFrame({
+        "X": ["Revenue", "Costs", "Other", "Other"],
+        "Y": [9, -7, 1, -4],
+        "category": ["Operating", "Operating", "Operating", "One-off"],
+    })
+    waterfall(df, x="X", y="Y", category="category", total=True)
+
+Options:
+
+| Argument | Values | Default |
+|---|---|---|
+| `mixed_signs` | `"steps"` (split into sub-steps), `"error"` (raise `NotImplementedError`, the behaviour before 1.0) | `"steps"` |
+| `net_ghost` | `True`, `False`, or a dict of plotly marker properties for the net bar | `True` |
+| `step_order` | `"data"` (order of the categories in the DataFrame), `"positive_first"`, `"largest_first"` | `"data"` |
+
+Bars whose categories share a sign are drawn as normal stacked bars. With several groups each group's
+bar walks on its own; with many groups and categories the sub-steps get narrow, so increase `barwidth`.
+
+
+## Disclaimer
+
+I might maintain and improve the package. I might also not.
+
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for environments and dependency locking.
+
+```bash
+git clone https://github.com/docdru/plotlywaterfall.git
+cd plotlywaterfall
+uv sync                       # creates .venv with the package + all dev tools
+uv run pre-commit install     # optional: run checks on every commit
+```
+
+Common tasks:
+
+| Task | Command |
+|---|---|
+| Run tests | `uv run pytest` |
+| Tests with coverage | `uv run pytest --cov` |
+| Test another Python | `uv run --python 3.11 pytest` |
+| Lint / auto-fix | `uv run ruff check --fix` |
+| Format | `uv run ruff format` |
+| Type check | `uv run mypy` |
+| Execute example notebook | `uv run pytest --nbmake examples/ -p no:warnings` |
+| Build the docs site (gallery + README image) | `uv run --group notebook --with nbconvert --with kaleido python scripts/build_docs.py --out site` |
+| Open notebooks | `uv run --with jupyterlab jupyter lab` |
+| Build sdist + wheel | `uv build` |
+
+CI (GitHub Actions) runs lint, type checks, the test suite on Python 3.11–3.15 (Linux, plus Windows; macOS on `main` and the weekly run),
+a test against the lowest supported dependency versions, the docs site, and a package build.
+
+The **docs site** job executes `examples/examples.ipynb`, renders it to HTML with interactive charts and
+renders the README image from `examples/readme_example.py` (keep it in sync with the README code).
+Pull requests get the result as the `docs-site` artifact of the CI run; on `main` it is published to
+[GitHub Pages](https://docdru.github.io/plotlywaterfall/). Nothing generated is committed. One-time setup: *Settings → Pages →
+Build and deployment → Source: GitHub Actions*.
+
+### AI pull-request review
+
+Pull requests get an automated review comment (correctness and tests, API/docs consistency,
+security and supply chain, surprising changes) from `.github/workflows/ai-review.yml`, which runs
+`scripts/ai_review.py` against the Mistral API. The comment is updated on every push.
+
+- **Setup:** add the repository secret `MISTRAL_API_KEY` (*Settings → Secrets and variables → Actions*).
+  Optionally set the repository variable `AI_REVIEW_MODEL` to override the default model (`mistral-large-2512`).
+- **Scope:** runs for non-draft PRs from branches in this repository by authors with write access;
+  fork, bot and draft PRs are skipped. Mark a draft "Ready for review" to trigger it.
+- **Try locally** (prints the prompt, calls nothing, posts nothing):
+  `GITHUB_REPOSITORY=docdru/plotlywaterfall GITHUB_TOKEN=$(gh auth token) python scripts/ai_review.py --pr 1 --dry-run`
+
+The review is advisory: it is not part of the required checks, and its findings should be verified.
+
+### Releasing
+
+1. Bump `__version__` in `src/plotlywaterfall/__about__.py` and add a `CHANGELOG.md` entry.
+2. Commit, then tag and push: `git tag v0.9.4 && git push origin v0.9.4`.
+3. The `Release` workflow builds the package and publishes it to PyPI via
+   [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no API token needed).
+
+## Changelog
+
+Refer to [CHANGELOG.md](https://github.com/docdru/plotlywaterfall/blob/main/CHANGELOG.md)

plotlywaterfall-1.1.0/README.md

@@ -0,0 +1,203 @@
+# plotlywaterfall
+
+[![CI](https://github.com/docdru/plotlywaterfall/actions/workflows/ci.yml/badge.svg)](https://github.com/docdru/plotlywaterfall/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/plotlywaterfall)](https://pypi.org/project/plotlywaterfall/)
+[![Python versions](https://img.shields.io/pypi/pyversions/plotlywaterfall)](https://pypi.org/project/plotlywaterfall/)
+[![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)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Examples](https://img.shields.io/badge/examples-gallery-2a78d6)](https://docdru.github.io/plotlywaterfall/)
+
+## Description
+
+A small package adding simple waterfall plotting capabilities on top of the plotly graphing package. Waterfall graphs are useful to display e.g. financial data such as cashflow statements in an easily digestible format. 
+
+While plotly includes basic capabilities to plot waterfall graphs, it ships only limited features. The *plotlywaterfall* package provides simple, plotly-express-style waterfall graphs with grouping, multiple stacked categories and variable colors. 
+
+## Installation
+
+Requires Python 3.11 or newer.
+
+```bash
+pip install plotlywaterfall
+# or
+uv add plotlywaterfall
+```
+
+## Usage
+
+**[Example gallery](https://docdru.github.io/plotlywaterfall/)** with interactive charts for every feature (rendered from
+[`examples/examples.ipynb`](https://github.com/docdru/plotlywaterfall/blob/main/examples/examples.ipynb) by CI).
+
+`waterfall(df, x=..., y=..., ...)` returns a plotly figure, like plotly express' `px.bar`. The class
+`Waterfall` takes the same arguments (`Waterfall(...).get_fig()`) and also lets you add subtotals step by
+step with `add_subtotal`.
+
+A complete example with groups, stacked categories, a subtotal and a total:
+
+```python
+import pandas as pd
+
+from plotlywaterfall import waterfall
+
+df = pd.DataFrame(
+    {
+        "X": ["A", "B", "C"] * 4 + ["D", "D"],
+        "Y": [4, 1, 8, 7, 3, 2] + [i - 1 for i in [4, 1, 8, 7, 3, 2]] + [8, 5],
+        "category": ["one"] * 3 + ["two"] * 3 + ["one"] * 3 + ["two"] * 3 + ["two", "three"],
+        "group": ["Group1"] * 6 + ["Group2"] * 6 + ["Group2", "Group3"],
+    }
+)
+
+fig = waterfall(
+    df,
+    x="X",
+    y="Y",
+    category="category",
+    group="group",
+    total=True,
+    subtotals={"C": "Subtotal"},
+    color_discrete_map={"one": "#2a78d6", "two": "#eb6834", "three": "#1baf7a"},
+    pattern_shape="group",
+)
+fig.update_layout(template="plotly_white")
+fig
+```
+
+![Example waterfall chart with three groups, stacked categories, a subtotal and a total](https://docdru.github.io/plotlywaterfall/images/readme-example.png)
+
+### Labels, number format and hover
+
+Every bar is labelled with its change (signed, e.g. `+9`) or, for totals, its value; hovering shows
+the step, its category and the running total.
+
+| Argument | Meaning | Default |
+|---|---|---|
+| `value_labels` | `"bar"` (one label per bar, outside), `"segment"` (inside each stacked segment), `"both"`, or `None` / `False` for no labels | `"bar"` |
+| `number_format` | Python format spec for the absolute value (e.g. `",.1f"`) or a function | thousands separators, up to two decimals |
+| `number_prefix` / `number_suffix` | Units around the number; the sign stays in front (`-$5M`) | `""` |
+| `number_unit` | `"k"`, `"M"`, `"bn"` (e.g. 12500000 → `12.5M`), or `"auto"` for one unit chosen from the chart's largest value | `None` |
+| `negative_style` | `"minus"` (`-7`, changes `+9`) or `"parentheses"` (accounting: `(7)`, changes unsigned) | `"minus"` |
+| `title` | Figure title | `None` |
+| `labels` | Display names for columns, like plotly express (`{"Y": "Cashflow [MUSD]"}`); titles the axes | y-axis titled with the y column |
+| `category_orders` | Order of x, group or category values, like plotly express (`{"X": ["Revenue", "Costs"]}`) | order of a pandas `Categorical`, else of appearance |
+| `x_format` | Labels of the x-values: a strftime pattern for dates (`"%b %Y"`) or a function | dates as `Jan 2026` (one per month) or `2026-01-31` |
+
+    waterfall(df, x="X", y="Y", total=True, number_prefix="$", number_suffix="M",
+              title="Cash bridge", labels={"Y": "Cashflow [MUSD]"})
+
+For financial statements: one unit for all labels and accounting negatives,
+
+    waterfall(df, x="X", y="Y", total=True, number_unit="auto", negative_style="parentheses",
+              number_prefix="$")   # $1.25M, ($0.73M), …
+
+### Colors
+
+Colours work like in plotly express:
+
+| Argument | Meaning |
+|---|---|
+| `color` | What drives the colour: the category column, the group column, or `"direction"` (increase / decrease / total). Default: the category column if given, else the group column, else `"direction"`. |
+| `color_discrete_map` | Colour per value, e.g. `{"one": "red"}`. `(group, category)` tuples colour one group's category. With `color="direction"` the keys are `"increase"`, `"decrease"`, `"total"` (default green / red / grey). Keys that match no value raise a warning. |
+| `color_discrete_sequence` | Colours for values missing from the map, assigned in order. Default: the colorway of the active plotly template. |
+| `pattern_shape` | The group or category column, to give its values different fill patterns, e.g. colour by category and pattern by group. |
+| `pattern_shape_map` | Pattern per value, e.g. `{"Actual": "/"}`. |
+
+Colours are assigned per value, so a category has the same colour in every group:
+
+    waterfall(df, x="X", y="Y", category="category", group="group", total=True,
+              pattern_shape="group")
+
+Coming from version 0.9? The `colors` argument was replaced by `color` / `color_discrete_map`; see
+[Upgrading from 0.9](https://github.com/docdru/plotlywaterfall/blob/main/CHANGELOG.md#upgrading-from-09).
+
+### Mixed signs
+
+Categories of one bar may have different signs, e.g. a subsidy (+1) and a restructuring charge (−4)
+at the same x-value, or a total that combines positive and negative categories. Such a bar is split
+into one narrow sub-step per category that walks from the level where the bar starts to where it
+ends, with a light "net ghost" bar behind it showing the net change:
+
+    df = pd.DataFrame({
+        "X": ["Revenue", "Costs", "Other", "Other"],
+        "Y": [9, -7, 1, -4],
+        "category": ["Operating", "Operating", "Operating", "One-off"],
+    })
+    waterfall(df, x="X", y="Y", category="category", total=True)
+
+Options:
+
+| Argument | Values | Default |
+|---|---|---|
+| `mixed_signs` | `"steps"` (split into sub-steps), `"error"` (raise `NotImplementedError`, the behaviour before 1.0) | `"steps"` |
+| `net_ghost` | `True`, `False`, or a dict of plotly marker properties for the net bar | `True` |
+| `step_order` | `"data"` (order of the categories in the DataFrame), `"positive_first"`, `"largest_first"` | `"data"` |
+
+Bars whose categories share a sign are drawn as normal stacked bars. With several groups each group's
+bar walks on its own; with many groups and categories the sub-steps get narrow, so increase `barwidth`.
+
+
+## Disclaimer
+
+I might maintain and improve the package. I might also not.
+
+
+## Development
+
+The project uses [uv](https://docs.astral.sh/uv/) for environments and dependency locking.
+
+```bash
+git clone https://github.com/docdru/plotlywaterfall.git
+cd plotlywaterfall
+uv sync                       # creates .venv with the package + all dev tools
+uv run pre-commit install     # optional: run checks on every commit
+```
+
+Common tasks:
+
+| Task | Command |
+|---|---|
+| Run tests | `uv run pytest` |
+| Tests with coverage | `uv run pytest --cov` |
+| Test another Python | `uv run --python 3.11 pytest` |
+| Lint / auto-fix | `uv run ruff check --fix` |
+| Format | `uv run ruff format` |
+| Type check | `uv run mypy` |
+| Execute example notebook | `uv run pytest --nbmake examples/ -p no:warnings` |
+| Build the docs site (gallery + README image) | `uv run --group notebook --with nbconvert --with kaleido python scripts/build_docs.py --out site` |
+| Open notebooks | `uv run --with jupyterlab jupyter lab` |
+| Build sdist + wheel | `uv build` |
+
+CI (GitHub Actions) runs lint, type checks, the test suite on Python 3.11–3.15 (Linux, plus Windows; macOS on `main` and the weekly run),
+a test against the lowest supported dependency versions, the docs site, and a package build.
+
+The **docs site** job executes `examples/examples.ipynb`, renders it to HTML with interactive charts and
+renders the README image from `examples/readme_example.py` (keep it in sync with the README code).
+Pull requests get the result as the `docs-site` artifact of the CI run; on `main` it is published to
+[GitHub Pages](https://docdru.github.io/plotlywaterfall/). Nothing generated is committed. One-time setup: *Settings → Pages →
+Build and deployment → Source: GitHub Actions*.
+
+### AI pull-request review
+
+Pull requests get an automated review comment (correctness and tests, API/docs consistency,
+security and supply chain, surprising changes) from `.github/workflows/ai-review.yml`, which runs
+`scripts/ai_review.py` against the Mistral API. The comment is updated on every push.
+
+- **Setup:** add the repository secret `MISTRAL_API_KEY` (*Settings → Secrets and variables → Actions*).
+  Optionally set the repository variable `AI_REVIEW_MODEL` to override the default model (`mistral-large-2512`).
+- **Scope:** runs for non-draft PRs from branches in this repository by authors with write access;
+  fork, bot and draft PRs are skipped. Mark a draft "Ready for review" to trigger it.
+- **Try locally** (prints the prompt, calls nothing, posts nothing):
+  `GITHUB_REPOSITORY=docdru/plotlywaterfall GITHUB_TOKEN=$(gh auth token) python scripts/ai_review.py --pr 1 --dry-run`
+
+The review is advisory: it is not part of the required checks, and its findings should be verified.
+
+### Releasing
+
+1. Bump `__version__` in `src/plotlywaterfall/__about__.py` and add a `CHANGELOG.md` entry.
+2. Commit, then tag and push: `git tag v0.9.4 && git push origin v0.9.4`.
+3. The `Release` workflow builds the package and publishes it to PyPI via
+   [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) (no API token needed).
+
+## Changelog
+
+Refer to [CHANGELOG.md](https://github.com/docdru/plotlywaterfall/blob/main/CHANGELOG.md)