# helebkat/msml604-final-project architecture

> Architecture diagram of the GitHub repository helebkat/msml604-final-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/helebkat/msml604-final-project
- Repository: https://github.com/helebkat/msml604-final-project

## Overview

##### Project type and purpose
- This is a batch data‐analytics pipeline (Python scripts + Jupyter notebook) for portfolio risk analysis:
- Retrieve historical stock data
- Compute daily returns
- Fit univariate (skew‐t & Student’s t) and multivariate Student‐t distributions
- Calculate VaR/CVaR
- Solve a multi‐objective optimization (Pareto frontier)
- Produce summary statistics and plots

##### File structure
- Top‐level:
- MSML_604_Group_Project.ipynb – narrative and orchestration (optional)
- README.md, proposal.md – documentation
- source/ – six numbered Python modules (1–6) forming the pipeline
- output/ – CSV, NPZ, and summary files created at each stage
- resources/ – reference papers
- No external services or databases—pure file I/O.
- Each script reads one or more input artifacts and writes outputs consumed by the next script.

##### Extract architectural insights from the README
- Sequential ordering: 1 → 2 → 3 → 4 → 5 → 6
- Key outputs: stock_data.csv ⇒ daily_returns.csv ⇒ fitted‐distribution parameters & samples ⇒ portfolio risk measures ⇒ Pareto‐frontier plot

1. Data Retrieval Module (1-retrieve-data.py)
2. Returns Computation Module (2-compute-returns.py)
3. Univariate MLE Module (3-fit-mle.py)
4. Multivariate Student‐t Module (4-multivariate-student.py)
5. Risk Calculation Module (5-calculate-var-cvar.py)
6. Optimization/Visualization Module (6-pareto-frontier.py)
7. Notebook / Orchestrator (MSML_604_Group_Project.ipynb) – optional high‐level driver

- Raw stock data CSV (stock_data.csv)
- Daily returns CSV (daily_returns.csv)
- Distribution parameters & PDF samples (in‐memory & as npz if saved)
- VaR & CVaR values (console output or CSV)
- Pareto frontier plot

1. Module 1 → stock_data.csv
2. stock_data.csv → Module 2 → daily_returns.csv
3. daily_returns.csv → Module 3 → Univariate fit parameters & samples
4. daily_returns.csv + univariate parameters → Module 4 → Multivariate params (mean, Σ, ν, C)
5. multivariate params + example weights → Module 5 → VaR, CVaR
6. daily_returns.csv + multivariate params → Module 6 → Pareto frontier plot

d. Architectural patterns / principles:
- Linear pipeline / ETL style
- Modular scripts with single responsibility
- Data‐driven (files as contracts between modules)
- Reproducibility: numbered steps

e. Technologies / frameworks:
- Python ≥3.x, pandas for CSV I/O, numpy & scipy for stats, matplotlib for plots
- Jupyter Notebook for orchestration / narrative

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Notebook Orchestrator
    Notebook["MSML_604_Group_Project.ipynb"]:::notebook

    %% Stage 1: Data Retrieval
    Retrieve["1-retrieve-data.py"]:::ingest
    RAW["stock_data.csv"]:::data

    %% Stage 2: Compute Returns
    Compute["2-compute-returns.py"]:::ingest
    RETURNS["daily_returns.csv"]:::data

    %% Stage 3: Univariate MLE
    Univariate["3-fit-mle.py"]:::modeling
    UniParams["Univariate parameters & samples"]:::data

    %% Stage 4: Multivariate Student-t
    Multi["4-multivariate-student.py"]:::modeling
    MultiParams["Multivariate params (μ, Σ, ν, C)"]:::data

    %% Stage 5: Risk Calculation
    Risk["5-calculate-var-cvar.py"]:::risk
    VaR["VaR & CVaR"]:::data

    %% Stage 6: Optimization & Visualization
    Opt["6-pareto-frontier.py"]:::opt
    Plot["Pareto frontier plot"]:::data

    %% Flow
    Notebook -->|orchestrates| Retrieve
    Retrieve -->|writes stock_data.csv| RAW
    RAW -->|reads stock_data.csv| Compute
    Compute -->|writes daily_returns.csv| RETURNS
    RETURNS -->|reads daily_returns.csv| Univariate
    Univariate -->|outputs params & samples| UniParams
    RETURNS -->|reads daily_returns.csv| Multi
    UniParams -->|uses univariate params| Multi
    Multi -->|outputs multivariate params| MultiParams
    MultiParams -->|reads params| Risk
    RETURNS -->|reads daily_returns.csv| Risk
    Risk -->|outputs VaR & CVaR| VaR
    RETURNS -->|reads daily_returns.csv| Opt
    MultiParams -->|reads multivariate params| Opt
    Opt -->|outputs plot| Plot

    %% Click Events
    click Notebook "https://github.com/helebkat/msml604-final-project/blob/main/MSML_604_Group_Project.ipynb"
    click Retrieve "https://github.com/helebkat/msml604-final-project/blob/main/source/1-retrieve-data.py"
    click Compute "https://github.com/helebkat/msml604-final-project/blob/main/source/2-compute-returns.py"
    click Univariate "https://github.com/helebkat/msml604-final-project/blob/main/source/3-fit-mle.py"
    click Multi "https://github.com/helebkat/msml604-final-project/blob/main/source/4-multivariate-student.py"
    click Risk "https://github.com/helebkat/msml604-final-project/blob/main/source/5-calculate-var-cvar.py"
    click Opt "https://github.com/helebkat/msml604-final-project/blob/main/source/6-pareto-frontier.py"
    click RAW "https://github.com/helebkat/msml604-final-project/blob/main/output/stock_data.csv"
    click RETURNS "https://github.com/helebkat/msml604-final-project/blob/main/output/daily_returns.csv"
    click MultiParams "https://github.com/helebkat/msml604-final-project/blob/main/output/mvt_params.npz"

    %% Styles
    classDef ingest fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef modeling fill:#90EE90,stroke:#000,stroke-width:1px
    classDef risk fill:#FFA500,stroke:#000,stroke-width:1px
    classDef opt fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef data fill:#F5F5F5,stroke:#333,stroke-width:1px,shape:cylinder
    classDef notebook fill:#FFFFE0,stroke:#000,stroke-width:1px,shape:rectangle
```
