popari.model.Popari

popari.model.Popari#

class popari.model.Popari(K, replicate_names=None, datasets=None, dataset_path=None, reloaded_hierarchy=None, lambda_Sigma_x_inv=0.0001, pretrained=False, initialization_method='leiden', hierarchical_levels=1, metagene_groups=None, spatial_affinity_groups=None, betas=None, prior_x_modes=None, M_constraint='simplex', sigma_yx_inv_mode='separate', torch_context=None, initial_context=None, metagene_mode='shared', spatial_affinity_mode='shared lookup', lambda_M=0.5, lambda_Sigma_bar=0.001, spatial_affinity_lr=0.01, spatial_affinity_tol=0.002, spatial_affinity_constraint=None, spatial_affinity_centering=False, spatial_affinity_scaling=10, spatial_affinity_regularization_power=2, embedding_mini_iterations=1000, embedding_acceleration_trick=True, embedding_step_size_multiplier=1.0, downsampling_method='grid', binning_downsample_rate=0.2, chunks=2, superresolution_lr=0.1, use_inplace_ops=True, random_state=0, verbose=0)[source]#

Popari optimization model.

Models spatial biological data using the NMF-HMRF formulation. Supports multiple fields-of-view (FOVs) and differential analysis.

Example of including math in docstring (for use later): \(||A||_F = [\sum_{i,j} abs(a_{i,j})^2]^{1/2}\)

Parameters:

  • K (int)

  • replicate_names (Sequence[str] | None)

  • datasets (Sequence[AnnData] | None)

  • dataset_path (str | Path | None)

  • reloaded_hierarchy (dict | None)

  • lambda_Sigma_x_inv (float)

  • pretrained (bool)

  • initialization_method (str)

  • hierarchical_levels (int)

  • metagene_groups (dict | None)

  • spatial_affinity_groups (dict | None)

  • betas (Sequence[float] | None)

  • prior_x_modes (Sequence[str] | None)

  • M_constraint (str)

  • sigma_yx_inv_mode (str)

  • torch_context (dict | None)

  • initial_context (dict | None)

  • metagene_mode (str)

  • spatial_affinity_mode (str)

  • lambda_M (float)

  • lambda_Sigma_bar (float)

  • spatial_affinity_lr (float)

  • spatial_affinity_tol (float)

  • spatial_affinity_constraint (str | None)

  • spatial_affinity_centering (bool)

  • spatial_affinity_scaling (int)

  • spatial_affinity_regularization_power (int)

  • embedding_mini_iterations (int)

  • embedding_acceleration_trick (bool)

  • embedding_step_size_multiplier (float)

  • downsampling_method (str)

  • binning_downsample_rate (float)

  • chunks (int)

  • superresolution_lr (float)

  • use_inplace_ops (bool)

  • random_state (int)

  • verbose (int)

K#

number of metagenes to learn

replicate_names#

names of spatial datasets

datasets#

list of input AnnData spatial datasets for Popari.

dataset_path#

path to AnnData merged dataset on disk. Ignored if datasets is specified.

reloaded_hierarchy#

data from previous hierarchical run of Popari.

lambda_Sigma_x_inv#

hyperparameter to balance importance of spatial information. Default: 1e-4

pretrained#

if set, attempts to load model state from input files. Default: False

initialization_method#

algorithm to use for initializing metagenes and embeddings. Default: leiden

hierarchical_levels#

number of hierarchical levels to use. Default: 1 (non-hierarchical mode)

metagene_groups#

defines a grouping of replicates for the metagene optimization. If metagene_mode == "shared", then one set of metagenes will be created for each group; if metagene_mode == "differential",  then all replicates will have their own set of metagenes, but each group will share an ``M_bar.

spatial_affinity_groups#

defines a grouping of replicates for the spatial affinity optimization. If spatial_affinity_mode == "shared lookup", then one set of spatial_affinities will be created for each group; if spatial_affinity_mode == "differential lookup", then all replicates will have their own set of spatial affinities, but each group will share a spatial_affinity_bar.

betas#

weighting of each dataset during optimization. Defaults to equally weighting each dataset

prior_x_modes#

family of prior distribution for embeddings of each dataset

M_constraint#

constraint on columns of M. Default: simplex

sigma_yx_inv_mode#

form of sigma_yx_inv parameter. Default: separate

torch_context#

keyword args to use of PyTorch tensors during training.

initial_context#

keyword args to use during initialization of PyTorch tensors.

metagene_mode#

modality of metagene parameters. Default: shared.

metagene_mode

Option

shared

A metagene set is shared between all replicates in a group.

differential

Each replicate learns its own metagene set.
spatial_affinity_mode#

modality of spatial affinity parameters. Default: shared lookup

lambda_M#

hyperparameter to constrain metagene deviation in differential case. Ignored if metagene_mode is shared. Default: 0.5

lambda_Sigma_bar#

hyperparameter to constrain spatial affinity deviation in differential case. Ignored if spatial_affinity_mode is shared lookup. Default: 0.5

spatial_affinity_lr#

learning rate for optimization of Sigma_x_inv

spatial_affinity_tol#

convergence tolerance during optimization of Sigma_x_inv

spatial_affinity_constraint#

method to ensure that spatial affinities lie within an appropriate range

spatial_affinity_centering#

if set, spatial affinities are zero-centered after every optimization step

spatial_affinity_scaling#

magnitude of spatial affinities during initial scaling. Default: 10

spatial_affinity_regularization_power#

exponent controlling penalization of spatial affinity magnitudes. Default: 2

embedding_mini_iterations#

number of mini-iterations to use during each iteration of embedding optimization. Default: 1000

embedding_acceleration_trick#

if set, use trick to accelerate convergence of embedding optimization. Default: True

embedding_step_size_multiplier#

controls relative step size during embedding optimization. Default: 1.0

binning_downsample_rate#

ratio of number of spots at low resolution to high resolution when using hierarchical mode

superresolution_lr#

learning rate for optimization of X from low-res embeddings

use_inplace_ops#

if set, inplace PyTorch operations will be used to speed up computation

random_state#

seed for reproducibility of randomized computations. Default: 0

verbose#

level of verbosity to use during optimization. Default: 0 (no print statements)

Methods

estimate_parameters([...])

Update parameters for each replicate.

estimate_weights([use_neighbors, synchronize])

Update embeddings (latent states) for each replicate.

load_anndata_datasets(datasets, replicate_names)

Load Popari data directly from AnnData objects.

load_dataset(dataset_path)

Load dataset into Popari from saved .h5ad file.

nll([level, use_spatial])

Compute the nll for the current configuration of model parameters.

save_results(dataset_path[, ignore_raw_data])

Save datasets and learned Popari parameters to disk.

set_superresolution_lr(new_lr[, target_level])

Change learning rate for superresolution optimization.

superresolve([...])

Superresolve embeddings in hierarchical case.

synchronize_datasets()

Synchronize datasets across all hierarchical levels.
Contents