core.outputmodules

This module contains the classes defining the output layer of the core.decoder.Decoder.

class core.outputmodules.OutputModuleNBFeatureDispersion(input_dim, output_dim, r_init, activation='softplus')

Class implementing an output layer representing the means of the negative binomial distributions modeling the outputs (i.e., the means of the gene expression counts). One negative binomial distribution with trainable mean is used for each gene.

__init__(input_dim, output_dim, r_init, activation='softplus')

Initialize an instance of the class.

Parameters:

input_dimint

The dimensionality of the input.

output_dimint

The dimensionality of the output.

r_initfloat

The initial ‘r’ value.

activationstr, {"sigmoid", "softplus"}, "softplus"

The name of the activation function to be used.

Available options are:

• "sigmoid": the sigmoid activation function.

• "softplus": the softplus activation function

forward(x)

Forward pass.

Parameters:

xtorch.Tensor

The input tensor.

Returns:

mtorch.Tensor

A tensor containing the means of the negative binomial distributions.

log_prob(obs_counts, pred_means, scaling_factors)

Get the log-probability mass of the negative binomial distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

The first dimension of this tensor must have a length equal to the number of samples whose counts are reported.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts and pred_means.

Returns:

log_prob_masstorch.Tensor

The log-probability mass of the negative binomial distributions.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts and pred_means.

• The second dimension has a length equal to the length of the second dimension of obs_counts and pred_means.

static log_prob_mass(k, m, r)

Compute the natural logarithm of the probability mass for a set of negative binomial distributions.

Thr formula used to compute the logarithm of the probability mass is:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log(m \cdot c + \epsilon) + r \cdot log(r \cdot c)\end{split}\]

Where \(\epsilon\) is a small value to prevent underflow/ overflow, and \(c\) is equal to \(\frac{1}{r+m+\epsilon}\).

The derivation of this formula from the non-logarithmic formulation of the probability mass function of the negative binomial distribution can be found below.

Parameters:

ktorch.Tensor

A one-dimensional tensor containing he “number of successes” seen before stopping the trials.

Each value in the tensor corresponds to the number of successes in a different negative binomial.

mtorch.Tensor

A one-dimensional tensor containing the means of the negative binomial distributions.

Each value in the tensor corresponds to the mean of a different negative binomial.

rtorch.Tensor

A one-dimensional tensor containing the “number of failures” after which the trials end.

Each value in the tensor corresponds to the number of failures in a different negative binomial.

Returns:

xtorch.Tensor

A one-dimensional tensor containing the lhe log-probability mass of each negative binomial distributions.

Each value in the tensor corresponds to the log-probability mass of a different negative binomial.

Notes

Here, we show how we derived the formula for the logarithm of the probability mass of the negative binomial distribution.

We start from the non-logarithmic version of the probability mass for the negative binomial, which is:

\[PDF_{NB(k,m,r)} = \binom{k+r-1}{k} (1-p)^{k} p^{r}\]

However, since:

• \(1-p\) is equal to \(\frac{m}{r+m}\)

• \(p\) is equal to \(\frac{r}{r+m}\)

• \(k+r-1\) can be rewritten in terms of the gamma function as \(\Gamma(k+r)\)

• \(k\) can also be rewritten as \(\Gamma(r) \cdot k!\)

The formula becomes:

\[PDF_{NB(k,m,r)} = \binom{\Gamma(k+r)}{\Gamma(r) \cdot k!} \left( \frac{m}{r+m} \right)^k \left( \frac{r}{r+m} \right)^r\]

However, \(k!\) can be also be rewritten as \(\Gamma(k+1)\), resulting in:

\[PDF_{NB(k,m,r)} = \binom{\Gamma(k+r)}{\Gamma(r) \cdot \Gamma(k+1)} \left( \frac{m}{r+m} \right)^k \left( \frac{r}{r+m} \right)^r\]

Then, we get the natural logarithm of both sides:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( \frac{m}{r+m} \right) + r \cdot log \left( \frac{r}{r+m} \right)\end{split}\]

Here, we are adding a small value \(\epsilon\) to prevent underflow/overflow:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( m \cdot \frac{1}{r+m+\epsilon} + \epsilon \right) + r \cdot log \left( r \cdot \frac{1}{r+m+\epsilon} \right)\end{split}\]

Finally, we substitute \(\frac{1}{r+m+\epsilon}\) with \(c\) and we obtain:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( m \cdot c + \epsilon \right) + r \cdot log \left( r \cdot c \right)\end{split}\]

loss(obs_counts, pred_means, scaling_factors)

Compute the loss given observed the means obs_counts and predicted scaled means pred_means, the latter rescaled by scaling_factors.

The loss corresponds to the negative log-probability mass of the binomial distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts and pred_means.

Returns:

losstorch.Tensor

The loss associated with the input x.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts and pred_means.

• The second dimension has a length equal to the length of the second dimension of obs_counts and pred_means.

static rescale(means, scaling_factors)

Rescale the means of the distributions.

Parameters:

meanstorch.Tensor

A 1D tensor containing the means of the distributions.

In the tensor, each value represents the mean of a different distribution.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length is equal to the number of scaling factors to be used to rescale the means.

Returns:

rescaled_meanstorch.Tensor

The rescaled means.

This is a 1D tensor whose length is equal to the number of distributions whose means were rescaled.

sample(n, pred_means, scaling_factors)

Get samples from the negative binomial distributions.

Parameters:

nint

The number of samples to get.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

scaling_factorstorch.Tensor

A tensor containing the scaling factors.

This is a 1D tensor whose length must match that of the first dimension of pred_means.

Returns:

samplestorch.Tensor

The samples drawn from the negative binomial distributions.

The shape of this tensor depends on the shape of n and pred_means, but the first dimension always has a length equal to the number of samples drawn from the negative binomial distribution.

property activation

The activation function used.

property input_dim

The dimensionality of the input.

property log_r

The natural logarithm of the ‘r’ values associated with the negative binomial distributions.

property output_dim

The dimensionality of the output.

class core.outputmodules.OutputModuleNBFullDispersion(input_dim, output_dim, activation='softplus')

Class implementing an output layer representing the means of the negative binomial distributions modeling the outputs (i.e., the means of the gene expression counts). One negative binomial distribution with trainable parameters is used for each gene.

__init__(input_dim, output_dim, activation='softplus')

Initialize an instance of the class.

Parameters:

input_dimint

The dimensionality of the input.

output_dimint

The dimensionality of the output.

activationstr, {"sigmoid", "softplus"}, "softplus"

The name of the activation function to be used.

Available options are:

• "sigmoid": the sigmoid activation function.

• "softplus": the softplus activation function

forward(x)

Forward pass.

Parameters:

xtorch.Tensor

The input tensor.

Returns:

mtorch.Tensor

A tensor containing the means of the negative binomial distributions.

log_rtorch.Tensor

A tensor containing the logarithm of the ‘r’ values of the negative binomial distributions.

log_prob(obs_counts, pred_means, pred_log_r_values, scaling_factors)

Get the log-probability mass of the negative binomial distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

The first dimension of this tensor must have a length equal to the number of samples whose counts are reported.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts.

pred_log_r_valuestorch.Tensor

The predicted logarithm of the r-values of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts and. pred_means.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts, pred_means, and pred_log_r_values.

Returns:

log_prob_masstorch.Tensor

The log-probability mass.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts,``pred_means``, and pred_log_r_values.

• The second dimension has a length equal to the length of the second dimension of obs_counts,``pred_means``, and pred_log_r_values.

static log_prob_mass(k, m, r)

Compute the natural logarithm of the probability mass for a set of negative binomial distributions.

Thr formula used to compute the logarithm of the probability mass is:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log(m \cdot c + \epsilon) + r \cdot log(r \cdot c)\end{split}\]

Where \(\epsilon\) is a small value to prevent underflow/ overflow, and \(c\) is equal to \(\frac{1}{r+m+\epsilon}\).

The derivation of this formula from the non-logarithmic formulation of the probability mass function of the negative binomial distribution can be found below.

Parameters:

ktorch.Tensor

A one-dimensional tensor containing he “number of successes” seen before stopping the trials.

Each value in the tensor corresponds to the number of successes in a different negative binomial.

mtorch.Tensor

A one-dimensional tensor containing the means of the negative binomial distributions.

Each value in the tensor corresponds to the mean of a different negative binomial.

rtorch.Tensor

A one-dimensional tensor containing the “number of failures” after which the trials end.

Each value in the tensor corresponds to the number of failures in a different negative binomial.

Returns:

xtorch.Tensor

A one-dimensional tensor containing the lhe log-probability mass of each negative binomial distributions.

Each value in the tensor corresponds to the log-probability mass of a different negative binomial.

Notes

Here, we show how we derived the formula for the logarithm of the probability mass of the negative binomial distribution.

We start from the non-logarithmic version of the probability mass for the negative binomial, which is:

\[PDF_{NB(k,m,r)} = \binom{k+r-1}{k} (1-p)^{k} p^{r}\]

However, since:

• \(1-p\) is equal to \(\frac{m}{r+m}\)

• \(p\) is equal to \(\frac{r}{r+m}\)

• \(k+r-1\) can be rewritten in terms of the gamma function as \(\Gamma(k+r)\)

• \(k\) can also be rewritten as \(\Gamma(r) \cdot k!\)

The formula becomes:

\[PDF_{NB(k,m,r)} = \binom{\Gamma(k+r)}{\Gamma(r) \cdot k!} \left( \frac{m}{r+m} \right)^k \left( \frac{r}{r+m} \right)^r\]

However, \(k!\) can be also be rewritten as \(\Gamma(k+1)\), resulting in:

\[PDF_{NB(k,m,r)} = \binom{\Gamma(k+r)}{\Gamma(r) \cdot \Gamma(k+1)} \left( \frac{m}{r+m} \right)^k \left( \frac{r}{r+m} \right)^r\]

Then, we get the natural logarithm of both sides:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( \frac{m}{r+m} \right) + r \cdot log \left( \frac{r}{r+m} \right)\end{split}\]

Here, we are adding a small value \(\epsilon\) to prevent underflow/overflow:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( m \cdot \frac{1}{r+m+\epsilon} + \epsilon \right) + r \cdot log \left( r \cdot \frac{1}{r+m+\epsilon} \right)\end{split}\]

Finally, we substitute \(\frac{1}{r+m+\epsilon}\) with \(c\) and we obtain:

\[\begin{split}logPDF_{NB(k,m,r)} &= log\Gamma(k+r) - log\Gamma(r) - log\Gamma(k+1) \\ &+ k \cdot log \left( m \cdot c + \epsilon \right) + r \cdot log \left( r \cdot c \right)\end{split}\]

loss(obs_counts, pred_means, pred_log_r_values, scaling_factors)

Compute the loss given observed the means obs_counts, the predicted scaled means pred_means (rescaled by scaling_factors), and the predicted logarithm of the r-values (pred_log_r_values) of the negative binomial distributions

The loss corresponds to the negative log-probability mass of the negative binomial distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts.

pred_log_r_valuestorch.Tensor

The predicted logarithm of the r-values of the negative binomial distributions.

This is a tensor whose shape must match that of obs_counts and. pred_means.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts, pred_means, and pred_log_r_values.

Returns:

losstorch.Tensor

The loss associated with the input x.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts,``pred_means``, and pred_log_r_values.

• The second dimension has a length equal to the length of the second dimension of obs_counts,``pred_means``, and pred_log_r_values.

static rescale(means, scaling_factors)

Rescale the means of the distributions.

Parameters:

meanstorch.Tensor

A 1D tensor containing the means of the distributions.

In the tensor, each value represents the mean of a different distribution.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length is equal to the number of scaling factors to be used to rescale the means.

Returns:

rescaled_meanstorch.Tensor

The rescaled means.

This is a 1D tensor whose length is equal to the number of distributions whose means were rescaled.

sample(n, pred_means, pred_log_r_values, scaling_factors)

Get samples from the negative binomial distributions.

Parameters:

nint

The number of samples to get.

pred_meanstorch.Tensor

The predicted scaled means of the negative binomial distributions.

pred_log_r_valuestorch.Tensor

The predicted logarithm of the r-values of the negative binomial distributions.

This is a 2D tensor whose shape must match that of pred_means.

scaling_factorstorch.Tensor

A tensor containing the scaling factors.

This is a 1D tensor whose length must match that of the first dimension of pred_means and pred_log_r_values.

Returns:

samplestorch.Tensor

The samples drawn from the negative binomial distributions.

The shape of this tensor depends on the shape of n and pred_means/pred_log_r_values, but the first dimension always has a length equal to the number of samples drawn from the negative binomial distribution.

property activation

The activation function used.

property input_dim

The dimensionality of the input.

property output_dim

The dimensionality of the output.

class core.outputmodules.OutputModulePoisson(input_dim, output_dim, activation='softplus')

__init__(input_dim, output_dim, activation='softplus')

Initialize an instance of the class.

Parameters:

input_dimint

The dimensionality of the input.

output_dimint

The dimensionality of the output.

activationstr, {"sigmoid", "softplus"}, "softplus"

The name of the activation function to be used.

Available options are:

• "sigmoid": the sigmoid activation function.

• "softplus": the softplus activation function.

forward(x)

Forward pass.

Parameters:

xtorch.Tensor

The input tensor.

Returns:

mtorch.Tensor

A tensor containing the means of the Poisson distributions.

log_prob(obs_counts, pred_means, scaling_factors)

Get the log-probability mass of the Poisson distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

The first dimension of this tensor must have a length equal to the number of samples whose counts are reported.

pred_meanstorch.Tensor

The predicted means of the Poisson distributions.

This is a tensor whose shape must match that of obs_counts.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts and pred_means.

Returns:

log_prob_masstorch.Tensor

The log-probability mass of the Poisson distributions.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts and pred_means.

• The second dimension has a length equal to the length of the second dimension of obs_counts and pred_means.

static log_prob_mass(k, m)

Compute the natural logarithm of the probability mass for a set of Poisson distributions.

The formula used to compute the logarithm of the probability mass is:

\[logPDF_{Poisson(k,m)} &= k * log(m + \epsilon) - m - log\Gamma(k+1)\]

Where \(\epsilon\) is a small value to prevent underflow/ overflow.

The derivation of this formula from the non-logarithmic formulation of the probability mass function of the Poisson distribution can be found below.

Parameters:

ktorch.Tensor

A one-dimensional tensor containing he “number of successes” seen before stopping the trials.

Each value in the tensor corresponds to the number of successes in a different Poisson distribution.

mtorch.Tensor

A one-dimensional tensor containing the means of the Poisson distributions.

Each value in the tensor corresponds to the mean of a different Poisson distribution.

Returns:

xtorch.Tensor

A one-dimensional tensor containing the lhe log-probability mass of each Poisson distribution.

Each value in the tensor corresponds to the log-probability mass of a different Poisson distribution.

Notes

Here, we show how we derived the formula for the logarithm of the probability mass of the Poisson distribution.

We start from the non-logarithmic version of the probability mass for the Poisson distribution, which is:

\[PDF_{Poisson(k,m)} = \frac{m^{k}e^{-m}}{k!}\]

However, since:

• \(k!\) can be rewritten in terms of the gamma function as \(\Gamma(k+1)\)

The formula becomes:

\[PDF_{Poisson(k,m)} = \frac{m^{k}e^{-m}}{\Gamma(k+1)}\]

Then, we get the natural logarithm of both sides:

\[logPDF_{Poisson(k,m)} &= k * log(m) - m - log\Gamma(k+1)\]

Finally, we add a small value \(\epsilon\) to prevent underflow/overflow:

\[logPDF_{Poisson(k,m)} &= k * log(m + \epsilon) - m - log\Gamma(k+1)\]

loss(obs_counts, pred_means, scaling_factors)

Compute the loss given observed the means obs_counts and predicted means pred_means, the latter rescaled by scaling_factors.

The loss corresponds to the negative log-probability mass of the Poisson distributions.

Parameters:

obs_countstorch.Tensor

The observed gene counts.

pred_meanstorch.Tensor

The predicted means of the Poisson distributions.

This is a tensor whose shape must match that of obs_counts.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length must match that of the first dimension of obs_counts and pred_means.

Returns:

losstorch.Tensor

The loss associated with the input x.

This is a 2D tensor where:

• The first dimension has a length equal to the length of the first dimension of obs_counts and pred_means.

• The second dimension has a length equal to the length of the second dimension of obs_counts and pred_means.

static rescale(means, scaling_factors)

Rescale the means of the distributions.

Parameters:

meanstorch.Tensor

A 1D tensor containing the means of the distributions.

In the tensor, each value represents the mean of a different distribution.

scaling_factorstorch.Tensor

The scaling factors.

This is a 1D tensor whose length is equal to the number of scaling factors to be used to rescale the means.

Returns:

rescaled_meanstorch.Tensor

The rescaled means.

This is a 1D tensor whose length is equal to the number of distributions whose means were rescaled.

sample(n, pred_means, scaling_factors)

Get samples from the Poisson distributions.

Parameters:

nint

The number of samples to get.

pred_meanstorch.Tensor

The predicted means of the Poisson distributions.

scaling_factorstorch.Tensor

A tensor containing the scaling factors.

This is a 1D tensor whose length must match that of the first dimension of pred_means.

Returns:

samplestorch.Tensor

The samples drawn from the Poisson distributions.

The shape of this tensor depends on the shape of n and pred_means, but the first dimension always has a length equal to the number of samples drawn from the Poisson distribution.

property activation

The activation function used.

property input_dim

The dimensionality of the input.

property output_dim

The dimensionality of the output.