pyproforma 0.3.1__tar.gz → 0.3.2__tar.gz

{pyproforma-0.3.1/pyproforma.egg-info → pyproforma-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyproforma
-Version: 0.3.1
+Version: 0.3.2
 Summary: A Python package for financial modeling and reporting
 Author-email: Robert Hannay <rhannay@gmail.com>
 Maintainer-email: Robert Hannay <rhannay@gmail.com>
@@ -33,6 +33,8 @@ Requires-Dist: ipython>=7.0.0; extra == "notebook"
 Provides-Extra: explorer
 Requires-Dist: flask>=2.0.0; extra == "explorer"
 Requires-Dist: PyYAML>=6.0.0; extra == "explorer"
+Provides-Extra: all
+Requires-Dist: pyproforma[charts,excel,explorer,notebook,pandas]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -230,6 +232,12 @@ model.charts.line_item("net_income", chart_type="bar").show()
 model.charts.line_items(["revenue", "gross_profit", "net_income"]).show()
 ```
 
+Compare items with different units or scales by rebasing them all to 100 at a common period:
+
+```python
+model.charts.indexed_line_items(["revenue", "headcount"]).show()
+```
+
 Charts return a `ChartSpec` which can also render to a matplotlib `Figure`:
 
 ```python

{pyproforma-0.3.1 → pyproforma-0.3.2}/README.md

@@ -188,6 +188,12 @@ model.charts.line_item("net_income", chart_type="bar").show()
 model.charts.line_items(["revenue", "gross_profit", "net_income"]).show()
 ```
 
+Compare items with different units or scales by rebasing them all to 100 at a common period:
+
+```python
+model.charts.indexed_line_items(["revenue", "headcount"]).show()
+```
+
 Charts return a `ChartSpec` which can also render to a matplotlib `Figure`:
 
 ```python

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproforma/charts/chart_def.py

@@ -2,8 +2,9 @@
 ChartDef — declarative definition of a chart to build from a model.
 
 Used with model.charts.build() to produce a Chart. Holds the line item names,
-chart type, title, and optional per-series colors. Accepts either the dataclass
-form (IDE autocomplete, validation) or a plain dict (JSON-serializable configs).
+chart type, title, optional per-series colors, and an optional value transform
+("indexed"). Accepts either the dataclass form (IDE autocomplete, validation)
+or a plain dict (JSON-serializable configs).
 """
 
 from dataclasses import dataclass
@@ -24,15 +25,19 @@ class ChartDef:
         >>> ChartDef(names=["revenue", "expenses"])
         >>> ChartDef(names=["revenue"], chart_type="bar", title="Revenue")
         >>> ChartDef(names=["revenue", "expenses"], colors=["#206bc4", "#d63939"])
+        >>> ChartDef(names=["revenue", "headcount"], transform="indexed")
 
     The dict form is equivalent:
         >>> {"names": ["revenue"], "chart_type": "bar", "colors": ["#206bc4"]}
+        >>> {"names": ["revenue", "headcount"], "transform": "indexed"}
     """
 
     names: list[str]
     chart_type: ChartType = "line"
     title: str | None = None
     colors: list[str] | None = None
+    transform: str | None = None
+    base_period: int | None = None
 
     @classmethod
     def from_dict(cls, data: dict) -> "ChartDef":
@@ -41,4 +46,6 @@ class ChartDef:
             chart_type=data.get("chart_type", "line"),
             title=data.get("title"),
             colors=data.get("colors"),
+            transform=data.get("transform"),
+            base_period=data.get("base_period"),
         )

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproforma/charts/charts.py

@@ -10,14 +10,17 @@ This layer knows about ProformaModel; the Chart class beneath it does not.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Literal
 
 from pyproforma.chart.chart import Chart, ChartSeries, ChartType
+from pyproforma.table import Format
 
 if TYPE_CHECKING:
     from pyproforma.charts.chart_def import ChartDef
     from pyproforma.proforma_model import ProformaModel
 
+Transform = Literal["indexed"]
+
 
 class Charts:
     """
@@ -92,6 +95,8 @@ class Charts:
         chart_type: ChartType = "line",
         title: str | None = None,
         value_format=None,
+        transform: Transform | None = None,
+        base_period: int | None = None,
     ) -> Chart:
         """
         Build a chart with one series per line item.
@@ -104,12 +109,25 @@ class Charts:
             chart_type: One of "line", "bar", "stacked_bar". Defaults to "line".
             title: Chart title. Defaults to None (no title).
             value_format: Override the auto-detected format for the y-axis.
+                Defaults to Format.NO_DECIMALS when transform="indexed".
+            transform: Optional value transform applied to every series before
+                charting. "indexed" rebases each series to 100 at base_period:
+                value[t] / value[base_period] * 100 — useful for comparing
+                items with different units or scales (e.g. revenue vs.
+                headcount) on a common axis. Defaults to None (raw values).
+            base_period: Reference period for transform="indexed". Defaults to
+                the model's first period. Raising if set without a transform
+                catches the likely mistake of forgetting transform="indexed".
 
         Returns:
             Chart ready for rendering.
 
         Raises:
-            ValueError: If any line item doesn't exist in the model.
+            ValueError: If any line item doesn't exist in the model, transform
+                is not a recognized value, base_period is set without
+                transform, base_period is not one of the model's periods, or
+                (for transform="indexed") a series' base_period value is None
+                or 0.
 
         Examples:
             >>> model.charts.line_items(["revenue", "expenses"]).show()
@@ -117,32 +135,114 @@ class Charts:
             >>> model.charts.line_items(  # noqa: E501
             ...     ["revenue", "expenses"], value_format=Format.MILLIONS_M
             ... ).show()
+            >>> # Compare growth trajectories on a common scale
+            >>> model.charts.line_items(["revenue", "headcount"], transform="indexed").show()
         """
         for name in names:
             self._validate_line_item(name)
 
+        if transform is not None and transform != "indexed":
+            raise ValueError(f"Unrecognized transform {transform!r}. Valid values: 'indexed'.")
+        if base_period is not None and transform is None:
+            raise ValueError(
+                "base_period is only valid with transform='indexed'. "
+                "Did you forget to pass transform='indexed'?"
+            )
+
+        resolved_base_period = base_period
+        if transform == "indexed" and resolved_base_period is None:
+            resolved_base_period = self._model.periods[0]
+
         series = []
         for name in names:
             result = self._model[name]
+            y_values = [result[p] for p in self._model.periods]
+            if transform == "indexed":
+                y_values = self._index_values(name, y_values, resolved_base_period)
             series.append(
                 ChartSeries(
                     label=result.label or name,
                     x_values=list(self._model.periods),
-                    y_values=[result[p] for p in self._model.periods],
+                    y_values=y_values,
                 )
             )
 
         if value_format is None:
-            formats = [self._model[n].value_format for n in names]
-            value_format = formats[0] if len(set(formats)) == 1 else None
+            if transform == "indexed":
+                value_format = Format.NO_DECIMALS
+            else:
+                formats = [self._model[n].value_format for n in names]
+                value_format = formats[0] if len(set(formats)) == 1 else None
+
+        y_label = f"Index (Base = 100, {resolved_base_period})" if transform == "indexed" else None
 
         return Chart(
             series=series,
             chart_type=chart_type,
             title=title,
             value_format=value_format,
+            y_label=y_label,
         )
 
+    def indexed_line_items(
+        self,
+        names: list[str],
+        base_period: int | None = None,
+        title: str | None = None,
+        value_format=None,
+    ) -> Chart:
+        """
+        Build a line chart with every series rebased to 100 at base_period.
+
+        Convenience wrapper for line_items(names, transform="indexed", ...).
+        Lets you compare line items with different units or scales (e.g.
+        revenue in dollars vs. headcount) on a common relative axis.
+
+        Args:
+            names: List of line item names to include as series.
+            base_period: Reference period; value[t] / value[base_period] * 100.
+                Defaults to the model's first period.
+            title: Chart title. Defaults to None (no title).
+            value_format: Override the default (Format.NO_DECIMALS) y-axis format.
+
+        Returns:
+            Chart ready for rendering.
+
+        Raises:
+            ValueError: If any line item doesn't exist in the model, base_period
+                is not one of the model's periods, or a series' base_period
+                value is None or 0.
+
+        Examples:
+            >>> model.charts.indexed_line_items(["revenue", "headcount"]).show()
+            >>> model.charts.indexed_line_items(["revenue"], base_period=2025).show()
+        """
+        return self.line_items(
+            names,
+            title=title,
+            value_format=value_format,
+            transform="indexed",
+            base_period=base_period,
+        )
+
+    def _index_values(
+        self, name: str, y_values: list[float | None], base_period: int
+    ) -> list[float | None]:
+        """Rebase a series to 100 at base_period. None stays None (a gap)."""
+        try:
+            base_index = self._model.periods.index(base_period)
+        except ValueError:
+            raise ValueError(
+                f"base_period {base_period} is not in model periods {self._model.periods}"
+            ) from None
+        base_value = y_values[base_index]
+        if not base_value:
+            raise ValueError(
+                f"Cannot index '{name}': base period {base_period} value is "
+                f"{base_value!r} (must be a non-zero number)."
+            )
+        return [v / base_value * 100 if v is not None else None for v in y_values]
+
     def build(self, template: "ChartDef | dict") -> Chart:
         """
         Build a Chart from a ChartDef or equivalent dict.
@@ -155,6 +255,10 @@ class Charts:
                 - names (list[str]): Line item names to include as series.
                 - chart_type (str, optional): "line", "bar", or "stacked_bar". Defaults to "line".
                 - title (str, optional): Chart title.
+                - transform (str, optional): "indexed" to rebase every series to
+                  100 at base_period. Defaults to None (raw values).
+                - base_period (int, optional): Reference period for
+                  transform="indexed". Defaults to the model's first period.
 
         Returns:
             Chart ready for rendering.
@@ -162,6 +266,9 @@ class Charts:
         Examples:
             >>> model.charts.from_template(ChartDef(names=["revenue", "expenses"]))
             >>> model.charts.from_template({"names": ["revenue"], "chart_type": "bar"})
+            >>> model.charts.from_template(
+            ...     {"names": ["revenue", "headcount"], "transform": "indexed"}
+            ... )
         """
         from pyproforma.charts.chart_def import ChartDef
         if isinstance(template, dict):
@@ -170,6 +277,8 @@ class Charts:
             names=template.names,
             chart_type=template.chart_type,
             title=template.title,
+            transform=template.transform,
+            base_period=template.base_period,
         )
         if template.colors:
             for series, color in zip(chart_spec.series, template.colors):

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproforma/explorer/components.py

@@ -20,7 +20,8 @@ class StatCard:
     Args:
         name: Line item name.
         label: Display label. Defaults to the line item's own label.
-        aggregation: One of "min", "max", "latest", "first", "sum", "avg", "cagr". Defaults to "latest".
+        aggregation: One of "min", "max", "latest", "first", "sum", "avg", "cagr".
+            Defaults to "latest".
         value_format: Optional format override. Uses the line item's format if not set.
         start: Optional start period for the aggregation range.
         end: Optional end period for the aggregation range.

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproforma/table/excel.py

@@ -1,6 +1,8 @@
 from typing import TYPE_CHECKING, Optional, Union
 
 if TYPE_CHECKING:
+    from io import BytesIO
+
     from .table_class import Table
 
 from .colors import color_to_rgb

{pyproforma-0.3.1 → pyproforma-0.3.2/pyproforma.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyproforma
-Version: 0.3.1
+Version: 0.3.2
 Summary: A Python package for financial modeling and reporting
 Author-email: Robert Hannay <rhannay@gmail.com>
 Maintainer-email: Robert Hannay <rhannay@gmail.com>
@@ -33,6 +33,8 @@ Requires-Dist: ipython>=7.0.0; extra == "notebook"
 Provides-Extra: explorer
 Requires-Dist: flask>=2.0.0; extra == "explorer"
 Requires-Dist: PyYAML>=6.0.0; extra == "explorer"
+Provides-Extra: all
+Requires-Dist: pyproforma[charts,excel,explorer,notebook,pandas]; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=6.0; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
@@ -230,6 +232,12 @@ model.charts.line_item("net_income", chart_type="bar").show()
 model.charts.line_items(["revenue", "gross_profit", "net_income"]).show()
 ```
 
+Compare items with different units or scales by rebasing them all to 100 at a common period:
+
+```python
+model.charts.indexed_line_items(["revenue", "headcount"]).show()
+```
+
 Charts return a `ChartSpec` which can also render to a matplotlib `Figure`:
 
 ```python

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproforma.egg-info/requires.txt

@@ -1,4 +1,7 @@
 
+[all]
+pyproforma[charts,excel,explorer,notebook,pandas]
+
 [charts]
 matplotlib>=3.5.0
 

{pyproforma-0.3.1 → pyproforma-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyproforma"
-version = "0.3.1"
+version = "0.3.2"
 description = "A Python package for financial modeling and reporting"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -55,6 +55,9 @@ explorer = [
     "flask>=2.0.0",
     "PyYAML>=6.0.0",
 ]
+all = [
+    "pyproforma[pandas,excel,charts,notebook,explorer]",
+]
 dev = [
     "pytest>=6.0",
     "pytest-cov",