torchdms.model¶

Generalized global epistasis models.

Classes

`Conditional`	Allows the latent space for the second output feature (i.e.
`ConditionalSequential`	Conditional with sequential training: stability then binding.
`Escape`	A model of viral escape with multiple epitopes, each with its own latent layer.
`FullyConnected`	A flexible fully connected neural network model.
`Independent`	Parallel and independent submodules of type `torchdms.model.FullyConnected` for each of two output dimensions.
`Linear`	A linear model, expressed as a single layer neural network with no nonlinear activations.
`TorchdmsModel`	An abstract superclass for our models to combine shared behavior.

class torchdms.model.TorchdmsModel(input_size, target_names, alphabet, monotonic_sign=None, non_lin_bias=False, output_bias=False)[source]¶

An abstract superclass for our models to combine shared behavior.

Parameters

input_size (int) – number of one-hot sequence indicators $L \times | A |$ , for sequence of length $L$ and amino acid alphabet $A$ .
target_names (List[str]) – output names (e.g. "expression", "stability").
alphabet (str) – amino acid alphabet $A$ .
monotonic_sign (Optional[bool]) – 1 or -1 for monotonicity, or None

__init__(input_size, target_names, alphabet, monotonic_sign=None, non_lin_bias=False, output_bias=False)[source]¶

output_size: int¶: output dimension (number of phenotypes)

layers: List[int]¶: list of layer names

training_style_sequence: List[Callable]¶: list of training style functions that (de)activate gradients in submodules

abstract property characteristics: Dict¶

Salient characteristics of the model that aren’t represented in the PyTorch description.

Return type: Dict

abstract property latent_dim: int¶

Number of dimensions in latent space.

Return type: int

abstract regularization_loss()[source]¶

Compute regularization penalty, a scalar-valued torch.Tensor

Return type: Tensor

abstract str_summary()[source]¶

A one-line summary of the model.

Return type: str

abstract beta_coefficients()[source]¶

Single mutant effects $β$

Return type: Tensor

abstract to_latent(x, **kwargs)[source]¶

Latent space representation $Z$

z \equiv ϕ (x) \equiv β^{⊺} x

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

abstract from_latent_to_output(z, **kwargs)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

forward(x, **kwargs)[source]¶

data $X$ $\to$ output $Y$ .

y = g (ϕ (x))

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

abstract fix_gauge(gauge_mask)[source]¶

Perform gauge-fixing procedure on latent space parameters.

Parameters: gauge_mask (Tensor) – 0/1 mask array the same shape as latent space input with 1s for parameters that should be zeroed

property sequence_length¶: input amino acid sequence length

numpy_single_mutant_predictions()[source]¶

Single mutant predictions as a numpy array of shape (AAs, sites, outputs).

Return type: ndarray

single_mutant_predictions()[source]¶

Single mutant predictions as a list (across output dimensions) of Pandas dataframes.

Return type: List[DataFrame]

monotonic_params_from_latent_space()[source]¶

Yields parameters to be floored to zero in a monotonic model. This is every parameter after the latent space excluding bias parameters.

We follow the convention that the latent layers of a network are named like latent_layer* and the weights and bias are denoted layer_name*.weight and layer_name*.bias.

Layers from nested modules will be prefixed (e.g. with Independent).

Return type: Generator[Tensor, None, None]

randomize_parameters()[source]¶: Randomize model parameters.

set_require_grad_for_all_parameters(value)[source]¶

Set require_grad for all parameters.

Parameters: value (bool) – require_grad=value for all parameters

seq_to_binary(seq)[source]¶: Takes a string of amino acids and creates an appropriate one-hot encoding.

class torchdms.model.Linear(*args, **kwargs)[source]¶

A linear model, expressed as a single layer neural network with no nonlinear activations.

Parameters

args – positional arguments, see torchdms.model.TorchdmsModel
kwargs – keyword arguments, see torchdms.model.TorchdmsModel

__init__(*args, **kwargs)[source]¶

property characteristics: Dict¶

Salient characteristics of the model that aren’t represented in the PyTorch description.

Return type: Dict

property latent_dim: int¶

Number of dimensions in latent space.

Return type: int

beta_coefficients()[source]¶

Single mutant effects $β$

Return type: Tensor

from_latent_to_output(z, **kwargs)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

regularization_loss()[source]¶

Compute regularization penalty, a scalar-valued torch.Tensor

Return type: Tensor

str_summary()[source]¶

A one-line summary of the model.

Return type: str

to_latent(x, **kwargs)[source]¶

Latent space representation $Z$

z \equiv ϕ (x) \equiv β^{⊺} x

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

fix_gauge(gauge_mask)[source]¶

Perform gauge-fixing procedure on latent space parameters.

Parameters: gauge_mask – 0/1 mask array the same shape as latent space input with 1s for parameters that should be zeroed

class torchdms.model.Escape(num_epitopes, *args, beta_l1_coefficient=0, **kwargs)[source]¶

A model of viral escape with multiple epitopes, each with its own latent layer.

The output is assumed to be escape fraction $\in (0, 1)$ . The nonlinearity is fixed as the product of Hill functions for each epitope.

Todo

model math markup, and schematic needed here

Parameters

num_epitopes – number of epitopes (latent dimensions)
args – base positional arguments, see torchdms.model.TorchdmsModel
beta_l1_coefficient (float) – lasso penalty on latent space $b e t a$ coefficients
kwargs – base keyword arguments, see torchdms.model.TorchdmsModel

__init__(num_epitopes, *args, beta_l1_coefficient=0, **kwargs)[source]¶

property characteristics: Dict¶

Salient characteristics of the model that aren’t represented in the PyTorch description.

Return type: Dict

property latent_dim: int¶

Number of dimensions in latent space.

Return type: int

str_summary()[source]¶: A one-line summary of the model.

to_latent(x, **kwargs)[source]¶

Latent space representation $Z$

z \equiv ϕ (x) \equiv β^{⊺} x

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

wt_activity()[source]¶

Wild type activity values for each epitope

Return type: Tensor

from_latent_to_output(z, concentrations=None)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

beta_coefficients()[source]¶

Single mutant effects $β$

Return type: Tensor

regularization_loss()[source]¶: Lasso penalty of single mutant effects, a scalar-valued torch.Tensor

fix_gauge(gauge_mask)[source]¶

Perform gauge-fixing procedure on latent space parameters.

Parameters: gauge_mask – 0/1 mask array the same shape as latent space input with 1s for parameters that should be zeroed

class torchdms.model.FullyConnected(layer_sizes, activations, *args, beta_l1_coefficient=0.0, interaction_l1_coefficient=0.0, **kwargs)[source]¶

A flexible fully connected neural network model.

Todo

schematic image

Parameters

layer_sizes (List[int]) – Sequence of widths for each layer between input and output.
activations (List[Callable]) –
Corresponding activation functions for each layer. The first layer with None or nn.Identity() activation is the latent space.

Todo

allowable activation function names?
args – base positional arguments, see torchdms.model.TorchdmsModel
beta_l1_coefficient (float) – lasso penalty on latent space $β$ coefficients
interaction_l1_coefficient (float) – lasso penalty on parameters in the pre-latent interaction layer(s)
kwargs – base keyword arguments, see torchdms.model.TorchdmsModel

Example

With layer_sizes = [10, 2, 10, 10] and activations = ["relu", None, "relu", "relu"] we have a latent space of 2 nodes, feeding into two more dense layers, each with 10 nodes, before the output. Layers before the latent layer are a nonlinear module for site-wise interactions, in this case one layer of 10 nodes. The latent space has skip connections directly from the input layer, so we always model single mutation effects.

__init__(layer_sizes, activations, *args, beta_l1_coefficient=0.0, interaction_l1_coefficient=0.0, **kwargs)[source]¶

property characteristics: Dict¶

Salient characteristics of the model that aren’t represented in the PyTorch description.

Return type: Dict

property internal_layer_dimensions: List[int]¶

List of widths of internal layers.

Return type: List[int]

property latent_dim: int¶

Number of dimensions in latent space.

Return type: int

str_summary()[source]¶

A one-line summary of the model.

Return type: str

fix_gauge(gauge_mask)[source]¶

Perform gauge-fixing procedure on latent space parameters.

Parameters: gauge_mask – 0/1 mask array the same shape as latent space input with 1s for parameters that should be zeroed

to_latent(x, **kwargs)[source]¶

Latent space representation $Z$

z \equiv ϕ (x) \equiv β^{⊺} x

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

from_latent_to_output(z, **kwargs)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

beta_coefficients()[source]¶

Beta coefficients (single mutant effects only, no interaction terms)

Return type: Tensor

regularization_loss()[source]¶

Lasso penalty of single mutant effects and pre-latent interaction weights, a scalar-valued torch.Tensor

Return type: Tensor

class torchdms.model.Independent(layer_sizes, activations, *args, beta_l1_coefficients=(0.0, 0.0), interaction_l1_coefficients=(0.0, 0.0), **kwargs)[source]¶

Parallel and independent submodules of type torchdms.model.FullyConnected for each of two output dimensions.

Todo

schematic image

Parameters

layer_sizes (List[int]) – Sequence of widths for each layer between input and output for both submodules.
activations (List[Callable]) –
Corresponding activation functions for each layer for both submodules. The first layer with None or nn.Identity() activation is the latent space.

Todo

allowable activation function names?
args – base positional arguments, see torchdms.model.TorchdmsModel
beta_l1_coefficients (Tuple[float]) – lasso penalties on latent space $β$ coefficients for each submodule
interaction_l1_coefficients (Tuple[float]) – lasso penalty on parameters in the pre-latent interaction layer(s) for each submodule
kwargs – base keyword arguments, see torchdms.model.TorchdmsModel

__init__(layer_sizes, activations, *args, beta_l1_coefficients=(0.0, 0.0), interaction_l1_coefficients=(0.0, 0.0), **kwargs)[source]¶

property characteristics: Dict¶

Salient characteristics of the model that aren’t represented in the PyTorch description.

Return type: Dict

property latent_dim: int¶

Number of dimensions in latent space.

Return type: int

str_summary()[source]¶

A one-line summary of the model.

Return type: str

from_latent_to_output(z, **kwargs)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

to_latent(x, **kwargs)[source]¶

Latent space representation $Z$

z \equiv ϕ (x) \equiv β^{⊺} x

Parameters: x (Tensor) – input data tensor $X$
Return type: Tensor

beta_coefficients()[source]¶

beta coefficients, skip coefficients only if interaction module.

Return type: Tensor

regularization_loss()[source]¶

Compute regularization penalty, a scalar-valued torch.Tensor

Return type: Tensor

fix_gauge(gauge_mask)[source]¶

Perform gauge-fixing procedure on latent space parameters.

Parameters: gauge_mask – 0/1 mask array the same shape as latent space input with 1s for parameters that should be zeroed

class torchdms.model.Conditional(*args, **kwargs)[source]¶

Allows the latent space for the second output feature (i.e. stability) to feed forward into the network for the first output feature (i.e. binding).

This requires a one-dimensional latent space (see torchdms.model.Conditional.from_latent_to_output() to see why).

Todo

schematic image: https://user-images.githubusercontent.com/1173298/89943302-d4524d00-dbd2-11ea-827d-6ad6c238ff52.png

Parameters

args – positional arguments, see torchdms.model.Independent
kwargs – keyword arguments, see torchdms.model.Independent

__init__(*args, **kwargs)[source]¶

from_latent_to_output(z, **kwargs)[source]¶

Evaluate the mapping from the latent space to output.

y = g (z)

Parameters: z (Tensor) – latent space representation
Return type: Tensor

class torchdms.model.ConditionalSequential(*args, **kwargs)[source]¶

Conditional with sequential training: stability then binding.

Todo

schematic image

Parameters

args – positional arguments, see torchdms.model.Conditional
kwargs – keyword arguments, see torchdms.model.Conditional

__init__(*args, **kwargs)[source]¶