Metadata-Version: 2.4
Name: fincontagion
Version: 0.2.0
Summary: Readable financial contagion library from market data to portfolio analytics
Author: FinContagion Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-username/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 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`

## Development

Run tests:

```bash
pytest -q
```

## License

MIT License.
