Core

class Cpab(tess_size: int, backend: str = 'numpy', device: str = 'cpu', zero_boundary: bool = True, basis: str = 'rref')[source]

Continous piecewise-affine based transformations. Package main class.

Parameters:

  • tess_size (int) – tesselation size, with the number of vertices.

  • backend (str, optional) – computational backend to use. Choose between “numpy”, or “pytorch”. Defaults to “numpy”.

  • device (str, optional) – device to use. Choose between “cpu” or “gpu”. For the numpy backend only the “cpu” option is valid. Defaults to “cpu”.

  • zero_boundary (bool, optional) – determines if the velocity at the boundary is zero

  • basis (str, optional) – constrain basis to use. Choose between “rref”, “svd”, or “sparse”. Defaults to “rref”.

params: Parameters
tess: Tessellation
backend_name: str
backend: module
uniform_meshgrid(n_points: int)[source]

Generates a uniformly separated, one-dimensional meshgrid

Parameters:

n_points (int) – number of points

Returns:

vector of points

Return type:

numpy.ndarray or torch.Tensor

covariance_cpa(length_scale: float = 0.1, output_variance: float = 1)[source]

Generates the covariance matrix for a continuous piecewise-affine space. This function uses the squared exponential kernel with parameters \(\lambda_s\): length_scale and \(\lambda_v\): output_variance

Parameters:

  • length_scale (float,>0) – how fast the covariance declines between the cells

  • output_variance (float,>0) – overall variance from the mean

Returns:

[d, d] matrix.

Return type:

numpy.ndarray or torch.Tensor

sample_transformation(n_sample: int, mean=None, cov=None)[source]

Generates samples of a random transformation vector. By default the method samples from a standard Gaussian distribution.

Parameters:
Returns:

[n_sample, d] matrix, where each row is a independent sample from a multivariate gaussian

Return type:

numpy.ndarray or torch.Tensor

sample_transformation_with_prior(n_sample: int, mean=None, length_scale: float = 0.1, output_variance: float = 1)[source]

Generates samples of smooth transitions. Covariance matrix for the continuous piecewise-affine space. This function uses the squared exponential kernel with parameters \(\lambda_s\): length_scale and \(\lambda_v\): output_variance

Parameters:

  • n_sample (int) – number of transformations to sample

  • mean (numpy.ndarray or torch.Tensor) – [d,] vector, mean of multivariate gaussian

  • length_scale (float,>0) – how fast the covariance declines between the cells

  • output_variance (float,>0) – overall variance from the mean

Returns:

[d, d] matrix.

Return type:

numpy.ndarray or torch.Tensor

identity(n_sample: int = 1, epsilon: float = 0)[source]

Generates the parameters for the identity transformation (vector of zeros)

Parameters:

  • n_sample (int) – number of transformations to sample

  • epsilon (float, >0) – number to add to the identity transformation for stability

Returns:

[n_sample, d] matrix, where each row is a sample

Return type:

numpy.ndarray or torch.Tensor

transform_grid(grid, theta, method=None, time=1.0)[source]

Integrates a grid using the parametrization in theta.

Parameters:

  • grid (numpy.ndarray or torch.Tensor) – [n_points] vector or [n_batch, n_points] tensor i.e. either a single grid for all theta values, or a grid for each theta value

  • theta (numpy.ndarray or torch.Tensor) – [n_batch, d] matrix

  • method (str) – integration method, one of “closed_form”, “numeric”.

  • time (float) – integration time. Defaults to 1.0

Returns:

[n_batch, n_points] tensor, with the transformed grid. The slice transformed_grid[i] corresponds to the grid being transformed by theta[i]

Return type:

numpy.ndarray or torch.Tensor

transform_grid_ss(grid, theta, method=None, time=1.0, N=0)[source]

Integrates a grid using the scaling-squaring method and the parametrization in theta.

Parameters:

  • grid (numpy.ndarray or torch.Tensor) – [n_points] vector or [n_batch, n_points] tensor i.e. either a single grid for all theta values, or a grid for each theta value

  • theta (numpy.ndarray or torch.Tensor) – [n_batch, d] matrix

  • method (str) – integration method, one of “closed_form”, “numeric”.

  • time (float) – integration time. Defaults to 1.0

  • N (int) – number of scaling iterations. Defaults to 0

Returns:

[n_batch, n_points] tensor, with the transformed grid. The slice transformed_grid[i] corresponds to the grid being transformed by theta[i]

Return type:

numpy.ndarray or torch.Tensor

gradient_grid(grid, theta, method=None, time=1.0)[source]

Integrates and returns the gradient of the transformation w.r.t. the parametrization in theta.

Parameters:
Returns:

tuple containing

  • transformed_grid (numpy.ndarray or torch.Tensor): [n_batch, n_points] tensor, with the transformed grid. The slice transformed_grid[i] corresponds to the grid being transformed by theta[i]

  • gradient_grid (numpy.ndarray or torch.Tensor): [n_batch, n_points, d] tensor, with the gradient grid. The slice gradient_grid[i, j] corresponds to the gradient of grid being transformed by theta[i] and with respect to the parameter theta[j]

Return type:

tuple

gradient_space(grid, theta, method=None, time=1.0)[source]

Integrates and returns the gradient of the transformation w.r.t. the parametrization in theta.

Parameters:
Returns:

tuple containing

  • transformed_grid (numpy.ndarray or torch.Tensor): [n_batch, n_points] tensor, with the transformed grid. The slice transformed_grid[i] corresponds to the grid being transformed by theta[i]

  • gradient_grid (numpy.ndarray or torch.Tensor): [n_batch, n_points, d] tensor, with the gradient grid. The slice gradient_grid[i, j] corresponds to the gradient of grid being transformed by theta[i] and with respect to the parameter theta[j]

Return type:

tuple

interpolate(data, grid, outsize: int)[source]

Linear interpolation method

Parameters:

  • data (numpy.ndarray or torch.Tensor) – [n_batch, n_points, n_channels] tensor with input data.

  • grid (numpy.ndarray or torch.Tensor) – [n_batch, n_points] tensor with grid points that are used to interpolate the data

  • outsize – number of points in the output

Returns:

[n_batch, outsize, n_channels] tensor with the interpolated data

Return type:

interpolated(numpy.ndarray or torch.Tensor)

transform_data(data, theta, outsize: int, method=None, time=1.0)[source]

Combines the transform_grid and interpolate methods

Parameters:

  • data (numpy.ndarray or torch.Tensor) – [n_batch, n_points, n_channels] tensor with input data.

  • theta (numpy.ndarray or torch.Tensor) – [n_batch, d] matrix

  • outsize – number of points that is transformed and interpolated

  • method (str) – integration method, one of “closed_form”, “numeric”.

  • time (float) – integration time. Defaults to 1.0

Returns:

[n_batch, outsize, n_channels] tensor, transformed and interpolated data

Return type:

numpy.ndarray or torch.Tensor

transform_data_ss(data, theta, outsize, method=None, time=1.0, N=0)[source]

Combines the transform_grid with scaling-squaring and interpolate methods

Parameters:

  • data (numpy.ndarray or torch.Tensor) – [n_batch, n_points, n_channels] tensor with input data

  • theta (numpy.ndarray or torch.Tensor) – [n_batch, d] matrix

  • outsize – number of points that is transformed (with scaling and squaring) and interpolated

  • method (str) – integration method, one of “closed_form”, “numeric”

  • time (float) – integration time. Defaults to 1.0

  • N (int) – number of scaling iterations. Defaults to 0

Returns:

[n_batch, outsize, n_channels] tensor, transformed and interpolated data

Return type:

numpy.ndarray or torch.Tensor

calc_velocity(grid, theta)[source]

Calculates the velocity for each point in grid based on the theta parametrization

Parameters:
Returns:

[n_points] vector with velocity values

Return type:

numpy.ndarray or torch.Tensor

visualize_velocity(theta, n_points: Optional[int] = None, fig: Optional[Figure] = None)[source]

Visualizes the vectorfield for a specific parametrization vector theta

Parameters:
Returns:

handle to lines plot

Return type:

matplotlib.axes.Axes

visualize_deformgrid(theta, method=None, time: float = 1.0, n_points: int = 100, fig: Optional[Figure] = None)[source]

Visualizes the deformation for a specific parametrization vector theta

Parameters:
Returns:

handle to lines plot

Return type:

matplotlib.axes.Axes

visualize_tesselation(n_points: int = 50, fig: Optional[Figure] = None)[source]

Visualizes the tesselation for a specific parametrization vector theta

Parameters:
Returns:

handle to tesselation plot

Return type:

matplotlib.axes.Axes

visualize_gradient(theta, method=None, time: float = 1.0, n_points: int = 100, fig: Optional[Figure] = None)[source]

Visualizes the gradient for a specific parametrization vector theta

Parameters:
Returns:

handle to gradient plot

Return type:

matplotlib.axes.Axes

visualize_deformdata(data, theta, method=None, outsize: int = 100, target=None, fig: Optional[Figure] = None)[source]

Visualizes the transformed data for a specific parametrization vector theta

Parameters:

  • theta (numpy.ndarray or torch.Tensor) – [n_batch, d] matrix

  • method (str) – integration method, one of “closed_form”, “numeric”

  • outsize (int) – number of points that is transformed and interpolated

  • target (numpy.ndarray or torch.Tensor) – [n_batch, n_points, n_channels] tensor with target data.

  • time (float) – integration time. Defaults to 1.0

  • n_points (int) – number of points to plot

  • fig (matplotlib.figure.Figure) – matplotlib figure handle

Returns:

handle to gradient plot

Return type:

matplotlib.axes.Axes