# Multi-Factor Risk Decomposition & Attribution Engine

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)
![NumPy](https://img.shields.io/badge/NumPy-Vectorized-green)
![SciPy](https://img.shields.io/badge/SciPy-Optimized-red)

An institutional-grade portfolio risk and performance attribution analytics framework built in modular, Object-Oriented Python. The repository programmatically executes **Brinson-Fachler Multi-Period Return Attribution (Carino Logarithmic Linking)**, **Covariance Matrix Risk Decomposition via Euler's Gradient Theorem (MCR/PCR)**, and **Non-Normal Fat-Tailed Tail-Risk Analytics (Cornish-Fisher Expansion & Expected Shortfall)**.

---

## 🏛️ System Architecture

```text
                     ┌─────────────────────────────────────────────────┐
                     │          risk_attribution_engine.py             │
                     └────────────────────────┬────────────────────────┘
                                              │
          ┌───────────────────────────────────┼───────────────────────────────────┐
          │                                   │                                   │
          ▼                                   ▼                                   ▼
┌───────────────────────────┐       ┌───────────────────┐               ┌────────────────────┐
│ BrinsonAttributionEngine  │       │ FactorRiskEngine  │               │ TailRiskAnalytics  │
├───────────────────────────┤       ├───────────────────┤               ├────────────────────┤
│ • Allocation (BF Model)   │       │ • Covariance Matrix│               │ • Historical VaR   │
│ • Selection & Interaction │       │   Decomposition   │               │ • Cornish-Fisher   │
│ • Carino Log Linking      │       │ • Euler MCR / PCR │               │   Expansion        │
│ • Zero-Weight Sector Fix  │       │ • Systematic/Idio │               │ • Expected Shortfall│
└───────────────────────────┘       └───────────────────┘               └────────────────────┘

---

📊 Analytics & Visualizations

1. Brinson-Fachler Performance Attribution

Decomposes total active return into Allocation Effect, Selection Effect, and Interaction Cross-Terms. Multi-period rebalancing frequencies are reconciled seamlessly using Carino's Logarithmic Linking Algorithm ($k_t$) to eliminate compounding return leakage.

2. Euler Risk Decomposition (MCR & PCR %)

Evaluates portfolio volatility via multivariate gradient calculus ($\nabla_{\mathbf{w}} \sigma_p = \frac{\Sigma \mathbf{w}}{\sigma_p}$). Measures how individual asset covariances alter absolute risk shares ($\text{PCR}_i$) relative to nominal portfolio weights.

3. Non-Normal Tail-Risk Analytics & Drawdowns

Evaluates downside tail-risk via higher-order Cornish-Fisher Taylor expansion, adjusting $z$-scores for empirical Skewness ($S$) and Excess Kurtosis ($K$). Overlaid with rolling peak-to-trough high-water-mark drawdowns ($DD_t$).

---

📐 Mathematical Formulations

1. Brinson-Fachler Return Attribution

• Allocation Effect ($A_j^{BF}$):

$$A_j^{BF} = (w_j^p - w_j^b)(r_j^b - R_b)$$

• Selection Effect ($S_j$):

$$S_j = w_j^b(r_j^p - r_j^b)$$

• Interaction Effect ($I_j$):

$$I_j = (w_j^p - w_j^b)(r_j^p - r_j^b)$$

2. Carino Multi-Period Logarithmic Scaling Factor ($k_t$)

$$k_t = \frac{\ln(1 + R_{p,t}) - \ln(1 + R_{b,t})}{R_{p,t} - R_{b,t}} \cdot \mathbf{K}, \quad \text{where } \mathbf{K} = \frac{R_p - R_b}{\ln(1 + R_p) - \ln(1 + R_b)}$$

3. Marginal Contribution to Risk (MCR)

$$\text{MCR}_i = \frac{\partial \sigma_p}{\partial w_i} = \frac{(\Sigma \mathbf{w})_i}{\sigma_p}$$

4. Euler Percentage Contribution to Risk (PCR)

$$\text{PCR}_i = \frac{w_i \cdot \text{MCR}_i}{\sigma_p} \implies \sum_{i=1}^N \text{PCR}_i = 100%$$

5. Cornish-Fisher Quantile Expansion

$$z_{CF} = z_\alpha + \frac{1}{6}(z_\alpha^2 - 1)S + \frac{1}{24}(z_\alpha^3 - 3z_\alpha)K - \frac{1}{36}(2z_\alpha^3 - 5z_\alpha)S^2$$

$$\text{VaR}_\alpha^{CF} = -\left( \mu_p + z_{CF} \cdot \sigma_p \right)$$

---

📁 Repository Structure

quant-risk-attribution-engine/
├── docs/                        # Exported chart artifacts for GitHub display
│   ├── brinson_waterfall.png
│   ├── risk_decomposition_pcr.png
│   └── tail_risk_drawdown.png
├── risk_attribution_engine.py   # Core Object-Oriented computational engine
├── visualizer.py                # Matplotlib publication chart generator
├── requirements.txt             # Environment dependencies manifest
├── .gitignore                   # Git version control filter
└── README.md                    # Repository documentation