smoother.models.deconv

Deconvolute spatial-omics data with spatial loss

Classes

`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.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

dim_in

dim_out

model_name

use_bias = None

nonneg = None

deconv_configs = None

deconv_time = None

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.

lr = None

nonneg = False

use_bias = True

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.

model_name = 'nnls_torch'

nonneg = True

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

model_name = 'svr_torch'

nonneg = False

loss_mode = 'l2'

C

nu

epsilon

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

model_name = 'dwls_torch'

nonneg = True

max_weights = 8

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

model_name = 'lognormreg_torch'

nonneg = True

epsilon = 1

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

dim_in

dim_out

model_name

nonneg = None

deconv_configs = None

obj = None

problem = None

deconv_time = None

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.

nonneg = False

use_bias = True

weights = None

list_w_row = None

model_loss_exp = None

lambda_spatial_loss = None

spatial_loss_exp = None

warm_start = None

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.

model_name = 'nnls_cvx'

nonneg = True

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

model_name = 'dwls_cvx'

nonneg = True

max_weights = 8

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

model_name = 'svr_cvx'

nonneg = False

loss_mode = 'l2'

C = 1.0

nu

epsilon = None

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

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