Metadata-Version: 2.4
Name: hpipy
Version: 0.1.2
Summary: House Price Indices with Python
Author-email: Reid Johnson <reid.johnson@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: altair~=5.5.0
Requires-Dist: captum~=0.8.0
Requires-Dist: h3~=4.2.1
Requires-Dist: numpy~=1.26.4; python_version < "3.13"
Requires-Dist: pandas~=2.2.3
Requires-Dist: quantile-forest~=1.4.0
Requires-Dist: scikit-learn~=1.6.1
Requires-Dist: scipy~=1.15.2
Requires-Dist: statsmodels~=0.14.4
Requires-Dist: torch~=2.6.0
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == "dev"
Requires-Dist: flake8>=7.2.0; extra == "dev"
Requires-Dist: isort>=6.0.1; extra == "dev"
Requires-Dist: mypy>=1.15.0; extra == "dev"
Requires-Dist: pytest>=8.3.5; extra == "dev"
Requires-Dist: pytest-cov>=6.1.1; extra == "dev"
Dynamic: license-file

# hpiPy <a href="https://reidjohnson.github.io/hpipy/"><img align="right" src="https://reidjohnson.github.io/hpipy/_static/hpipy-logo.svg" height="50"></img></a>

[![PyPI - Version](https://img.shields.io/pypi/v/hpipy)](https://pypi.org/project/hpipy)
[![License](https://img.shields.io/github/license/reidjohnson/hpipy)](https://github.com/reidjohnson/hpipy/blob/main/LICENSE)
[![GitHub Actions](https://github.com/reidjohnson/hpipy/actions/workflows/build.yml/badge.svg)](https://github.com/reidjohnson/hpipy/actions/workflows/build.yml)
[![Codecov](https://codecov.io/gh/reidjohnson/hpipy/branch/main/graph/badge.svg?token=STRT8T67YP)](https://codecov.io/gh/reidjohnson/hpipy)
[![Code Style black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

**hpiPy** simplifies and standardizes the creation of house price indices in Python.

The package provides tools to evaluate index quality through predictive accuracy, volatility, and revision metrics—enabling meaningful comparisons across different methods and estimators. It focuses on the most widely used approaches: repeat sales and hedonic pricing models, with support for base, robust, and weighted estimators where applicable. The package also includes a random forest–based method with partial dependence plots for post-model interpretability, as well as a neural network approach that separates property-specific and market-level effects to jointly estimate quality and index components from property-level data. Based on [hpiR](https://github.com/andykrause/hpiR).

## Quick Start

To install hpiPy from [PyPI](https://pypi.org/project/hpipy) using `pip`:

```bash
pip install hpipy
```

## Example

A basic example of creating a house price index:

```python
import altair as alt
import pandas as pd
from hpipy.datasets import load_ex_sales
from hpipy.price_index import RepeatTransactionIndex
from hpipy.utils.plotting import plot_index

# Load prepared data.
df = load_ex_sales()

# Create an index.
hpi = RepeatTransactionIndex.create_index(
    trans_data=df,
    prop_id="pinx",
    trans_id="sale_id",
    price="sale_price",
    date="sale_date",
    periodicity="M",
    estimator="robust",
    log_dep=True,
    smooth=True,
)

# Visualize the index.
with alt.renderers.enable("browser"):
    plot_index(hpi, smooth=True).properties(title="Example Index").show()
```

## Documentation

An installation guide, API documentation, and examples can be found in the [documentation](https://reidjohnson.github.io/hpipy/).

## Running the Tests

1. Create a virtual environment (we recommend [`uv`](https://github.com/astral-sh/uv)):

```bash
uv venv
```

2. Install base and development dependencies:

```bash
uv pip install --requirements pyproject.toml --extra dev
```

3. Run the test suite:

```bash
pytest
```

## Acknowledgements

Based on the [hpiR](https://github.com/andykrause/hpiR) package.
