real-return-deflator 0.1.0

Deflate nominal financial returns into real returns using the Fisher equation, with support for inflation rates and parallel-market exchange-rate depreciation.

real-return-deflator

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

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:

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:

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 guide.