How 0xreisearch/hanabi-1 works
Main Components
• Input Data & Data Sources:
• Hourly Price Data (CSV files such as “hourly_data.csv” – as described in the README)
• Fear and Greed Index Data (CSV files within a folder like “fear_greed_data”, with examples provided in “example_data”)
• Data Preprocessing:
• The “data_preprocessor.py” script handles loading, normalization, and sequence creation including positional encoding.
• Transformer Model Core:
• “transformer_model.py” contains the architecture details – multiple transformer layers with multi-head self-attention, BatchNorm, leaky activations, specialized prediction heads (for Direction, Volatility, Price Change, and Spread).
• Training Pipeline:
• “train_model.py” manages the training process with configurable parameters (e.g., window size, hidden dimensions, learning rate, etc.).
• Training scripts (like “robust_model.sh”, “balance_test.sh”, “seed_test.sh” as mentioned in the README) orchestrate different training configurations.
• Prediction & Evaluation:
• “predict.py” is used for generating predictions.
• “evaluate_ensemble.py” supports ensemble evaluations and performance metrics.
• Data Output and Logging:
• Directories such as “trained_models/”, “logs/”, “evaluation/”, and “predictions/” (as mentioned in the README) store outputs, checkpoints, metrics, and visualizations.
Relationships and Interactions
• Data Sources feed into Data Preprocessing. The preprocessed data is then fed into the Transformer Architecture.
• The Transformer Model’s outputs branch out into different “heads” for each prediction type (classification for direction, regressions for volatility, price change, and spread).
• The Training Pipeline takes preprocessed data and feeds it into the model, applying techniques like Xavier initialization, BatchNorm, and gradient clipping.
• Once trained, the model checkpoints (saved in “trained_models/”) are used by the Prediction and Evaluation components.
• Evaluation and ensemble testing generate metrics and visualizations that are stored in “evaluation/” and “logs/”.
Architectural Patterns and Design Principles
• Modular Design: There is clear separation of concerns – data processing, model architecture, training, prediction, and evaluation are all handled by distinct modules.
• Configurable Parameters: The architecture highlights flexibility (e.g., adjustable window sizes, transformer layers, learning rate) making the system highly parameterizable.
• Ensemble and Robust Evaluation: Support for ensemble approaches and dynamic calibration of thresholds emphasize reliability in prediction.
Relevant Technologies and Libraries
• Core language: Python
• Frameworks/Libraries: Likely PyTorch or TensorFlow for transformer implementations (inferred from typical practices), though the exact one isn’t specified.
• Additional tools: Scripts for training (shell scripts) and likely use of visualization libraries for evaluation outputs (e.g., matplotlib or similar).
Elements
• Raw Data → Preprocessing → Transformer Model → Training → Prediction/Evaluation
• Data sources (input files)
• Processing components (data_preprocessor.py)
• Core model components (transformer_model.py with sub-heads for each prediction type)
• Execution scripts (train_model.py, predict.py, evaluation scripts) and output/storage (trained_models, logs, predictions)
• Optionally, annotate connections with key parameters (e.g., window sizes, hidden dimensions) and details like “BatchNorm, Xavier, Gradient clipping.”