Metadata-Version: 2.4
Name: mjf-finance
Version: 0.1.0
Summary: Modified Jones-Faddy Skew t-Distributions for Financial Modeling
Project-URL: Homepage, https://github.com/kuslavicek/mjf-finance
Project-URL: Bug Tracker, https://github.com/kuslavicek/mjf-finance/issues
Author-email: kuslavicek <kuslavicek@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Requires-Dist: numpy
Requires-Dist: scipy
Description-Content-Type: text/markdown

# mjf-finance

![](https://img.shields.io/badge/SciPy-654FF0?logo=SciPy&logoColor=white)
[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=fff)](#)
[![NumPy](https://img.shields.io/badge/NumPy-4DABCF?logo=numpy&logoColor=fff)](#)
[![Pytest](https://img.shields.io/badge/Pytest-fff?logo=pytest&logoColor=000)](#)
[![PyPI](https://img.shields.io/badge/PyPI-3775A9?logo=pypi&logoColor=fff)](#)
![License](https://img.shields.io/github/license/kuslavicek/mjf-finance)
![Version](https://img.shields.io/github/v/release/kuslavicek/mjf-finance)
![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)
[![zread](https://img.shields.io/badge/Ask_Zread-_.svg?style=flat&color=00b0aa&labelColor=000000&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB3aWR0aD0iMTYiIGhlaWdodD0iMTYiIHZpZXdCb3g9IjAgMCAxNiAxNiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTQuOTYxNTYgMS42MDAxSDIuMjQxNTZDMS44ODgxIDEuNjAwMSAxLjYwMTU2IDEuODg2NjQgMS42MDE1NiAyLjI0MDFWNC45NjAxQzEuNjAxNTYgNS4zMTM1NiAxLjg4ODEgNS42MDAxIDIuMjQxNTYgNS42MDAxSDQuOTYxNTZDNS4zMTUwMiA1LjYwMDEgNS42MDE1NiA1LjMxMzU2IDUuNjAxNTYgNC45NjAxVjIuMjQwMUM1LjYwMTU2IDEuODg2NjQgNS4zMTUwMiAxLjYwMDEgNC45NjE1NiAxLjYwMDFaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00Ljk2MTU2IDEwLjM5OTlIMi4yNDE1NkMxLjg4ODEgMTAuMzk5OSAxLjYwMTU2IDEwLjY4NjQgMS42MDE1NiAxMS4wMzk5VjEzLjc1OTlDMS42MDE1NiAxNC4xMTM0IDEuODg4MSAxNC4zOTk5IDIuMjQxNTYgMTQuMzk5OUg0Ljk2MTU2QzUuMzE1MDIgMTQuMzk5OSA1LjYwMTU2IDE0LjExMzQgNS42MDE1NiAxMy43NTk5VjExLjAzOTlDNS42MDE1NiAxMC42ODY0IDUuMzE1MDIgMTAuMzk5OSA0Ljk2MTU2IDEwLjM5OTlaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik0xMy43NTg0IDEuNjAwMUgxMS4wMzg0QzEwLjY4NSAxLjYwMDEgMTAuMzk4NCAxLjg4NjY0IDEwLjM5ODQgMi4yNDAxVjQuOTYwMUMxMC4zOTg0IDUuMzEzNTYgMTAuNjg1IDUuNjAwMSAxMS4wMzg0IDUuNjAwMUgxMy43NTg0QzE0LjExMTkgNS42MDAxIDE0LjM5ODQgNS4zMTM1NiAxNC4zOTg0IDQuOTYwMVYyLjI0MDFDMTQuMzk4NCAxLjg4NjY0IDE0LjExMTkgMS42MDAxIDEzLjc1ODQgMS42MDAxWiIgZmlsbD0iI2ZmZiIvPgo8cGF0aCBkPSJNNCAxMkwxMiA0TDQgMTJaIiBmaWxsPSIjZmZmIi8%2BCjxwYXRoIGQ9Ik00IDEyTDEyIDQiIHN0cm9rZT0iI2ZmZiIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIvPgo8L3N2Zz4K&logoColor=ffffff)](https://zread.ai/kuslavicek/mjf-finance)

**Broken Symmetry of Stock Returns - Modified Jones-Faddy Skew t-Distributions**

`mjf-finance` is a Python library that implements the Modified Jones-Faddy (mJF) Skew t-Distribution, a statistical model designed to capture the "broken symmetry" of stock market returns. Unlike traditional models that assume symmetry, mJF accounts for the fact that market crashes are more frequent and violent than rallies (negative skew) and that the market generally trends upwards over time.

## Features

-   **mJF1 Distribution**: Implements Eq. 20 from the paper, allowing for asymmetric power-law tails for gains and losses.
-   **Gain/Loss Decoupling**: Analyze the "volatility of gains" and "volatility of losses" separately.
-   **Physics-Inspired**: Parameters are derived from multiplicative stochastic volatility models, offering interpretability.
-   **Risk Metrics**: Designed for better estimation of Value at Risk (VaR) and tail risk (Black Swans).

## Installation

You can install the package using pip:

```bash
pip install mjf-finance
```

Or install from source:

```bash
git clone https://github.com/username/mjf-finance.git
cd mjf-finance
pip install .
```

## Usage

### Analyzing Returns

```python
import numpy as np
from mjf_finance.distributions import pdf_mjf1

# Example parameters based on S&P 500 (illustrative)
mu = 0.0005        # Location parameter (drift)
alpha_g = 3.5      # Shape parameter for gains
alpha_l = 2.8      # Shape parameter for losses (heavier tail)
theta = 0.00015    # Mean variance
tau = 1.0          # Time increment (e.g., 1 day)

# Evaluate PDF at specific return
ret = -0.05 # 5% loss
density = pdf_mjf1(ret, mu, alpha_g, alpha_l, theta, tau)
print(f"Probability density at -5%: {density}")
```

### Calculating Statistics

```python
from mjf_finance.statistics import statistical_mean, statistical_variance

mean_val = statistical_mean(mu, alpha_g, alpha_l, theta, tau)
variance_val = statistical_variance(alpha_g, alpha_l, theta, tau)

print(f"Expected Return: {mean_val}")
print(f"Variance: {variance_val}")
```

## References

This project incorporates research from the following paper:

- **Broken Symmetry of Stock Returns -- a Modified Jones-Faddy Skew t-Distribution**
  Siqi Shao, Arshia Ghasemi, Hamed Farahani, R. A. Serota
  *arXiv:2512.23640*



