spateo.alignment

Subpackages

• spateo.alignment.methods
  • spateo.alignment.methods.morpho
  • spateo.alignment.methods.morpho_sparse
  • spateo.alignment.methods.morpho_sparse_utils
  • spateo.alignment.methods.paste
  • spateo.alignment.methods.utils

Submodules

• spateo.alignment.deformation
• spateo.alignment.morpho_alignment
• spateo.alignment.paste_alignment
• spateo.alignment.transform
• spateo.alignment.utils

Package Contents

Functions

grid_deformation(model[, spatial_key, vecfld_key, ...])
align_preprocess(...)	Data preprocessing before alignment.
calc_exp_dissimilarity(→ Union[numpy.ndarray, ...)	Calculate expression dissimilarity.
morpho_align(→ Tuple[List[anndata.AnnData], ...)	Continuous alignment of spatial transcriptomic coordinates based on Morpho.
morpho_align_ref(→ Tuple[List[anndata.AnnData], ...)	Continuous alignment of spatial transcriptomic coordinates with the reference models based on Morpho.
morpho_align_sparse(→ Tuple[List[anndata.AnnData], ...)	Continuous alignment of spatial transcriptomic coordinates based on Morpho.
paste_align(→ Tuple[List[anndata.AnnData], ...)	Align spatial coordinates of models.
paste_align_ref(→ Tuple[List[anndata.AnnData], ...)	Align the spatial coordinates of one model list through the affine transformation matrix obtained from another model list.
BA_transform(vecfld, quary_points[, ...])	Apply non-rigid transform to the quary points
BA_transform_and_assignment(samples, vecfld[, layer, ...])
paste_transform(→ anndata.AnnData)	Align the space coordinates of the new model with the transformation matrix obtained from PASTE.
downsampling(→ Union[List[anndata.AnnData], ...)
get_labels_based_on_coords(→ pandas.DataFrame)	Obtain the label information in anndata.obs[key] corresponding to the coords.
get_optimal_mapping_relationship(X, Y, pi[, keep_all])
mapping_aligned_coords(→ Tuple[dict, dict])	Optimal mapping coordinates between X and Y.
mapping_center_coords(→ dict)	Optimal mapping coordinates between X and Y based on intermediate coordinates.

spateo.alignment.grid_deformation(model: anndata.AnnData, spatial_key: str = 'spatial', vecfld_key: str = 'VecFld_morpho', key_added: str = 'deformation', deformation_scale: int = 3, grid_num: numpy.asarray | None = None, dtype: str = 'float64', device: str = 'cpu')

spateo.alignment.align_preprocess(samples: List[anndata.AnnData], genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', layer: str = 'X', normalize_c: bool = False, normalize_g: bool = False, select_high_exp_genes: bool | float | int = False, dtype: str = 'float64', device: str = 'cpu', verbose: bool = True, **kwargs) → Tuple[ot.backend.TorchBackend or ot.backend.NumpyBackend, torch.Tensor or np.ndarray, list, list, list, Optional[float], Optional[list]]

Data preprocessing before alignment.

Parameters:

samples

A list of anndata object.

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinates.

layer

If ‘X’, uses sample.X to calculate dissimilarity between spots, otherwise uses the representation given by sample.layers[layer].

normalize_c

Whether to normalize spatial coordinates.

normalize_g

Whether to normalize gene expression.

select_high_exp_genes

Whether to select genes with high differences in gene expression.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: ‘0’.

verbose

If True, print progress updates.

spateo.alignment.calc_exp_dissimilarity(X_A: numpy.ndarray | torch.Tensor, X_B: numpy.ndarray | torch.Tensor, dissimilarity: str = 'kl', chunk_num: int = 1) → numpy.ndarray | torch.Tensor

Calculate expression dissimilarity. :param X_A: Gene expression matrix of sample A. :param X_B: Gene expression matrix of sample B. :param dissimilarity: Expression dissimilarity measure: 'kl' or 'euclidean'.

Returns:

The dissimilarity matrix of two feature samples.

Return type:

Union[np.ndarray, torch.Tensor]

spateo.alignment.morpho_align(models: List[anndata.AnnData], layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', iter_key_added: str | None = 'iter_spatial', vecfld_key_added: str = 'VecFld_morpho', mode: Literal[SN - N, SN - S] = 'SN-S', dissimilarity: str = 'kl', max_iter: int = 100, SVI_mode: bool = True, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True, **kwargs) → Tuple[List[anndata.AnnData], List[numpy.ndarray], List[numpy.ndarray]]

Continuous alignment of spatial transcriptomic coordinates based on Morpho.

Parameters:

models

List of models (AnnData Object).

layer

If 'X', uses .X to calculate dissimilarity between spots, otherwise uses the representation given by .layers[layer].

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinate.

key_added

.obsm key under which to add the aligned spatial coordinate.

iter_key_added

.uns key under which to add the result of each iteration of the iterative process. If iter_key_added is None, the results are not saved.

vecfld_key_added

The key that will be used for the vector field key in .uns. If vecfld_key_added is None, the results are not saved.

mode

The method of alignment. Available mode are: 'SN-N', and 'SN-S'.

• 'SN-N': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a non-rigid aligned result;

• 'SN-S': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a rigid aligned result. The non-rigid is used here to solve the optimal mapping, thus returning a more accurate rigid transformation. The default is 'SN-S'.

dissimilarity

Expression dissimilarity measure: 'kl' or 'euclidean'.

max_iter

Max number of iterations for morpho alignment.

SVI_mode

Whether to use stochastic variational inferential (SVI) optimization strategy.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

verbose

If True, print progress updates.

**kwargs

Additional parameters that will be passed to BA_align function.

Returns:

List of models (AnnData Object) after alignment. pis: List of pi matrices. sigma2s: List of sigma2.

Return type:

align_models

spateo.alignment.morpho_align_ref(models: List[anndata.AnnData], models_ref: List[anndata.AnnData] | None = None, n_sampling: int | None = 2000, sampling_method: str = 'trn', layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', iter_key_added: str | None = 'iter_spatial', vecfld_key_added: str | None = 'VecFld_morpho', mode: Literal[SN - N, SN - S] = 'SN-S', dissimilarity: str = 'kl', max_iter: int = 100, SVI_mode: bool = True, return_full_assignment: bool = False, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True, **kwargs) → Tuple[List[anndata.AnnData], List[anndata.AnnData], List[numpy.ndarray], List[numpy.ndarray], List[numpy.ndarray]]

Continuous alignment of spatial transcriptomic coordinates with the reference models based on Morpho.

Parameters:

models

List of models (AnnData Object).

models_ref

Another list of models (AnnData Object).

n_sampling

When models_ref is None, new data containing n_sampling coordinate points will be automatically generated for alignment.

sampling_method

The method to sample data points, can be one of ["trn", "kmeans", "random"].

layer

If 'X', uses .X to calculate dissimilarity between spots, otherwise uses the representation given by .layers[layer].

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinate.

key_added

.obsm key under which to add the aligned spatial coordinate.

iter_key_added

.uns key under which to add the result of each iteration of the iterative process. If iter_key_added is None, the results are not saved.

vecfld_key_added

The key that will be used for the vector field key in .uns. If vecfld_key_added is None, the results are not saved.

mode

The method of alignment. Available mode are: 'SN-N', and 'SN-S'.

• 'SN-N': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a non-rigid aligned result;

• 'SN-S': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a rigid aligned result. The non-rigid is used here to solve the optimal mapping, thus returning a more accurate rigid transformation. The default is 'SN-S'.

dissimilarity

Expression dissimilarity measure: 'kl' or 'euclidean'.

max_iter

Max number of iterations for morpho alignment.

SVI_mode

Whether to use stochastic variational inferential (SVI) optimization strategy.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

verbose

If True, print progress updates.

**kwargs

Additional parameters that will be passed to BA_align function.

Returns:

List of models (AnnData Object) after alignment. align_models_ref: List of models_ref (AnnData Object) after alignment. pis: List of pi matrices for models. pis_ref: List of pi matrices for models_ref. sigma2s: List of sigma2.

Return type:

align_models

spateo.alignment.morpho_align_sparse(models: List[anndata.AnnData], layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', iter_key_added: str | None = 'iter_spatial', vecfld_key_added: str = 'VecFld_morpho', mode: Literal[SN - N, SN - S] = 'SN-S', dissimilarity: str = 'kl', max_iter: int = 100, SVI_mode: bool = True, use_label_prior: bool = False, label_key: str | None = 'cluster', label_transfer_prior: dict | None = None, dtype: str = 'float32', device: str = '0', verbose: bool = True, **kwargs) → Tuple[List[anndata.AnnData], List[numpy.ndarray], List[numpy.ndarray]]

Continuous alignment of spatial transcriptomic coordinates based on Morpho.

Parameters:

models

List of models (AnnData Object).

layer

If 'X', uses .X to calculate dissimilarity between spots, otherwise uses the representation given by .layers[layer].

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinate.

key_added

.obsm key under which to add the aligned spatial coordinate.

iter_key_added

.uns key under which to add the result of each iteration of the iterative process. If iter_key_added is None, the results are not saved.

vecfld_key_added

The key that will be used for the vector field key in .uns. If vecfld_key_added is None, the results are not saved.

mode

The method of alignment. Available mode are: 'SN-N', and 'SN-S'.

• 'SN-N': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a non-rigid aligned result;

• 'SN-S': use both rigid and non-rigid alignment to keep the overall shape unchanged, while including local non-rigidity, and finally returns a rigid aligned result. The non-rigid is used here to solve the optimal mapping, thus returning a more accurate rigid transformation. The default is 'SN-S'.

dissimilarity

Expression dissimilarity measure: 'kl' or 'euclidean'.

max_iter

Max number of iterations for morpho alignment.

SVI_mode

Whether to use stochastic variational inferential (SVI) optimization strategy.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

verbose

If True, print progress updates.

**kwargs

Additional parameters that will be passed to BA_align_sparse function.

Returns:

List of models (AnnData Object) after alignment. pis: List of pi matrices. sigma2s: List of sigma2.

Return type:

align_models

spateo.alignment.paste_align(models: List[anndata.AnnData], layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', mapping_key_added: str = 'models_align', alpha: float = 0.1, numItermax: int = 200, numItermaxEmd: int = 100000, dtype: str = 'float64', device: str = 'cpu', verbose: bool = True, **kwargs) → Tuple[List[anndata.AnnData], List[numpy.ndarray | numpy.ndarray]]

Align spatial coordinates of models.

Parameters:

models

List of models (AnnData Object).

layer

If 'X', uses .X to calculate dissimilarity between spots, otherwise uses the representation given by .layers[layer].

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinate.

key_added

.obsm key under which to add the aligned spatial coordinates.

mapping_key_added

.uns key under which to add the alignment info.

alpha

Alignment tuning parameter. Note: 0 <= alpha <= 1.

When alpha = 0 only the gene expression data is taken into account, while when alpha =1 only the spatial coordinates are taken into account.

numItermax

Max number of iterations for cg during FGW-OT.

numItermaxEmd

Max number of iterations for emd during FGW-OT.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

verbose

If True, print progress updates.

**kwargs

Additional parameters that will be passed to pairwise_align function.

Returns:

List of models (AnnData Object) after alignment. pis: List of pi matrices.

Return type:

align_models

spateo.alignment.paste_align_ref(models: List[anndata.AnnData], models_ref: List[anndata.AnnData] | None = None, n_sampling: int | None = 2000, sampling_method: str = 'trn', layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', mapping_key_added: str = 'models_align', alpha: float = 0.1, numItermax: int = 200, numItermaxEmd: int = 100000, dtype: str = 'float64', device: str = 'cpu', verbose: bool = True, **kwargs) → Tuple[List[anndata.AnnData], List[anndata.AnnData], List[numpy.ndarray | numpy.ndarray]]

Align the spatial coordinates of one model list through the affine transformation matrix obtained from another model list.

Parameters:

models

List of models (AnnData Object).

models_ref

Another list of models (AnnData Object).

n_sampling

When models_ref is None, new data containing n_sampling coordinate points will be automatically generated for alignment.

sampling_method

The method to sample data points, can be one of ["trn", "kmeans", "random"].

layer

If 'X', uses .X to calculate dissimilarity between spots, otherwise uses the representation given by .layers[layer].

genes

Genes used for calculation. If None, use all common genes for calculation.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinates.

key_added

.obsm key under which to add the aligned spatial coordinates.

mapping_key_added

.uns key under which to add the alignment info.

alpha

Alignment tuning parameter. Note: 0 <= alpha <= 1.

When alpha = 0 only the gene expression data is taken into account, while when alpha =1 only the spatial coordinates are taken into account.

numItermax

Max number of iterations for cg during FGW-OT.

numItermaxEmd

Max number of iterations for emd during FGW-OT.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

verbose

If True, print progress updates.

**kwargs

Additional parameters that will be passed to models_align function.

Returns:

List of models (AnnData Object) after alignment. align_models_ref: List of models_ref (AnnData Object) after alignment. pis: The list of pi matrices from align_models_ref.

Return type:

align_models

spateo.alignment.BA_transform(vecfld, quary_points, deformation_scale: int = 1, dtype: str = 'float64', device: str = 'cpu')

Apply non-rigid transform to the quary points

Parameters:

vecfld

A dictionary containing information about vector fields

quary_points

deformation_scale

If deformation_scale is greater than 1, increase the degree of deformation.

dtype

The floating-point number type. Only float32 and float64.

device

Equipment used to run the program. You can also set the specified GPU for running. E.g.: '0'.

spateo.alignment.BA_transform_and_assignment(samples, vecfld, layer: str = 'X', genes: List | torch.Tensor | None = None, spatial_key: str = 'spatial', small_variance: bool = False, dtype: str = 'float64', device: str = 'cpu', verbose: bool = False)

spateo.alignment.paste_transform(adata: anndata.AnnData, adata_ref: anndata.AnnData, spatial_key: str = 'spatial', key_added: str = 'align_spatial', mapping_key: str = 'models_align') → anndata.AnnData

Align the space coordinates of the new model with the transformation matrix obtained from PASTE.

Parameters:

adata

The anndata object that need to be aligned.

adata_ref

The anndata object that have been aligned by PASTE.

spatial_key

The key in .obsm that corresponds to the raw spatial coordinates.

key_added

.obsm key under which to add the aligned spatial coordinates.

mapping_key

The key in .uns that corresponds to the alignment info from PASTE.

Returns:

The anndata object that have been to be aligned.

Return type:

adata

spateo.alignment.downsampling(models: List[anndata.AnnData] | anndata.AnnData, n_sampling: int | None = 2000, sampling_method: str = 'trn', spatial_key: str = 'spatial') → List[anndata.AnnData] | anndata.AnnData

spateo.alignment.get_labels_based_on_coords(model: anndata.AnnData, coords: numpy.ndarray, labels_key: str | List[str], spatial_key: str = 'align_spatial') → pandas.DataFrame

Obtain the label information in anndata.obs[key] corresponding to the coords.

spateo.alignment.get_optimal_mapping_relationship(X: numpy.ndarray, Y: numpy.ndarray, pi: numpy.ndarray, keep_all: bool = False)

spateo.alignment.mapping_aligned_coords(X: numpy.ndarray, Y: numpy.ndarray, pi: numpy.ndarray, keep_all: bool = False) → Tuple[dict, dict]

Optimal mapping coordinates between X and Y.

Parameters:

X

Aligned spatial coordinates.

Y

Aligned spatial coordinates.

pi

Mapping between the two layers output by PASTE.

keep_all

Whether to retain all the optimal relationships obtained only based on the pi matrix, If keep_all is False, the optimal relationships obtained based on the pi matrix and the nearest coordinates.

Returns:

Two dicts of mapping_X, mapping_Y, pi_index, pi_value.

mapping_X is X coordinates aligned with Y coordinates. mapping_Y is the Y coordinate aligned with X coordinates. pi_index is index between optimal mapping points in the pi matrix. pi_value is the value of optimal mapping points.

spateo.alignment.mapping_center_coords(modelA: anndata.AnnData, modelB: anndata.AnnData, center_key: str) → dict

Optimal mapping coordinates between X and Y based on intermediate coordinates.

Parameters:

modelA

modelA aligned with center model.

modelB

modelB aligned with center model.

center_key

The key in .uns that corresponds to the alignment info between modelA/modelB and center model.

Returns:

A dict of raw_X, raw_Y, mapping_X, mapping_Y, pi_value.

raw_X is the raw X coordinates. raw_Y is the raw Y coordinates. mapping_X is the Y coordinates aligned with X coordinates. mapping_Y is the X coordinates aligned with Y coordinates. pi_value is the value of optimal mapping points.