Metadata-Version: 2.4
Name: fincontagion
Version: 0.2.1
Summary: Readable financial contagion library from market data to portfolio analytics
Author: FinContagion Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/arjunb002/fincontagion
Project-URL: Repository, https://github.com/your-username/fincontagion
Project-URL: Issues, https://github.com/your-username/fincontagion/issues
Keywords: finance,contagion,sir,risk,portfolio,systemic-risk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: yfinance>=0.2.40
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: examples
Requires-Dist: yfinance>=0.2.40; extra == "examples"
Provides-Extra: full
Requires-Dist: networkx>=3.0; extra == "full"
Requires-Dist: cvxpy>=1.4; extra == "full"
Requires-Dist: plotly>=5.0; extra == "full"
Dynamic: license-file

# fincontagion

`fincontagion` is a Python library for financial contagion analysis, from market data preparation to network-aware portfolio analytics. It is inspired by and extends the framework proposed in:

> Bozhidarova, Ball, van Gennip, O'Dea & Stupfler (2024). *Describing financial crisis propagation through epidemic modelling on multiplex networks.* Proc. R. Soc. A 480: 20230787. https://doi.org/10.1098/rspa.2023.0787

This library was developed as part of the **Computational Finance course (PGDM)** at Madras School of Economics, taught by **Dr. Parthajit Kayal** and **Dr. Sumanjay Datta**, by students **Arjun Balakrishnan**, **Sriharinandan Raghuraman**, and **Yogesh Verma** — who extended the original theoretical framework into a practical, deployable Python library.

It provides:
- price download and cleaning utilities
- infection-state construction using volatility and SIR-like states
- tail-dependence estimation and multiplex network construction
- crisis-window parameter estimation and Monte Carlo simulation
- contagion-aware portfolio rebalancing and performance summaries
- optional Plotly visualizations

## Installation

Install the core package:
```bash
pip install fincontagion
```

Install with optional extras:
```bash
pip install "fincontagion[full]"
```

- `full` includes: `networkx`, `cvxpy`, `plotly`
- `dev` includes: `pytest`

## Quick Start

```python
import fincontagion as fc

universe = {
    "AAPL": {"region": "USA", "sector": "Technology"},
    "MSFT": {"region": "USA", "sector": "Technology"},
    "JPM":  {"region": "USA", "sector": "Finance"},
}

config = fc.PipelineConfig(
    tickers=list(universe.keys()),
    start="2020-01-01",
    end="2024-12-31",
    crises={"COVID_2020": ("2020-02-20", "2020-05-31")},
    universe=universe,
)

result = fc.run_full_pipeline(config)
print(result["portfolio"]["summary"])
```

## Main API

- `run_full_pipeline`, `PipelineConfig`
- `prepare_market_data`, `prices_to_log_returns`
- `compute_infection_states`
- `compute_tail_dependence`
- `build_network_layers`
- `estimate_parameters`, `simulate_sir`, `predict_crises`
- `rebalance_portfolio`

Visualization helpers:
- `plot_infection_timeline`
- `plot_region_infection_heatmap`
- `plot_sector_infection_breakdown`
- `plot_tail_dependence_heatmap`
- `plot_firm_network`
- `plot_portfolio_performance`
- `plot_portfolio_weights`

## Credits & Acknowledgements

This library builds directly on the theoretical framework of Bozhidarova et al. (2024), and full credit is due to the original authors for their pioneering work on SIR-based financial contagion modelling on multiplex networks.

The library was built and extended by:
- **Arjun Balakrishnan**
- **Sriharinandan Raghuraman**
- **Yogesh Verma**

under the guidance of:
- **Dr. Parthajit Kayal** (Madras School of Economics)
- **Dr. Sumanjay Datta** (Madras School of Economics)

as part of the Computational Finance course, where the original model was extended into an agentic AI-driven financial decision platform — combining agent-based contagion dynamics, adaptive decision-making, portfolio optimization under systemic risk, and emergent market simulation.

## Development

Run tests:
```bash
pytest -q
```

## License

MIT License.
