pyproforma 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyproforma
-Version: 0.3.0
+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.0 → 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.0 → pyproforma-0.3.2}/pyproforma/chart/chart.py

@@ -23,11 +23,15 @@ ChartType = Literal["line", "bar", "stacked_bar"]
 
 @dataclass
 class ChartSeries:
-    """A single data series for a chart."""
+    """A single data series for a chart.
+
+    A y-value of None means "no data for this period" (e.g. a line item not
+    yet applicable) — renderers treat it as a gap, not zero.
+    """
 
     label: str
     x_values: list[int]
-    y_values: list[float]
+    y_values: list[float | None]
     color: str | None = None
 
 

{pyproforma-0.3.0 → pyproforma-0.3.2}/pyproforma/chart/renderers/matplotlib_renderer.py

@@ -11,6 +11,15 @@ from pyproforma.chart.chart import Chart as ChartSpec
 from pyproforma.chart.renderers.base import ChartRenderer
 
 
+def _as_gaps(y_values: list[float | None]) -> list[float]:
+    """Convert None to NaN — matplotlib's documented "break the plot here" sentinel.
+
+    A plain Python list mixing floats and None becomes a numpy object array,
+    which matplotlib doesn't reliably render; NaN keeps it a clean float array.
+    """
+    return [v if v is not None else float("nan") for v in y_values]
+
+
 class MatplotlibRenderer(ChartRenderer):
     """Renders a ChartSpec to a matplotlib Figure."""
 
@@ -55,7 +64,7 @@ class MatplotlibRenderer(ChartRenderer):
         for series in spec.series:
             ax.plot(
                 series.x_values,
-                series.y_values,
+                _as_gaps(series.y_values),
                 label=series.label,
                 color=series.color,
                 marker="o",
@@ -72,7 +81,10 @@ class MatplotlibRenderer(ChartRenderer):
 
         for i, series in enumerate(spec.series):
             offset = (i - n / 2 + 0.5) * width
-            ax.bar(x + offset, series.y_values, width, label=series.label, color=series.color)
+            ax.bar(
+                x + offset, _as_gaps(series.y_values), width,
+                label=series.label, color=series.color,
+            )
 
         ax.set_xticks(x)
         ax.set_xticklabels([str(v) for v in spec.series[0].x_values])
@@ -84,9 +96,15 @@ class MatplotlibRenderer(ChartRenderer):
         bottom = np.zeros(len(spec.series[0].x_values))
 
         for series in spec.series:
-            y = np.array(series.y_values)
-            ax.bar(x, y, bottom=bottom, label=series.label, color=series.color)
-            bottom += y
+            # None contributes nothing to the running stack height, but its own
+            # segment doesn't draw (NaN) rather than rendering as a visible
+            # zero-height bar — so a gap in one series doesn't blank out the
+            # segments stacked above it.
+            ax.bar(
+                x, _as_gaps(series.y_values), bottom=bottom,
+                label=series.label, color=series.color,
+            )
+            bottom += np.array([v if v is not None else 0.0 for v in series.y_values])
 
         ax.set_xticks(x)
         ax.set_xticklabels([str(v) for v in spec.series[0].x_values])

{pyproforma-0.3.0 → 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.0 → 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.0 → pyproforma-0.3.2}/pyproforma/engine/calculation_engine.py

@@ -117,12 +117,11 @@ def _calculate_single_line_item(
         return period_values[period]  # None is a valid value — means "no input this period"
 
     if isinstance(line_item, FixedLine):
-        value = line_item.get_value(period)
-        if value is None:
+        if period not in line_item.values:
             raise ValueError(
                 f"No value defined for '{line_item.name}' in period {period}"
             )
-        return value
+        return line_item.get_value(period)  # None is a valid value — means "not applicable"
 
     if isinstance(line_item, FormulaLine):
         if period in line_item.values:

{pyproforma-0.3.0 → 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.0 → pyproforma-0.3.2}/pyproforma/results/line_item_selection.py

@@ -95,6 +95,9 @@ class LineItemSelection:
         """
         Get the sum of all selected line items for a specific period.
 
+        Line items with a value of None for the period (e.g. a FixedLine or
+        InputLine period marked "not applicable") are skipped, not treated as 0.
+
         Args:
             period: The period to sum values for.
 
@@ -113,7 +116,7 @@ class LineItemSelection:
             105
         """
         values = self.value(period)
-        return sum(values.values())
+        return sum(v for v in values.values() if v is not None)
 
     def table(
         self,

{pyproforma-0.3.0 → pyproforma-0.3.2}/pyproforma/specs/fixed_line.py

@@ -12,13 +12,22 @@ class FixedLine(LineItem):
     Values are supplied as a dict mapping periods to floats. For a scalar
     constant that applies across all periods use ``ScalarLine`` instead.
 
+    A period may be explicitly mapped to ``None`` to mean "not applicable"
+    (e.g. a line item that doesn't exist yet in an early period) — it
+    resolves to ``None`` rather than raising, formats as blank in tables, and
+    is skipped by tag sums. This is different from omitting the period
+    entirely, which still raises ``ValueError`` when the model tries to
+    calculate it.
+
     Examples:
         >>> revenue = FixedLine(values={2024: 100_000, 2025: 110_000})
+        >>> # 2024 not applicable — the product launched in 2025
+        >>> new_product_revenue = FixedLine(values={2024: None, 2025: 50_000})
     """
 
     def __init__(
         self,
-        values: dict[int, float] | None = None,
+        values: dict[int, float | None] | None = None,
         label: str | None = None,
         tags: list[str] | None = None,
         value_format: Union[str, NumberFormatSpec, dict, None] = None,

{pyproforma-0.3.0 → 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.0 → pyproforma-0.3.2}/pyproforma/tables/row_types.py

@@ -482,9 +482,13 @@ class LineItemsTotalRow(BaseRow):
         for _ in range(label_col_count - len(cells)):
             cells.append(Cell(value=""))
 
-        # Calculate totals for each period
+        # Calculate totals for each period. Items with a None value (e.g. a
+        # FixedLine period marked "not applicable") are skipped, not treated as 0.
         for period in model.periods:
-            total = sum(model[name][period] for name in self.line_item_names)
+            total = sum(
+                v for name in self.line_item_names
+                if (v := model[name][period]) is not None
+            )
             cells.append(
                 Cell(
                     value=total,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyproforma
-Version: 0.3.0
+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.0 → 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.0 → pyproforma-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pyproforma"
-version = "0.3.0"
+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",