Reductions & Utilities

Robust, policy-aware aggregation and helper functions for financial data.

What Are Reductions Utilities?

Reductions are operations that combine multiple values into a single result—like sum, mean, or weighted mean. In Metric Engine, reductions are:

  • Type-safe: Work with FinancialValue objects and units

  • Policy-driven: Respect formatting, rounding, and null-handling policies

  • Null-safe: Flexible handling of missing or invalid data

Utilities are helper functions for validation, formatting, and type conversion, supporting robust financial workflows.

Why Use Reductions?

  • Aggregate financial data (e.g., total revenue, average margin)

  • Handle missing data gracefully (skip, propagate, treat as zero, or raise)

  • Enforce consistent policies across all calculations

  • Support advanced analytics (weighted averages, custom aggregations)

How Reductions Work

Reductions utilities operate on sequences of values (numbers or FinancialValue objects) and:

  • Choose the correct policy and unit for the result

  • Handle None/missing values according to the current null reduction mode:

    • SKIP: Ignore None values (default)

    • PROPAGATE: Any None → result is None

    • ZERO: Treat None as zero

    • RAISE: Raise an error if any None is present

  • Return a FinancialValue with the correct type, unit, and policy

Usage Examples

Summing Financial Values

from metricengine.reductions import fv_sum
from metricengine import money

amounts = [money(100), money(200), None, money(50)]
total = fv_sum(amounts)  # SKIP mode by default
print(total)  # $350.00

Mean (Average) Calculation

from metricengine.reductions import fv_mean

values = [money(100), money(200), None]
avg = fv_mean(values)  # SKIP mode: ignores None
print(avg)  # $150.00

Weighted Mean

from metricengine.reductions import fv_weighted_mean

# (value, weight) pairs
pairs = [(money(100), 2), (money(200), 1), (None, 3)]
weighted = fv_weighted_mean(pairs)  # SKIP mode: skips pairs with None
print(weighted)  # $133.33

Custom Null Handling

from metricengine.reductions import fv_sum, fv_mean
from metricengine.null_behaviour import NullReductionMode

# Propagate: any None → result is None
result = fv_sum([money(100), None], mode=NullReductionMode.PROPAGATE)
print(result.is_none())  # True

# Zero: treat None as zero
result = fv_mean([money(100), None, money(200)], mode=NullReductionMode.ZERO)
print(result)  # $100.00 (mean of 100, 0, 200)

Best Practices

  • Use FinancialValue objects for type safety and policy enforcement

  • Choose the right null handling mode for your use case

  • Document your aggregation logic for maintainability

  • Validate input data before aggregation if needed

Common Pitfalls

  • Forgetting to handle None values can lead to unexpected results

  • Using PROPAGATE or RAISE modes without checking for missing data may cause errors

  • Mixing units in a single reduction is not allowed—ensure all values are compatible

Real-World Patterns

  • Portfolio analysis: Aggregate returns, calculate weighted averages

  • Financial reporting: Sum revenues, compute average margins

  • Data cleaning: Use SKIP or ZERO modes to handle incomplete datasets

Reductions utilities are essential for robust, maintainable, and policy-consistent financial analytics in Metric Engine. Use them to aggregate, analyze, and report on your financial data with confidence.