ise.models

Subpackages

• ise.models.ISEFlow
  • ise.models.ISEFlow.ISEFlow
    • ISEFlow
      • ISEFlow.device
      • ISEFlow.deep_ensemble
      • ISEFlow.normalizing_flow
      • ISEFlow.trained
      • ISEFlow.scaler_path
      • ISEFlow.fit()
      • ISEFlow.forward()
      • ISEFlow.load()
      • ISEFlow.predict()
      • ISEFlow.save()
    • ISEFlow_AIS
      • ISEFlow_AIS.load()
      • ISEFlow_AIS.predict()
      • ISEFlow_AIS.process()
    • ISEFlow_GrIS
      • ISEFlow_GrIS.load()
  • ise.models.ISEFlow.de
    • ISEFlow_AIS_DE
      • ISEFlow_AIS_DE.input_size
      • ISEFlow_AIS_DE.output_size
      • ISEFlow_AIS_DE.iseflow_ais_ensemble
    • ISEFlow_GrIS_DE
      • ISEFlow_GrIS_DE.input_size
      • ISEFlow_GrIS_DE.output_size
      • ISEFlow_GrIS_DE.iseflow_gris_ensemble
  • ise.models.ISEFlow.nf
    • ISEFlow_AIS_NF
    • ISEFlow_GrIS_NF
• ise.models.density_estimators
  • ise.models.density_estimators.normalizing_flow
    • NormalizingFlow
      • NormalizingFlow.num_flow_transforms
      • NormalizingFlow.num_input_features
      • NormalizingFlow.num_predicted_sle
      • NormalizingFlow.flow_hidden_features
      • NormalizingFlow.output_sequence_length
      • NormalizingFlow.device
      • NormalizingFlow.base_distribution
      • NormalizingFlow.t
      • NormalizingFlow.flow
      • NormalizingFlow.optimizer
      • NormalizingFlow.criterion
      • NormalizingFlow.trained
      • NormalizingFlow.aleatoric()
      • NormalizingFlow.fit()
      • NormalizingFlow.get_latent()
      • NormalizingFlow.load()
      • NormalizingFlow.sample()
      • NormalizingFlow.save()
• ise.models.predictors
  • ise.models.predictors.deep_ensemble
    • DeepEnsemble
      • DeepEnsemble.input_size
      • DeepEnsemble.output_size
      • DeepEnsemble.output_sequence_length
      • DeepEnsemble.loss_choices
      • DeepEnsemble.ensemble_members
      • DeepEnsemble.trained
      • DeepEnsemble.fit()
      • DeepEnsemble.forward()
      • DeepEnsemble.load()
      • DeepEnsemble.predict()
      • DeepEnsemble.save()
  • ise.models.predictors.lstm
    • LSTM
      • LSTM.lstm_num_layers
      • LSTM.lstm_num_hidden
      • LSTM.input_size
      • LSTM.output_size
      • LSTM.output_sequence_length
      • LSTM.device
      • LSTM.lstm
      • LSTM.relu
      • LSTM.linear1
      • LSTM.linear_out
      • LSTM.optimizer
      • LSTM.dropout
      • LSTM.criterion
      • LSTM.trained
      • LSTM.fit()
      • LSTM.forward()
      • LSTM.predict()
• ise.models.pretrained

ise.models.loss

class ise.models.loss.GridCriterion

Bases: Module

Custom loss function enforcing spatial smoothness using total variation regularization.

This function encourages smoothness in spatial predictions by penalizing large variations.

- total_variation_regularization

Computes the smoothness loss.

- forward

Computes the final loss.

forward(true, predicted, smoothness_weight=0.001)

Computes the final loss by combining pixel-wise MSE and TVR.

Parameters:

• true (Tensor) - Ground truth values.

• predicted (Tensor) - Model predictions.

• smoothness_weight (float, optional) - Weight for TVR. Defaults to 0.001.

Returns:

Computed loss.

Return type:

Tensor

total_variation_regularization(grid)

Computes total variation regularization (TVR) loss.

Parameters:

grid (Tensor) - A 2D tensor representing spatial data.

Returns:

TVR loss.

Return type:

Tensor

class ise.models.loss.MSEDeviationLoss(threshold=1.0, penalty_multiplier=2.0)

Bases: Module

Custom MSE Loss with an additional penalty for large deviations.

This function penalizes predictions that deviate significantly from the target.

threshold

Deviation threshold for applying penalties.

Type:

float

penalty_multiplier

Multiplier controlling penalty severity.

Type:

float

- forward

Computes the loss with deviation penalties.

forward(predictions, targets)

Computes the MSE loss with an additional deviation penalty.

Parameters:

• predictions (Tensor) - Predicted values.

• targets (Tensor) - Ground truth values.

Returns:

Computed loss.

Return type:

Tensor

class ise.models.loss.WeightedGridLoss

Bases: Module

Custom loss function that penalizes errors based on the total variation of a grid.

This loss function consists of two components: 1. Pixel-wise Weighted Mean Squared Error (MSE): Higher weight is assigned to extreme values. 2. Total Variation Regularization (TVR): Enforces spatial smoothness by penalizing large differences

between adjacent grid values.

device

The device on which the model runs (‘cuda’ or ‘cpu’).

Type:

str

- total_variation_regularization

Computes TVR penalty for smoothness.

- weighted_pixelwise_mse

Computes MSE loss with per-pixel weighting.

- forward

Computes the final weighted loss.

forward(true, predicted, smoothness_weight=0.001, extreme_value_threshold=1e-06)

Computes the final weighted loss combining pixel-wise MSE and TVR.

Parameters:

• true (Tensor) - Ground truth values.

• predicted (Tensor) - Model predictions.

• smoothness_weight (float, optional) - Weighting factor for the TVR loss. Defaults to 0.001.

• extreme_value_threshold (float, optional) - Threshold to define extreme values. Defaults to 1e-6.

Returns:

The total computed loss.

Return type:

Tensor

total_variation_regularization(grid)

Computes the total variation regularization (TVR) loss for spatial smoothness.

Parameters:

grid (Tensor) - A 2D tensor representing spatial data.

Returns:

The total variation loss.

Return type:

Tensor

weighted_pixelwise_mse(true, predicted, weights)

Computes the pixel-wise mean squared error (MSE) with custom weights.

Parameters:

• true (Tensor) - Ground truth values.

• predicted (Tensor) - Model predictions.

• weights (Tensor) - Weighting factor for each pixel.

Returns:

Weighted mean squared error.

Return type:

Tensor

class ise.models.loss.WeightedMSELoss(data_mean, data_std, weight_factor=1.0)

Bases: Module

Custom loss function that applies a weighted penalty to extreme values.

This function increases the weight of extreme values based on their deviation from the dataset mean, normalizing by the standard deviation.

data_mean

Mean value of the dataset.

Type:

Tensor

data_std

Standard deviation of the dataset.

Type:

Tensor

weight_factor

Factor controlling how much extreme values are penalized.

Type:

Tensor

- forward

Computes the weighted mean squared error loss.

forward(input, target)

Computes the Weighted Mean Squared Error (MSE) Loss.

Parameters:

• input (Tensor) - Predicted values.

• target (Tensor) - Ground truth values.

Returns:

Computed loss.

Return type:

Tensor

class ise.models.loss.WeightedMSELossWithSignPenalty(data_mean, data_std, weight_factor=1.0, sign_penalty_factor=1.0)

Bases: Module

Custom loss function that penalizes errors on extreme values and opposite sign predictions.

This function extends WeightedMSELoss by adding a penalty when the sign of the prediction differs from the target.

data_mean

Mean of the dataset.

Type:

Tensor

data_std

Standard deviation of the dataset.

Type:

Tensor

weight_factor

Factor controlling extreme value weighting.

Type:

Tensor

sign_penalty_factor

Factor controlling penalty for opposite sign predictions.

Type:

Tensor

- forward

Computes the weighted loss with sign penalties.

forward(input, target)

Computes the Weighted MSE Loss with an additional sign penalty.

Parameters:

• input (Tensor) - Predicted values.

• target (Tensor) - Ground truth values.

Returns:

Computed loss.

Return type:

Tensor

class ise.models.loss.WeightedMSEPCALoss(data_mean, data_std, weight_factor=1.0, custom_weights=None)

Bases: Module

Extension of WeightedMSELoss that allows for custom per-batch weighting.

This loss function enables additional user-defined weights to further adjust penalties for different predictions.

data_mean

Mean of the dataset.

Type:

Tensor

data_std

Standard deviation of the dataset.

Type:

Tensor

weight_factor

Controls the penalty for extreme values.

Type:

Tensor

custom_weights

User-defined weight tensor.

Type:

Tensor, optional

- forward

Computes the batch-weighted MSE loss.

forward(input, target)

Computes the batch-weighted mean squared error loss.

Parameters:

• input (Tensor) - Predicted values.

• target (Tensor) - Ground truth values.

Returns:

Computed loss.

Return type:

Tensor

class ise.models.loss.WeightedPCALoss(component_weights, reduction='mean')

Bases: Module

Custom loss function applying different weights to errors in principal component analysis.

This function allows assigning higher penalties to the first components.

component_weights

Weighting factors for each principal component.

Type:

Tensor

reduction

Specifies reduction mode (‘mean’, ‘sum’, or ‘none’).

Type:

str

- forward

Computes the weighted PCA loss.

forward(input, target)

Computes the weighted PCA loss.

Parameters:

• input (Tensor) - Predicted principal components.

• target (Tensor) - Actual principal components.

Returns:

Computed loss.

Return type:

Tensor

ise.models.scenario

class ise.models.scenario.ScenarioPredictor(input_size, hidden_layers=[128, 64], output_size=1, dropout_rate=0.1)

Bases: Module

evaluate(data_loader)

Evaluates the model on a dataset.

Parameters:

data_loader (torch.utils.data.DataLoader) - DataLoader for the dataset to evaluate.

Returns:

A tuple containing:

• avg_loss (float): Average loss over the dataset.

• accuracy (float): Accuracy of predictions (0 to 1).

Return type:

tuple

fit(train_loader, val_loader=None, epochs=10, lr=0.001, print_every=1, save_checkpoint=True)

Trains the model on the given dataset.

Parameters:

• train_loader (torch.utils.data.DataLoader) - DataLoader for the training dataset.

• val_loader (torch.utils.data.DataLoader, optional) - DataLoader for the validation dataset. Defaults to None.

• epochs (int, optional) - Number of epochs for training. Defaults to 10.

• lr (float, optional) - Learning rate for the optimizer. Defaults to 1e-3.

• print_every (int, optional) - Interval for printing training progress. Defaults to 1.

• save_checkpoint (bool, optional) - Whether to save model checkpoints based on validation loss. Defaults to True.

Returns:

None

forward(x)

Forward pass through the model.

Parameters:

x (torch.Tensor) - Input tensor with shape (batch_size, input_size).

Returns:

Output tensor with probabilities in the range [0,1].

Return type:

torch.Tensor

load(path)

Loads the model state from a file.

Parameters:

path (str) - Path to the file containing the model state.

Returns:

None

predict(x)

Predicts the output for a given input.

Parameters:

x (torch.Tensor) - Input tensor.

Returns:

Predicted output tensor with probabilities in the range [0,1].

Return type:

torch.Tensor

ise.models.variational_lstm_emulator

This module contains the VariationalLSTMEmulator, which is a class that contains the model architecture for the variational LSTM emulator presented in https://doi.org/10.1029/2023MS003899.

class ise.models.variational_lstm_emulator.VariationalLSTMEmulator(architecture, mc_dropout=False, dropout_prob=None)

Bases: Module

Variational LSTM Emulator model for time series data.

enable_dropout()

Enable dropout during model evaluation.

This method turns on dropout for each layer that starts with “Dropout”.

forward(x)

Forward pass of the VariationalLSTMEmulator model.

Parameters:

x (torch.Tensor) - Input tensor.

Returns:

Output tensor.

Return type:

torch.Tensor

predict(x, approx_dist=None, mc_iterations=None, quantile_range=[0.025, 0.975], confidence='95')

Make predictions using the VariationalLSTMEmulator model.

Parameters:

• x (np.ndarray or torch.Tensor or pd.DataFrame) - Input data.

• approx_dist (bool, optional) - Flag indicating whether to approximate the distribution using MC Dropout. Defaults to None.

• mc_iterations (int, optional) - Number of MC iterations. Required if approx_dist is True.

• quantile_range (list, optional) - Quantile range for prediction intervals. Defaults to [0.025, 0.975].

• confidence (str, optional) - Confidence level for prediction intervals. Defaults to “95”.

Returns:

Tuple containing the predictions, mean predictions, and standard deviations.

Return type:

tuple