# royayush27/decision-focused-volatility-timing architecture

> Architecture diagram of the GitHub repository royayush27/decision-focused-volatility-timing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/royayush27/decision-focused-volatility-timing
- Repository: https://github.com/royayush27/decision-focused-volatility-timing

## Overview

This repository documents a financial-engineering research project testing whether decision-focused variance estimation improves volatility-timed portfolios. The documented workflow uses Ken French daily data to build daily and monthly research datasets, then compares variance models and estimation objectives under a fixed monthly trading rule. Data preparation is represented by the notebook, but its contents were not sampled; model fitting and portfolio evaluation are described as future work, not inspected implementations.

Main entry points: [`Data_Collection.ipynb`](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/Data_Collection.ipynb) (Data preparation), [`README.md`](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md) (Monthly timing), [`ff_daily_garchdata.parquet`](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_daily_garchdata.parquet) (Daily returns), [`ff_monthly_baselinedata.parquet`](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_monthly_baselinedata.parquet) (Monthly baseline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Research data"]
  node_factors_zip["Factor archives"]
  node_momentum_zip["Momentum archive"]
  node_industry_zip["Industry archive"]
  node_collection["Data preparation"]
end

subgraph group_models["Forecast experiment"]
  node_rv_model["RV baseline<br/>[README.md]"]
  node_garch_models["GARCH forecasts<br/>[README.md]"]
  node_ginngarch["GINN forecasts<br/>[README.md]"]
  node_estimation["Estimation objectives<br/>[README.md]"]
  node_timing["Monthly timing<br/>[README.md]"]
  node_evaluation["Portfolio comparison<br/>[README.md]"]
end

subgraph group_outputs["Dataset artifacts"]
  node_daily["Daily returns"]
  node_monthly["Monthly baseline"]
  node_csv_views["CSV views<br/>[ff_long.csv]"]
  node_merged_csv["Merged data<br/>[ff_merged.csv]"]
  node_rv_csv["Monthly RV"]
end

node_researcher(("Researcher"))
node_french[("Ken French data")]

node_researcher -->|"prepares data"| node_collection
node_french -->|"provides data"| node_factors_zip
node_french -->|"provides data"| node_momentum_zip
node_french -->|"provides data"| node_industry_zip
node_factors_zip -->|"ingests"| node_collection
node_momentum_zip -->|"ingests"| node_collection
node_industry_zip -->|"ingests"| node_collection
node_collection -->|"writes daily"| node_daily
node_collection -->|"writes monthly"| node_monthly
node_collection -->|"exports CSV"| node_csv_views
node_collection -->|"exports CSV"| node_merged_csv
node_collection -->|"exports RV"| node_rv_csv
node_monthly -->|"supplies baseline"| node_rv_model
node_daily -->|"fits daily"| node_garch_models
node_daily -->|"feeds forecasts"| node_ginngarch
node_rv_model -->|"forecasts variance"| node_timing
node_garch_models -->|"forecasts variance"| node_timing
node_ginngarch -->|"forecasts variance"| node_timing
node_estimation -->|"selects parameters"| node_garch_models
node_estimation -->|"selects parameters"| node_ginngarch
node_timing -->|"produces portfolios"| node_evaluation
node_monthly -->|"supplies returns"| node_evaluation
node_evaluation -->|"compares results"| node_researcher

click node_factors_zip "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/F-F_Research_Data_5_Factors_2x3_daily_CSV.zip"
click node_momentum_zip "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/F-F_Momentum_Factor_daily_CSV.zip"
click node_industry_zip "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/10_Industry_Portfolios_daily_CSV.zip"
click node_collection "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/Data_Collection.ipynb"
click node_daily "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_daily_garchdata.parquet"
click node_monthly "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_monthly_baselinedata.parquet"
click node_csv_views "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_long.csv"
click node_merged_csv "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_merged.csv"
click node_rv_csv "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/monthly_returns_rv.csv"
click node_rv_model "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"
click node_garch_models "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"
click node_ginngarch "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"
click node_estimation "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"
click node_timing "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"
click node_evaluation "https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_factors_zip,node_momentum_zip,node_industry_zip,node_collection toneBlue
class node_rv_model,node_garch_models,node_ginngarch,node_estimation,node_timing,node_evaluation,node_french toneAmber
class node_daily,node_monthly,node_csv_views,node_merged_csv,node_rv_csv toneMint
class node_researcher toneIndigo
```

## Components

### Research data

- [Factor archives](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/F-F_Research_Data_5_Factors_2x3_daily_CSV.zip): `raw/F-F_Research_Data_5_Factors_2x3_daily_CSV.zip`
- [Momentum archive](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/F-F_Momentum_Factor_daily_CSV.zip): `raw/F-F_Momentum_Factor_daily_CSV.zip`
- [Industry archive](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/raw/10_Industry_Portfolios_daily_CSV.zip): `raw/10_Industry_Portfolios_daily_CSV.zip`
- [Data preparation](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/Data_Collection.ipynb): `Data_Collection.ipynb`

### Forecast experiment

- [RV baseline](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`
- [GARCH forecasts](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`
- [GINN forecasts](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`
- [Estimation objectives](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`
- [Monthly timing](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`
- [Portfolio comparison](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/README.md): `README.md`

### Dataset artifacts

- [Daily returns](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_daily_garchdata.parquet): `ff_daily_garchdata.parquet`
- [Monthly baseline](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_monthly_baselinedata.parquet): `ff_monthly_baselinedata.parquet`
- [CSV views](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_long.csv): `ff_long.csv`
- [Merged data](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/ff_merged.csv): `ff_merged.csv`
- [Monthly RV](https://github.com/royayush27/decision-focused-volatility-timing/blob/main/monthly_returns_rv.csv): `monthly_returns_rv.csv`

### Other components

- **Researcher**
- **Ken French data**

## Connections

- Researcher → Data preparation: prepares data
- Ken French data → Factor archives: provides data
- Ken French data → Momentum archive: provides data
- Ken French data → Industry archive: provides data
- Factor archives → Data preparation: ingests
- Momentum archive → Data preparation: ingests
- Industry archive → Data preparation: ingests
- Data preparation → Daily returns: writes daily
- Data preparation → Monthly baseline: writes monthly
- Data preparation → CSV views: exports CSV
- Data preparation → Merged data: exports CSV
- Data preparation → Monthly RV: exports RV
- Monthly baseline → RV baseline: supplies baseline
- Daily returns → GARCH forecasts: fits daily
- Daily returns → GINN forecasts: feeds forecasts
- RV baseline → Monthly timing: forecasts variance
- GARCH forecasts → Monthly timing: forecasts variance
- GINN forecasts → Monthly timing: forecasts variance
- Estimation objectives → GARCH forecasts: selects parameters
- Estimation objectives → GINN forecasts: selects parameters
- Monthly timing → Portfolio comparison: produces portfolios
- Monthly baseline → Portfolio comparison: supplies returns
- Portfolio comparison → Researcher: compares results