ReMoMa is a research framework for classifying future limit order book price movements as down (0), flat (1), or up (2). Graph neural networks and a recurrent sparse spatio-temporal model share preprocessing, training, and evaluation in one Python package.
The complete CSCO pipeline builds normalized mutual information (NMI) matrices and Triangulated Maximally Filtered Graphs (TMFGs) from each split's training dates, then trains and evaluates the selected models. Relative-lag NMI is the default; full pairwise NMI is also available.
Developed collaboratively by NrdAnd and SimoSaimon. Both contributors' commits and authorship are preserved in Git history.
| Family | model.type values |
Configuration |
|---|---|---|
| GNN | gcn, gat, sage, cgnn, cgnn_sage, cgnn_gat, stgcn, stgcn_sage, stgcn_gat |
GNN default |
| Recurrent | recurrent_sparse_sthnn |
Recurrent by-file |
The recurrent model applies shared graph messages and GRU updates to feature/lag nodes. Both families are graph-based and available on main; model selection requires no branch change. The complete pipeline supplies matched experiment settings; the individual presets use different lag depths.
Use Python 3.10 or 3.11 and run commands from the repository root. See setup for CPU/CUDA installation.
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
python scripts/check_repository.pyPlace the five original CSCO ten-level orderbook files listed in the pipeline guide in data/raw/. Raw market data is not included. Once the files are present, inspect the fixed or walk-forward plan:
python scripts/run_pipeline.py
python scripts/run_pipeline.py --mode walk_forwardThese commands inspect filenames and settings without reading raw contents or training. Run the complete fixed-split experiment on a compute host with:
python scripts/run_pipeline.py --runThe default NMI backend is auto; use --nmi-backend cpu or cuda to select it explicitly. GPU NMI requires the optional CuPy installation described in the pipeline guide. Model training selects CUDA independently through PyTorch.
For individual preprocessing, model selection, training, and checkpoint evaluation commands, see usage. Those commands accept a supplied graph; the complete pipeline constructs training-only graphs automatically.
src/remoma/ Shared Python package
dataset/ Labels, binning, indexed/materialized features, preprocessing
graph/ NMI estimation, graph validation, and TMFG construction
models/gnn/ Nine graph-convolution architectures
models/recurrent/ Recurrent sparse STHNN implementation
pipeline/ Fixed-split and walk-forward experiment orchestration
training/ Trainer, metrics, decision thresholds
utils/ Caches, artifact locks, checkpoint provenance
scripts/ Training, evaluation, experiments, and analysis commands
configs/ GNN, recurrent, and complete-pipeline configurations
data/graphs/ Historical reference adjacency matrices
docs/ User guides, technical reference, and research reports
notebooks/ Exploratory LOB, GLASSO, and TMFG notebooks
tests/ Synthetic integration and regression tests
deploy/ CPU batch-execution container
archive/legacy/ Historical prototypes outside the supported pipeline
gnn/ Compatibility entry points for previous commands
Start with setup and the complete pipeline. Use the architecture, data contract, and configuration reference for technical details.
The documentation index also covers individual commands, development, deployment, integration history, and historical reports.
Results from earlier experiments are preserved in the GNN report and recurrent model report. The experiment archive describes their evaluation protocols and scope. Software checks are documented in the validation record.
Original code and documentation: GNU Affero General Public License v3.0 only (AGPL-3.0-only). Copyright 2026 Andrea Nardi and Simone Somazzi.
Bundled visualization assets retain their own licenses; see third-party notices. Raw LOBSTER data is not included or licensed by this repository.