CrossAxis is a production-grade, end-to-end quantitative portfolio execution framework designed for cross-sectional stock selection. By bridging cutting-edge Spatio-Temporal Graph Neural Networks (STGNNs) with strict financial causal execution pipelines, the framework automates the entire loop of streaming data alignment, multi-view topological Alpha mining, Rank IC loss optimization, and double-track backtesting.
⚠️ Notice: This repository serves as a production-hardened deployment engine. All idealized academic benchmark assumptions (such as offline batch processing or hindsight filtering) have been systematically decoupled to strictly enforce point-in-time information barriers and streaming causality.
The physical layout strictly adheres to institutional software engineering hygiene, enforcing a robust separation between immutable code logic and dynamic data states as shown below (matching the live environment topology):
CrossAxis/
├── configs/
│ └── default.yaml # Global production configuration (Data scopes, model hyperparams, transaction costs)
├── data/ # ⚠️ Added to .gitignore (Never commit processed data to GitHub)
│ ├── processed/ # Production middleware generated via cross-sectional alignment
│ │ ├── normalized_adj_matrix.npy # Symmetrically normalized prior graph matrix
│ │ ├── st_grad_signals.csv # Point-in-time cross-sectional alpha scores generated via inference
│ │ └── stock_dataset.npz # Compact feature/label tensor tensors blocked from timeline leakage
│ └── raw/ # Multi-source raw market data repository
│ ├── BasicMaterials/ # Historical daily bars (Open, High, Low, Close, Volume) sorted by sectors
│ ├── Energy/
│ ├── Healthcare/
│ ├── Industrials/
│ ├── Technology/
│ ├── all_close.csv # Underlying price matrix for rolling calculations
│ ├── cluster_results.csv # Deep behavioral feature clustering records defining graph concepts
│ └── stock_order.npy # Immutable cross-sectional index sequence ensuring alignment geometry
├── models/
│ └── saved/ # ⚠️ Added to .gitignore (Saves trained network weights)
│ └── st_grad_best_model.pth # Best model state dictionary driven exclusively by Rank IC metrics
├── scripts/ # Top-level operational execution scripts
│ ├── run_backtest.py # Awakens Backtrader broker engine for cross-sectional rotation backtests
│ └── run_inference.py # Batch streaming inference and alpha scoring utility
├── src/ # Core source package
│ ├── data/ # Streaming feature factories and alignment data streams
│ │ ├── feature_factory.py # Alpha assembly workshop computing 24-dimensional Quant indicators
│ │ ├── loader.py # Customized PyTorch Dataloader optimized for 4D spatio-temporal tensors
│ │ └── pipeline.py # Cross-sectional transformation and forward-return label generator
│ ├── models/ # Neural topological operators and tensor flow pipelines
│ │ ├── attention.py # Multi-View Cross-Attention (MVCA) optimized for hardware parallelism
│ │ ├── graph_conv.py # Bidirectional Diffusion Graph Convolution (BDGC) operator
│ │ └── st_grad.py # Main network architecture definition and forward execution stream
│ └── trainer.py # Quantitative Alpha optimizer embedded with customized ICLoss
├── main.py # Main orchestration entrypoint (Controls data, graph, and train routines)
├── requirements.txt # Rigid software environment dependency manifest
└── README.md # Technical framework documentation
This framework (CrossAxis) serves as the production-hardened deployment extension of the core architecture accepted by Expert Systems with Applications (ESWA) for ST-GRAD: Multi-View Cross-Attention and Bidirectional Diffusion for Stock Trend Prediction.
Rather than duplicating static academic benchmarks, CrossAxis explores the scalability and generalizability of spatio-temporal graph operators under the constraints of live asset management systems with rigorous point-in-time info barriers. To bridge the gap between theoretical modeling and live execution, the framework implements two fundamental architectural adaptions:
- Academic Benchmark Setting: In the research phase, to perform rigorous controlled-variable evaluations against baseline models on standardized static datasets, the model follows a classical Global Transductive Paradigm. Features are normalized using global training statistics to maximize the graph network's absolute capacity for extracting long-term spatio-temporal representations across full asset life cycles.
-
Production Engineering Adaptation:In an actual asset management environment, market data flows sequentially as a daily streaming feed. To ensure robust Inductive Generalization, the preprocessing pipeline (src/data/pipeline.py) abandons longitudinal data pooling in favor of a strict Point-in-Time Cross-Sectional Z-Score Transformation. At any historical step
$T$ , the system standardizes features exclusively across the spatial asset dimension (axis=2), ensuring zero information leakage across the timeline and total compliance with streaming causality.
- Academic Benchmark Setting: Rooted in a computer vision and pattern recognition paradigm, the journal paper evaluates the model's capacity to capture nonlinear trend reversals. It treats forecasting as a structured state classification problem driven by BCELoss and verified via macro classification metrics (F1-Score/AUC).
-
Production Engineering Adaptation: To feed signals directly into a live portfolio construction module, the execution layer undergoes a complete target reformulating. The smoothed classification targets are migrated into the feature space as momentum factors. The training target is redefined as pure, raw
$N$ -day Forward Returns. Furthermore, src/trainer.py completely discards classification losses, implementing a customized ICLoss optimizer driven by cross-sectional covariance to maximize the Spearman Rank IC, mapping directly to multi-factor long-short ranking logic.
To process the multi-scale temporal patches required by the Feature-Spatial view (DS-View), the framework entirely eliminates expensive Python for loops. By restructuring high-dimensional tensor geometries via .contiguous().view(), the patch-wise max, min, and mean aggregations are executed entirely in parallel on the GPU. This ensures physical memory continuity, completely eliminating the fragmentary memory overheads caused by frequent tensor mutations (permute) and mitigating the risk of CuDNN stack overrun crashes (0xC0000409) under dense training workloads.
- Top-K Ranking Strategy: Integrates natively with Backtrader to construct a rigorous cross-sectional rotation model. Every 5 trading days, the engine slices the cross-sectional score matrix generated by the GNN model, isolates the top 20% alpha-dominant stocks, and executes an equal-weight portfolio rebalancing.
- Hardened Friction Models: Incorporates a strict double-track benchmark verification. The model portfolio runs alongside an EqualWeightBenchmark (the market consensus). Every trade enforces a 0.02% (2 bps) round-trip commission and slippage friction fee, ensuring that the extracted outperformance represents pure, tradeable Net Alpha rather than theoretical backtest artifacts.
pip install -r requirements.txtComputes the 24 institutional-grade price-volume, oscillator, and volatility features via AlphaFeatureFactory and executes point-in-time cross-sectional transformation:
python main.py --mode dataActivates the customized ICLoss optimization sequence to train the graph neural network under cross-sectional ranking constraints:
python main.py --mode trainGenerates the forward-looking alpha matrices and triggers the Backtrader engine to execute the cross-sectional allocation strategy:
python scripts/run_inference.py
python scripts/run_backtest.pyUnder a strict rolling out-of-sample forward evaluation on the 50 major large-cap asset universe (fully factoring in the 2 bps double-sided friction cost), the CrossAxis framework delivers the following metrics:
| Evaluation Metric | Market Benchmark (Equal Weight) | CrossAxis Engine (Top 20% Active Rotation) |
|---|---|---|
| Total Return | 4.03% | 25.71% |
| Sharpe | 0.2817 | 1.5037 |
| Max Drawdown | -23.35% | -23.71% |
| 🌟 Net Alpha | — | +21.68% |