plotlywaterfall 1.0.0__tar.gz → 1.1.0__tar.gz

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

@@ -2,6 +2,24 @@
 
 ## [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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plotlywaterfall
-Version: 1.0.0
+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
@@ -107,12 +107,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.1.0}/README.md

@@ -75,12 +75,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.1.0/src/plotlywaterfall/__about__.py

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

{plotlywaterfall-1.0.0 → plotlywaterfall-1.1.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.1.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

{plotlywaterfall-1.0.0 → plotlywaterfall-1.1.0}/src/plotlywaterfall/waterfall.py

@@ -1,3 +1,5 @@
+import datetime
+from collections.abc import Callable
 from typing import Any, Literal, get_args
 
 import numpy as np
@@ -5,7 +7,14 @@ import pandas as pd
 import plotly.graph_objects as go
 
 from plotlywaterfall._coloring import Coloring
-from plotlywaterfall._format import NumberFormat, NumberFormatter
+from plotlywaterfall._format import (
+    NUMBER_UNITS,
+    NegativeStyle,
+    NumberFormat,
+    NumberFormatter,
+    NumberUnit,
+    auto_unit,
+)
 
 DEFAULT_CONNECTOR_LINE: dict[str, Any] = {"color": "darkgrey", "width": 0.75}
 TotalType = Literal["category", "sumtotal"]
@@ -21,6 +30,8 @@ DEFAULT_NET_GHOST: dict[str, Any] = {
 }
 # Share of a sub-step's slot that is filled by its bar; the rest is a small visual gap
 SUBSTEP_FILL = 0.9
+# helper column with each row's position in the original DataFrame (order of appearance)
+ROW = "__plotlywaterfall_row__"
 VALUE_LABELS: tuple[str, ...] = get_args(ValueLabels)
 
 
@@ -51,8 +62,12 @@ class Waterfall:
         number_format: NumberFormat = None,
         number_prefix: str = "",
         number_suffix: str = "",
+        number_unit: NumberUnit | None = None,
+        negative_style: NegativeStyle = "minus",
         title: str | None = None,
         labels: dict | None = None,
+        category_orders: dict[str, list] | None = None,
+        x_format: str | Callable[[Any], str] | None = None,
     ):
         """Instanciate Waterfall object. All configuration is done by handing the correct kwargs.
 
@@ -110,11 +125,26 @@ class Waterfall:
             number_prefix (str, optional): Text before numbers, after the sign, e.g. "$"
                 gives "-$5". Defaults to "".
             number_suffix (str, optional): Text after numbers, e.g. " M€". Defaults to "".
+            number_unit (str | None, optional): Show numbers in thousands ("k"), millions
+                ("M") or billions ("bn"), e.g. 12500000 as "12.5M"; "auto" picks one unit for
+                the whole chart from its largest value. The unit is written after the number,
+                before number_suffix. Defaults to None (no scaling).
+            negative_style (str, optional): "minus" ("-7", changes signed "+9") or
+                "parentheses" (accounting style: "(7)", changes unsigned). Defaults to "minus".
             title (str | None, optional): Figure title. Defaults to None.
             labels (dict | None, optional): Display names for columns, as in plotly express,
                 e.g. {"Y": "Cashflow [MUSD]"}. Used for the axis titles. The y-axis is titled
                 with the (renamed) y column; the x-axis only gets a title if x is in labels.
                 Defaults to None.
+            category_orders (dict | None, optional): Order of the values of the x, group or
+                category column, as in plotly express, e.g. {"X": ["Revenue", "Costs"]}.
+                Listed values come first, others follow in order of appearance. Without it,
+                the order of a pandas Categorical column is used, else the order of
+                appearance. Defaults to None.
+            x_format (str | callable | None, optional): Labels of the x-values: a strftime
+                pattern for dates (e.g. "%b %Y"), or a callable taking an x-value and returning
+                its label. Defaults to None: dates are shown as "Jan 2026" when they are in
+                different months, else as "2026-01-31"; other values as str(value).
 
         Raises:
             TypeError: If df is not a DataFrame or subtotals is not a dict.
@@ -158,10 +188,30 @@ class Waterfall:
                 f"value_labels must be one of {VALUE_LABELS}, None or False, got {value_labels!r}"
             )
         self._value_labels: str | None = value_labels
-        self._fmt = NumberFormatter(number_format, number_prefix, number_suffix)
         self._title = title
         self._labels = dict(labels or {})
+        if number_unit is not None and number_unit not in NUMBER_UNITS:
+            raise ValueError(
+                f"number_unit must be one of {NUMBER_UNITS} or None, got {number_unit!r}"
+            )
+        self._number_unit = number_unit
+        self._fmt = NumberFormatter(
+            number_format,
+            number_prefix,
+            number_suffix,
+            negative_style=negative_style,
+            unit=None if number_unit == "auto" else number_unit,
+        )
         self._test_df()
+        self._category_orders = dict(category_orders or {})
+        dimensions = [c for c in (x, group, category) if c is not None]
+        unknown = [c for c in self._category_orders if c not in dimensions]
+        if unknown:
+            raise ValueError(
+                f"category_orders keys must be the x, group or category column; got {unknown}"
+            )
+        self._x_values = self._ordered_values(x)
+        self._x_label = self._x_labeller(x_format)
         self._coloring = Coloring(
             df,
             group=group,
@@ -172,6 +222,7 @@ class Waterfall:
             pattern_shape=pattern_shape,
             pattern_shape_map=pattern_shape_map,
             total_name=total_column_name,
+            orders={c: self._ordered_values(c) for c in (group, category) if c is not None},
         )
         if subtotals is None:
             subtotals = {}
@@ -186,7 +237,7 @@ class Waterfall:
         self._total = total
         self._total_type = total_type
         if total and (total_type == "category"):
-            self._subtotals[self._df[self._x].unique()[-1]] = total_column_name
+            self._subtotals[self._x_values[-1]] = total_column_name
 
     def get_fig(self) -> go.Figure:
         """Creates Plotly Figure instance
@@ -198,8 +249,13 @@ class Waterfall:
             Figure: Configured plotly.graph_objects.Figure instance
         """
 
-        tdf = self._df.copy()
+        # rows in x-axis order (stable), so that running levels follow the axis in every group
+        position = {value: i for i, value in enumerate(self._x_values)}
+        tdf = self._df.assign(**{ROW: np.arange(len(self._df))})
+        tdf = tdf.iloc[np.argsort(tdf[self._x].map(position).to_numpy(), kind="stable")]
         X = self._get_x_values(tdf)
+        if self._number_unit == "auto":
+            self._fmt.unit = auto_unit(self._chart_values(tdf))
         self._coloring.resolve()
         self._used_directions: set[str] = set()
         self._label_ys: dict[str, list[float]] = {"above": [], "below": []}
@@ -210,8 +266,9 @@ class Waterfall:
             self.__totalgroups = 1
             self._add_group(fig, X, 0, None, tdf)
         else:
-            self.__totalgroups = len(tdf[self._group].unique())
-            for groupno, (groupname, group) in enumerate(tdf.groupby(self._group, sort=False)):
+            groups = self._groups(tdf)
+            self.__totalgroups = len(groups)
+            for groupno, (groupname, group) in enumerate(groups):
                 self._add_group(fig, X, groupno, groupname, group)
 
         if self._total and (self._total_type == "sumtotal"):
@@ -224,7 +281,14 @@ class Waterfall:
             fig.add_bar(**legend_entry)
 
         fig.update_layout(
-            xaxis={"tickmode": "array", "tickvals": X[self._x], "ticktext": X.index},
+            xaxis={
+                "tickmode": "array",
+                "tickvals": X[self._x],
+                "ticktext": [
+                    self._label(value, bool(total))
+                    for value, total in zip(X.index, X.makeTotal.fillna(True), strict=True)
+                ],
+            },
             yaxis_title_text=self._labels.get(self._y, self._y),
         )
         if self._x in self._labels:
@@ -237,6 +301,20 @@ class Waterfall:
             fig.update_layout(uniformtext_minsize=9, uniformtext_mode="hide")
         return fig
 
+    def _groups(self, tdf: pd.DataFrame) -> list[tuple[Any, pd.DataFrame]]:
+        """(group name, rows) pairs in display order."""
+        assert self._group is not None
+        return [(name, tdf[tdf[self._group] == name]) for name in self._ordered_values(self._group)]
+
+    def _chart_values(self, tdf: pd.DataFrame) -> list[float]:
+        """Bar values and running levels, to choose number_unit="auto"."""
+        frames = [g for _, g in self._groups(tdf)] if self._group is not None else [tdf]
+        values: list[float] = []
+        for frame in frames:
+            sums = frame.groupby(self._x, sort=False, observed=True)[self._y].sum()
+            values += [*sums.abs(), *sums.cumsum().abs()]
+        return values
+
     def _test_df(self) -> None:
         for argument in ("x", "y", "group", "category"):
             column = getattr(self, f"_{argument}")
@@ -266,10 +344,53 @@ class Waterfall:
         Raises:
             ValueError: If `x` is not an x-value of the data.
         """
-        if x not in self._df[self._x].unique():
+        if x not in self._x_values:
             raise ValueError(f"Cannot find value {x!r} in data column {self._x!r}")
         self._subtotals[x] = name
 
+    def _ordered_values(self, column: str) -> list:
+        """Values of a column in display order: category_orders first, then a Categorical's
+        order, else the order of appearance."""
+        series = self._df[column]
+        values = list(series.unique())
+        if column in self._category_orders:
+            present = set(values)
+            given = [v for v in self._category_orders[column] if v in present]
+            listed = set(given)
+            return given + [v for v in values if v not in listed]
+        if isinstance(series.dtype, pd.CategoricalDtype):
+            present = set(values)
+            return [v for v in series.cat.categories if v in present]
+        return values
+
+    def _x_labeller(self, x_format: str | Callable[[Any], str] | None) -> Callable[[Any], str]:
+        """Function that turns an x-value into its axis / hover label."""
+        if callable(x_format):
+            return x_format
+        dates = [v for v in self._x_values if isinstance(v, (datetime.date, np.datetime64))]
+        if x_format is not None:
+            if len(dates) != len(self._x_values):
+                raise ValueError(
+                    "x_format as a string is a strftime pattern for date x-values; "
+                    "use a callable for other values"
+                )
+            pattern = x_format
+        elif dates and len(dates) == len(self._x_values):
+            stamps = pd.to_datetime(pd.Series(dates))
+            if (stamps != stamps.dt.normalize()).any():
+                pattern = "%Y-%m-%d %H:%M"
+            elif stamps.dt.to_period("M").nunique() == len(stamps):
+                pattern = "%b %Y"
+            else:
+                pattern = "%Y-%m-%d"
+        else:
+            return str
+        return lambda value: pd.Timestamp(value).strftime(pattern)
+
+    def _label(self, value: Any, is_total: bool) -> str:
+        """Label of an x-axis position; totals and subtotals carry their name."""
+        return str(value) if is_total else self._x_label(value)
+
     def _offset(self, groupno: int) -> float:
         """Horizontal offset of the left edge of group `groupno`'s bars from the x-value."""
         step = self._barwidth + self._gap / 2
@@ -277,7 +398,7 @@ class Waterfall:
 
     def _get_x_values(self, tdf: pd.DataFrame) -> pd.DataFrame:
         # Define x axis and include subtotals and totals
-        labels = list(tdf[self._x].unique())
+        labels = list(self._x_values)
         mt = [False] * len(labels)
         for total in self._subtotals:
             pos = labels.index(total) + 1
@@ -294,17 +415,15 @@ class Waterfall:
     def _add_group(
         self, fig: go.Figure, X: pd.DataFrame, groupno: int, groupname: Any, group: pd.DataFrame
     ) -> None:
-        level = group.groupby([self._x], sort=False)[self._y].sum().cumsum().shift(1).fillna(0)
-        level = X.merge(pd.DataFrame(level), left_index=True, right_index=True, how="left")[
-            self._y
-        ].fillna(0)
+        # running level before each x-position, in x-axis order; totals start at 0
+        sums = group.groupby([self._x], sort=False)[self._y].sum()
+        steps = X.merge(pd.DataFrame(sums), left_index=True, right_index=True, how="left")[self._y]
+        # (positions without data of this group have no bar; their base stays 0 as before)
+        level = steps.fillna(0).cumsum().shift(1).fillna(0).where(steps.notna(), 0)
 
         # (category name, rows) pairs; a single unnamed "category" without a category column
         categories: list[tuple[Any, pd.DataFrame]]
-        if self._category is None:
-            categories = [(None, group)]
-        else:
-            categories = list(group.groupby(self._category, sort=False, observed=True))
+        categories = [(None, group)] if self._category is None else self._categories(group)
         # values[p, c]: height of category c's segment at x-position p (NaN = no segment)
         values = np.column_stack([self._category_values(X, category) for _, category in categories])
         level_values = level.to_numpy(dtype=float)
@@ -372,12 +491,12 @@ class Waterfall:
             name = categoryname if categoryname is not None else ("Total" if total else "Change")
             lines = [f"{name}: {self._fmt(value, signed=not total)}"]
             if total and n_segments[p] > 1:
-                lines.append(f"{label}: {self._fmt(net[p])}")
+                lines.append(f"{self._label(label, total)}: {self._fmt(net[p])}")
             elif not total:
                 if n_segments[p] > 1:
                     lines.append(f"Step: {self._fmt(net[p], signed=True)}")
                 lines.append(f"Running total: {self._fmt(level_after[p])}")
-            hover.append([str(label), "<br>".join(lines)])
+            hover.append([self._label(label, total), "<br>".join(lines)])
             texts.append(self._fmt(value, signed=not total))
         extra = "" if groupname is None else str(groupname)
         kwargs: dict = {
@@ -455,6 +574,20 @@ class Waterfall:
         if (steps < 0).any():
             self._used_directions.add("decrease")
 
+    def _categories(self, group: pd.DataFrame) -> list[tuple[Any, pd.DataFrame]]:
+        """(category name, rows) pairs of one group in stacking order: category_orders or a
+        Categorical's order if given, else the order of appearance in the original data."""
+        assert self._category is not None
+        column = self._category
+        explicit = column in self._category_orders or isinstance(
+            self._df[column].dtype, pd.CategoricalDtype
+        )
+        if explicit:
+            names = [v for v in self._ordered_values(column) if (group[column] == v).any()]
+        else:
+            names = list(group.sort_values(ROW, kind="stable")[column].unique())
+        return [(name, group[group[column] == name]) for name in names]
+
     def _category_values(self, X: pd.DataFrame, category: pd.DataFrame) -> np.ndarray:
         """Segment heights of one category per x-position; totals hold the running sum."""
         values = category.groupby([self._x])[self._y].sum()
@@ -556,7 +689,7 @@ class Waterfall:
             y = tdf[self._y].sum()
             self._add_total_bar_line(fig, x, y, 0, None)
         else:
-            for groupno, (groupname, group) in enumerate(tdf.groupby(self._group, sort=False)):
+            for groupno, (groupname, group) in enumerate(self._groups(tdf)):
                 y = group[self._y].sum()
                 self._add_total_bar_line(fig, x, y, groupno, groupname)
 
@@ -609,8 +742,12 @@ def waterfall(
     number_format: NumberFormat = None,
     number_prefix: str = "",
     number_suffix: str = "",
+    number_unit: NumberUnit | None = None,
+    negative_style: NegativeStyle = "minus",
     title: str | None = None,
     labels: dict | None = None,
+    category_orders: dict[str, list] | None = None,
+    x_format: str | Callable[[Any], str] | None = None,
     mixed_signs: MixedSigns = "steps",
     net_ghost: bool | dict = True,
     step_order: StepOrder = "data",
@@ -646,8 +783,12 @@ def waterfall(
         number_format=number_format,
         number_prefix=number_prefix,
         number_suffix=number_suffix,
+        number_unit=number_unit,
+        negative_style=negative_style,
         title=title,
         labels=labels,
+        category_orders=category_orders,
+        x_format=x_format,
         mixed_signs=mixed_signs,
         net_ghost=net_ghost,
         step_order=step_order,

plotlywaterfall-1.1.0/tests/test_order_and_format.py

@@ -0,0 +1,209 @@
+"""x-axis order, date labels, accounting negatives and number units (1.1.0)."""
+
+import datetime
+
+import pandas as pd
+import pytest
+
+from plotlywaterfall import Waterfall, waterfall
+from plotlywaterfall._format import NumberFormatter, auto_unit
+
+
+def _ticks(fig):
+    return list(fig.layout.xaxis.ticktext)
+
+
+def _labels(fig):
+    return [a["text"] for a in fig.layout.annotations]
+
+
+# --- running levels follow the x-axis in every group ---------------------------------------
+
+
+def test_group_rows_in_different_order_get_the_same_levels():
+    # regression: levels were accumulated in each group's own row order
+    df = pd.DataFrame(
+        {
+            "X": ["A", "B", "C", "C", "A", "B"],
+            "Y": [10, -3, 2, 2, 10, -3],
+            "group": ["G1"] * 3 + ["G2"] * 3,
+        }
+    )
+    fig = waterfall(df, x="X", y="Y", group="group", total=True)
+    bases = {t["name"]: list(t["base"]) for t in fig.data}
+    assert bases["G1"] == bases["G2"] == [0, 10, 7, 0]
+    connectors = [s["y0"] for s in fig.layout.shapes]
+    assert connectors == [10, 7, 9] * 2
+
+
+# --- order of x, groups and categories -----------------------------------------------------
+
+
+def test_categorical_order_of_x_is_used():
+    df = pd.DataFrame(
+        {"X": pd.Categorical(["B", "A", "C"], categories=["A", "B", "C", "unused"]), "Y": [1, 2, 3]}
+    )
+    fig = waterfall(df, x="X", y="Y", total=True)
+    assert _ticks(fig) == ["A", "B", "C", "Total"]
+    assert list(fig.data[0]["base"]) == [0, 2, 3, 0]  # A=2 first, then B=1, C=3
+
+
+def test_category_orders_for_x():
+    df = pd.DataFrame({"X": ["B", "A", "C"], "Y": [1, 2, 3]})
+    fig = waterfall(df, x="X", y="Y", category_orders={"X": ["C", "A"]})
+    assert _ticks(fig) == ["C", "A", "B"]  # listed values first, the rest in order of appearance
+
+
+def test_total_goes_after_the_last_x_in_display_order():
+    df = pd.DataFrame({"X": ["B", "A"], "Y": [1, 2]})
+    fig = waterfall(df, x="X", y="Y", total=True, category_orders={"X": ["B", "A"]})
+    assert _ticks(fig) == ["B", "A", "Total"]
+    fig = waterfall(df, x="X", y="Y", total=True, category_orders={"X": ["A", "B"]})
+    assert _ticks(fig) == ["A", "B", "Total"]
+
+
+def test_category_orders_for_groups_and_categories():
+    df = pd.DataFrame(
+        {
+            "X": ["A"] * 4,
+            "Y": [1, 2, 3, 4],
+            "category": ["c1", "c2", "c1", "c2"],
+            "group": ["G1", "G1", "G2", "G2"],
+        }
+    )
+    fig = waterfall(
+        df,
+        x="X",
+        y="Y",
+        category="category",
+        group="group",
+        category_orders={"group": ["G2", "G1"], "category": ["c2", "c1"]},
+    )
+    assert [(t["legendgroup"], t["name"]) for t in fig.data] == [
+        ("G2", "c2"),
+        ("G2", "c1"),
+        ("G1", "c2"),
+        ("G1", "c1"),
+    ]
+    stack = {(t["legendgroup"], t["name"]): t["base"][0] for t in fig.data}
+    assert stack[("G2", "c2")] == 0  # c2 is stacked first
+    assert stack[("G2", "c1")] == 4
+
+
+def test_palette_follows_category_orders():
+    df = pd.DataFrame({"X": ["A", "A"], "Y": [1, 2], "category": ["c1", "c2"]})
+    fig = waterfall(
+        df,
+        x="X",
+        y="Y",
+        category="category",
+        category_orders={"category": ["c2", "c1"]},
+        color_discrete_sequence=["red", "blue"],
+    )
+    assert {t["name"]: t["marker"]["color"] for t in fig.data} == {"c2": "red", "c1": "blue"}
+
+
+def test_category_orders_unknown_column():
+    df = pd.DataFrame({"X": ["A"], "Y": [1]})
+    with pytest.raises(ValueError, match="category_orders keys"):
+        waterfall(df, x="X", y="Y", category_orders={"Region": ["EU"]})
+
+
+def test_subtotal_after_categorical_x():
+    df = pd.DataFrame({"X": pd.Categorical(["B", "A"], categories=["A", "B"]), "Y": [1, 2]})
+    wf = Waterfall(df, x="X", y="Y")
+    wf.add_subtotal("A", "Sub")
+    assert _ticks(wf.get_fig()) == ["A", "Sub", "B"]
+
+
+# --- date labels ---------------------------------------------------------------------------
+
+
+def test_month_end_dates_are_shown_as_months():
+    df = pd.DataFrame({"X": pd.date_range("2026-01-31", periods=3, freq="ME"), "Y": [5, -2, 3]})
+    fig = waterfall(df, x="X", y="Y", total=True)
+    assert _ticks(fig) == ["Jan 2026", "Feb 2026", "Mar 2026", "Total"]
+    assert fig.data[0]["customdata"][0][0] == "Jan 2026"  # hover uses the same label
+
+
+def test_days_in_one_month_are_shown_as_dates():
+    df = pd.DataFrame({"X": pd.to_datetime(["2026-01-05", "2026-01-12"]), "Y": [1, 2]})
+    assert _ticks(waterfall(df, x="X", y="Y")) == ["2026-01-05", "2026-01-12"]
+
+
+def test_dates_with_times_and_python_dates():
+    df = pd.DataFrame({"X": pd.to_datetime(["2026-01-05 09:30", "2026-01-05 17:00"]), "Y": [1, 2]})
+    assert _ticks(waterfall(df, x="X", y="Y")) == ["2026-01-05 09:30", "2026-01-05 17:00"]
+
+    df = pd.DataFrame({"X": [datetime.date(2026, 1, 1), datetime.date(2026, 2, 1)], "Y": [1, 2]})
+    assert _ticks(waterfall(df, x="X", y="Y")) == ["Jan 2026", "Feb 2026"]
+
+
+def test_x_format():
+    df = pd.DataFrame({"X": pd.date_range("2026-01-31", periods=2, freq="ME"), "Y": [1, 2]})
+    assert _ticks(waterfall(df, x="X", y="Y", x_format="%m/%y")) == ["01/26", "02/26"]
+
+    df = pd.DataFrame({"X": [2025, 2026], "Y": [1, 2]})
+    assert _ticks(waterfall(df, x="X", y="Y", x_format=lambda v: f"FY{v}")) == ["FY2025", "FY2026"]
+    with pytest.raises(ValueError, match="strftime pattern"):
+        waterfall(df, x="X", y="Y", x_format="%Y")
+
+
+# --- accounting negatives and units --------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("value", "signed", "expected"),
+    [(-7, True, "(7)"), (9, True, "9"), (-1234.5, False, "(1,234.5)"), (0, True, "0")],
+)
+def test_parentheses(value, signed, expected):
+    assert NumberFormatter(negative_style="parentheses")(value, signed=signed) == expected
+
+
+def test_parentheses_wrap_prefix_unit_and_suffix():
+    fmt = NumberFormatter(prefix="$", suffix=" USD", negative_style="parentheses", unit="M")
+    assert fmt(-2_500_000) == "($2.5M USD)"
+
+
+@pytest.mark.parametrize(
+    ("unit", "expected"),
+    [("k", "+1,250k"), ("M", "+1.25M"), ("bn", "0bn")],  # 0.00125bn rounds to zero: no sign
+)
+def test_units(unit, expected):
+    assert NumberFormatter(unit=unit)(1_250_000, signed=True) == expected
+
+
+@pytest.mark.parametrize(
+    ("values", "unit"),
+    [([5, 999], None), ([1_000, 3], "k"), ([-2_500_000], "M"), ([3e9, 1], "bn"), ([], None)],
+)
+def test_auto_unit(values, unit):
+    assert auto_unit(values) == unit
+
+
+def test_auto_unit_uses_one_unit_for_the_whole_chart():
+    df = pd.DataFrame({"X": ["Sales", "Costs", "Tax"], "Y": [1_250_000, -730_000, -95_000]})
+    fig = waterfall(df, x="X", y="Y", total=True, number_unit="auto")
+    assert _labels(fig) == ["+1.25M", "-0.73M", "-0.1M", "0.42M"]
+
+
+def test_accounting_chart():
+    df = pd.DataFrame({"X": ["Sales", "Costs"], "Y": [1_250_000, -730_000]})
+    fig = waterfall(
+        df,
+        x="X",
+        y="Y",
+        total=True,
+        number_unit="k",
+        negative_style="parentheses",
+        number_prefix="$",
+    )
+    assert _labels(fig) == ["$1,250k", "($730k)", "$520k"]
+
+
+def test_invalid_number_options():
+    df = pd.DataFrame({"X": ["A"], "Y": [1]})
+    with pytest.raises(ValueError, match="number_unit"):
+        waterfall(df, x="X", y="Y", number_unit="mio")  # type: ignore[arg-type]
+    with pytest.raises(ValueError, match="negative_style"):
+        waterfall(df, x="X", y="Y", negative_style="red")  # type: ignore[arg-type]

plotlywaterfall-1.0.0/src/plotlywaterfall/__about__.py

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

plotlywaterfall-1.0.0/src/plotlywaterfall/_format.py

@@ -1,46 +0,0 @@
-"""Number formatting shared by value labels and hover texts."""
-
-from collections.abc import Callable
-
-NumberFormat = str | Callable[[float], str] | None
-
-
-class NumberFormatter:
-    """Format numbers as `[sign][prefix]number[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.
-    """
-
-    def __init__(self, number_format: NumberFormat = None, prefix: str = "", suffix: str = ""):
-        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
-        self._format = number_format
-        self._prefix = prefix
-        self._suffix = suffix
-
-    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:
-        body = self._body(abs(value))
-        is_zero = body.strip("0.,") == ""
-        if value < 0 and not is_zero:
-            sign = "-"
-        elif signed and value > 0 and not is_zero:
-            sign = "+"
-        else:
-            sign = ""
-        return f"{sign}{self._prefix}{body}{self._suffix}"