smoother.models.deconv

Deconvolute spatial-omics data with spatial loss

Classes

`SpatialLoss`	Spatial loss.
`TopLoss`	Topological loss.
`DeconvModel`	Interface for convex deconvolution models.
`DeconvModelTorch`	Class for deconvolution models implemented using pytorch.
`LinearRegressionTorch`	Linear regression implemented using pytorch.
`NNLSTorch`	Non-negative least square implemented using pytorch.
`NuSVRTorch`	Nu-Support vector regression implemented using pytorch.
`DWLSTorch`	Damped weighted least square implemented using pytorch.
`LogNormRegTorch`	Log-normal deconvolution implemented using pytorch.
`DeconvModelConvex`	Class for convex deconvolution models implemented using cvxpy.
`LinearRegressionConvex`	Linear regression implemented using cvxpy.
`NNLSConvex`	Non-negative least square implemented using cvxpy.
`DWLSConvex`	Damped weighted least square implemented using cvxpy.
`NuSVRConvex`	Nu-Support vector regression implemented using cvxpy.

Functions

`LinearRegression`(→ DeconvModel)
`NNLS`(→ DeconvModel)
`NuSVR`(→ DeconvModel)
`DWLS`(→ DeconvModel)
`LogNormReg`(→ DeconvModel)
`_deconv_torch`(x, y, deconv_model[, spatial_loss, ...])	Train a regression-based spatial deconvolution model.
`_nu_svr_loss`(input, target, coefs, C, nu, epsilon[, ...])	Calculate nu-SVR loss.
`_dwls_loss`(input, target[, max_weights])	Calculate dampened weighted least square loss.

Module Contents

class smoother.models.deconv.SpatialLoss(prior, spatial_weights: List[smoother.weights.SpatialWeightMatrix] = None, rho=1, use_sparse=True, standardize_cov=False)

Bases: torch.nn.Module

Spatial loss.

The spatial smoothing loss on a spatial random variable (num_group x num_spot).

prior

The prior spatial process model, can be one of ‘sma’,’sar’, ‘car’, ‘icar’.

Type:: str

spatial_weights

Spatial weight matrix collection of length num_group or 1. If 1 then all groups will be subject to the same covariance.

Type:: List[SpatialWeightMatrix]

rho

The spatial autocorrelation parameter (for SpatialWeightMatrix.get_inv_cov).

Type:: float

use_sparse

Whether to use sparse inverse covariance matrix in the calculation.

Type:: bool

standardize_cov

Whether to standardize the covariance matrix to have same variance (1) across locations. Only proper covariance can be standardized.

Type:: bool

inv_cov

Inverse covariance (precision) matrix of spatial variables of each group, (num_group or 1) x n x n. If the first dimension has length 1, all groups will have the same covariance structure.

Type:: 3D tensor

inv_cov_2d_sp

Sparse block diagonal inverse covariance (precision) matrix.

Type:: 2D sparse tensor

confidences

Relative prior confidence of each group. The higher the confidence, the stronger the smoothing will be. If float, all groups will have the same confidence.

Type:: 1D tensor or float

_sanity_check() → None: Check whether the spatial loss is defined properly.

estimate_confidence(ref_exp, st_exp, method='lr') → None

Estimate the relative confidence for each group.

The covariance matrix will be scaled accordingly.

Parameters:

ref_exp (2D tensor) – Bulk expression signiture matrix, num_gene x num_group.
st_exp (2D tensor) – Spatial expression matrix, num_gene x num_spot.
method (str) – Method used to estimate variance.

forward(coefs, normalize=True)

Calculate spatial loss.

Parameters:: coefs (2D tensor) – Columns of regression coefficients, num_group x num_spot.

calc_corr_decay_stats(coords, min_k=0, max_k=50, cov_ind=0, return_var=False)

Calculate spatial covariance decay over degree of neighborhoods.

Covariance measured between k-nearest neighbors. If the number of covariance matrices (i.e. self.inv_cov.shape[0]) is larger than 1, use ‘cov_ind’ to select the covariance matrix to use.

Parameters:

coords (2D tensor) – Coordinates of spots, num_spot x 2.
min_k – Minimum number of k in k-nearest neighbors. k = 0: self.
max_k – Maximum number of k in k-nearest neighbors.
cov_ind (int) – Index of the covariance matrix to use.
return_var (bool) – Whether to return variance stats.

Returns:

Correlation decay quantiles. var_quantiles_df (pd.DataFrame): Per-spot variance quantiles.

Return type:

corr_decay_quantiles_df (pd.DataFrame)

class smoother.models.deconv.TopLoss(betti_priors: dict, coords_xy)

Bases: torch.nn.Module

Topological loss.

The topological smoothing loss on a spatial random variable (num_group x num_spot).

betti_prior

A nested dictionary that specifies topological priors for each group. {group_id: {betti_k : expectation}}.

Type:: dict

coords_xy

Spatial coordinates (2D), num_spot x 2.

Type:: 2D array

pdfn

Super-level set layer.

Type:: topologylayer.nn.LevelSetLayer2D

topfn

Topological features for each group. {group_id: {betti_k: topologylayer.nn.PartialSumBarcodeLengths}}.

Type:: dict

reshape_coefs(beta, pad_value: float = None)

Reshape 2D coefficients into 3D and pad with zeros.

The original coefficient matrix has 1 location axis (the first dimension) while the transformed matrix will have 2 location axes (x and y, the first two). Spatial arrangement specified in self.coords_xy.

Parameters:

beta (2D array) – Columns of regression coefficients, num_group x num_spot.
pad_value (float) – Value of coefficients at unobserved regions.

forward(coefs)

Calculate topological loss.

Parameters:: coefs (2D tensor) – Columns of regression coefficients, num_group x num_spot.

class smoother.models.deconv.DeconvModel

Interface for convex deconvolution models.

abstract get_model_loss(): Get regression reconstruction loss.

abstract get_sp_loss(): Get spatial loss (weighted by lambda_spatial_loss).

abstract get_props(): Get the predicted celltype abundance from the trained deconvolution model.

smoother.models.deconv.LinearRegression(backend='pytorch', **kwargs) → DeconvModel

smoother.models.deconv.NNLS(backend='pytorch', **kwargs) → DeconvModel

smoother.models.deconv.NuSVR(backend='pytorch', **kwargs) → DeconvModel

smoother.models.deconv.DWLS(backend='pytorch', **kwargs) → DeconvModel

smoother.models.deconv.LogNormReg(backend='pytorch', **kwargs) → DeconvModel

class smoother.models.deconv.DeconvModelTorch(dim_in, dim_out, model_name)

Bases: torch.nn.Module, DeconvModel

Class for deconvolution models implemented using pytorch.

dim_in

Input dimension, also number of groups.

Type:: int

dim_out

Output dimension, also number of spots.

Type:: int

use_bias

Whether to add bias term in regression.

Type:: bool

model_name

Name of the deconvolution model.

Type:: str

nonneg

Whether to apply nonnegative contraint on spatial variables.

Type:: bool

deconv_configs

Dictionary of deconvolution configurations.

Type:: dict

deconv_time

Time spent on deconvolution.

Type:: float

abstract set_params(dim_in, dim_out, bias)

abstract get_top_loss(): Get toplogical loss (weighted by lambda_top_loss).

abstract init_with_lr_sol(x, y): Initialize model with linear regression solution.

abstract final_sanity_check(): Make sure constraints are followed after deconvolution.

deconv(x, y, spatial_loss: smoother.losses.SpatialLoss = None, lambda_spatial_loss=0.0, top_loss: smoother.losses.TopLoss = None, lambda_top_loss=0.0, lr=0.001, max_epochs=1000, patience=10, tol=1e-05, init_with_lr_sol=True, verbose=True, quiet=False)

Deconvolute spatial-omics data with spatial loss.

Loss_total = Loss_model + lambda_spatial_loss * Loss_spatial +: lambda_top_loss * Loss_topological.

Parameters:

x (2D tensor) – Bulk feature signiture matrix, num_feature x num_group.
y (2D tensor) – Spatial feature matrix, num_feature x num_spot.
spatial_loss (SpatialLoss) – The spatial smoothing loss. Spatial prior can be one of ‘none’, ‘kl’, ‘sma’, ‘sar’, ‘car’, ‘icar’ - KL : KL divergence of cell type proportion vectors of neiboring spots - SMA : Spatial moving average - SAR : Simultaneous auto-regressive model - CAR : Conditional auto-regressive model - ICAR : Intrinsic conditional auto-regressive model See model description for more details.
lambda_spatial_loss (float) – Specifies the strength of the spatial smoothing.
top_loss (TopLoss) –
The topological loss (expected betti number for each group). top_loss.betti_priors = {

group_id : {betti_k : expected number of barcodes (prior)}, …

}
lambda_top_loss (float) – Specifies the strength of the topological constraints.
lr (float) – Learning rate.
max_epochs (int) – Maximum number of training epochs. If -1, iterate until convergence (d_loss < 1e-5).
patient (int) – Number of epochs to wait for the loss to decrease before stopping.
tol (float) – Tolerance of loss convergence.
init_with_lr_sol (bool) – Whether to initialize regression weights with the OLE solution.
verbose (bool) – If True, print out loss while training.
quiet (bool) – If True, no output printed.

smoother.models.deconv._deconv_torch(x, y, deconv_model: DeconvModelTorch, spatial_loss: smoother.losses.SpatialLoss = None, lambda_spatial_loss=1.0, top_loss: smoother.losses.TopLoss = None, lambda_top_loss=0.0, lr=0.001, max_epochs=1000, patience=10, tol=1e-05, init_with_lr_sol=True, verbose=True, quiet=False, return_model=True)

Train a regression-based spatial deconvolution model.

Loss_total = Loss_model + lambda_spatial_loss * Loss_spatial +: lambda_top_loss * Loss_topological.

Parameters:

x (2D tensor) – Bulk feature signiture matrix, num_feature x num_group.
y (2D tensor) – Spatial feature matrix, num_feature x num_spot.
deconv_model (DeconvModelTorch) – A deconvolution model to be used. Model can be one of ‘linear’, ‘nnls’, ‘svr’, or ‘dwls’. The ‘svr’ model takes ‘C’ and ‘nu’ as two additional inputs, see https://scikit-learn.org/stable/modules/generated/sklearn.svm.NuSVR.html.
spatial_loss (SpatialLoss) – The spatial smoothing loss. Spatial prior can be one of ‘none’, ‘kl’, ‘sma’, ‘sar’, ‘car’, ‘icar’ - KL : KL divergence of cell type proportion vectors of neiboring spots - SMA : Spatial moving average - SAR : Simultaneous auto-regressive model - CAR : Conditional auto-regressive model - ICAR : Intrinsic conditional auto-regressive model See model description for more details.
lambda_spatial_loss (float) – Specifies the strength of the spatial smoothing.
top_loss (TopLoss) –
The topological loss (expected betti number for each group). top_loss.betti_priors = {

group_id : {betti_k : expected number of barcodes (prior)}, …

}
lambda_top_loss (float) – Specifies the strength of the topological constraints.
lr (float) – Learning rate.
max_epochs (int) – Maximum number of training epochs. If -1, iterate until convergence (d_loss < 1e-5).
patient (int) – Number of epochs to wait for the loss to decrease before stopping.
tol (float) – Tolerance of loss convergence.
init_with_lr_sol (bool) – Whether to initialize regression weights with the OLE solution.
verbose (bool) – If True, print out loss while training.
quiet (bool) – If True, no output printed.
return_model (bool) – If True, return the trained model.

class smoother.models.deconv.LinearRegressionTorch(bias=True, dim_in=1, dim_out=1)

Bases: DeconvModelTorch

Linear regression implemented using pytorch.

set_params(dim_in, dim_out, bias=True) → None

forward(x)

get_model_loss_fn()

get_model_loss(): Calculate regression loss.

get_sp_loss(): Calculate spatial loss (weighted by lambda_spatial_loss).

get_top_loss(): Calculate topological loss (weighted by lambda_top_loss).

get_props(): Get the predicted celltype abundance from the trained deconvolution model.

init_with_lr_sol(x, y): Initialize model with linear regression solution.

final_sanity_check(): Make sure constraints are satisfied.

class smoother.models.deconv.NNLSTorch(bias=True, dim_in=1, dim_out=1)

Bases: LinearRegressionTorch

Non-negative least square implemented using pytorch.

class smoother.models.deconv.NuSVRTorch(bias=True, dim_in=1, dim_out=1, C=1.0, nu=0.1, nonneg=False, loss_mode='l2')

Bases: LinearRegressionTorch

Nu-Support vector regression implemented using pytorch.

C

SVR regularization parameter.

Type:: float

nu

Nu-SVR parameter.

Type:: float

epsilon

Epsilon in the epsilon-SVR model, specifying the the epsilon-tube within which no penalty is associated in the training loss function with points predicted within a distance epsilon from the actual value.

Type:: float

loss_mode

Specifies the regression loss function to use. Either ‘l2’ or ‘l1’.

Type:: str

get_model_loss_fn()

final_sanity_check(): Make sure constraints are satisfied.

smoother.models.deconv._nu_svr_loss(input, target, coefs, C, nu, epsilon, reduction='mean', loss='l2')

Calculate nu-SVR loss.

Parameters:

input (2D tensor) – Predicted spatial features (pred = X * beta), num_feature x num_spot.
target (2D tensor) – Observed spatial features, num_feature x num_spot.
coefs (2D tenor) – Columns of regression coefficients, num_group x num_spot.
C (float) – SVR regularization parameter.
nu (float) – Nu-SVR parameter.
epsilon (float) – Epsilon in the epsilon-SVR model, specifying the the epsilon-tube within which no penalty is associated in the training loss function with points predicted within a distance epsilon from the actual value.
reduction (str) – Specifies the reduction to apply to the output.
loss (str) – Specifies the regression loss function to use. Either ‘l2’ or ‘l1’.

Returns:

Aggregated nu-SVR loss.

Return type:

loss (float)

class smoother.models.deconv.DWLSTorch(bias=True, dim_in=1, dim_out=1, nonneg=True, max_weights=8)

Bases: LinearRegressionTorch

Damped weighted least square implemented using pytorch.

Here the error term for each feature is scaled by its observed value, not the predicted value as described in https://www.nature.com/articles/s41467-019-10802-z.

max_weights

The upper limit of weights.

Type:: float

get_model_loss_fn()

smoother.models.deconv._dwls_loss(input, target, max_weights=8)

Calculate dampened weighted least square loss.

Here the error term for each feature is scaled by its observed value, not the predicted value as described in https://www.nature.com/articles/s41467-019-10802-z.

Parameters:

input (2D tensor) – Predicted spatial features (pred = X * beta), num_feature x num_spot.
target (2D tensor) – Observed spatial features, num_feature x num_spot.
max_weights (float) – The upper limit of weights.

class smoother.models.deconv.LogNormRegTorch(bias=True, epsilon=1, dim_in=1, dim_out=1)

Bases: LinearRegressionTorch

Log-normal deconvolution implemented using pytorch.

Minimize MSE(log(Y), log(X @ W)). Here Y and X are all in the raw count space.

Instead of minimizing the least square loss, this model will minimize MSE after log-transforming both observation and prediction, as described in in https://www.nature.com/articles/s41467-022-28020-5 as Algorithm 1.

epsilon

pseudo count added before log transformation.

Type:: float

get_model_loss_fn()

class smoother.models.deconv.DeconvModelConvex(dim_in, dim_out, model_name)

Bases: DeconvModel

Class for convex deconvolution models implemented using cvxpy.

dim_in

Input dimension, also number of groups.

Type:: int

dim_out

Output dimension, also number of spots.

Type:: int

model_name

Name of the deconvolution model.

Type:: str

nonneg

Whether to apply nonnegative contraint on spatial variables.

Type:: bool

deconv_configs

Dictionary of deconvolution configurations.

Type:: dict

deconv_time

Time spent on deconvolution.

Type:: float

abstract set_params(configs) → bool: Set model parameters. Return True if warm start.

abstract get_model_loss(): Get regression reconstruction loss.

abstract get_sp_loss(): Get spatial loss (weighted by lambda_spatial_loss).

abstract get_props(): Get the predicted celltype abundance from the trained deconvolution model.

deconv(x, y, spatial_loss: smoother.losses.SpatialLoss = None, lambda_spatial_loss=0.0, verbose=False, quiet=False, solver=None, **kwargs)

Solve the regression-based spatial deconvolution problem using cvxpy.

Loss_total = Loss_model + lambda_spatial_loss * Loss_spatial

See https://www.cvxpy.org/tutorial/advanced/index.html#solve-method-options for solver options.

Parameters:

x (2D tensor) – Bulk feature signiture matrix, num_feature x num_group.
y (2D tensor) – Spatial feature matrix, num_feature x num_spot.
spatial_loss (SpatialLoss) – The spatial smoothing loss. Spatial prior can be one of ‘none’, ‘kl’, ‘sma’, ‘sar’, ‘car’, ‘icar’ - KL : KL divergence of cell type proportion vectors of neiboring spots - SMA : Spatial moving average - SAR : Simultaneous auto-regressive model - CAR : Conditional auto-regressive model - ICAR : Intrinsic conditional auto-regressive model See model description for more details.
lambda_spatial_loss (float) – Specifies the strength of the spatial smoothing. Notice that setting spatial_loss = None will be more efficient than setting lambda_spatial_loss = 0, but the former won’t benefit from warm start (i.e., speedup when only lambda_spatial_loss is changed).
verbose (bool) – If True, print solver output.
quiet (bool) – If True, no output printed, including final message.
solver (str) – The solver to use.
kwargs – Additional keyword arguments specifying solver specific options.

class smoother.models.deconv.LinearRegressionConvex(bias=True, dim_in=1, dim_out=1)

Bases: DeconvModelConvex

Linear regression implemented using cvxpy.

set_lambda_only(configs) → bool

Check if the same configuration is used except lambda_spatial_loss.

If True, will only update lambda_spatial_loss and enable warm start.

set_params(configs) → bool: Set model parameters. Return True if warm start.

set_model_loss(): Set model reconstruction loss.

set_sp_loss(): Set spatial loss.

get_model_loss(): Get model regression reconstruction loss.

get_sp_loss(): Get spatial loss (weighted by lambda_spatial_loss).

get_props(): Get the predicted celltype abundance from the trained deconvolution model.

class smoother.models.deconv.NNLSConvex(bias=True, dim_in=1, dim_out=1)

Bases: LinearRegressionConvex

Non-negative least square implemented using cvxpy.

class smoother.models.deconv.DWLSConvex(bias=True, dim_in=1, dim_out=1, nonneg=True, max_weights=8)

Bases: LinearRegressionConvex

Damped weighted least square implemented using cvxpy.

Here the error term for each feature is scaled by its observed value, not the predicted value as described in https://www.nature.com/articles/s41467-019-10802-z.

max_weights

The upper limit of the scaling weights for regression loss.

Type:: float

set_model_loss(): Set DWLS regression loss.

class smoother.models.deconv.NuSVRConvex(bias=True, dim_in=1, dim_out=1, C=1.0, nu=0.1, nonneg=False, loss_mode='l2')

Bases: LinearRegressionConvex

Nu-Support vector regression implemented using cvxpy.

C

SVR regularization parameter.

Type:: float

nu

Nu-SVR parameter.

Type:: float

epsilon

Epsilon in the epsilon-SVR model, specifying the the epsilon-tube within which no penalty is associated in the training loss function with points predicted within a distance epsilon from the actual value.

Type:: float

loss_mode

Specifies the regression loss function to use. Either ‘l2’ or ‘l1’.

Type:: str

set_model_loss(): Set Nu-SVR regression loss.

set_params(configs) → bool: Set model parameters. Return True if warm start.