featkit 0.4.2__tar.gz → 0.4.3__tar.gz

{featkit-0.4.2 → featkit-0.4.3}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.3] - 2026-06-30
+
+### Added
+- `RatioMode` enum with two values: `ALL_PROJECTIONS` (default, existing behaviour) and `GLOBAL_TOTAL` (restricts Layer 2C denominators to the single all-∅ grand-total column, producing one ratio per numerator representing its share of the portfolio total).
+- `FeatureStoreConfig.ratio_mode` parameter (default `RatioMode.ALL_PROJECTIONS`) to select the denominator strategy for `RatioSpaceBuilder`.
+
 ## [0.4.2] - 2026-06-30
 
 ### Fixed

{featkit-0.4.2 → featkit-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: featkit
-Version: 0.4.2
+Version: 0.4.3
 Summary: featkit — automated feature store generation from relational facts tables
 Project-URL: Repository, https://github.com/Mirkiux/featkit
 Project-URL: Documentation, https://mirkiux.github.io/featkit
@@ -214,16 +214,23 @@ where `NUMERATOR` and `DENOMINATOR` are full Layer 2A pivot feature names. The d
 
 The underlying value is `numerator / NULLIF(denominator, 0)` computed per entity per period.
 
-```
-# Numerator: DIGITAL channel + RETAIL sector
-# Denominator: RETAIL sector only (CANAL marginalized → share of DIGITAL within RETAIL)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__SECTOR_RETAIL
+Enabled by setting `include_ratios=True` (requires `include_marginals=True`). The `ratio_mode` parameter controls which denominators are paired with each numerator:
 
-# Denominator: DIGITAL channel only (SECTOR marginalized → share of RETAIL within DIGITAL)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__CANAL_DIGITAL
+| `ratio_mode` | Denominators considered | Ratios produced per numerator |
+|---|---|---|
+| `RatioMode.ALL_PROJECTIONS` *(default)* | Every proper marginal projection (partial or fully marginalised) | One per valid denominator |
+| `RatioMode.GLOBAL_TOTAL` | Only the fully-marginalised column (all fields ∅) | Exactly one — the share of the grand total |
 
-# Denominator: global total (both marginalized → share of DIGITAL/RETAIL in total portfolio)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO
+```
+# With RatioMode.ALL_PROJECTIONS (default):
+# Numerator: DIGITAL channel + RETAIL sector → three denominators
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__SECTOR_RETAIL   # share within RETAIL
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__CANAL_DIGITAL   # share within DIGITAL
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO                  # share of total
+
+# With RatioMode.GLOBAL_TOTAL:
+# Same numerator → only the grand-total denominator
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO                  # share of total only
 ```
 
 ---

{featkit-0.4.2 → featkit-0.4.3}/README.md

@@ -146,16 +146,23 @@ where `NUMERATOR` and `DENOMINATOR` are full Layer 2A pivot feature names. The d
 
 The underlying value is `numerator / NULLIF(denominator, 0)` computed per entity per period.
 
-```
-# Numerator: DIGITAL channel + RETAIL sector
-# Denominator: RETAIL sector only (CANAL marginalized → share of DIGITAL within RETAIL)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__SECTOR_RETAIL
+Enabled by setting `include_ratios=True` (requires `include_marginals=True`). The `ratio_mode` parameter controls which denominators are paired with each numerator:
 
-# Denominator: DIGITAL channel only (SECTOR marginalized → share of RETAIL within DIGITAL)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__CANAL_DIGITAL
+| `ratio_mode` | Denominators considered | Ratios produced per numerator |
+|---|---|---|
+| `RatioMode.ALL_PROJECTIONS` *(default)* | Every proper marginal projection (partial or fully marginalised) | One per valid denominator |
+| `RatioMode.GLOBAL_TOTAL` | Only the fully-marginalised column (all fields ∅) | Exactly one — the share of the grand total |
 
-# Denominator: global total (both marginalized → share of DIGITAL/RETAIL in total portfolio)
-SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO
+```
+# With RatioMode.ALL_PROJECTIONS (default):
+# Numerator: DIGITAL channel + RETAIL sector → three denominators
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__SECTOR_RETAIL   # share within RETAIL
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO__CANAL_DIGITAL   # share within DIGITAL
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO                  # share of total
+
+# With RatioMode.GLOBAL_TOTAL:
+# Same numerator → only the grand-total denominator
+SUM__MTO__CANAL_DIGITAL__SECTOR_RETAIL__over__SUM__MTO                  # share of total only
 ```
 
 ---

{featkit-0.4.2 → featkit-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "featkit"
-version = "0.4.2"
+version = "0.4.3"
 description = "featkit — automated feature store generation from relational facts tables"
 readme = "README.md"
 license = { file = "LICENSE" }

{featkit-0.4.2 → featkit-0.4.3}/src/featkit/builders/ratio_space.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import logging
 
+from featkit.enums import RatioMode
 from featkit.layer2.pivoted import PivotedColumn
 from featkit.layer2.ratio import RatioPivotedColumn
 
@@ -31,6 +32,11 @@ class RatioSpaceBuilder:
     Args:
         pivot_columns: The full set of Layer 2A pivot columns, typically
             ``FeatureStorePipeline.layer2a``.
+        ratio_mode: Controls which columns are eligible as denominators.
+            ``RatioMode.ALL_PROJECTIONS`` (default) considers every column
+            with at least one ∅ (``None``) field.  ``RatioMode.GLOBAL_TOTAL``
+            restricts to columns where *all* fields are ∅ — the grand-total
+            column — producing one ratio per numerator.
         verbose: When ``True``, emits ``DEBUG``-level log messages listing
             each generated ratio column name.
     """
@@ -38,9 +44,11 @@ class RatioSpaceBuilder:
     def __init__(
         self,
         pivot_columns: list[PivotedColumn],
+        ratio_mode: RatioMode = RatioMode.ALL_PROJECTIONS,
         verbose: bool = False,
     ) -> None:
         self.pivot_columns = pivot_columns
+        self.ratio_mode = ratio_mode
         self.verbose = verbose
 
     def build(self) -> list[RatioPivotedColumn]:
@@ -56,12 +64,22 @@ class RatioSpaceBuilder:
             if c.categorical_combination
             and any(v is not None for v in c.categorical_combination.values())
         ]
-        # Potential denominators: any column with at least one None categorical value
-        denominators = [
-            c
-            for c in self.pivot_columns
-            if any(v is None for v in c.categorical_combination.values())
-        ]
+        # Potential denominators: depends on mode.
+        # ALL_PROJECTIONS: any column with at least one ∅ field (partial or full marginal).
+        # GLOBAL_TOTAL: only the column where every field is ∅ (grand total).
+        if self.ratio_mode == RatioMode.GLOBAL_TOTAL:
+            denominators = [
+                c
+                for c in self.pivot_columns
+                if c.categorical_combination
+                and all(v is None for v in c.categorical_combination.values())
+            ]
+        else:
+            denominators = [
+                c
+                for c in self.pivot_columns
+                if any(v is None for v in c.categorical_combination.values())
+            ]
 
         results: list[RatioPivotedColumn] = []
         seen: set[str] = set()

{featkit-0.4.2 → featkit-0.4.3}/src/featkit/config.py

@@ -6,7 +6,13 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 from featkit.dataset.base import AbstractDataset
-from featkit.enums import Layer2Aggregator, Layer2OutputType, MeasurementType, TemporalOperator
+from featkit.enums import (
+    Layer2Aggregator,
+    Layer2OutputType,
+    MeasurementType,
+    RatioMode,
+    TemporalOperator,
+)
 
 if TYPE_CHECKING:
     from featkit.execution.adapters.base import DataSourceAdapter
@@ -32,6 +38,13 @@ class FeatureStoreConfig:
             combination over each of its proper marginal projections.  Has no
             effect when ``include_marginals`` is ``False`` (no marginal
             denominators exist).
+        ratio_mode: Controls which denominators are considered when
+            ``include_ratios`` is ``True``.  ``RatioMode.ALL_PROJECTIONS``
+            (default) pairs each numerator with every valid proper marginal
+            projection.  ``RatioMode.GLOBAL_TOTAL`` restricts denominators to
+            the single fully-marginalised column (all categorical fields set to
+            ∅), producing one ratio per numerator representing its share of the
+            grand total.
         aggregators_override: Per-measurement-type override for Layer 2
             aggregators. Only contract-valid aggregators are used.
         operators_override: Per-output-type override for temporal operators.
@@ -53,6 +66,7 @@ class FeatureStoreConfig:
     composed_windows: list[int] | None = None
     include_marginals: bool = True
     include_ratios: bool = True
+    ratio_mode: RatioMode = RatioMode.ALL_PROJECTIONS
     aggregators_override: dict[MeasurementType, list[Layer2Aggregator]] | None = None
     operators_override: dict[Layer2OutputType, list[TemporalOperator]] | None = field(default=None)
     adapter: DataSourceAdapter | None = None

{featkit-0.4.2 → featkit-0.4.3}/src/featkit/enums.py

@@ -108,3 +108,19 @@ class TimeWindowDirection(Enum):
 
     BACKWARD = "BACKWARD"
     FORWARD = "FORWARD"
+
+
+class RatioMode(Enum):
+    """Controls which denominators are paired with each numerator in Layer 2C.
+
+    ``ALL_PROJECTIONS`` (default): every proper marginal projection of the
+    numerator is used as a denominator — partial marginals (some fields set to
+    ∅) as well as the global total (all fields ∅).
+
+    ``GLOBAL_TOTAL``: only the fully-marginalised column (all categorical fields
+    set to ∅) is used as a denominator, producing a single ratio per numerator
+    that represents its share of the grand total.
+    """
+
+    ALL_PROJECTIONS = "ALL_PROJECTIONS"
+    GLOBAL_TOTAL = "GLOBAL_TOTAL"

{featkit-0.4.2 → featkit-0.4.3}/src/featkit/pipeline.py

@@ -66,7 +66,7 @@ class FeatureStorePipeline:
             verbose=cfg.verbose,
         ).build()
         self.layer2c = (
-            RatioSpaceBuilder(self.layer2a, verbose=cfg.verbose).build()
+            RatioSpaceBuilder(self.layer2a, ratio_mode=cfg.ratio_mode, verbose=cfg.verbose).build()
             if cfg.include_ratios and cfg.include_marginals
             else []
         )

{featkit-0.4.2 → featkit-0.4.3}/tests/test_ratio.py

@@ -12,6 +12,7 @@ from featkit.enums import (
     Layer2Aggregator,
     Layer2OutputType,
     MeasurementType,
+    RatioMode,
     TimeGranularity,
 )
 from featkit.fields.categorical_field import CategoricalField
@@ -387,3 +388,121 @@ class TestSQLRatioGeneration:
         sql = DatabricksSQLCodeGenerator().build_final_join(pipeline).sql
         for col in pipeline.layer2c:
             assert col.column_name in sql
+
+
+# ---------------------------------------------------------------------------
+# RatioMode.GLOBAL_TOTAL
+# ---------------------------------------------------------------------------
+
+
+class TestRatioModeGlobalTotal:
+    """RatioMode.GLOBAL_TOTAL restricts denominators to the all-None column only."""
+
+    def test_global_total_produces_fewer_ratios_than_all_projections(
+        self, full_combo, marginal_channel, marginal_region, marginal_all
+    ):
+        cols = [full_combo, marginal_channel, marginal_region, marginal_all]
+        all_proj = RatioSpaceBuilder(cols, ratio_mode=RatioMode.ALL_PROJECTIONS).build()
+        global_only = RatioSpaceBuilder(cols, ratio_mode=RatioMode.GLOBAL_TOTAL).build()
+        assert len(global_only) < len(all_proj)
+
+    def test_global_total_denominators_are_all_none(
+        self, full_combo, marginal_channel, marginal_region, marginal_all
+    ):
+        cols = [full_combo, marginal_channel, marginal_region, marginal_all]
+        ratios = RatioSpaceBuilder(cols, ratio_mode=RatioMode.GLOBAL_TOTAL).build()
+        for ratio in ratios:
+            denom_vals = ratio.denominator.categorical_combination.values()
+            assert all(v is None for v in denom_vals), (
+                f"Expected all-None denominator, got {ratio.denominator.column_name}"
+            )
+
+    def test_global_total_full_combo_produces_one_ratio(
+        self, full_combo, marginal_channel, marginal_region, marginal_all
+    ):
+        # full_combo (ch=retail, r=north) should only pair with marginal_all (ch=None, r=None)
+        cols = [full_combo, marginal_channel, marginal_region, marginal_all]
+        ratios = RatioSpaceBuilder(cols, ratio_mode=RatioMode.GLOBAL_TOTAL).build()
+        full_combo_ratios = [r for r in ratios if r.numerator is full_combo]
+        assert len(full_combo_ratios) == 1
+        assert full_combo_ratios[0].denominator is marginal_all
+
+    def test_global_total_partial_marginals_also_pair_with_global(
+        self, full_combo, marginal_channel, marginal_region, marginal_all
+    ):
+        # marginal_channel (ch=None, r=north) should also pair with marginal_all
+        cols = [full_combo, marginal_channel, marginal_region, marginal_all]
+        ratios = RatioSpaceBuilder(cols, ratio_mode=RatioMode.GLOBAL_TOTAL).build()
+        partial_ratios = [r for r in ratios if r.numerator is marginal_channel]
+        assert len(partial_ratios) == 1
+        assert partial_ratios[0].denominator is marginal_all
+
+    def test_global_total_no_global_marginal_returns_empty(
+        self, full_combo, marginal_channel, marginal_region
+    ):
+        # Without the all-None column there is no valid denominator
+        cols = [full_combo, marginal_channel, marginal_region]
+        ratios = RatioSpaceBuilder(cols, ratio_mode=RatioMode.GLOBAL_TOTAL).build()
+        assert ratios == []
+
+    def test_global_total_default_mode_is_all_projections(
+        self, full_combo, marginal_channel, marginal_region, marginal_all
+    ):
+        cols = [full_combo, marginal_channel, marginal_region, marginal_all]
+        default = RatioSpaceBuilder(cols).build()
+        explicit = RatioSpaceBuilder(cols, ratio_mode=RatioMode.ALL_PROJECTIONS).build()
+        assert [r.column_name for r in default] == [r.column_name for r in explicit]
+
+
+class TestPipelineRatioModeIntegration:
+    def test_global_total_via_config(self):
+        cfg = FeatureStoreConfig(
+            dataset=_two_cat_dataset(),
+            output_schema="s",
+            output_table_prefix="p_",
+            time_windows=[3],
+            include_marginals=True,
+            include_ratios=True,
+            ratio_mode=RatioMode.GLOBAL_TOTAL,
+        )
+        pipeline = FeatureStorePipeline(cfg).build()
+        assert len(pipeline.layer2c) > 0
+        for col in pipeline.layer2c:
+            denom_vals = col.denominator.categorical_combination.values()
+            assert all(v is None for v in denom_vals)
+
+    def test_global_total_fewer_ratios_than_all_projections(self):
+        ds = _two_cat_dataset()
+        all_proj = FeatureStorePipeline(
+            FeatureStoreConfig(
+                dataset=ds,
+                output_schema="s",
+                output_table_prefix="p_",
+                time_windows=[3],
+                include_marginals=True,
+                include_ratios=True,
+            )
+        ).build()
+        global_only = FeatureStorePipeline(
+            FeatureStoreConfig(
+                dataset=ds,
+                output_schema="s",
+                output_table_prefix="p_",
+                time_windows=[3],
+                include_marginals=True,
+                include_ratios=True,
+                ratio_mode=RatioMode.GLOBAL_TOTAL,
+            )
+        ).build()
+        assert len(global_only.layer2c) < len(all_proj.layer2c)
+
+    def test_default_ratio_mode_is_all_projections(self):
+        cfg = FeatureStoreConfig(
+            dataset=_two_cat_dataset(),
+            output_schema="s",
+            output_table_prefix="p_",
+            time_windows=[3],
+            include_marginals=True,
+            include_ratios=True,
+        )
+        assert cfg.ratio_mode == RatioMode.ALL_PROJECTIONS