fincontagion 0.2.1

Readable financial contagion library from market data to portfolio analytics

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:

pip install fincontagion

Install with optional extras:

pip install "fincontagion[full]"

• full includes: networkx, cvxpy, plotly
• dev includes: pytest

Quick Start

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:

pytest -q

License

MIT License.