# animeshav14/pmg-econ architecture

> Architecture diagram of the GitHub repository animeshav14/pmg-econ, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/animeshav14/pmg-econ
- Repository: https://github.com/animeshav14/pmg-econ

## Overview

PMG Macro Regime Engine retrieves and prepares macroeconomic and market observations, builds four distinct feature pillars, classifies pillar and composite regimes, and studies sector behavior within those regimes. Its principal workflow runs through `run_engine.py` into `src/engine.py`; separate expanding-window and archived-vintage diagnostics extend that analysis. The README documents outputs for current state, pillar diagnostics, composite maps, sector statistics, and backtests. Relationships reflect shown calls and documented capabilities; some output and retrieval links rely on README statements or SOURCE INDEX references rather than complete source excerpts.

Main entry points: [`src/engine.py`](https://github.com/animeshav14/pmg-econ/blob/main/src/engine.py) (Analysis orchestrator), [`src/transforms.py`](https://github.com/animeshav14/pmg-econ/blob/main/src/transforms.py) (Monthly preparation), [`src/vintages.py`](https://github.com/animeshav14/pmg-econ/blob/main/src/vintages.py) (Vintage backtest), [`update_data.py`](https://github.com/animeshav14/pmg-econ/blob/main/update_data.py) (Data updater)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_acquisition["Data acquisition"]
  node_updater["Data updater<br/>[update_data.py]"]
  node_sources["Data sources<br/>[registry.py]"]
  node_raw[("Raw snapshots")]
end

subgraph group_features["Feature preparation"]
  node_transforms["Monthly preparation<br/>[transforms.py]"]
  node_growth["Growth features<br/>[features.py]"]
  node_financial["Financial features<br/>[features.py]"]
  node_inflation["Inflation features<br/>[features.py]"]
  node_market["Market features<br/>[features.py]"]
end

subgraph group_analysis["Regime analysis"]
  node_engine["Analysis orchestrator<br/>[engine.py]"]
  node_model["Pillar regime models<br/>[model.py]"]
  node_composite["Composite regime<br/>[model.py]"]
  node_sectors["Sector statistics<br/>[sectors.py]"]
end

subgraph group_diagnostics["Historical diagnostics"]
  node_backtest["Expanding backtest<br/>[engine.py]"]
  node_vintage_runner["Vintage command"]
  node_vintages["Vintage backtest<br/>[vintages.py]"]
end

subgraph group_reporting["Reporting"]
  node_plots["Maps and charts<br/>[plots.py]"]
  node_outputs["Analysis outputs"]
end

node_user(("Analyst"))
node_runner["Run interface<br/>[run_engine.py]"]
node_fred(("FRED / ALFRED"))
node_yahoo(("Yahoo Finance"))

node_user -->|"runs"| node_runner
node_runner -->|"invokes"| node_engine
node_user -->|"requests updates"| node_updater
node_updater -->|"uses series"| node_sources
node_updater -->|"downloads"| node_fred
node_updater -->|"downloads"| node_yahoo
node_updater -->|"saves snapshots"| node_raw
node_engine -->|"prepares panels"| node_transforms
node_transforms -->|"loads cached data"| node_raw
node_transforms -->|"uses metadata"| node_sources
node_transforms -->|"builds features"| node_growth
node_transforms -->|"builds features"| node_financial
node_transforms -->|"builds features"| node_inflation
node_transforms -->|"builds features"| node_market
node_engine -->|"fits pillar models"| node_model
node_engine -->|"combines pillars"| node_composite
node_engine -->|"computes associations"| node_sectors
node_engine -->|"renders figures"| node_plots
node_engine -->|"writes results"| node_outputs
node_engine -->|"runs diagnostics"| node_backtest
node_backtest -->|"refits models"| node_model
node_backtest -->|"summarizes returns"| node_sectors
node_vintage_runner -->|"invokes"| node_vintages
node_vintages -->|"fetches vintages"| node_fred
node_vintages -->|"prepares vintage panels"| node_transforms
node_vintages -->|"uses one-step fit"| node_engine
node_vintages -->|"analyzes forward returns"| node_sectors
node_vintages -->|"writes vintage results"| node_outputs

click node_runner "https://github.com/animeshav14/pmg-econ/blob/main/run_engine.py"
click node_updater "https://github.com/animeshav14/pmg-econ/blob/main/update_data.py"
click node_sources "https://github.com/animeshav14/pmg-econ/blob/main/src/registry.py"
click node_raw "https://github.com/animeshav14/pmg-econ/tree/main/data/raw"
click node_transforms "https://github.com/animeshav14/pmg-econ/blob/main/src/transforms.py"
click node_growth "https://github.com/animeshav14/pmg-econ/blob/main/pillar_1/features.py"
click node_financial "https://github.com/animeshav14/pmg-econ/blob/main/pillar_2/features.py"
click node_inflation "https://github.com/animeshav14/pmg-econ/blob/main/pillar_3/features.py"
click node_market "https://github.com/animeshav14/pmg-econ/blob/main/pillar_4/features.py"
click node_engine "https://github.com/animeshav14/pmg-econ/blob/main/src/engine.py"
click node_model "https://github.com/animeshav14/pmg-econ/blob/main/src/model.py"
click node_composite "https://github.com/animeshav14/pmg-econ/blob/main/src/model.py"
click node_sectors "https://github.com/animeshav14/pmg-econ/blob/main/src/sectors.py"
click node_backtest "https://github.com/animeshav14/pmg-econ/blob/main/src/engine.py"
click node_vintage_runner "https://github.com/animeshav14/pmg-econ/blob/main/backtest_vintages.py"
click node_vintages "https://github.com/animeshav14/pmg-econ/blob/main/src/vintages.py"
click node_plots "https://github.com/animeshav14/pmg-econ/blob/main/src/plots.py"
click node_outputs "https://github.com/animeshav14/pmg-econ/tree/main/outputs"

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_updater,node_sources,node_raw toneBlue
class node_transforms,node_growth,node_financial,node_inflation,node_market toneAmber
class node_engine,node_model,node_composite,node_sectors toneMint
class node_backtest,node_vintage_runner,node_vintages toneRose
class node_plots,node_outputs,node_user,node_fred,node_yahoo toneIndigo
class node_runner toneTeal
```

## Components

### Data acquisition

- [Data updater](https://github.com/animeshav14/pmg-econ/blob/main/update_data.py): `update_data.py`
- [Data sources](https://github.com/animeshav14/pmg-econ/blob/main/src/registry.py): `src/registry.py`
- [Raw snapshots](https://github.com/animeshav14/pmg-econ/tree/main/data/raw): `data/raw`

### Feature preparation

- [Monthly preparation](https://github.com/animeshav14/pmg-econ/blob/main/src/transforms.py): `src/transforms.py`
- [Growth features](https://github.com/animeshav14/pmg-econ/blob/main/pillar_1/features.py): `pillar_1/features.py`
- [Financial features](https://github.com/animeshav14/pmg-econ/blob/main/pillar_2/features.py): `pillar_2/features.py`
- [Inflation features](https://github.com/animeshav14/pmg-econ/blob/main/pillar_3/features.py): `pillar_3/features.py`
- [Market features](https://github.com/animeshav14/pmg-econ/blob/main/pillar_4/features.py): `pillar_4/features.py`

### Regime analysis

- [Analysis orchestrator](https://github.com/animeshav14/pmg-econ/blob/main/src/engine.py): `src/engine.py`
- [Pillar regime models](https://github.com/animeshav14/pmg-econ/blob/main/src/model.py): `src/model.py`
- [Composite regime](https://github.com/animeshav14/pmg-econ/blob/main/src/model.py): `src/model.py`
- [Sector statistics](https://github.com/animeshav14/pmg-econ/blob/main/src/sectors.py): `src/sectors.py`

### Historical diagnostics

- [Expanding backtest](https://github.com/animeshav14/pmg-econ/blob/main/src/engine.py): `src/engine.py`
- [Vintage command](https://github.com/animeshav14/pmg-econ/blob/main/backtest_vintages.py): `backtest_vintages.py`
- [Vintage backtest](https://github.com/animeshav14/pmg-econ/blob/main/src/vintages.py): `src/vintages.py`

### Reporting

- [Maps and charts](https://github.com/animeshav14/pmg-econ/blob/main/src/plots.py): `src/plots.py`
- [Analysis outputs](https://github.com/animeshav14/pmg-econ/tree/main/outputs): `outputs`

### Other components

- **Analyst**
- [Run interface](https://github.com/animeshav14/pmg-econ/blob/main/run_engine.py): `run_engine.py`
- **FRED / ALFRED**
- **Yahoo Finance**

## Connections

- Analyst → Run interface: runs (evidence: `run_engine.py`)
- Run interface → Analysis orchestrator: invokes (evidence: `run_engine.py`)
- Analyst → Data updater: requests updates (evidence: `README.md`)
- Data updater → Data sources: uses series
- Data updater → FRED / ALFRED: downloads
- Data updater → Yahoo Finance: downloads
- Data updater → Raw snapshots: saves snapshots (evidence: `README.md`)
- Analysis orchestrator → Monthly preparation: prepares panels (evidence: `src/engine.py`)
- Monthly preparation → Raw snapshots: loads cached data (evidence: `src/transforms.py`)
- Monthly preparation → Data sources: uses metadata (evidence: `src/transforms.py`)
- Monthly preparation → Growth features: builds features (evidence: `src/transforms.py`)
- Monthly preparation → Financial features: builds features (evidence: `src/transforms.py`)
- Monthly preparation → Inflation features: builds features (evidence: `src/transforms.py`)
- Monthly preparation → Market features: builds features (evidence: `src/transforms.py`)
- Analysis orchestrator → Pillar regime models: fits pillar models (evidence: `src/engine.py`)
- Analysis orchestrator → Composite regime: combines pillars (evidence: `src/engine.py`)
- Analysis orchestrator → Sector statistics: computes associations (evidence: `src/engine.py`)
- Analysis orchestrator → Maps and charts: renders figures (evidence: `src/engine.py`)
- Analysis orchestrator → Analysis outputs: writes results (evidence: `README.md`)
- Analysis orchestrator → Expanding backtest: runs diagnostics (evidence: `run_engine.py`)
- Expanding backtest → Pillar regime models: refits models (evidence: `src/engine.py`)
- Expanding backtest → Sector statistics: summarizes returns (evidence: `src/engine.py`)
- Vintage command → Vintage backtest: invokes (evidence: `backtest_vintages.py`)
- Vintage backtest → FRED / ALFRED: fetches vintages (evidence: `src/vintages.py`)
- Vintage backtest → Monthly preparation: prepares vintage panels (evidence: `src/vintages.py`)
- Vintage backtest → Analysis orchestrator: uses one-step fit (evidence: `src/vintages.py`)
- Vintage backtest → Sector statistics: analyzes forward returns (evidence: `src/vintages.py`)
- Vintage backtest → Analysis outputs: writes vintage results (evidence: `README.md`)
