# omnimahui/thetadata-spx architecture

> Architecture diagram of the GitHub repository omnimahui/thetadata-spx, 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/omnimahui/thetadata-spx
- Repository: https://github.com/omnimahui/thetadata-spx
- Video tour (about a minute): https://gitdiagram.com/omnimahui/thetadata-spx/video

## Overview

This repository contains SPX options feature engineering, a Temporal Fusion Transformer training workflow, an options-analysis notebook, and a reusable trend-scanning label function. The visible feature script reads a prebuilt one-minute parquet dataset and writes engineered features. The training excerpt shows preprocessing, time-series dataset construction, model training or weight loading, and checkpoint copying. The notebook’s contents and the training data-loading section are not available, so their wiring is left unspecified.

Main entry points: [`train.py`](https://github.com/omnimahui/thetadata-spx/blob/main/train.py) (TFT model), [`thetadata-spx-features.py`](https://github.com/omnimahui/thetadata-spx/blob/main/thetadata-spx-features.py) (SPX feature job), [`trend_scanning_labels.py`](https://github.com/omnimahui/thetadata-spx/blob/main/trend_scanning_labels.py) (Trend-scanning labels)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_features["Feature engineering"]
  node_feature_job["SPX feature job"]
  node_features_out[("Engineered features")]
end

subgraph group_training["Model training"]
  node_train_data[("Training data")]
  node_preprocess["Prepare time series<br/>[train.py]"]
  node_dataset["Time-series datasets<br/>[train.py]"]
  node_tft["TFT model<br/>[train.py]"]
  node_checkpoint[("Model checkpoint")]
end

subgraph group_research["Research tools"]
  node_notebook["Options analysis"]
  node_label_function["Trend-scanning labels"]
  node_labels["Trend labels"]
end

node_market_data[("Minute options data")]
node_price_series["Price series"]

node_market_data -->|"reads"| node_feature_job
node_feature_job -->|"writes"| node_features_out
node_train_data -->|"reads"| node_preprocess
node_preprocess -->|"builds"| node_dataset
node_dataset -->|"feeds"| node_tft
node_tft -->|"saves"| node_checkpoint
node_checkpoint -.->|"loads weights"| node_tft
node_price_series -->|"labels"| node_label_function
node_label_function -->|"returns"| node_labels

click node_feature_job "https://github.com/omnimahui/thetadata-spx/blob/main/thetadata-spx-features.py"
click node_preprocess "https://github.com/omnimahui/thetadata-spx/blob/main/train.py"
click node_dataset "https://github.com/omnimahui/thetadata-spx/blob/main/train.py"
click node_tft "https://github.com/omnimahui/thetadata-spx/blob/main/train.py"
click node_notebook "https://github.com/omnimahui/thetadata-spx/blob/main/thetadata-spx-options.ipynb"
click node_label_function "https://github.com/omnimahui/thetadata-spx/blob/main/trend_scanning_labels.py"

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_feature_job,node_features_out toneBlue
class node_train_data,node_preprocess,node_dataset,node_tft,node_checkpoint,node_market_data toneAmber
class node_notebook,node_label_function,node_labels toneMint
class node_price_series toneIndigo
```

## Components

### Feature engineering

- [SPX feature job](https://github.com/omnimahui/thetadata-spx/blob/main/thetadata-spx-features.py): `thetadata-spx-features.py`
- **Engineered features**

### Model training

- **Training data**
- [Prepare time series](https://github.com/omnimahui/thetadata-spx/blob/main/train.py): `train.py`
- [Time-series datasets](https://github.com/omnimahui/thetadata-spx/blob/main/train.py): `train.py`
- [TFT model](https://github.com/omnimahui/thetadata-spx/blob/main/train.py): `train.py`
- **Model checkpoint**

### Research tools

- [Options analysis](https://github.com/omnimahui/thetadata-spx/blob/main/thetadata-spx-options.ipynb): `thetadata-spx-options.ipynb`
- [Trend-scanning labels](https://github.com/omnimahui/thetadata-spx/blob/main/trend_scanning_labels.py): `trend_scanning_labels.py`
- **Trend labels**

### Other components

- **Minute options data**
- **Price series**

## Connections

- Minute options data → SPX feature job: reads
- SPX feature job → Engineered features: writes
- Training data → Prepare time series: reads
- Prepare time series → Time-series datasets: builds
- Time-series datasets → TFT model: feeds
- TFT model → Model checkpoint: saves
- Model checkpoint → TFT model: loads weights
- Price series → Trend-scanning labels: labels
- Trend-scanning labels → Trend labels: returns