plotlywaterfall 1.0.0__tar.gz → 1.2.0__tar.gz

{plotlywaterfall-1.0.0 → plotlywaterfall-1.2.0}/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-11-05
+
+### Added
+- **Start and end levels for bridges**: `start="EBIT 2025"` marks x-values that hold a level, not a
+  change; they are drawn like totals (grey with direction colours, unsigned labels).
+- **`measure` column** with plotly's `go.Waterfall` names: `"relative"` (change), `"absolute"`
+  (given level, e.g. budget or actual) and `"total"` (calculated level, value ignored). Works with
+  categories (stacked levels) and groups (each group its own levels).
+- **`reconcile`** for given levels that the changes before them do not add up to: `"other"` (default)
+  inserts a bar for the difference (`reconcile_label`, default `"Other"`), `"jump"` draws the given
+  level, `"error"` raises `ValueError`.
+- Example gallery: a new first part with finance examples (EBIT bridge, budget vs actual by segment,
+  monthly cash-flow walk, one bridge per region, from a ledger to a bridge) and sections on order,
+  dates and export.
+
+### Changed
+- Hover text of totals without categories names the total (`Subtotal: 5`) instead of `Total: 5`.
+- Dates mixed with text labels on the x-axis (e.g. `"Opening"` and month ends) are formatted one by one.
+
+## [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

{plotlywaterfall-1.0.0 → plotlywaterfall-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plotlywaterfall
-Version: 1.0.0
+Version: 1.2.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
@@ -97,6 +97,30 @@ fig
 
 ![Example waterfall chart with three groups, stacked categories, a subtotal and a total](https://docdru.github.io/plotlywaterfall/images/readme-example.png)
 
+### Bridges: start and end levels
+
+A finance bridge goes from one level to another, e.g. from last year's EBIT to this year's.
+`start` marks the x-value that holds a level instead of a change; it is drawn like a total:
+
+```python
+waterfall(df, x="item", y="MEUR", start="EBIT 2025", total=True, total_column_name="EBIT 2026")
+```
+
+When the data says what each row is, pass a `measure` column with plotly's names: `"relative"`
+(a change, also for empty cells), `"absolute"` (a given level, e.g. budget or actual) or `"total"`
+(a level calculated from the rows before; its value is ignored).
+
+| X | Y | measure |
+|---|---|---|
+| Budget | 100 | absolute |
+| Volume | 2 | relative |
+| Costs | -3.5 | relative |
+| Actual | 102 | absolute |
+
+If the changes do not add up to a given level, `reconcile` decides: `"other"` (default) inserts a bar
+for the difference, labelled `reconcile_label` (`"Other"`), so the walk adds up; `"jump"` draws the
+given level as it is; `"error"` raises a `ValueError`.
+
 ### Labels, number format and hover
 
 Every bar is labelled with its change (signed, e.g. `+9`) or, for totals, its value; hovering shows
@@ -107,12 +131,21 @@ the step, its category and the running total.
 | `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:

{plotlywaterfall-1.0.0 → plotlywaterfall-1.2.0}/README.md

@@ -65,6 +65,30 @@ fig
 
 ![Example waterfall chart with three groups, stacked categories, a subtotal and a total](https://docdru.github.io/plotlywaterfall/images/readme-example.png)
 
+### Bridges: start and end levels
+
+A finance bridge goes from one level to another, e.g. from last year's EBIT to this year's.
+`start` marks the x-value that holds a level instead of a change; it is drawn like a total:
+
+```python
+waterfall(df, x="item", y="MEUR", start="EBIT 2025", total=True, total_column_name="EBIT 2026")
+```
+
+When the data says what each row is, pass a `measure` column with plotly's names: `"relative"`
+(a change, also for empty cells), `"absolute"` (a given level, e.g. budget or actual) or `"total"`
+(a level calculated from the rows before; its value is ignored).
+
+| X | Y | measure |
+|---|---|---|
+| Budget | 100 | absolute |
+| Volume | 2 | relative |
+| Costs | -3.5 | relative |
+| Actual | 102 | absolute |
+
+If the changes do not add up to a given level, `reconcile` decides: `"other"` (default) inserts a bar
+for the difference, labelled `reconcile_label` (`"Other"`), so the walk adds up; `"jump"` draws the
+given level as it is; `"error"` raises a `ValueError`.
+
 ### Labels, number format and hover
 
 Every bar is labelled with its change (signed, e.g. `+9`) or, for totals, its value; hovering shows
@@ -75,12 +99,21 @@ the step, its category and the running total.
 | `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:

plotlywaterfall-1.2.0/src/plotlywaterfall/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.2.0"

{plotlywaterfall-1.0.0 → plotlywaterfall-1.2.0}/src/plotlywaterfall/_coloring.py

@@ -50,6 +50,7 @@ class Coloring:
         pattern_shape: str | None,
         pattern_shape_map: dict | None,
         total_name: str = "Total",
+        orders: dict[str, list] | None = None,
     ):
         self._group = group
         self._category = category
@@ -74,8 +75,14 @@ class Coloring:
             )
         self.pattern_shape = pattern_shape
 
-        self._color_values = [] if color == DIRECTION else list(df[color].unique())
-        self._pattern_values = [] if pattern_shape is None else list(df[pattern_shape].unique())
+        # display order of the group / category values (palette colours are handed out in it)
+        orders = orders or {}
+
+        def values(column: str) -> list:
+            return list(orders[column]) if column in orders else list(df[column].unique())
+
+        self._color_values = [] if color == DIRECTION else values(color)
+        self._pattern_values = [] if pattern_shape is None else values(pattern_shape)
         self._warn_unknown_keys(df)
 
     # ------------------------------------------------------------------ validation

plotlywaterfall-1.2.0/src/plotlywaterfall/_format.py

@@ -0,0 +1,84 @@
+"""Number formatting shared by value labels and hover texts."""
+
+from collections.abc import Callable, Iterable
+from typing import Literal, get_args
+
+NumberFormat = str | Callable[[float], str] | None
+NegativeStyle = Literal["minus", "parentheses"]
+NumberUnit = Literal["k", "M", "bn", "auto"]
+
+NEGATIVE_STYLES: tuple[str, ...] = get_args(NegativeStyle)
+NUMBER_UNITS: tuple[str, ...] = get_args(NumberUnit)
+UNIT_DIVISORS = {"k": 1e3, "M": 1e6, "bn": 1e9}
+
+
+def auto_unit(values: Iterable[float]) -> str | None:
+    """The unit for a chart whose largest absolute value is max(|values|): one unit for all
+    labels, so that a chart never mixes "950k" and "1.2M"."""
+    largest = max((abs(v) for v in values), default=0.0)
+    for unit in ("bn", "M", "k"):
+        if largest >= UNIT_DIVISORS[unit]:
+            return unit
+    return None
+
+
+class NumberFormatter:
+    """Format numbers as `[sign][prefix]number[unit][suffix]`.
+
+    `number_format` is a Python format spec applied to the absolute value (e.g. ",.1f"), a
+    callable returning the text for the absolute value, or None for the default: thousands
+    separators and up to two decimals without trailing zeros (9, 0.5, 1,234.57).
+    The sign is written by the formatter itself, so that currency prefixes come out right
+    ("-$5", not "$-5"); changes (steps) are always signed ("+9", "-7"), levels and totals only
+    when negative. With negative_style="parentheses" negatives are written as in accounting,
+    "(7)", and positive changes get no "+".
+    `unit` ("k", "M", "bn") divides values by thousand, million or billion and writes the unit
+    after the number ("12.5M").
+    """
+
+    def __init__(
+        self,
+        number_format: NumberFormat = None,
+        prefix: str = "",
+        suffix: str = "",
+        negative_style: NegativeStyle = "minus",
+        unit: str | None = None,
+    ):
+        if number_format is not None and not callable(number_format):
+            try:
+                format(1234.5, number_format)
+            except (ValueError, TypeError) as exc:
+                raise ValueError(f"Invalid number_format {number_format!r}: {exc}") from exc
+        if negative_style not in NEGATIVE_STYLES:
+            raise ValueError(
+                f"negative_style must be one of {NEGATIVE_STYLES}, got {negative_style!r}"
+            )
+        if unit is not None and unit not in UNIT_DIVISORS:
+            raise ValueError(f"unit must be one of {tuple(UNIT_DIVISORS)} or None, got {unit!r}")
+        self._format = number_format
+        self._prefix = prefix
+        self._suffix = suffix
+        self._negative_style = negative_style
+        self.unit = unit
+
+    def _body(self, value: float) -> str:
+        if self._format is None:
+            text = f"{value:,.2f}"
+            return text.rstrip("0").rstrip(".") if "." in text else text
+        if callable(self._format):
+            return self._format(value)
+        return format(value, self._format)
+
+    def __call__(self, value: float, signed: bool = False) -> str:
+        divisor = UNIT_DIVISORS[self.unit] if self.unit else 1.0
+        body = self._body(abs(value) / divisor)
+        is_zero = body.strip("0.,") == ""
+        number = f"{self._prefix}{body}{self.unit or ''}{self._suffix}"
+        negative = value < 0 and not is_zero
+        if self._negative_style == "parentheses":
+            return f"({number})" if negative else number
+        if negative:
+            return f"-{number}"
+        if signed and value > 0 and not is_zero:
+            return f"+{number}"
+        return number