# matteoprata/lobcast architecture

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

- Interactive diagram: https://gitdiagram.com/matteoprata/lobcast
- Repository: https://github.com/matteoprata/lobcast

## Overview

LOBCAST is a framework for benchmarking deep-learning models that predict stock-price trends from limit order book data. The main workflow configures a simulation, loads FI-2010 samples, selects a model, trains and evaluates it, then writes metrics and PDF reports. Separate capabilities support hyperparameter sweeps, sequential experiment plans, and optional Weights & Biases logging. The graph covers the documented model families and core learning, data, and reporting layers; relationships for unsampled modules are limited to README statements and SOURCE INDEX references.

Main entry points: [`src/lobcast.py`](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/lobcast.py) (Simulation), [`src/models/models_classes.py`](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/models_classes.py) (Model registry), [`src/utils/util_training.py`](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/util_training.py) (Learning engine), [`src/models/lobcast_model.py`](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/lobcast_model.py) (Model interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Simulation control"]
  node_cli["CLI entry<br/>[run.py]"]
  node_orchestrator["Simulation<br/>[lobcast.py]"]
  node_settings["Settings<br/>[settings.py]"]
  node_hyperparams["Hyperparameters"]
  node_generic["Shared utilities<br/>[utils_generic.py]"]
end

subgraph group_data["Dataset preparation"]
  node_dataset_picker["Dataset selection<br/>[utils_dataset.py]"]
  node_data_module["Data module<br/>[dataModule.py]"]
  node_fi_dataset["FI-2010 samples<br/>[FIDataBuilder.py]"]
end

subgraph group_models["Prediction models"]
  node_model_picker["Model selection<br/>[utils_models.py]"]
  node_model_registry["Model registry<br/>[models_classes.py]"]
  node_model_base["Model interface<br/>[lobcast_model.py]"]
  node_mlp["MLP<br/>[mlp.py]"]
  node_cnn1["CNN1<br/>[cnn1.py]"]
  node_cnn2["CNN2<br/>[cnn2.py]"]
  node_binctabl["BINCTABL<br/>[binctabl.py]"]
  node_binctabl_base["BINCTABL layers<br/>[base.py]"]
end

subgraph group_learning["Training and evaluation"]
  node_training_engine["Learning engine<br/>[util_training.py]"]
  node_learning_metrics["Learning metrics"]
  node_metric_log["Metric logging<br/>[metrics_log.py]"]
  node_callbacks["Model checkpointing<br/>[model_callbacks.py]"]
  node_report["PDF reports<br/>[report.py]"]
end

subgraph group_experiments["Experiment management"]
  node_hyper_search["Hyperparameter search<br/>[ultils_run.py]"]
  node_batch_setup["Batch experiment plan<br/>[setup01.py]"]
  node_batch_runner["Batch runner<br/>[run_batch.py]"]
end

node_user(("Researcher"))
node_wandb["Weights &amp; Biases"]
node_fi_files[("FI-2010 files")]

node_user -->|"starts run"| node_cli
node_cli -->|"creates simulation"| node_orchestrator
node_orchestrator -->|"configures"| node_settings
node_orchestrator -->|"sets parameters"| node_hyperparams
node_orchestrator -->|"selects dataset"| node_dataset_picker
node_dataset_picker -->|"uses module"| node_data_module
node_dataset_picker -->|"builds samples"| node_fi_dataset
node_fi_dataset -->|"reads files"| node_fi_files
node_orchestrator -->|"selects model"| node_model_picker
node_model_picker -->|"wraps for training"| node_training_engine
node_model_picker -->|"resolves model"| node_model_registry
node_model_registry -->|"registers"| node_mlp
node_model_registry -->|"registers"| node_cnn1
node_model_registry -->|"registers"| node_cnn2
node_model_registry -->|"registers"| node_binctabl
node_mlp -->|"extends"| node_model_base
node_cnn1 -->|"extends"| node_model_base
node_cnn2 -->|"extends"| node_model_base
node_binctabl -->|"extends"| node_model_base
node_binctabl -->|"uses layers"| node_binctabl_base
node_orchestrator -->|"trains and tests"| node_training_engine
node_training_engine -->|"computes metrics"| node_learning_metrics
node_training_engine -->|"records metrics"| node_metric_log
node_orchestrator -->|"configures checkpointing"| node_callbacks
node_orchestrator -->|"generates reports"| node_report
node_report -->|"reads JSON"| node_generic
node_orchestrator -->|"uses sweep utilities"| node_hyper_search
node_cli -->|"chooses configurations"| node_hyper_search
node_user -->|"starts batch"| node_batch_runner
node_batch_runner -->|"loads plan"| node_batch_setup
node_batch_runner -->|"runs configurations"| node_orchestrator
node_hyper_search -.->|"starts sweep"| node_wandb
node_orchestrator -.->|"logs metrics"| node_wandb

click node_cli "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/run.py"
click node_orchestrator "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/lobcast.py"
click node_settings "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/settings.py"
click node_hyperparams "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/hyper_parameters.py"
click node_generic "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/utils_generic.py"
click node_dataset_picker "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/utils_dataset.py"
click node_data_module "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/dataModule.py"
click node_fi_dataset "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/FI/FIDataBuilder.py"
click node_model_picker "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/utils_models.py"
click node_model_registry "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/models_classes.py"
click node_model_base "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/lobcast_model.py"
click node_mlp "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/mlp/mlp.py"
click node_cnn1 "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/cnn1/cnn1.py"
click node_cnn2 "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/cnn2/cnn2.py"
click node_binctabl "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/binctabl/binctabl.py"
click node_binctabl_base "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/binctabl/base.py"
click node_training_engine "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/util_training.py"
click node_learning_metrics "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/metrics_learning.py"
click node_metric_log "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/metrics_log.py"
click node_callbacks "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/model_callbacks.py"
click node_report "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/report.py"
click node_hyper_search "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/ultils_run.py"
click node_batch_setup "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/batch_experiments/setup01.py"
click node_batch_runner "https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/run_batch.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_cli,node_orchestrator,node_settings,node_hyperparams,node_generic toneBlue
class node_dataset_picker,node_data_module,node_fi_dataset,node_fi_files toneAmber
class node_model_picker,node_model_registry,node_model_base,node_mlp,node_cnn1,node_cnn2,node_binctabl,node_binctabl_base toneMint
class node_training_engine,node_learning_metrics,node_metric_log,node_callbacks,node_report toneRose
class node_hyper_search,node_batch_setup,node_batch_runner,node_user,node_wandb toneIndigo
```

## Components

### Simulation control

- [CLI entry](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/run.py): `src/run.py`
- [Simulation](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/lobcast.py): `src/lobcast.py`
- [Settings](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/settings.py): `src/settings.py`
- [Hyperparameters](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/hyper_parameters.py): `src/hyper_parameters.py`
- [Shared utilities](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/utils_generic.py): `src/utils/utils_generic.py`

### Dataset preparation

- [Dataset selection](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/utils_dataset.py): `src/data_preprocessing/utils_dataset.py`
- [Data module](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/dataModule.py): `src/data_preprocessing/dataModule.py`
- [FI-2010 samples](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/data_preprocessing/FI/FIDataBuilder.py): `src/data_preprocessing/FI/FIDataBuilder.py`

### Prediction models

- [Model selection](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/utils_models.py): `src/models/utils_models.py`
- [Model registry](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/models_classes.py): `src/models/models_classes.py`
- [Model interface](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/lobcast_model.py): `src/models/lobcast_model.py`
- [MLP](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/mlp/mlp.py): `src/models/mlp/mlp.py`
- [CNN1](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/cnn1/cnn1.py): `src/models/cnn1/cnn1.py`
- [CNN2](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/cnn2/cnn2.py): `src/models/cnn2/cnn2.py`
- [BINCTABL](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/binctabl/binctabl.py): `src/models/binctabl/binctabl.py`
- [BINCTABL layers](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/binctabl/base.py): `src/models/binctabl/base.py`

### Training and evaluation

- [Learning engine](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/util_training.py): `src/utils/util_training.py`
- [Learning metrics](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/metrics_learning.py): `src/metrics/metrics_learning.py`
- [Metric logging](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/metrics_log.py): `src/metrics/metrics_log.py`
- [Model checkpointing](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/models/model_callbacks.py): `src/models/model_callbacks.py`
- [PDF reports](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/metrics/report.py): `src/metrics/report.py`

### Experiment management

- [Hyperparameter search](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/utils/ultils_run.py): `src/utils/ultils_run.py`
- [Batch experiment plan](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/batch_experiments/setup01.py): `src/batch_experiments/setup01.py`
- [Batch runner](https://github.com/matteoprata/lobcast/blob/mini-LOBCAST/src/run_batch.py): `src/run_batch.py`

### Other components

- **Researcher**
- **Weights & Biases**
- **FI-2010 files**

## Connections

- Researcher → CLI entry: starts run (evidence: `README.md`)
- CLI entry → Simulation: creates simulation (evidence: `README.md`)
- Simulation → Settings: configures (evidence: `src/lobcast.py`)
- Simulation → Hyperparameters: sets parameters (evidence: `src/lobcast.py`)
- Simulation → Dataset selection: selects dataset (evidence: `src/lobcast.py`)
- Dataset selection → Data module: uses module (evidence: `src/data_preprocessing/utils_dataset.py`)
- Dataset selection → FI-2010 samples: builds samples (evidence: `src/data_preprocessing/utils_dataset.py`)
- FI-2010 samples → FI-2010 files: reads files (evidence: `src/data_preprocessing/FI/FIDataBuilder.py`)
- Simulation → Model selection: selects model (evidence: `src/lobcast.py`)
- Model selection → Learning engine: wraps for training (evidence: `src/models/utils_models.py`)
- Model selection → Model registry: resolves model (evidence: `src/models/utils_models.py`)
- Model registry → MLP: registers (evidence: `src/models/models_classes.py`)
- Model registry → CNN1: registers (evidence: `src/models/models_classes.py`)
- Model registry → CNN2: registers (evidence: `src/models/models_classes.py`)
- Model registry → BINCTABL: registers (evidence: `src/models/models_classes.py`)
- MLP → Model interface: extends (evidence: `src/models/mlp/mlp.py`)
- CNN1 → Model interface: extends (evidence: `src/models/cnn1/cnn1.py`)
- CNN2 → Model interface: extends (evidence: `src/models/cnn2/cnn2.py`)
- BINCTABL → Model interface: extends (evidence: `src/models/binctabl/binctabl.py`)
- BINCTABL → BINCTABL layers: uses layers (evidence: `src/models/binctabl/binctabl.py`)
- Simulation → Learning engine: trains and tests (evidence: `src/lobcast.py`)
- Learning engine → Learning metrics: computes metrics (evidence: `src/utils/util_training.py`)
- Learning engine → Metric logging: records metrics (evidence: `src/utils/util_training.py`)
- Simulation → Model checkpointing: configures checkpointing (evidence: `src/lobcast.py`)
- Simulation → PDF reports: generates reports (evidence: `src/lobcast.py`)
- PDF reports → Shared utilities: reads JSON (evidence: `src/metrics/report.py`)
- Simulation → Hyperparameter search: uses sweep utilities (evidence: `src/lobcast.py`)
- CLI entry → Hyperparameter search: chooses configurations (evidence: `README.md`)
- Researcher → Batch runner: starts batch (evidence: `README.md`)
- Batch runner → Batch experiment plan: loads plan (evidence: `src/run_batch.py`)
- Batch runner → Simulation: runs configurations (evidence: `README.md`)
- Hyperparameter search → Weights & Biases: starts sweep (evidence: `src/utils/ultils_run.py`)
- Simulation → Weights & Biases: logs metrics (evidence: `src/lobcast.py`)
