Metadata-Version: 2.4
Name: real-return-deflator
Version: 0.1.0
Summary: Deflate nominal financial returns into real returns using the Fisher equation, with support for inflation rates and parallel-market exchange-rate depreciation.
Project-URL: Homepage, https://github.com/TODO/real-return-deflator
Project-URL: Repository, https://github.com/TODO/real-return-deflator
Project-URL: Issues, https://github.com/TODO/real-return-deflator/issues
Author-email: TODO <todo@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: deflator,exchange-rate,finance,fisher-equation,inflation,quantitative-finance,real-return
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Description-Content-Type: text/markdown

# real-return-deflator

**Deflate nominal financial returns into real returns using the discrete-time Fisher equation.**

[![PyPI version](https://badge.fury.io/py/real-return-deflator.svg)](https://badge.fury.io/py/real-return-deflator)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/release/python-3100/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Financial returns in high-inflation or currency-controlled economies suffer from the "Money Illusion." A nominal portfolio gain of 40% might seem impressive, but if the local currency depreciated by 45% against a stable hard currency in the same period, the *real* purchasing power has actually declined. 

`real-return-deflator` is a numerically precise, dependency-light Python library designed specifically for quantitative finance applications where silent floating-point errors, division-by-zero edge cases, or ambiguous handling of negative rates are unacceptable. It provides a standardized data-ingestion layer to calculate accurate real returns using official inflation indices or parallel-market exchange rates as inflation proxies.

---

## Installation

Install the library directly from PyPI using pip:

```bash
pip install real-return-deflator
```

*Note: The library requires Python 3.10 or higher. To use the Excel file adapter, install the optional excel dependencies:* `pip install real-return-deflator[excel]`.

---

## Quick Start

The library provides a simple functional interface. Here is how to deflate a single period's nominal return against an inflation rate:

```python
from realreturndeflator import deflate_single

nominal_return = 0.05  # A 5% nominal gain in a given period
inflation_rate = 0.04  # 4% inflation (or currency depreciation) in the same period

# Calculate the real return using the Fisher equation
real_return = deflate_single(nominal_return, inflation_rate)
print(f"Real Return: {real_return:.4%}")
# Output: Real Return: 0.9615%
```

---

## Key Concepts

### 1. The Fisher Equation
The library uses the exact discrete-time Fisher equation rather than the approximate additive formula ($r_{real} \approx r_{nominal} - i$).

$$ r_{real} = \frac{1 + r_{nominal}}{1 + i} - 1 $$

Where:
- $r_{nominal}$ is the nominal return.
- $i$ is the inflation rate (or currency depreciation rate).

*Why this matters:* The additive approximation works fine when inflation is 2%. In high-inflation economies where monthly inflation might be 15%, the additive approximation fails mathematically. `real-return-deflator` strictly enforces the exact formula.

### 2. Inflation Proxies (Exchange Rate Depreciation)
In economies with capital controls and multiple exchange rates, official inflation figures may lag or fail to reflect the true loss of purchasing power. A common quantitative practice is to use the depreciation rate of the local currency against a hard currency (like the US Dollar) on the parallel/black market as an *inflation proxy*. 

The library includes utility functions (`utils.conversion.exchange_rate_to_depreciation`) to convert raw exchange-rate time series directly into the period-over-period depreciation rates expected by the deflator.

### 3. Compounded vs. Per-Period Deflation
When working with time-series data, you often need to answer two different questions:
- **Per-Period:** What was my real return *during* Month 3? (`cumulative=False`)
- **Compounded (Cumulative):** What is my total real return from Month 1 *through* Month 3? (`cumulative=True`)

`real-return-deflator` handles both modes natively, correctly chaining the period-over-period Fisher calculations using a cumulative product when compounding is requested.

---

## Documentation

For detailed examples of data ingestion (from lists, Pandas Series, CSV/Excel files, and external JSON APIs) and compounded time-series calculations, please see the [USAGE.md](USAGE.md) guide.
