smoother.models.deconv ====================== .. py:module:: smoother.models.deconv .. autoapi-nested-parse:: Deconvolute spatial-omics data with spatial loss Classes ------- .. autoapisummary:: smoother.models.deconv.DeconvModel smoother.models.deconv.DeconvModelTorch smoother.models.deconv.LinearRegressionTorch smoother.models.deconv.NNLSTorch smoother.models.deconv.NuSVRTorch smoother.models.deconv.DWLSTorch smoother.models.deconv.LogNormRegTorch smoother.models.deconv.DeconvModelConvex smoother.models.deconv.LinearRegressionConvex smoother.models.deconv.NNLSConvex smoother.models.deconv.DWLSConvex smoother.models.deconv.NuSVRConvex Functions --------- .. autoapisummary:: smoother.models.deconv.LinearRegression smoother.models.deconv.NNLS smoother.models.deconv.NuSVR smoother.models.deconv.DWLS smoother.models.deconv.LogNormReg smoother.models.deconv._deconv_torch smoother.models.deconv._nu_svr_loss smoother.models.deconv._dwls_loss Module Contents --------------- .. py:class:: DeconvModel Interface for convex deconvolution models. .. py:method:: get_model_loss() :abstractmethod: Get regression reconstruction loss. .. py:method:: get_sp_loss() :abstractmethod: Get spatial loss (weighted by lambda_spatial_loss). .. py:method:: get_props() :abstractmethod: Get the predicted celltype abundance from the trained deconvolution model. .. py:function:: LinearRegression(backend='pytorch', **kwargs) -> DeconvModel .. py:function:: NNLS(backend='pytorch', **kwargs) -> DeconvModel .. py:function:: NuSVR(backend='pytorch', **kwargs) -> DeconvModel .. py:function:: DWLS(backend='pytorch', **kwargs) -> DeconvModel .. py:function:: LogNormReg(backend='pytorch', **kwargs) -> DeconvModel .. py:class:: DeconvModelTorch(dim_in, dim_out, model_name) Bases: :py:obj:`torch.nn.Module`, :py:obj:`DeconvModel` Class for deconvolution models implemented using pytorch. .. attribute:: dim_in Input dimension, also number of groups. :type: int .. attribute:: dim_out Output dimension, also number of spots. :type: int .. attribute:: use_bias Whether to add bias term in regression. :type: bool .. attribute:: model_name Name of the deconvolution model. :type: str .. attribute:: nonneg Whether to apply nonnegative contraint on spatial variables. :type: bool .. attribute:: deconv_configs Dictionary of deconvolution configurations. :type: dict .. attribute:: deconv_time Time spent on deconvolution. :type: float .. py:attribute:: dim_in .. py:attribute:: dim_out .. py:attribute:: model_name .. py:attribute:: use_bias :value: None .. py:attribute:: nonneg :value: None .. py:attribute:: deconv_configs :value: None .. py:attribute:: deconv_time :value: None .. py:method:: set_params(dim_in, dim_out, bias) :abstractmethod: .. py:method:: get_top_loss() :abstractmethod: Get toplogical loss (weighted by lambda_top_loss). .. py:method:: init_with_lr_sol(x, y) :abstractmethod: Initialize model with linear regression solution. .. py:method:: final_sanity_check() :abstractmethod: Make sure constraints are followed after deconvolution. .. py:method:: 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. :param x: Bulk feature signiture matrix, num_feature x num_group. :type x: 2D tensor :param y: Spatial feature matrix, num_feature x num_spot. :type y: 2D tensor :param spatial_loss: 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. :type spatial_loss: SpatialLoss :param lambda_spatial_loss: Specifies the strength of the spatial smoothing. :type lambda_spatial_loss: float :param top_loss: The topological loss (expected betti number for each group). top_loss.betti_priors = { group_id : {betti_k : expected number of barcodes (prior)}, ... } :type top_loss: TopLoss :param lambda_top_loss: Specifies the strength of the topological constraints. :type lambda_top_loss: float :param lr: Learning rate. :type lr: float :param max_epochs: Maximum number of training epochs. If -1, iterate until convergence (`d_loss` < 1e-5). :type max_epochs: int :param patient: Number of epochs to wait for the loss to decrease before stopping. :type patient: int :param tol: Tolerance of loss convergence. :type tol: float :param init_with_lr_sol: Whether to initialize regression weights with the OLE solution. :type init_with_lr_sol: bool :param verbose: If True, print out loss while training. :type verbose: bool :param quiet: If True, no output printed. :type quiet: bool .. py:function:: _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. :param x: Bulk feature signiture matrix, num_feature x num_group. :type x: 2D tensor :param y: Spatial feature matrix, num_feature x num_spot. :type y: 2D tensor :param deconv_model: 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. :type deconv_model: DeconvModelTorch :param spatial_loss: 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. :type spatial_loss: SpatialLoss :param lambda_spatial_loss: Specifies the strength of the spatial smoothing. :type lambda_spatial_loss: float :param top_loss: The topological loss (expected betti number for each group). top_loss.betti_priors = { group_id : {betti_k : expected number of barcodes (prior)}, ... } :type top_loss: TopLoss :param lambda_top_loss: Specifies the strength of the topological constraints. :type lambda_top_loss: float :param lr: Learning rate. :type lr: float :param max_epochs: Maximum number of training epochs. If -1, iterate until convergence (`d_loss` < 1e-5). :type max_epochs: int :param patient: Number of epochs to wait for the loss to decrease before stopping. :type patient: int :param tol: Tolerance of loss convergence. :type tol: float :param init_with_lr_sol: Whether to initialize regression weights with the OLE solution. :type init_with_lr_sol: bool :param verbose: If True, print out loss while training. :type verbose: bool :param quiet: If True, no output printed. :type quiet: bool :param return_model: If True, return the trained model. :type return_model: bool .. py:class:: LinearRegressionTorch(bias=True, dim_in=1, dim_out=1) Bases: :py:obj:`DeconvModelTorch` Linear regression implemented using pytorch. .. py:attribute:: lr :value: None .. py:attribute:: nonneg :value: False .. py:attribute:: use_bias :value: True .. py:method:: set_params(dim_in, dim_out, bias=True) -> None .. py:method:: forward(x) .. py:method:: get_model_loss_fn() .. py:method:: get_model_loss() Calculate regression loss. .. py:method:: get_sp_loss() Calculate spatial loss (weighted by lambda_spatial_loss). .. py:method:: get_top_loss() Calculate topological loss (weighted by lambda_top_loss). .. py:method:: get_props() Get the predicted celltype abundance from the trained deconvolution model. .. py:method:: init_with_lr_sol(x, y) Initialize model with linear regression solution. .. py:method:: final_sanity_check() Make sure constraints are satisfied. .. py:class:: NNLSTorch(bias=True, dim_in=1, dim_out=1) Bases: :py:obj:`LinearRegressionTorch` Non-negative least square implemented using pytorch. .. py:attribute:: model_name :value: 'nnls_torch' .. py:attribute:: nonneg :value: True .. py:class:: NuSVRTorch(bias=True, dim_in=1, dim_out=1, C=1.0, nu=0.1, nonneg=False, loss_mode='l2') Bases: :py:obj:`LinearRegressionTorch` Nu-Support vector regression implemented using pytorch. .. attribute:: C SVR regularization parameter. :type: float .. attribute:: nu Nu-SVR parameter. :type: float .. attribute:: 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 .. attribute:: loss_mode Specifies the regression loss function to use. Either 'l2' or 'l1'. :type: str .. py:attribute:: model_name :value: 'svr_torch' .. py:attribute:: nonneg :value: False .. py:attribute:: loss_mode :value: 'l2' .. py:attribute:: C .. py:attribute:: nu .. py:attribute:: epsilon .. py:method:: get_model_loss_fn() .. py:method:: final_sanity_check() Make sure constraints are satisfied. .. py:function:: _nu_svr_loss(input, target, coefs, C, nu, epsilon, reduction='mean', loss='l2') Calculate nu-SVR loss. :param input: Predicted spatial features (pred = X * beta), num_feature x num_spot. :type input: 2D tensor :param target: Observed spatial features, num_feature x num_spot. :type target: 2D tensor :param coefs: Columns of regression coefficients, num_group x num_spot. :type coefs: 2D tenor :param C: SVR regularization parameter. :type C: float :param nu: Nu-SVR parameter. :type nu: float :param 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 epsilon: float :param reduction: Specifies the reduction to apply to the output. :type reduction: str :param loss: Specifies the regression loss function to use. Either 'l2' or 'l1'. :type loss: str :returns: Aggregated nu-SVR loss. :rtype: loss (float) .. py:class:: DWLSTorch(bias=True, dim_in=1, dim_out=1, nonneg=True, max_weights=8) Bases: :py:obj:`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. .. attribute:: max_weights The upper limit of weights. :type: float .. py:attribute:: model_name :value: 'dwls_torch' .. py:attribute:: nonneg :value: True .. py:attribute:: max_weights :value: 8 .. py:method:: get_model_loss_fn() .. py:function:: _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. :param input: Predicted spatial features (pred = X * beta), num_feature x num_spot. :type input: 2D tensor :param target: Observed spatial features, num_feature x num_spot. :type target: 2D tensor :param max_weights: The upper limit of weights. :type max_weights: float .. py:class:: LogNormRegTorch(bias=True, epsilon=1, dim_in=1, dim_out=1) Bases: :py:obj:`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. .. attribute:: epsilon pseudo count added before log transformation. :type: float .. py:attribute:: model_name :value: 'lognormreg_torch' .. py:attribute:: nonneg :value: True .. py:attribute:: epsilon :value: 1 .. py:method:: get_model_loss_fn() .. py:class:: DeconvModelConvex(dim_in, dim_out, model_name) Bases: :py:obj:`DeconvModel` Class for convex deconvolution models implemented using cvxpy. .. attribute:: dim_in Input dimension, also number of groups. :type: int .. attribute:: dim_out Output dimension, also number of spots. :type: int .. attribute:: model_name Name of the deconvolution model. :type: str .. attribute:: nonneg Whether to apply nonnegative contraint on spatial variables. :type: bool .. attribute:: deconv_configs Dictionary of deconvolution configurations. :type: dict .. attribute:: deconv_time Time spent on deconvolution. :type: float .. py:attribute:: dim_in .. py:attribute:: dim_out .. py:attribute:: model_name .. py:attribute:: nonneg :value: None .. py:attribute:: deconv_configs :value: None .. py:attribute:: obj :value: None .. py:attribute:: problem :value: None .. py:attribute:: deconv_time :value: None .. py:method:: set_params(configs) -> bool :abstractmethod: Set model parameters. Return True if warm start. .. py:method:: get_model_loss() :abstractmethod: Get regression reconstruction loss. .. py:method:: get_sp_loss() :abstractmethod: Get spatial loss (weighted by lambda_spatial_loss). .. py:method:: get_props() :abstractmethod: Get the predicted celltype abundance from the trained deconvolution model. .. py:method:: 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. :param x: Bulk feature signiture matrix, num_feature x num_group. :type x: 2D tensor :param y: Spatial feature matrix, num_feature x num_spot. :type y: 2D tensor :param spatial_loss: 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. :type spatial_loss: SpatialLoss :param lambda_spatial_loss: 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). :type lambda_spatial_loss: float :param verbose: If True, print solver output. :type verbose: bool :param quiet: If True, no output printed, including final message. :type quiet: bool :param solver: The solver to use. :type solver: str :param kwargs: Additional keyword arguments specifying solver specific options. .. py:class:: LinearRegressionConvex(bias=True, dim_in=1, dim_out=1) Bases: :py:obj:`DeconvModelConvex` Linear regression implemented using cvxpy. .. py:attribute:: nonneg :value: False .. py:attribute:: use_bias :value: True .. py:attribute:: weights :value: None .. py:attribute:: list_w_row :value: None .. py:attribute:: model_loss_exp :value: None .. py:attribute:: lambda_spatial_loss :value: None .. py:attribute:: spatial_loss_exp :value: None .. py:attribute:: warm_start :value: None .. py:method:: 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. .. py:method:: set_params(configs) -> bool Set model parameters. Return True if warm start. .. py:method:: set_model_loss() Set model reconstruction loss. .. py:method:: set_sp_loss() Set spatial loss. .. py:method:: get_model_loss() Get model regression reconstruction loss. .. py:method:: get_sp_loss() Get spatial loss (weighted by lambda_spatial_loss). .. py:method:: get_props() Get the predicted celltype abundance from the trained deconvolution model. .. py:class:: NNLSConvex(bias=True, dim_in=1, dim_out=1) Bases: :py:obj:`LinearRegressionConvex` Non-negative least square implemented using cvxpy. .. py:attribute:: model_name :value: 'nnls_cvx' .. py:attribute:: nonneg :value: True .. py:class:: DWLSConvex(bias=True, dim_in=1, dim_out=1, nonneg=True, max_weights=8) Bases: :py:obj:`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. .. attribute:: max_weights The upper limit of the scaling weights for regression loss. :type: float .. py:attribute:: model_name :value: 'dwls_cvx' .. py:attribute:: nonneg :value: True .. py:attribute:: max_weights :value: 8 .. py:method:: set_model_loss() Set DWLS regression loss. .. py:class:: NuSVRConvex(bias=True, dim_in=1, dim_out=1, C=1.0, nu=0.1, nonneg=False, loss_mode='l2') Bases: :py:obj:`LinearRegressionConvex` Nu-Support vector regression implemented using cvxpy. .. attribute:: C SVR regularization parameter. :type: float .. attribute:: nu Nu-SVR parameter. :type: float .. attribute:: 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 .. attribute:: loss_mode Specifies the regression loss function to use. Either 'l2' or 'l1'. :type: str .. py:attribute:: model_name :value: 'svr_cvx' .. py:attribute:: nonneg :value: False .. py:attribute:: loss_mode :value: 'l2' .. py:attribute:: C :value: 1.0 .. py:attribute:: nu .. py:attribute:: epsilon :value: None .. py:method:: set_model_loss() Set Nu-SVR regression loss. .. py:method:: set_params(configs) -> bool Set model parameters. Return True if warm start.