Machine Learning¶

GNN Predictor¶

Temporal Graph Neural Network predictor for spectral metric evolution.

Replaces the flat LSTM with a GCN encoder that operates on the actual interbank graph at each timestep, producing graph-level embeddings that feed into a temporal LSTM for spectral metric forecasting.

Architecture: GCNConv layers → global_mean_pool → LSTM → FC → [λ₂, gap, ρ]

class scr_financial.ml.gnn_predictor.GNNEncoder(in_channels, hidden_channels, num_gcn_layers=3, dropout=0.1)[source]¶

Bases: Module

Multi-layer GCN that produces a graph-level embedding.

Parameters:

in_channels (int)
hidden_channels (int)
num_gcn_layers (int)
dropout (float)

forward(x, edge_index, edge_weight=None, batch=None)[source]¶

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:

x (Tensor)
edge_index (Tensor)
edge_weight (Tensor | None)
batch (Tensor | None)

Return type:

Tensor

class scr_financial.ml.gnn_predictor.TemporalGNN(node_features, hidden_dim=64, output_dim=3, num_gcn_layers=3, num_lstm_layers=2, dropout=0.1)[source]¶

Bases: Module

GNN encoder + LSTM for temporal graph sequences → spectral predictions.

Parameters:

node_features (int)
hidden_dim (int)
output_dim (int)
num_gcn_layers (int)
num_lstm_layers (int)
dropout (float)

forward(graph_sequences)[source]¶

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:: graph_sequences (List[List[Data]])
Return type:: Tensor

count_parameters()[source]¶

Return type:: int

class scr_financial.ml.gnn_predictor.GNNPredictor(seq_len=10, hidden_dim=64, num_gcn_layers=3, num_lstm_layers=2, dropout=0.1)[source]¶

Bases: object

Drop-in replacement for SCGPredictor using a temporal GNN.

Supports a progress_callback(epoch, total_epochs, train_loss, test_loss) for real-time UI updates during training.

Parameters:

seq_len (int)
hidden_dim (int)
num_gcn_layers (int)
num_lstm_layers (int)
dropout (float)

static extract_graph_snapshot(sim)[source]¶

Extract graph snapshot (node features + edges + spectral targets) from sim.

Return type:: Dict[str, Any]

static extract_features(sim, spectral_fn)[source]¶

Compatibility shim — extract scalar features like SCGPredictor.

Return type:: Dict[str, float]

train(snapshots, epochs=200, lr=0.003, test_fraction=0.2, progress_callback=None)[source]¶

Train the temporal GNN. Returns final train loss.

Parameters:

progress_callback (callable(epoch, total_epochs, train_loss, test_loss_or_None)) – Called every 5 epochs for UI progress updates.
snapshots (List[Dict[str, Any]])
epochs (int)
lr (float)
test_fraction (float)

Return type:

float

predict(recent_snapshots, steps=20)[source]¶

Autoregressively predict spectral metrics forward.

Parameters:

recent_snapshots (List[Dict[str, Any]])
steps (int)

Return type:

List[Dict[str, float]]

SCG Predictor¶

SCG-aware predictor for spectral metric evolution.

Wraps the existing LSTMPredictor to forecast spectral features (algebraic connectivity, spectral gap, spectral radius) from stochastic ABM trajectories.

class scr_financial.ml.scg_predictor.SCGPredictor(seq_len=10, hidden_dim=32, num_layers=2)[source]¶

Bases: object

Train an LSTM on ABM-generated spectral trajectories and predict forward.

Parameters:

seq_len (int)
hidden_dim (int)
num_layers (int)

static extract_features(sim, spectral_fn)[source]¶

Extract one feature vector from the current simulation state.

Parameters:

sim (BankingSystemSimulation)
spectral_fn (callable returning spectral data dict (eigenvalues, gap_size, etc.))

Return type:

Dict[str, float]

build_training_data(feature_history)[source]¶

Convert a list of per-step feature dicts into (X, y) arrays.

X: shape (samples, seq_len, n_features) y: shape (samples, n_targets)

Parameters:: feature_history (List[Dict[str, float]])
Return type:: Tuple[ndarray, ndarray]

train(feature_history, epochs=60, lr=0.001, test_fraction=0.2)[source]¶

Train the LSTM with chronological train/test split. Returns final train loss.

Parameters:

feature_history (List[Dict[str, float]])
epochs (int)
lr (float)
test_fraction (float)

Return type:

float

predict(recent_features, steps=20)[source]¶

Autoregressively predict spectral metrics forward.

Parameters:

recent_features (list of dicts) – Must have at least seq_len entries.
steps (int) – Number of future steps to predict.

Return type:

list of dicts with keys from TARGET_NAMES

Base Predictors¶

Predictors for financial network analysis.

This module provides predictors for forecasting network evolution and market indicators.

class scr_financial.ml.predictors.NetworkPredictor(method='rf')[source]¶

Bases: object

Predictor for financial network evolution.

This class implements methods for predicting how the financial network will evolve over time based on historical data and external factors.

Parameters:: method (str)

method¶: Prediction method identifier.

model¶: Underlying sklearn estimator.

scaler_X¶: Feature scaler.

scaler_y¶: Target scaler.

__init__(method='rf')[source]¶

Initialize the network predictor.

Parameters:: method (str) – Prediction method (‘rf’ for Random Forest, ‘gb’ for Gradient Boosting, ‘elastic’ for Elastic Net).
Raises:: ValueError – If method is not one of the supported values.
Return type:: None

prepare_features(network_history, system_indicators)[source]¶

Prepare features for network prediction.

Parameters:

network_history (List[Dict]) – List of network states over time.
system_indicators (DataFrame) – DataFrame of system-wide indicators.

Returns:

Tuple containing (X, y) where X is features and y is target values.

Return type:

Tuple[ndarray, ndarray]

fit(X, y)[source]¶

Fit the predictor to training data.

Parameters:

X (ndarray) – Feature matrix.
y (ndarray) – Target values.

Return type:

None

predict(X)[source]¶

Make predictions with the fitted model.

Parameters:: X (ndarray) – Feature matrix.
Returns:: Predicted values.
Raises:: RuntimeError – If fit() has not been called yet.
Return type:: ndarray

predict_network_evolution(current_state, system_forecast, steps=10)[source]¶

Predict network evolution over multiple time steps.

Parameters:

current_state (Dict) – Current network state.
system_forecast (DataFrame) – Forecast of system indicators.
steps (int) – Number of steps to predict.

Returns:

List of predicted network states.

Return type:

List[Dict]

class scr_financial.ml.predictors.MarketPredictor(input_dim, hidden_dim, output_dim, num_layers=2)[source]¶

Bases: object

Predictor for market indicators.

This class implements a deep learning model for predicting market indicators based on historical data and network features.

Parameters:

input_dim (int)
hidden_dim (int)
output_dim (int)
num_layers (int)

model¶: Underlying LSTM model.

scaler_X¶: Feature scaler.

scaler_y¶: Target scaler.

seq_length¶: Default sequence length used during prepare_sequences.

__init__(input_dim, hidden_dim, output_dim, num_layers=2)[source]¶

Initialize the market predictor.

Parameters:

input_dim (int) – Input dimension (number of features).
hidden_dim (int) – Hidden dimension for LSTM.
output_dim (int) – Output dimension (number of indicators to predict).
num_layers (int) – Number of LSTM layers.

Return type:

None

prepare_sequences(features, targets, seq_length)[source]¶

Prepare sequences for LSTM training.

Parameters:

features (ndarray) – Feature matrix of shape [n_samples, n_features].
targets (ndarray) – Target matrix of shape [n_samples, n_targets].
seq_length (int) – Length of sequences.

Returns:

Tuple (X, y) where X has shape [n_sequences, seq_length, n_features] and y has shape [n_sequences, n_targets].

Return type:

Tuple[ndarray, ndarray]

train(X, y, batch_size=32, epochs=100, learning_rate=0.001, device='cpu')[source]¶

Train the market predictor.

Parameters:

X (ndarray) – Sequence data of shape [n_sequences, seq_length, n_features].
y (ndarray) – Target data of shape [n_sequences, n_targets].
batch_size (int) – Batch size for training.
epochs (int) – Number of training epochs.
learning_rate (float) – Learning rate for optimizer.
device (str) – Device to train on (‘cpu’ or ‘cuda’).

Returns:

Dictionary containing training history.

Return type:

Dict

predict(features, device='cpu')[source]¶

Make predictions with the trained model.

Parameters:

features (ndarray) – Feature matrix of shape [seq_length, n_features] or [n_features].
device (str) – Device to run prediction on.

Returns:

Predicted values.

Raises:

RuntimeError – If prepare_sequences() has not been called yet.

Return type:

ndarray

class scr_financial.ml.predictors.LSTMPredictor(input_dim, hidden_dim, output_dim, num_layers=2)[source]¶

Bases: Module

LSTM-based predictor for time series forecasting.

Parameters:

input_dim (int)
hidden_dim (int)
output_dim (int)
num_layers (int)

hidden_dim¶: Hidden dimension for LSTM.

num_layers¶: Number of LSTM layers.

lstm¶: LSTM layer.

fc¶: Fully connected output layer.

__init__(input_dim, hidden_dim, output_dim, num_layers=2)[source]¶

Initialize the LSTM predictor.

Parameters:

input_dim (int) – Input dimension (number of features).
hidden_dim (int) – Hidden dimension for LSTM.
output_dim (int) – Output dimension (number of indicators to predict).
num_layers (int) – Number of LSTM layers.

Return type:

None

forward(x)[source]¶

Forward pass through the model.

Note

Hidden states are re-initialised to zeros on every forward call (stateless inference).

Parameters:: x (Tensor) – Input tensor of shape [batch_size, seq_length, input_dim].
Returns:: Output tensor of shape [batch_size, output_dim].
Return type:: Tensor

Sentiment Model¶

Sentiment analysis model for financial market data.

This module provides an LSTM-based model for analyzing market sentiment from financial time series data.

class scr_financial.ml.sentiment_model.LSTMSentimentModel(input_dim, hidden_dim, num_layers=2, output_dim=1, dropout=0.2)[source]¶

Bases: Module

LSTM-based sentiment analysis model for financial time series.

Parameters:

input_dim (int)
hidden_dim (int)
num_layers (int)
output_dim (int)
dropout (float)

hidden_dim¶: Dimension of hidden state.

num_layers¶: Number of LSTM layers.

lstm¶: LSTM layer.

dropout¶: Dropout layer.

fc¶: Fully connected output layer.

__init__(input_dim, hidden_dim, num_layers=2, output_dim=1, dropout=0.2)[source]¶

Initialize the LSTM sentiment model.

Parameters:

input_dim (int) – Number of input features.
hidden_dim (int) – Dimension of hidden state.
num_layers (int) – Number of LSTM layers.
output_dim (int) – Dimension of output (typically 1 for sentiment score).
dropout (float) – Dropout probability.

Return type:

None

forward(x)[source]¶

Forward pass through the model.

Note

Hidden states are re-initialised to zeros on every forward call (stateless inference).

Parameters:: x (Tensor) – Input tensor of shape [batch_size, seq_len, input_dim].
Returns:: Output tensor of shape [batch_size, output_dim].
Return type:: Tensor

scr_financial.ml.sentiment_model.prepare_sentiment_data(data, target, seq_length, train_split=0.8)[source]¶

Prepare data for sentiment model training.

Parameters:

data (ndarray) – Feature data of shape [n_samples, n_features].
target (ndarray) – Target values of shape [n_samples].
seq_length (int) – Length of sequence for LSTM.
train_split (float) – Proportion of data to use for training.

Returns:

Tuple containing (X_train, y_train, X_test, y_test).

Raises:

ValueError – If seq_length is not positive or train_split is outside (0, 1).

Return type:

Tuple[Tensor, Tensor, Tensor, Tensor]

scr_financial.ml.sentiment_model.train_sentiment_model(model, X_train, y_train, X_test, y_test, batch_size=64, epochs=100, learning_rate=0.001, device='cpu')[source]¶

Train the sentiment model.

Parameters:

model (Module) – The model to train.
X_train (Tensor) – Training features.
y_train (Tensor) – Training targets.
X_test (Tensor) – Test features.
y_test (Tensor) – Test targets.
batch_size (int) – Batch size for training.
epochs (int) – Number of training epochs.
learning_rate (float) – Learning rate for optimizer.
device (str) – Device to train on (‘cpu’ or ‘cuda’).

Returns:

Dictionary containing training history with keys 'train_loss' and 'test_loss'.

Return type:

Dict

scr_financial.ml.sentiment_model.predict_sentiment(model, features, seq_length, device='cpu')[source]¶

Predict sentiment score from features.

Parameters:

model (Module) – Trained sentiment model.
features (ndarray) – Input features of shape [n_features] or [seq_length, n_features].
seq_length (int) – Length of sequence for LSTM.
device (str) – Device to run prediction on.

Returns:

Predicted sentiment score.

Raises:

ValueError – If features has fewer than seq_length time steps.

Return type:

float