ANGLE (anglepy.ANGLE)

This module implements the main ANGLE API, which includes the CircularEngressor class and the ANGLE function for fitting the model to data. It allows for multivariate predictors and circular response variables, with options for standardization, noise injection, and various distance metrics in the loss function.

anglepy.ANGLE.ANGLE(x, y, classification=False, num_layer=2, hidden_dim=100, noise_dim=100, noise_std=1, noise_dist='gaussian', out_act=None, add_bn=True, resblock=False, gamma=1, kernel_func=None, lr=0.0001, num_epochs=500, batch_size=None, print_every_nepoch=100, print_times_per_epoch=1, device='cpu', standardize=True, verbose=True, dist_method='geodesic', noise_all_layer=True, circular_indices=None, sdr=False, reduced_dim=None, random_state=None, unbounded=False, circular_projection='atan2')

API to fit ANGLE to the data. It allows multivariate predictors and circular response variables. Variables are per default internally standardized (training with standardized data, while predictions and evaluations are on original scale).

Parameters:

  • x (torch.Tensor) – training data of predictors.

  • y (torch.Tensor) – training data of circular responses in [0, 2pi).

  • classification (bool, optional) – classification or not. Defaults to False.

  • num_layer (int, optional) – number of (linear) layers. Defaults to 2.

  • hidden_dim (int, optional) – number of neurons per layer. Defaults to 100.

  • noise_dim (int, optional) – noise dimension. Defaults to 100.

  • noise_std (float, optional) – standard deviation of the injected noise. Defaults to 1.

  • noise_dist (str, optional) – distribution of the noise. Choices = [“gaussian”, “uniform”]. Defaults to “gaussian”.

  • out_act (str, optional) – output activation function. Defaults to None.

  • add_bn (bool, optional) – whether to add BN layer. Defaults to True.

  • resblock (bool, optional) – whether to use residual blocks (skip connections). Defaults to False.

  • gamma (float, optional) – power parameter in the energy loss. Defaults to 1.

  • kernel_func (callable, optional) – Instantiated negative of strictly positive definite kernel function applied to the distance metric. Defaults to None. See kernels.py for available kernels, e.g., powered_exponential(c=1, alpha=1).

  • lr (float, optional) – learning rate. Defaults to 0.005.

  • num_epochs (int, optional) – number of epochs. Defaults to 500.

  • batch_size (int, optional) – batch size. Defaults to None, referring to the full batch.

  • print_every_nepoch (int, optional) – print losses every print_every_nepoch number of epochs. Defaults to 100.

  • print_times_per_epoch (int, optional) – print losses for print_times_per_epoch times per epoch. Defaults to 1.

  • device (str, torch.device, optional) – device. Defaults to “cpu”. Choices = [“cpu”, “gpu”, “cuda”].

  • standardize (bool, optional) – whether to standardize data during training. Defaults to True.

  • verbose (bool, optional) – whether to print losses and info. Defaults to True.

  • dist_method (str, optional) – underlying distance metric in the GCES loss. Choices = [“chordal”, “geodesic”, “cosine”]. Defaults to “chordal”.

  • noise_all_layer (bool, optional) – whether to inject noise into every hidden layer (pre-ANM) or only the last layer (post-ANM). Defaults to True (pre-ANM).

  • circular_indices (list of int, optional) – indices specifying which input features are circular. Defaults to None.

  • sdr (bool, optional) – whether to use Single-Index / Multiple-Index mode for sufficient dimension reduction. Defaults to False.

  • reduced_dim (int, optional) – target dimension size when using SDR mode. Defaults to None.

  • random_state (int, optional) – random seed for reproducibility. Defaults to None.

  • unbounded (bool, optional) – whether to output in modulated (unbounded) mode. Defaults to False.

  • circular_projection (str, optional) – method used to project outputs to the circle when bounded. Choices = [‘atan2’, ‘sigmoid’]. Defaults to ‘atan2’.

Returns:

a fitted circular engression model.

Return type:

CircularEngressor

class anglepy.ANGLE.CircularEngressor(in_dim, out_dim, classification=False, num_layer=2, hidden_dim=100, noise_dim=100, noise_std=1, noise_dist='gaussian', out_act=False, resblock=False, add_bn=True, gamma=1, kernel_func=<function powered_exponential.<locals>.kernel>, lr=0.0001, num_epochs=500, batch_size=None, standardize=True, device='cpu', check_device=True, verbose=True, dist_method='geodesic', circular_indices=None, sdr=False, reduced_dim=None, random_state=None, unbounded=False, noise_all_layer=True, circular_projection='atan2')

Bases: object

Circular Engressor class.

A distributional regression model tailored for circular responses. Minimizes the generalized circular energy score loss.

Parameters:

  • in_dim (int) – input dimension.

  • out_dim (int) – output dimension.

  • classification (bool, optional) – classification or not. Defaults to False.

  • num_layer (int, optional) – number of layers. Defaults to 2.

  • hidden_dim (int, optional) – number of neurons per layer. Defaults to 100.

  • noise_dim (int, optional) – noise dimension. Defaults to 100.

  • noise_std (float, optional) – standard deviation of the injected noise. Defaults to 1.

  • noise_dist (str, optional) – distribution of the noise. Choices = [“gaussian”, “uniform”]. Defaults to “gaussian”.

  • out_act (str or bool, optional) – output activation function. Defaults to False.

  • resblock (bool, optional) – whether to use residual blocks (skip-connections). Defaults to False.

  • add_bn (bool, optional) – whether to add Batch Normalization layers. Defaults to True.

  • gamma (float, optional) – power parameter in the energy loss. Defaults to 1.

  • kernel_func (callable, optional) – Instantiated negative of strictly positive definite kernel function applied to the distance metric. Defaults to powered_exponential(c=1, alpha=1). See kernels.py for available kernels.

  • lr (float, optional) – learning rate. Defaults to 0.005.

  • num_epochs (int, optional) – number of epochs for training. Defaults to 500.

  • batch_size (int, optional) – batch size. Defaults to None, referring to the full batch.

  • standardize (bool, optional) – whether to standardize data during training. Defaults to True.

  • device (str or torch.device, optional) – compute device. Choices = [“cpu”, “gpu”, “cuda”]. Defaults to “cpu”.

  • check_device (bool, optional) – whether to verify the selected device is available. Defaults to True.

  • verbose (bool, optional) – whether to print training progress and logs. Defaults to True.

  • dist_method (str, optional) – underlying distance metric in the GCES loss. Choices = [“chordal”, “geodesic”, “cosine”]. Defaults to “chordal”.

  • circular_indices (list of int, optional) – indices specifying which input features are circular. Defaults to None.

  • sdr (bool, optional) – whether to use Single-Index / Multiple-Index mode for sufficient dimension reduction. Defaults to False.

  • reduced_dim (int, optional) – target dimension size when using SDR mode. Defaults to None.

  • random_state (int, optional) – random seed for reproducibility. Defaults to None.

  • unbounded (bool, optional) – whether to output in modulated (unbounded) mode. Defaults to False.

  • noise_all_layer (bool, optional) – whether to inject noise into every hidden layer (pre-ANM) or only the last layer (post-ANM). Defaults to True (pre-ANM).

  • circular_projection (str, optional) – method used to project outputs to the circle when bounded. Choices = [‘atan2’, ‘sigmoid’]. Defaults to ‘atan2’.

property beta_proj

Returns the estimated gamma matrix if the model has SDR enabled. The returned tensor has shape (reduced_dim, embedded_in_dim).

eval_loss(x, y, loss_type='l2', sample_size=None, gamma=1, verbose=False)

Compute the loss for evaluation.

Parameters:

  • x (torch.Tensor) – data of predictors.

  • y (torch.Tensor) – data of responses.

  • loss_type (str, optional) – loss type. Defaults to “l2”. Choices: [“l2”, “l1”, “energy”, “cor”].

  • sample_size (int, optional) – generated sample sizes for each x. Defaults to 100.

  • gamma (float, optional) – gamma in energy score. Defaults to 1.

Returns:

evaluation loss.

Return type:

float

eval_mode()
predict(x, target='mean', sample_size=100)

Point prediction.

Parameters:

  • x (torch.Tensor) – data of predictors.

  • target (str or float or list, optional) – a quantity of interest to predict. float refers to the quantiles. Defaults to “mean”.

  • sample_size (int, optional) – generated sample sizes for each x. Defaults to 100.

Returns:

point predictions.

Return type:

torch.Tensor or list of torch.Tensor

print_loss(epoch_idx, batch_idx, return_loss=False)
sample(x, sample_size=100, expand_dim=True)

Sample new response data.

Parameters:

  • x (torch.Tensor) – test data of predictors.

  • sample_size (int, optional) – generated sample sizes for each x. Defaults to 100.

  • expand_dim (bool, optional) – whether to expand the sample dimension. Defaults to True.

Returns:

torch.Tensor of shape (data_size, response_dim, sample_size).

  • [:,:,i] consists of the i-th sample of all x.

  • [i,:,:] consists of all samples of x_i.

standardize_data(x, y=None)

Standardize the data, if self.standardize is True. Avoid standardizing the circular target y.

Parameters:

  • x (torch.Tensor) – training data of predictors.

  • y (torch.Tensor, optional) – training data of responses. Defaults to None.

Returns:

standardized or original data.

Return type:

torch.Tensor

summary()

Print the model architecture and hyperparameters.

train(x, y, num_epochs=None, batch_size=None, lr=None, print_every_nepoch=100, print_times_per_epoch=1, standardize=None, verbose=True)

Fit the model.

Parameters:

  • x (torch.Tensor) – training data of predictors.

  • y (torch.Tensor) – trainging data of responses.

  • num_epochs (int, optional) – number of training epochs. Defaults to None.

  • batch_size (int, optional) – batch size for mini-batch SGD. Defaults to None.

  • lr (float, optional) – learning rate.

  • print_every_nepoch (int, optional) – print losses every print_every_nepoch number of epochs. Defaults to 100.

  • print_times_per_epoch (int, optional) – print losses for print_times_per_epoch times per epoch. Defaults to 1.

  • standardize (bool, optional) – whether to standardize the data. Defaults to True.

  • verbose (bool, optional) – whether to print losses and info. Defaults to True.

train_mode()
train_one_iter(x_batch, y_batch)
unstandardize_data(y, x=None, expand_dim=False)

Transform the predictions back to the original scale.

For circular data: - y (targets): Remains unchanged (Standardization was skipped). - x (predictors): Unstandardized using recorded mean/std.

zero_loss()