models module

class arch.models.Diresa(*args: Any, **kwargs: Any)

Distance Regularized Autoencoder.

Can be built using class method from_hyper_param which builds the encoder and decoder from a list of hyperparameters. DIRESA can also be built by providing a custom encoder and decoder using class method from_custom.

classmethod from_hyper_param(input_shape: Tuple[int, ...] = (), activation: torch.nn.Module = torch.nn.ReLU, dense_units: Tuple[int, ...] | None = None, stack: Tuple[int, ...] | None = None, stack_filters: Tuple[int, ...] | None = None, kernel_size: Tuple[int, int] = (3, 3), attention: bool | Tuple[bool, ...] = False)

Builds DIRESA from hyperparameters. DIRESA can be built using fully connected layers, CNN layers or a combination of both.

The argument dense_units is used to add fully connected layers, where the length of the tuple represents depth of the network and each individual value represents the number of nodes per layer. First element describes the first hidden layer. Last layer defines the output layer which is the size of latent space. E.g. dense_units = (16, 32, 64) is a fully connected network with two hidden layers (16, 32) and last layer which defines latent space of size 64. When only one value is present it represents a linear projection on to a latent space with dimensions of that value (as for the last layer no activation is used).

To build a convolutional encoder, parameters stack and stack_filters have to be provided. stack handles the number of convolutional layers per block and stack_filters handles the number of filters per block. That is, if stack = (2, 1) and stack_filters = (16, 8), the encoder network is going to be split as [Conv2D 16 -> Activation -> Conv2D 16 -> Activation] -> MaxPool -> [Conv2D 8] -> MaxPool -> Flatten. Each block is always followed by a MaxPool layer and at the end a Flatten layer is added.

The attention parameter indicates whether an attention layer is added before the MaxPool (or UpSample) layer.

If dense parameters and convolutional parameters are both specified the network is built as follows: [CNN] -> [Dense] -> LatentSpace -> [Dense] -> [CNN].

Parameters:

  • input_shape – is the shape of input features

  • activation – activation function used by all layers, except for the last layer of the encoder/decoder, which doesn’t have an activation function

  • stack – the number of Conv2D layers in each block

  • stack_filters – number of filters (out channels) for the Conv2D layers in each block, len(stack_filters) has to be equal to len(stack)

  • kernel_size – kernel size for all Conv2D layers

  • attention – whether to add an attention layer in a block, bool or list of bool (len has to be equal to len(stack))

  • dense_units – tuple which describes the width of each fully connected layer

classmethod from_custom(encoder: torch.nn.Module, decoder: torch.nn.Module)

Builds Diresa from custom provided encoder and decoder. Distance and ordering layers are added through the Diresa class.

Parameters:

  • encoder – encoder model

  • decoder – decoder model

get_ordering() → torch.Tensor | None
Returns:

Tensor representing ordering of the latent components by R2-score or None if no ordering has been computed yet.

is_ordered() → bool

Returns True if ordering of the latent components has been computed on the model, False otherwise.

Returns:

Ordering status

reset_ordering() → torch.Tensor | None

Removes current ordering and returns it.

Returns:

Tensor representing current ordering or None if no ordering has been computed yet.

encode(x: torch.Tensor) → torch.Tensor

Runs encoder to provide latent space representation, latent components are ordered by R2-score if ordering has been previously computed.

Parameters:

x – batch of original data

Returns:

encoded batch, ordered if ordering has been previously computed.

decode(x: torch.Tensor) → torch.Tensor

Runs decoder to provide reconstructed data from latent space representation (keeping ordering of the latent components in mind if ordering has been computed).

Parameters:

x – batch of latent data.

Returns:

decoded batch

forward(x: torch.Tensor, x_twin: torch.Tensor | None = None) → Tuple[torch.Tensor, torch.Tensor, torch.Tensor]

Produces reconstructed, latent and distance information

fast_eval(x: torch.Tensor) → torch.Tensor

Produces a reconstructed output by using only encoder and decoder. This skips the distance layer and ordering layer.

Parameters:

x – batch to evaluate.