pyindexnum 0.2.0

Python library for index numbers calculations

PyIndexNum

A high-performance Python library for calculating economic index numbers using Polars. Designed for statisticians and economists working with price and quantity indices.

Features

• High Performance: Built on Polars for efficient data processing of large datasets
• Comprehensive Index Methods: Support for bilateral and multilateral price/quantity indices
• Data Preparation Tools: Built-in utilities for data standardization and temporal aggregation
• Panel Data Handling: Robust methods for dealing with unbalanced panels through removal or imputation
• Extension Methods: Support for index splicing and rolling window calculations
• Type Safety: Full type annotations for better IDE support and code reliability

Installation

Using pip

pip install pyindexnum

Using uv

uv add pyindexnum

From source

git clone https://github.com/paluigi/PyIndexNum.git
cd PyIndexNum
uv sync

Quick Start

Here's the typical workflow for calculating economic indices:

import polars as pl
import pyindexnum as pin

# Load your price data
df = pl.read_csv("price_data.csv")

# 1. Standardize column names
df_std = pin.standardize_columns(df, date_col="date", price_col="price", id_col="product_id", quantity_col="quantity")

# 2. Aggregate to desired time frequency
df_agg = pin.aggregate_time(df_std, freq="1mo", agg_type="arithmetic")

# 3. Handle unbalanced panels (optional)
df_balanced = pin.remove_unbalanced(df_agg)
# or
df_imputed = pin.carry_forward_imputation(df_agg, ["aggregated_price", "aggregated_quantity"])

# 4. Calculate bilateral indices (two periods)
laspeyres_idx = pin.laspeyres(df_balanced)
fisher_idx = pin.fisher(df_balanced)

# 5. Calculate multilateral indices (multiple periods)
# Split data into two overlapping rolling windows
periods = sorted(df_agg["period"].unique())
window1 = df_agg.filter(pl.col("period").is_in(periods[:-1]))
window2 = df_agg.filter(pl.col("period").is_in(periods[1:]))

geks_fisher_idx1 = pin.geks_fisher(window1)
geks_fisher_idx2 = pin.geks_fisher(window2)

# 6. Apply extension methods (optional)
extended_idx = pin.movement_splice(geks_fisher_idx1, geks_fisher_idx2)

Supported Index Methods

Bilateral Indices (Two-Period Comparisons)

Index	Formula	Use Case
Jevons	Geometric mean of price relatives	Unweighted geometric average
Carli	Arithmetic mean of price relatives	Unweighted arithmetic average
Dutot	Ratio of arithmetic means of prices	Simple price average comparison
Laspeyres	Weighted by base period quantities	Fixed basket approach
Paasche	Weighted by current period quantities	Current basket approach
Fisher	Geometric mean of Laspeyres and Paasche	Ideal index (time/quantity reversal)
Törnqvist	Weighted geometric mean with average expenditure shares	Symmetric treatment
Walsh	Geometric mean of quantities as fixed basket	Alternative symmetric approach

Multilateral Indices (Multi-Period Comparisons)

Index	Method	Description
GEKS-Fisher	Chained Fisher indices	Most widely used multilateral method
GEKS-Törnqvist	Chained Törnqvist indices	Alternative chaining approach
GEKS-Jevons	Unweighted geometric mean of price relatives	Transitive multilateral index (no quantity)
Geary-Khamis	System of equations	Global approach
Time Product Dummy	Regression-based	WLS with expenditure shares or unweighted OLS

Extension Methods

• Movement Splice: Chain indices using movement ratios
• Window Splice: Moving window chaining
• Half Splice: Half-year overlapping windows
• Mean Splice: Average of overlapping windows
• Fixed Base Rolling Window: Rolling window with fixed base

Data Requirements

Your data should contain:

• Date column: Date or datetime values
• Price column: Numeric price observations
• Product ID column: Unique identifier for each product/variety
• Quantity column: Numeric quantities (required for weighted indices, optional for unweighted methods like GEKS-Jevons)

Example data structure:

┌────────────┬────────────┬───────┬──────────┐
│ date       ┆ product_id ┆ price ┆ quantity │
│ ---        ┆ ---        ┆ ---   ┆ ---      │
│ date       ┆ str        ┆ f64   ┆ f64      │
╞════════════╪════════════╪═══════╪══════════╡
│ 2023-01-01 ┆ A          ┆ 100.0 ┆ 10.0     │
│ 2023-01-01 ┆ B          ┆ 200.0 ┆ 5.0      │
│ 2023-02-01 ┆ A          ┆ 105.0 ┆ 12.0     │
│ 2023-02-01 ┆ B          ┆ 210.0 ┆ 4.5      │
└────────────┴────────────┴────────────┴──────────┘

API Overview

Data Preparation

# Standardize column names and types
df_std = pin.standardize_columns(df, date_col="date", price_col="price", id_col="id")

# Aggregate time series data
df_agg = pin.aggregate_time(df_std, freq="1mo", agg_type="weighted_arithmetic")

# Handle unbalanced panels
df_balanced = pin.remove_unbalanced(df_agg)
df_imputed = pin.carry_forward_imputation(df_agg, ["aggregated_price", "aggregated_quantity"])

Index Calculation

# Bilateral indices
jevons = pin.jevons(df)
laspeyres = pin.laspeyres(df)
fisher = pin.fisher(df)

# Multilateral indices
geks = pin.geks_fisher(df)
gk = pin.geary_khamis(df)

# Unweighted multilateral index (no quantity required)
geks_j = pin.geks_jevons(df)

Extensions

# Splicing methods
movement_spliced = pin.movement_splice(multilateral_index1, multilateral_index2)
window_spliced = pin.window_splice(multilateral_index1, multilateral_index2)

Documentation

Full documentation is available at https://pyindexnum.readthedocs.io/

Contributing

PyIndexNum is an open-source project and welcomes contributions! See our contributing guide for details.

Development Setup

# Clone and setup
git clone https://github.com/paluigi/PyIndexNum.git
cd PyIndexNum
uv sync --dev

# Run tests
uv run pytest

# Build documentation
cd docs && make html

Areas for Contribution

• New index methods and formulations
• Performance optimizations
• Additional data validation
• Enhanced documentation and examples
• Bug fixes and improvements

Citation

If you use PyIndexNum in your research, please cite:

@software{pyindexnum,
  title = {PyIndexNum: A Python Library for Economic Index Numbers},
  author = {Palumbo, Luigi, and Yu, Mengting},
  url = {https://github.com/paluigi/PyIndexNum},
  version = {0.2.0},
}

License

PyIndexNum is licensed under the MIT License. See LICENSE for details.

Related Projects

• Polars: The high-performance DataFrame library that powers PyIndexNum

---

Built with ❤️ for the economic statistics community