Add Performance Analysis utils (Hurst, Omega, Tail, Gain-Pain, Active Performance), update main README to v2.0.0, and ensure emoji-free documentation

Author: MeridianAlgo-Developer

README.md

@@ -1,4 +1,4 @@
-# Learn-Quant: Master Quantitative Finance & Python (v1.9.0)
+# Learn-Quant: Master Quantitative Finance & Python (v2.0.0)
 
 [![Lint](https://github.com/MeridianAlgo/Learn-Quant/actions/workflows/lint.yml/badge.svg)](https://github.com/MeridianAlgo/Learn-Quant/actions/workflows/lint.yml)
 
@@ -8,7 +8,7 @@
 
 ## Overview
 
-Learn-Quant is a massive, curated collection of over 55+ self-contained modules designed to bridge the gap between academic theory and production-grade code. Whether you are a student, a software engineer moving into finance, or a trader learning to code, this repository provides the building blocks you need.
+Learn-Quant is a massive, curated collection of over 60+ self-contained modules designed to bridge the gap between academic theory and production-grade code. Whether you are a student, a software engineer moving into finance, or a trader learning to code, this repository provides the building blocks you need.
 
 ### Key Learning Outcomes
 - **Master Quant Strategies**: Implement Pairs Trading, Momentum, Mean Reversion, Position Sizing, and more.
@@ -55,6 +55,7 @@ Every folder is a fully functional lesson. Pick a topic and run the code.
 - `UTILS - Quantitative Methods - Regression`: Factor models & Alpha generation.
 - `UTILS - Quantitative Methods - Linear Algebra`: Portfolio optimization & risk modelling.
 - `UTILS - Quantitative Methods - Factor Models`: Fama-French 3-Factor model, factor regression, alpha decomposition, and performance attribution.
+- `UTILS - Quantitative Methods - Performance Analysis`: Hurst Exponent, Omega Ratio, Tail Ratio, and Active Metrics.
 
 ### Level 5: Strategies & Finance
 *Applied quantitative finance.*
@@ -100,10 +101,10 @@ cd "UTILS - Strategies - Momentum Trading"
 python momentum_strategy.py
 ```
 
-**Example: Learning Context Managers**
+**Example: Learning Performance Metrics**
 ```bash
-cd "UTILS - Advanced Python - Context Managers"
-python context_managers_tutorial.py
+cd "UTILS - Quantitative Methods - Performance Analysis"
+python hurst_exponent.py
 ```
 
 ---
@@ -121,6 +122,6 @@ This project is open-sourced under the MIT License.
 
 ---
 
-**Learn-Quant v1.9.0**
+**Learn-Quant v2.0.0**
 *Quantitative Finance | Algorithmic Trading | Python Mastery*
 **Maintained by MeridianAlgo**

UTILS - Quantitative Methods - Performance Analysis/README.md

@@ -0,0 +1,41 @@
+# Performance Analysis Utilities
+
+## Overview
+This module provides quantitative performance metrics to evaluate risk-adjusted returns and the quality of investment strategies. Beyond simple metrics like the Sharpe Ratio, these tools help quants analyze tail risk, active management skill, and the statistical properties of return series.
+
+## Key Metrics Included
+
+### 1. Hurst Exponent
+Characterizes the long-term memory of a time series.
+- **H < 0.5**: Mean-reverting series.
+- **H = 0.5**: Random walk.
+- **H > 0.5**: Trending series.
+Files: `hurst_exponent.py`
+
+### 2. Omega Ratio
+Measures the risk-adjusted return relative to a target return level. It considers the entire return distribution, representing the ratio of probability-weighted gains to probability-weighted losses.
+Files: `omega_ratio.py`
+
+### 3. Tail Ratio
+Highlights the relationship between the extreme positive and negative outliers of a return distribution. It is the absolute value of the 95th percentile return divided by the absolute value of the 5th percentile return.
+Files: `tail_ratio.py`
+
+### 4. Gain-to-Pain Ratio
+A metric popularized by market wizards like Jack Schwager, representing the sum of all returns divided by the absolute sum of all negative returns. It provides a quick way to gauge the consistency of a strategy.
+Files: `gain_to_pain_ratio.py`
+
+### 5. Tracking Error and Information Ratio
+Metrics for active portfolio management.
+- **Tracking Error**: The standard deviation of the difference between the portfolio and its benchmark.
+- **Information Ratio**: The active return per unit of tracking error, measuring a manager's skill in outperforming the index.
+Files: `active_performance.py`
+
+## Usage
+Each script contains a baseline implementation and a sample execution in the `if __name__ == "__main__":` block. To run any utility, execute it from the command line:
+
+```bash
+python hurst_exponent.py
+```
+
+## Portfolio Performance
+These utilities are designed to be used in conjunction with risk metrics like Value at Risk (VaR) and Drawdown to provide a holistic view of portfolio performance and risk of ruin.

UTILS - Quantitative Methods - Performance Analysis/active_performance.py

@@ -0,0 +1,54 @@
+"""
+Active Performance Metrics Utility
+----------------------------------
+Information Ratio and Tracking Error measure a portfolio manager's skill
+at outperforming a benchmark.
+
+- Tracking Error: Standard deviation of active returns.
+- Information Ratio: Active return divided by Tracking Error.
+"""
+
+import numpy as np
+
+
+def active_metrics(returns, benchmark_returns):
+    """
+    Computes Tracking Error and Information Ratio.
+
+    Args:
+        returns (list or np.array): Series of portfolio returns.
+        benchmark_returns (list or np.array): Series of benchmark returns.
+
+    Returns:
+        dict: A dictionary containing 'tracking_error' and 'information_ratio'.
+    """
+    returns = np.array(returns)
+    benchmark_returns = np.array(benchmark_returns)
+
+    if len(returns) != len(benchmark_returns):
+        raise ValueError("Return series and benchmark series must be the same length.")
+
+    active_returns = returns - benchmark_returns
+    tracking_error = np.std(active_returns)
+
+    if tracking_error == 0:
+        return {"tracking_error": 0, "information_ratio": 0}
+
+    information_ratio = np.mean(active_returns) / tracking_error
+
+    return {
+        "tracking_error": tracking_error,
+        "information_ratio": information_ratio
+    }
+
+
+if __name__ == "__main__":
+    # Simulate a benchmark index (e.g. S&P 500)
+    benchmark = np.random.normal(0.0005, 0.01, 252)
+    # Simulate an active manager with some "alpha"
+    alpha = 0.0001
+    portfolio = benchmark + alpha + np.random.normal(0, 0.002, 252)
+
+    stats = active_metrics(portfolio, benchmark)
+    for k, v in stats.items():
+        print(f"{k.replace('_', ' ').title()}: {v:.4f}")

UTILS - Quantitative Methods - Performance Analysis/gain_to_pain_ratio.py

@@ -0,0 +1,35 @@
+"""
+Gain-to-Pain Ratio Calculation Utility
+--------------------------------------
+The Gain-to-Pain Ratio measures the cumulative return divided by the absolute
+loss sum of a return series. It's used to identify strategies with smooth paths.
+Created by Jack Schwager for his Market Wizards interviews.
+"""
+
+import numpy as np
+
+
+def gain_to_pain_ratio(returns):
+    """
+    Computes the Gain-to-Pain Ratio.
+
+    Args:
+        returns (list or np.array): Series of returns.
+
+    Returns:
+        float: Gain-to-Pain Ratio.
+    """
+    returns = np.array(returns)
+    total_returns = np.sum(returns)
+    abs_loss_sum = np.abs(np.sum(returns[returns < 0]))
+
+    if abs_loss_sum == 0:
+        return 0
+
+    return total_returns / abs_loss_sum
+
+
+if __name__ == "__main__":
+    # Simulate some normally distributed returns
+    daily = np.random.normal(0.001, 0.01, 252)
+    print(f"Gain-to-Pain Ratio: {gain_to_pain_ratio(daily):.4f}")

UTILS - Quantitative Methods - Performance Analysis/hurst_exponent.py

@@ -0,0 +1,45 @@
+"""
+Hurst Exponent Calculation Utility
+----------------------------------
+The Hurst exponent (H) characterizes the long-term memory of a time series.
+
+Interpretation:
+- H < 0.5: Mean-reverting (anti-persistent) series
+- H = 0.5: Random walk (Geometric Brownian Motion)
+- H > 0.5: Trending (persistent) series
+"""
+
+import numpy as np
+
+
+def compute_hurst(ts):
+    """
+    Computes the Hurst exponent of a time series using rescaled range (R/S) analysis.
+
+    Args:
+        ts (list or np.array): Time series of price data.
+
+    Returns:
+        float: Hurst exponent.
+    """
+    ts = np.array(ts)
+    lags = range(2, 20)
+
+    # Calculate the variance of the lagged differences
+    tau = [np.sqrt(np.std(np.subtract(ts[lag:], ts[:-lag]))) for lag in lags]
+
+    # Use a linear fit to estimate the Hurst exponent
+    poly = np.polyfit(np.log(lags), np.log(tau), 1)
+
+    # The Hurst exponent is the slope of the fit
+    return poly[0] * 2.0
+
+
+if __name__ == "__main__":
+    # Create a trending series
+    trending = np.cumsum(np.random.randn(1000) + 0.1)
+    # Create a mean-reverting series
+    reverting = np.random.randn(1000)
+
+    print(f"Trending Hurst: {compute_hurst(trending):.4f}")
+    print(f"Mean-Reverting Hurst: {compute_hurst(reverting):.4f}")

UTILS - Quantitative Methods - Performance Analysis/omega_ratio.py

@@ -0,0 +1,37 @@
+"""
+Omega Ratio Calculation Utility
+-------------------------------
+The Omega Ratio measures the risk-adjusted return relative to a target return.
+It's calculated as the probability-weighted gains divided by probability-weighted losses.
+Used to identify the performance relative to a benchmark (minimum acceptable return).
+"""
+
+import numpy as np
+
+
+def omega_ratio(returns, target=0):
+    """
+    Computes the Omega Ratio.
+
+    Args:
+        returns (list or np.array): Series of returns.
+        target (float): Minimum acceptable return level.
+
+    Returns:
+        float: Omega Ratio.
+    """
+    returns = np.array(returns)
+    gains = returns[returns > target] - target
+    losses = target - returns[returns < target]
+
+    if len(losses) == 0 or np.sum(losses) == 0:
+        return np.inf
+
+    return np.sum(gains) / np.sum(losses)
+
+
+if __name__ == "__main__":
+    # Simulate some normally distributed returns
+    daily = np.random.normal(0.001, 0.01, 252)
+    print(f"Omega Ratio at target 0%: {omega_ratio(daily):.4f}")
+    print(f"Omega Ratio at target 0.1%: {omega_ratio(daily, target=0.001):.4f}")

UTILS - Quantitative Methods - Performance Analysis/tail_ratio.py

@@ -0,0 +1,38 @@
+"""
+Tail Ratio Calculation Utility
+------------------------------
+The Tail Ratio measures the relationship between positive and negative outliers.
+It's calculated as the absolute value of the 95th percentile (right tail)
+divided by the absolute value of the 5th percentile (left tail).
+"""
+
+import numpy as np
+
+
+def compute_tail_ratio(returns):
+    """
+    Computes the Tail Ratio.
+
+    Args:
+        returns (list or np.array): Series of returns.
+
+    Returns:
+        float: Tail Ratio.
+    """
+    returns = np.array(returns)
+    right_tail = np.percentile(returns, 95)
+    left_tail = np.abs(np.percentile(returns, 5))
+
+    if left_tail == 0:
+        return 0
+
+    return right_tail / left_tail
+
+
+if __name__ == "__main__":
+    # Simulate some fat-tailed returns or normal ones
+    daily = np.random.standard_t(df=5, size=1000) * 0.01
+    print(f"Tail Ratio (T-Dist with df=5): {compute_tail_ratio(daily):.4f}")
+
+    normal = np.random.normal(0.0005, 0.01, 1000)
+    print(f"Tail Ratio (Normal): {compute_tail_ratio(normal):.4f}")