Utils

Utility_Functions

Accuracy

epilearn.utils.utils.accuracy(output, labels)

Return accuracy of output compared to labels.

Parameters:

output (torch.Tensor) – output from model
labels (torch.Tensor or numpy.array) – node labels

Returns:

accuracy

Return type:

float

Normalize

epilearn.utils.utils.normalize(X)

Normalizes the input tensor X to have zero mean and unit standard deviation. Handles 3D tensors.

Parameters:

X (torch.Tensor) – The input tensor to be normalized.

Returns:

torch.Tensor – The normalized tensor.
torch.Tensor – The means of the input tensor.
torch.Tensor – The standard deviations of the input tensor.

Normalize_Adj

epilearn.utils.utils.normalize_adj(Adj)

Returns the degree normalized adjacency matrix.

Parameters:: Adj (torch.Tensor or np.array) – The input adjacency matrix.
Returns:: The degree normalized adjacency matrix.
Return type:: torch.Tensor

Diff

epilearn.utils.utils.diff(features)

Computes the discrete difference along the time dimension of the input tensor.

Parameters:: features (torch.Tensor) – The input feature tensor.
Returns:: The tensor of differences along the time dimension.
Return type:: torch.Tensor

Degree_Matrix

epilearn.utils.utils.Degree_Matrix(ST_matrix)

Computes the degree matrix for a given spatio-temporal adjacency matrix.

Parameters:: ST_matrix (torch.Tensor) – The input spatio-temporal adjacency matrix.
Returns:: The degree matrix.
Return type:: torch.Tensor

Static_Full

epilearn.utils.utils.Static_full(n, t, A)

Constructs the full spatio-temporal adjacency matrix using the binary spatio-temporal adjacency matrix method.

Parameters:

n (int) – The dimension of the spatial adjacency matrix.
t (int) – The length of periods.
A (torch.Tensor) – The spatial adjacency matrix.

Returns:

The full spatio-temporal adjacency matrix.

Return type:

torch.Tensor

Kronecker

epilearn.utils.utils.kronecker(A, B)

Constructs the spatio-temporal adjacency matrix using the Kronecker product.

Parameters:

A (torch.Tensor) – The temporal adjacency matrix.
B (torch.Tensor) – The spatial adjacency matrix.

Returns:

The adjacency matrix of one space-time neighboring block.

Return type:

torch.Tensor

Edge_to_Adj

epilearn.utils.utils.edge_to_adj(edge_index, num_nodes)

Converts edge index representation to adjacency matrix.

Parameters:

edge_index (torch.Tensor) – The edge index tensor where each column represents an edge.
num_nodes (int) – The number of nodes in the graph.

Returns:

The adjacency matrix.

Return type:

torch.Tensor

Moving_Avg

class epilearn.utils.transforms.moving_avg(kernel_size, stride)

Moving average block to highlight the trend of time series. This module smooths the input time series data using a moving average filter, which helps in capturing the underlying trend by averaging over a specified window.

Parameters:

kernel_size (int) – The size of the moving average window.
stride (int) – The stride of the moving average window.

forward(x)

Applies the moving average to the input tensor ‘x’, padding the time series at both ends to ensure that the moving average is computed correctly for the entire series.

Parameters:: x (torch.Tensor) – The input time-series data tensor, typically of shape (batch_size, time_steps, features).
Returns:: The tensor smoothed using the moving average, maintaining the original shape of the input.
Return type:: torch.Tensor

Series_Decomp

class epilearn.utils.transforms.series_decomp(kernel_size)

A PyTorch module for series decomposition using a single moving average kernel. This module decomposes a time series into its residual and moving average components, providing a straightforward approach to trend extraction.

Parameters:: kernel_size (int) – The kernel size to be used for the moving average calculation. The kernel size defines the window for the moving average.

forward(x)

Applies the series decomposition to the input tensor ‘x’. It calculates the moving average using the specified kernel size and computes the residual by subtracting the moving average from the original series.

Parameters:: x (torch.Tensor) – The input time-series data tensor, typically of shape (batch_size, time_steps).
Returns:: A tuple containing: - The residual tensor after subtracting the moving average from the input. - The moving average tensor computed from the input.
Return type:: tuple(torch.Tensor, torch.Tensor)

Series_Decomp_Multi

class epilearn.utils.transforms.series_decomp_multi(kernel_size)

A PyTorch module for series decomposition using multiple moving average kernels. This module decomposes a time series into its residual and moving average components, leveraging multiple kernel sizes for enhanced flexibility and accuracy in capturing trends.

Parameters:: kernel_size (list of int) – List of kernel sizes to be used for moving average calculations. Each kernel size defines the window for the moving average.

forward(x)

Applies the series decomposition to the input tensor ‘x’. It calculates multiple moving averages using the initialized kernels, weights them using a linear layer followed by a softmax, and computes the residual by subtracting the weighted moving average from the original series.

Parameters:: x (torch.Tensor) – The input time-series data tensor, typically of shape (batch_size, time_steps).
Returns:: A tuple containing: - The residual tensor after subtracting the weighted moving average from the input. - The weighted moving average tensor computed from the input.
Return type:: tuple(torch.Tensor, torch.Tensor)

Metrics

MSE_loss

epilearn.utils.metrics.get_loss(loss_name='mse')

Retrieves the specified loss function based on the input loss name. It supports mean squared error (MSE), a standardized loss (stan), an epidemic-collaboration specific loss (epi_cola), and cross-entropy loss.

Parameters:: loss_name (str, optional) – Name of the loss function to retrieve. Default is ‘mse’.
Returns:: The corresponding loss function as specified by loss_name.
Return type:: callable

Stan_loss

epilearn.utils.metrics.stan_loss(output, label, scale=0.5)

Calculates a combined mean squared error loss on predicted and physically informed predicted values, scaled by a given factor.

Parameters:

output (tuple of torch.Tensor) – The predicted values and the physically informed predicted values.
label (torch.Tensor) – The ground truth values.
scale (float, optional) – Scaling factor for the physical informed loss component. Default: 0.5.

Returns:

The calculated total loss as a scalar tensor.

Return type:

torch.Tensor

Epi_cola_loss

epilearn.utils.metrics.epi_cola_loss(output, label, scale=0.5)

Calculates a combined L1 and mean squared error loss on the output and an epidemiological output, scaled by a given factor.

Parameters:

output (tuple of torch.Tensor) – The primary model output and the epidemiological model output.
label (torch.Tensor) – The ground truth values.
scale (float, optional) – Scaling factor for the epidemiological loss component. Default: 0.5.

Returns:

The calculated total loss as a scalar tensor.

Return type:

torch.Tensor

Cross_entropy_loss

epilearn.utils.metrics.cross_entropy_loss(output, label)

Computes the cross-entropy loss between the logits and labels, adjusting the label tensor to fit the logits dimensions.

Parameters:

output (torch.Tensor) – The logits from the model.
label (torch.Tensor) – The ground truth labels, scaled to match the number of classes based on output dimensions.

Returns:

The cross-entropy loss as a scalar tensor.

Return type:

torch.Tensor

MAE

epilearn.utils.metrics.get_MAE(pred, target)

Calculates the Mean Absolute Error (MAE) between predictions and targets.

Parameters:

pred (torch.Tensor) – Predicted values.
target (torch.Tensor) – Ground truth values.

Returns:

The MAE value as a scalar tensor.

Return type:

torch.Tensor

RMSE

epilearn.utils.metrics.get_RMSE(pred, target)

Calculates the Root Mean Squared Error (RMSE) between predictions and targets.

Parameters:

pred (torch.Tensor) – Predicted values.
target (torch.Tensor) – Ground truth values.

Returns:

The RMSE value as a scalar tensor.

Return type:

torch.Tensor

ACC

epilearn.utils.metrics.get_ACC(pred, target)

Calculates the accuracy of predictions by comparing them to the targets.

Parameters:

pred (torch.Tensor) – Predicted labels.
target (torch.Tensor) – True labels.

Returns:

The accuracy as a scalar tensor.

Return type:

torch.Tensor

Simulation

Time_Geo

class epilearn.utils.simulation.Time_geo(region_input, pop_input, p_t_raw=None, pop_num=7, time_slot=10, rho=0.6, gamma=0.41, alpha=1.86, n_w=6.1, beta1=3.67, beta2=10, simu_slot=144)

Models spatial-temporal movement patterns of individuals across different regions, simulating movement based on temporal rhythms, personal habits, and regional exploration probabilities. It includes mechanisms to simulate individual trajectories, predict location changes, and calculate movement probabilities based on historical data.

Parameters:

region_input (ndarray) – Input array of region coordinates.
pop_input (ndarray) – Population distribution across regions.
p_t_raw (ndarray, optional) – Raw probability distribution of time slots for movement. Default: Loads from “epilearn/data/rhythm.npy”.
pop_num (int, optional) – Number of individuals in the population to simulate. Default: 7.
time_slot (int, optional) – Time resolution in minutes for one slot. Default: 10.
rho (float, optional) – Controls the exploration probability for other regions. Default: 0.6.
gamma (float, optional) – Attenuation parameter for exploration probability. Default: 0.41.
alpha (float, optional) – Controls the exploration depth. Default: 1.86.
n_w (float, optional) – Average number of tours based on home per week. Default: 6.1.
beta1 (float, optional) – Dwell rate. Default: 3.67.
beta2 (float, optional) – Burst rate, affecting movement speed. Default: 10.
simu_slot (int, optional) – Total number of simulation slots. Default: 144.

Returns:

Each dictionary contains the movement trace and other metrics for an individual simulated over the simu_slot duration.

Return type:

list of dicts

trace_simulate()

Generates simulated movement traces for each individual in the population. The simulation captures the dynamics of movement based on initial conditions and predefined movement parameters over a set number of time slots.

Returns:: Each dictionary contains detailed information and metrics for an individual’s simulated trace, including home location, total number of movements, cumulative distance traveled, and the sequence of visited locations across the simulation period.
Return type:: list of dicts

Transformation

Compose

class epilearn.utils.transforms.Compose(transforms, device='cpu')

Composes several transforms together. This transform does not support torchscript. Please, see the note below.

Parameters:: transforms (list of Transform objects) – list of transforms to compose.

Example

>>> transforms.Compose([
>>>     transforms.CenterCrop(10),
>>>     transforms.ToTensor(),
>>> ])

Note

In order to script the transformations, please use torch.nn.Sequential as below.

>>> transforms = torch.nn.Sequential(
>>>     transforms.CenterCrop(10),
>>>     transforms.Normalize((0.485, 0.456, 0.406), (0.229, 0.224, 0.225)),
>>> )
>>> scripted_transforms = torch.jit.script(transforms)

Make sure to use only scriptable transformations, i.e. that work with torch.Tensor, does not require lambda functions or PIL.Image.

Normalize_Feat

class epilearn.utils.transforms.normalize_feat(dim=1)

A normalization module for feature standardization in PyTorch. This module adjusts features to have zero mean and unit variance along specified dimensions, handling 3D and 4D tensors.

Parameters:: dim (int, optional) – The dimension over which to calculate the mean and standard deviation for normalization. Default: 1.

forward(X, device='cpu')

Forward pass of the normalization module that normalizes a given input tensor X.

Parameters:

X (torch.Tensor) – The input tensor to be normalized. Can be either a 3D or 4D tensor.
device (str, optional) – The device to which the normalized tensor is transferred. Default: ‘cpu’.

Returns:

The normalized tensor, adjusted to have zero mean and unit variance along the specified dimensions, and transferred to the specified device.

Return type:

torch.Tensor

Normalize_Adj

class epilearn.utils.transforms.normalize_adj(dim=0)

A PyTorch module for normalizing adjacency matrices to facilitate operations in graph neural networks. The normalization adjusts adjacency matrices to account for node degrees, enhancing the propagation of features through the network. This class can handle both batched and single adjacency matrices.

Parameters:: dim (int, optional) – The dimension over which to perform normalization (not utilized in current implementation). Default: 0.

forward(Adj, device='cpu')

Forward pass of the normalize_adj module that computes a degree-normalized adjacency matrix from the input adjacency matrix ‘Adj’.

Parameters:

Adj (torch.Tensor or np.array) – The input adjacency matrix, which can be a 2D matrix for a single graph or a 3D tensor for batch processing.
device (str, optional) – The device to which the normalized adjacency matrix is transferred. Default: ‘cpu’.

Returns:

The degree-normalized adjacency matrix, transferred to the specified device.

Return type:

torch.Tensor

Convert_To_Frequency

class epilearn.utils.transforms.convert_to_frequency(ftype='fft', n_fft=8)

A PyTorch module for transforming time-domain data into frequency-domain representations using either FFT (Fast Fourier Transform) or STFT (Short Time Fourier Transform). This module is configurable to handle different lengths of FFT and hop sizes for STFT, making it flexible for various signal processing tasks.

Parameters:

ftype (str, optional) – The type of frequency transformation to perform, either ‘fft’ for Fast Fourier Transform or ‘stft’ for Short Time Fourier Transform. Default: “fft”.
n_fft (int, optional) – The window size for the FFT or STFT. Default: 8.

forward(data, **kwarg)

Applies the configured frequency transformation (FFT or STFT) to the input data.

Parameters:

data (torch.Tensor) – The input data tensor, expected to be a time-domain signal. It can be a 3D tensor (batch, channels, time) for ‘fft’ or a 4D tensor (batch, nodes, time, features) for ‘stft’.
**kwargs (dict) – Additional keyword arguments, such as ‘device’ for specifying the computation device.

Returns:

The frequency-domain representation of the input data. The output format depends on the transformation type (‘fft’ returns real parts of the FFT, ‘stft’ returns the magnitude of the STFT as a 5D tensor).

Return type:

torch.Tensor

Add_Time_Embedding

class epilearn.utils.transforms.add_time_embedding(embedding_dim=13, fourier=False)

A PyTorch module that appends time-based embeddings to each feature vector in the dataset. It can generate embeddings using sinusoidal functions, optionally using a Fourier transform approach, enhancing the temporal aspects of data for tasks such as time series forecasting or sequence modeling.

Parameters:

embedding_dim (int, optional) – The dimensionality of the time embeddings. Default: 13.
fourier (bool, optional) – Specifies whether to use a Fourier transform-based approach for time embedding. Default: False.

forward(data, **kwarg)

Generates and appends time-based embeddings to the input data tensor.

Parameters:

data (torch.Tensor) – The input data tensor, which can vary in dimensions depending on the application (e.g., batch, nodes, time).
**kwargs (dict) – Additional keyword arguments such as ‘device’ for specifying the computation device.

Returns:

The input data tensor augmented with time-based embeddings. The resulting tensor includes an additional dimension for the embeddings, concatenated to the last dimension of the input data tensor.

Return type:

torch.Tensor

Learnable_Time_Embedding

class epilearn.utils.transforms.learnable_time_embedding(timesteps=13, embedding_dim=13)

A PyTorch module that appends learnable time embeddings to the input data, facilitating the capture of temporal dependencies in models that process sequences or time-series data. The embedding is learned during the training process, allowing it to adapt to specific temporal patterns observed in the dataset.

Parameters:

timesteps (int) – The total number of timesteps in the data sequence, which defines the number of unique time indices.
embedding_dim (int) – The dimensionality of each time embedding vector.

forward(data, **kwarg)

Appends learnable time-based embeddings to the input data tensor. The embeddings are added to each timestep, augmenting the feature dimensions of the data.

Parameters:

data (torch.Tensor) – The input data tensor, typically including dimensions for batch, nodes, and time.
**kwargs (dict) – Additional keyword arguments such as ‘device’ for specifying the computation device.

Returns:

The input data tensor augmented with time-based embeddings, expanding the last dimension to include the embeddings.

Return type:

torch.Tensor

Seasonality_And_Trend_Decompose

class epilearn.utils.transforms.seasonality_and_trend_decompose(decompose_type='dynamic', moving_avg=25, kernel_size=[4, 8, 12])

A PyTorch module designed to decompose time-series data into seasonality and trend components. It supports both dynamic and static decomposition methods. Dynamic decomposition leverages a Fourier transform approach for seasonality and convolutional filters for trend extraction. Static decomposition utilizes a moving average approach.

Parameters:

decompose_type (str, optional) – The type of decomposition to perform. “dynamic” for Fourier and convolutional methods, “static” for moving average based decomposition. Default: “dynamic”.
moving_avg (int, optional) – The window size for the moving average in static decomposition. Default: 25.
kernel_size (list of int, optional) – List of kernel sizes for convolutional filters in dynamic trend decomposition. Default: [4, 8, 12].

forward(data, **kwarg)

Decomposes the input data tensor into seasonality and trend components. The method of decomposition (dynamic or static) impacts the models and techniques used.

Parameters:

data (torch.Tensor) – The input data tensor, typically including dimensions for batch, nodes, and time.
**kwargs (dict) – Additional keyword arguments such as ‘device’ for specifying the computation device.

Returns:

A list containing the seasonality and trend components of the input data, each as a separate tensor.

Return type:

list of torch.Tensor

Calculate_DTW_Matrix

class epilearn.utils.transforms.calculate_dtw_matrix(dataset_name)

A PyTorch module designed to compute the Dynamic Time Warping (DTW) distance matrix between all pairs of time-series in a dataset. DTW is a method that calculates an optimal match between two given sequences with certain restrictions. The matrix is computed once and saved for future use to avoid redundant computations.

Parameters:: dataset_name (str) – The name of the dataset, used to save and retrieve the computed DTW matrix.

forward(data, **kwarg)

Computes the Dynamic Time Warping (DTW) matrix for the input data. If a precomputed matrix exists in the cache, it loads that matrix; otherwise, it computes a new matrix and saves it.

Parameters:

data (np.ndarray) – The input data array where each row represents a time step and each column a time-series node.
**kwargs (dict) – Additional keyword arguments not utilized in this method.

Returns:

The computed or loaded DTW distance matrix, where each element (i, j) represents the DTW distance between the i-th and j-th time-series.

Return type:

np.ndarray

Utils

metrics

simulation

transformation

utils