pynnlf 0.2.2__py3-none-any.whl

pynnlf/scaffold/models/README_models.md

@@ -0,0 +1,61 @@
+# Models folder (auto-discovery)
+
+This folder is **user-editable**. You can add new forecasting models here without editing any package code or config mappings.
+
+## Add a new model (no config edits)
+
+1) Create a new Python file in this folder named like:
+
+- `m19_my_model.py` (example)
+
+2) The file name **must start** with the model ID prefix (`m19_`).
+
+3) Inside that file, define **two functions** whose names match the **file stem** (file name without `.py`).
+
+Example file: `m19_my_model.py`
+
+Required functions:
+
+- `train_model_m19_my_model(hyperparameter, train_df_X, train_df_y, forecast_horizon=None)`
+- `produce_forecast_m19_my_model(model, train_df_X, test_df_X, train_df_y=None, forecast_horizon=None)`
+
+## Add hyperparameters (YAML)
+
+Hyperparameters live in:
+
+- `hyperparameters.yaml`
+
+The top-level key **must equal** the model file stem.
+
+Example:
+
+```yaml
+m19_my_model:
+  hp1:
+    bias: 0.0
+  hp2:
+    bias: 5.0
+```
+
+## Run the model (4-key spec only)
+
+Edit `../specs/experiment.yaml`:
+
+```yaml
+dataset: ds0
+forecast_horizon: fh1
+model: m19
+hyperparameter: hp1
+```
+
+Then run:
+
+```bash
+python -c "import pynnlf; pynnlf.run_experiment('PATH_TO_WORKSPACE/specs/experiment.yaml')"
+```
+
+## Rules / gotchas
+
+- Auto-discovery requires **exactly one** match for a model ID. If you have both `m19_a.py` and `m19_b.py`, the runner will raise an error asking you to rename.
+- Your model outputs can be `pd.Series` or 1D `np.ndarray`. The engine will align outputs to timestamps.
+- Keep model files import-safe: include all required imports inside your model file.

pynnlf/scaffold/models/hyperparameters.yaml

@@ -0,0 +1,264 @@
+m1_naive:
+  hp1:
+    hyperparameter_1: No hyperparameter
+
+m2_snaive:
+  hp1:
+    days: 1
+  hp2:
+    days: 7
+
+m3_ets:
+  hp1:
+    trend: false
+    damped_trend: false
+    seasonal_periods_days: null
+  hp2:
+    trend: false
+    damped_trend: false
+    seasonal_periods_days: 1
+  hp3:
+    trend: add
+    damped_trend: false
+    seasonal_periods_days: null
+
+m4_arima:
+  hp1:
+    p: 1
+    d: 0
+    q: 1
+  hp2:
+    p: 1
+    d: 1
+    q: 1
+
+m5_sarima:
+  hp1:
+    p: 1
+    d: 0
+    q: 1
+    P: 0
+    D: 1
+    Q: 0
+    seasonal_period_days: 1
+  hp2:
+    p: 1
+    d: 0
+    q: 1
+    P: 0
+    D: 1
+    Q: 0
+    seasonal_period_days: 7
+
+m6_lr:
+  hp1:
+    num_features: 50
+
+m7_ann:
+  hp1:
+    seed: 99
+    hidden_size: 10
+    activation_function: relu
+    learning_rate: 0.001
+    solver: adam
+    epochs: 500
+  hp2:
+    seed: 99
+    hidden_size: 10
+    activation_function: relu
+    learning_rate: 0.01
+    solver: adam
+    epochs: 500
+
+m8_dnn:
+  hp1:
+    seed: 1
+    n_hidden: 3
+    hidden_size: 10
+    activation_function: relu
+    learning_rate: 0.001
+    solver: adam
+    epochs: 500
+  hp2:
+    seed: 1
+    n_hidden: 3
+    hidden_size: 10
+    activation_function: relu
+    learning_rate: 0.01
+    solver: adam
+    epochs: 500
+  hp3:
+    seed: 1
+    n_hidden: 4
+    hidden_size: 10
+    activation_function: relu
+    learning_rate: 0.01
+    solver: adam
+    epochs: 500
+
+m9_rt:
+  hp1:
+    seed: 1
+    max_depth: 3
+    min_samples_split: 2
+    min_samples_leaf: 1
+    max_features: sqrt
+  hp2:
+    seed: 1
+    max_depth: 30
+    min_samples_split: 2
+    min_samples_leaf: 1
+    max_features: sqrt
+  hp3:
+    seed: 1
+    max_depth: 15
+    min_samples_split: 2
+    min_samples_leaf: 1
+    max_features: sqrt
+
+m10_rf:
+  hp1:
+    seed: 1
+    n_estimators: 100
+    max_depth: 3
+    min_samples_split: 2
+    min_samples_leaf: 1
+  hp2:
+    seed: 1
+    n_estimators: 50
+    max_depth: 3
+    min_samples_split: 2
+    min_samples_leaf: 1
+
+m11_svr:
+  hp1:
+    seed: 1
+    kernel: rbf
+    C: 100
+    gamma: 0.001
+    epsilon: 0.3
+
+m12_rnn:
+  hp1:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 2
+    learning_rate: 0.001
+  hp2:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 100
+    learning_rate: 0.001
+
+m13_lstm:
+  hp1:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 2
+    learning_rate: 0.001
+  hp2:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 100
+    learning_rate: 0.001
+
+m14_gru:
+  hp1:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 2
+    learning_rate: 0.001
+  hp2:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    epochs: 100
+    learning_rate: 0.001
+
+m15_transformer:
+  hp1:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    nhead: 4
+    epochs: 2
+    learning_rate: 0.001
+  hp2:
+    seed: 1
+    input_size: 1
+    hidden_size: 64
+    num_layers: 1
+    output_size: 1
+    batch_size: 4096
+    nhead: 4
+    epochs: 100
+    learning_rate: 0.001
+
+m16_prophet:
+  hp1:
+    seed: 1
+    seasonality_prior_scale: 10
+    seasonality_mode: additive
+    weekly_seasonality: true
+    daily_seasonality: true
+    growth: linear
+
+m17_xgb:
+  hp1:
+    xgb_seed: 1
+    n_estimators: 200
+    learning_rate: 0.1
+    max_depth: 6
+    subsample: 0.8
+    colsample_bytree: 0.8
+  hp2:
+    xgb_seed: 1
+    n_estimators: 100
+    learning_rate: 0.1
+    max_depth: 3
+    subsample: 0.8
+    colsample_bytree: 0.8
+
+m18_nbeats:
+  hp1:
+    seed: 1
+    hidden_size: 64
+    num_layers: 1
+    num_blocks: 3
+    output_size: 1
+    epochs: 2
+    lr: 0.001
+  hp2:
+    seed: 1
+    hidden_size: 64
+    num_layers: 1
+    num_blocks: 3
+    output_size: 1
+    epochs: 100
+    lr: 0.001

pynnlf/scaffold/models/m10_rf.py

@@ -0,0 +1,65 @@
+# IMPORT IMPORTANT LIBRARY
+from sklearn.ensemble import RandomForestRegressor
+import pandas as pd
+
+def train_model_m10_rf(hyperparameter, train_df_X, train_df_y):
+    ''' Train and test a random forest model for point forecasting. 
+        
+    Args:
+        hyperparameter (df) : hyperparameter value of the model consisting of number of features
+        train_df_X (df) : features matrix for training
+        train_df_y (df) : target matrix for training
+
+    
+    Returns:
+        model (model) : trained model with all features
+    '''
+    
+    #UNPACK HYPERPARAMETER
+    seed = int(hyperparameter['seed'])
+    n_estimators = int(hyperparameter['n_estimators'])
+    max_depth = int(hyperparameter['max_depth'])
+    min_samples_split = int(hyperparameter['min_samples_split'])
+    min_samples_leaf = int(hyperparameter['min_samples_leaf'])
+    
+    
+    #TRAIN MODEL
+    rf = RandomForestRegressor(
+        n_estimators=n_estimators,       # number of trees
+        max_depth=max_depth,           # maximum depth of a tree
+        min_samples_split=min_samples_split,    # min samples to split a node
+        min_samples_leaf=min_samples_leaf,     # min samples in a leaf
+        random_state=seed
+    )
+    
+    rf.fit(train_df_X, train_df_y) # fit the model to the training data
+  
+    # PACK MODEL
+    model = {"rf": rf}
+  
+
+    return model
+
+def produce_forecast_m10_rf(model, train_df_X, test_df_X):
+    """Create forecast at the train and test set using the trained model
+
+    Args:
+        model (dictionary): all parameters of the trained model
+        train_df_X (df): predictors of train set
+        test_df_X (df): predictors of test set
+
+    Returns:
+        train_df_y_hat (df) : forecast result at train set
+        test_df_y_hat (df) : forecast result at test set
+        
+    """
+    
+    # UNPACK MODEL
+    rf = model['rf']
+    
+    # PRODUCE FORECAST
+    train_df_y_hat = pd.DataFrame(rf.predict(train_df_X), index = train_df_X.index, columns = ['y_hat'])
+    test_df_y_hat = pd.DataFrame(rf.predict(test_df_X), index = test_df_X.index, columns = ['y_hat'])
+    
+    return train_df_y_hat, test_df_y_hat
+

pynnlf/scaffold/models/m11_svr.py

@@ -0,0 +1,53 @@
+def train_model_m11_svr(hyperparameter, train_df_X, train_df_y):
+    ''' Train and test a linear model for point forecasting. 
+        
+    Args:
+        hyperparameter (df) : hyperparameter value of the model consisting of number of features
+        train_df_X (df) : features matrix for training
+        train_df_y (df) : target matrix for training
+
+    
+    Returns:
+        model (model) : trained model with all features
+    '''
+    
+    from sklearn.svm import SVR
+    
+    #UNPACK HYPERPARAMETER
+    seed = hyperparameter['seed'] #seem we can't use this using sklearn
+    kernel = hyperparameter['kernel']
+    C = hyperparameter['C']
+    gamma = hyperparameter['gamma']
+    epsilon = hyperparameter['epsilon']
+        
+    #TRAIN MODEL
+    train_df_y = train_df_y.values.ravel()  # Flatten the target array if necessary
+    svr = SVR(kernel=kernel, C=C, gamma=gamma, epsilon=epsilon)
+    svr.fit(train_df_X, train_df_y)
+  
+    # PACK MODEL
+    model = {"svr": svr}
+  
+
+    return model
+
+def produce_forecast_m11_svr(model, train_df_X, test_df_X):
+    """Create forecast at the train and test set using the trained model
+
+    Args:
+        model (dictionary): all parameters of the trained model
+        train_df_X (df): predictors of train set
+        test_df_X (df): predictors of test set
+
+    Returns:
+        train_df_y_hat (df) : forecast result at train set
+        test_df_y_hat (df) : forecast result at test set
+        
+    """
+    
+    svr = model['svr']
+    train_df_y_hat = svr.predict(train_df_X)
+    test_df_y_hat = svr.predict(test_df_X)
+
+    return train_df_y_hat, test_df_y_hat
+

pynnlf/scaffold/models/m12_rnn.py

@@ -0,0 +1,152 @@
+# IMPORT IMPORTANT LIBRARY
+import time
+import pandas as pd
+import numpy as np
+import random
+import os
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, TensorDataset
+from pynnlf.model_utils import separate_lag_and_exogenous_features
+
+def train_model_m12_rnn(hyperparameter, train_df_X, train_df_y):
+    ''' Train and test an RNN model for point forecasting. 
+    Essentially we use the RNN block to learn the temporal patterns of the time series, 
+    and then use a fully connected layer to learn the relationship between the lag features.
+    We take the last hidden state of the RNN as the output, and concatenate it with the exogenous features 
+    (like calendar) to make the final prediction using a fully connected layer.
+    '''
+
+    # UNPACK HYPERPARAMETER
+    seed = int(hyperparameter['seed'])
+    input_size = int(hyperparameter['input_size'])
+    hidden_size = int(hyperparameter['hidden_size'])
+    num_layers = int(hyperparameter['num_layers'])
+    output_size = int(hyperparameter['output_size'])
+    batch_size = int(hyperparameter['batch_size'])
+    epochs = int(hyperparameter['epochs'])
+    learning_rate = hyperparameter['learning_rate']
+
+    # DEFINE MODEL AND TRAINING FUNCTION
+    class RNNModel(nn.Module):
+        def __init__(self, input_size, hidden_size, num_layers, exog_size, output_size=1):
+            super(RNNModel, self).__init__()
+
+            # Define the RNN layer
+            self.rnn = nn.RNN(input_size, hidden_size, num_layers, batch_first=True)
+
+            # Define the Fully Connected (FC) layer
+            self.fc = nn.Linear(hidden_size + exog_size, output_size)
+
+        def forward(self, x, exogenous_data):
+            # Pass the input through the RNN
+            out, h_n = self.rnn(x)
+
+            # Get the last timestep hidden state
+            last_hidden_state = out[:, -1, :]  # Shape: (batch_size, hidden_size)
+
+            # Concatenate hidden state with exogenous vars
+            combined_input = torch.cat((last_hidden_state, exogenous_data), dim=1)
+
+            # Pass through FC
+            out = self.fc(combined_input)
+            return out
+
+    def train_rnn_with_minibatches(model, train_loader, epochs, learning_rate=0.001):
+        criterion = nn.MSELoss()
+        optimizer = optim.Adam(model.parameters(), lr=learning_rate)
+
+        for epoch in range(epochs):
+            print(f'Epoch [{epoch+1}/{epochs}]')
+            start_time = time.time()
+
+            model.train()
+            batch_no = 1
+            for X_lags_batch, X_exog_batch, y_batch in train_loader:
+                print(f'Epoch [{epoch+1}/{epochs}] and batch [{batch_no}/{len(train_loader)}]')
+                batch_no += 1
+
+                # Forward pass
+                predictions = model(X_lags_batch, X_exog_batch)
+                loss = criterion(predictions, y_batch)
+
+                # Backward pass
+                optimizer.zero_grad()
+                loss.backward()
+                optimizer.step()
+
+            end_time = time.time()
+            epoch_time = end_time - start_time
+            print(f'Epoch [{epoch+1}/{epochs}], Loss: {loss.item():.4f}, time taken: {epoch_time:.2f} seconds')
+
+    def set_seed(seed=seed):
+        random.seed(seed)
+        np.random.seed(seed)
+        torch.manual_seed(seed)
+        os.environ["PYTHONHASHSEED"] = str(seed)
+
+    # PREPARE TRAIN DATA
+    X_lags, X_exog = separate_lag_and_exogenous_features(train_df_X)
+    X_lags_tensor = torch.tensor(X_lags.values, dtype=torch.float32)
+    X_exog_tensor = torch.tensor(X_exog.values, dtype=torch.float32)
+    y_tensor = torch.tensor(train_df_y.values, dtype=torch.float32).view(-1, 1)
+
+    total_lag_features = X_lags_tensor.shape[1]
+    sequence_length = total_lag_features // input_size
+    exog_size = X_exog_tensor.shape[1]
+
+    # Reshape to 3D
+    X_lags_tensor = X_lags_tensor.view(-1, sequence_length, input_size)
+
+    # INITIALIZE MODEL + DATALOADER
+    set_seed(seed=seed)
+    rnn = RNNModel(input_size, hidden_size, num_layers, exog_size, output_size)
+    train_data = TensorDataset(X_lags_tensor, X_exog_tensor, y_tensor)
+    train_loader = DataLoader(train_data, batch_size=batch_size, shuffle=True)
+
+    # TRAIN MODEL
+    train_rnn_with_minibatches(rnn, train_loader, epochs=epochs, learning_rate=learning_rate)
+
+    # PACK MODEL
+    model = {"rnn": rnn, 'hyperparameter': hyperparameter, "train_df_X": train_df_X, "train_df_y": train_df_y}
+    return model
+
+def produce_forecast_m12_rnn(model, train_df_X, test_df_X):
+    """Create forecast at the train and test set using the trained RNN model"""
+
+    # UNPACK MODEL
+    rnn = model['rnn']
+    hyperparameter = model['hyperparameter']
+
+    # UNPACK HYPERPARAMETER
+    input_size = int(hyperparameter['input_size'])
+    batch_size = int(hyperparameter['batch_size'])
+
+    # PRODUCE FORECAST
+    def produce_forecast(rnn, X):
+        X_lags, X_exog = separate_lag_and_exogenous_features(X)
+        X_lags_tensor = torch.tensor(X_lags.values, dtype=torch.float32)
+        X_exog_tensor = torch.tensor(X_exog.values, dtype=torch.float32)
+
+        total_lag_features = X_lags_tensor.shape[1]
+        sequence_length = total_lag_features // input_size
+        X_lags_tensor = X_lags_tensor.view(-1, sequence_length, input_size)
+
+        predictions = []
+        for i in range(0, len(X_lags_tensor), batch_size):
+            batch_X_lags = X_lags_tensor[i:i+batch_size]
+            batch_X_exog = X_exog_tensor[i:i+batch_size]
+
+            with torch.no_grad():
+                batch_pred = rnn(batch_X_lags, batch_X_exog)
+
+            predictions.append(batch_pred)
+
+        predictions = torch.cat(predictions, dim=0)
+        return predictions.detach().numpy()
+
+    train_df_y_hat = produce_forecast(rnn, train_df_X)
+    test_df_y_hat = produce_forecast(rnn, test_df_X)
+
+    return train_df_y_hat, test_df_y_hat