spateo.alignment.methods¶

Submodules¶

Attributes¶

`_chunk`
`_data`
`_dot`
`_mul`
`_pi`
`_power`
`_prod`
`_unsqueeze`
`intersect_lsts`

Classes¶

`NumpyBackend`	NumPy implementation of the backend.
`TorchBackend`	PyTorch implementation of the backend
`Morpho_pairwise`	A class to align two spatial transcriptomics AnnData objects using the Spateo alignment algorithm.
`Mesh_correction`	A class to perform 3D reconstruction correction from slices using a mesh.

Functions¶

`align_preprocess`(...)	Preprocess the data before alignment.
`cal_dist`(→ Union[numpy.ndarray, torch.Tensor])	Calculate the distance between two vectors
`cal_dot`(→ Union[numpy.ndarray, torch.Tensor])	Calculate the matrix multiplication of two matrices
`calc_exp_dissimilarity`(→ Union[numpy.ndarray, ...)	Calculate expression dissimilarity.
`generalized_procrustes_analysis`(X, Y, pi)	Finds and applies optimal rotation between spatial coordinates of two layers (may also do a reflection).
`paste_center_align`(→ Tuple[anndata.AnnData, ...)	Computes center alignment of slices.
`paste_pairwise_align`(→ Tuple[numpy.ndarray, Optional[int]])	Calculates and returns optimal alignment of two slices.
`calc_distance`(→ Union[numpy.ndarray, torch.Tensor])	Calculate the distance between all pairs of samples in matrices X and Y using the specified metric.
`check_backend`([device, dtype, verbose])	Check the proper backend for the device.
`check_exp`(→ numpy.ndarray)	Check expression matrix.
`con_K`(→ Union[numpy.ndarray, torch.Tensor])	con_K constructs the Squared Exponential (SE) kernel, where K(i,j)=k(X_i,Y_j)=exp(-beta*\|\|X_i-Y_j\|\|^2).
`empty_cache`([device])
`filter_common_genes`(→ list)	Filters for the intersection of genes between all samples.
`generate_label_transfer_dict`(→ Dict[str, Dict[str, float]])	Generate a label transfer dictionary with normalized values.

Package Contents¶

class spateo.alignment.methods.NumpyBackend[source]¶

Bases: Backend

NumPy implementation of the backend.

__name__ is “numpy”
__type__ is np.ndarray

__name__ = 'numpy'¶

__type__¶

__type_list__¶

rng_¶

_to_numpy(a)[source]¶: Returns the numpy version of a tensor

_from_numpy(a, type_as=None)[source]¶: Creates a tensor cloning a numpy array, with the given precision (defaulting to input’s precision) and the given device (in case of GPUs)

zeros(shape, type_as=None)[source]¶

Creates a tensor full of zeros.

This function follows the api from numpy.zeros

See: https://numpy.org/doc/stable/reference/generated/numpy.zeros.html

einsum(subscripts, *operands)[source]¶

Evaluates the Einstein summation convention on the operands.

This function follows the api from numpy.einsum

See: https://numpy.org/doc/stable/reference/generated/numpy.einsum.html

mean(a, axis=None)[source]¶

Computes the arithmetic mean of a tensor along given dimensions.

This function follows the api from numpy.mean

See: https://numpy.org/doc/stable/reference/generated/numpy.mean.html

full(shape, fill_value, type_as=None)[source]¶

Creates a tensor with given shape, filled with given value.

This function follows the api from numpy.full

See: https://numpy.org/doc/stable/reference/generated/numpy.full.html

sqrt(a)[source]¶

Returns the non-ngeative square root of a tensor, element-wise.

This function follows the api from numpy.sqrt

See: https://numpy.org/doc/stable/reference/generated/numpy.sqrt.html

ones(shape, type_as=None)[source]¶

Creates a tensor full of ones.

This function follows the api from numpy.ones

See: https://numpy.org/doc/stable/reference/generated/numpy.ones.html

maximum(a, b)[source]¶

Returns element-wise maximum of array elements.

This function follows the api from numpy.maximum

See: https://numpy.org/doc/stable/reference/generated/numpy.maximum.html

minimum(a, b)[source]¶

Returns element-wise minimum of array elements.

This function follows the api from numpy.minimum

See: https://numpy.org/doc/stable/reference/generated/numpy.minimum.html

max(a, axis=None, keepdims=False)[source]¶

Returns the maximum of an array or maximum along given dimensions.

This function follows the api from numpy.amax

See: https://numpy.org/doc/stable/reference/generated/numpy.amax.html

min(a, axis=None, keepdims=False)[source]¶

Returns the maximum of an array or maximum along given dimensions.

This function follows the api from numpy.amin

See: https://numpy.org/doc/stable/reference/generated/numpy.amin.html

eye(N, M=None, type_as=None)[source]¶

Creates the identity matrix of given size.

This function follows the api from numpy.eye

See: https://numpy.org/doc/stable/reference/generated/numpy.eye.html

argsort(a, axis=-1)[source]¶

Returns the indices that would sort a tensor.

This function follows the api from numpy.argsort

See: https://numpy.org/doc/stable/reference/generated/numpy.argsort.html

exp(a)[source]¶

log(a)[source]¶

Computes the natural logarithm, element-wise.

This function follows the api from numpy.log

See: https://numpy.org/doc/stable/reference/generated/numpy.log.html

concatenate(arrays, axis=0)[source]¶

Joins a sequence of tensors along an existing dimension.

This function follows the api from numpy.concatenate

See: https://numpy.org/doc/stable/reference/generated/numpy.concatenate.html

sum(a, axis=None, keepdims=False)[source]¶

Sums tensor elements over given dimensions.

This function follows the api from numpy.sum

See: https://numpy.org/doc/stable/reference/generated/numpy.sum.html

arange(stop, start=0, step=1, type_as=None)[source]¶

Returns evenly spaced values within a given interval.

This function follows the api from numpy.arange

See: https://numpy.org/doc/stable/reference/generated/numpy.arange.html

data(a, type_as=None)[source]¶

unique(a, return_index, return_inverse=False, axis=None)[source]¶

Finds unique elements of given tensor.

This function follows the api from numpy.unique

See: https://numpy.org/doc/stable/reference/generated/numpy.unique.html

unsqueeze(a, axis=-1)[source]¶

multiply(a, b)[source]¶

power(a, exponents)[source]¶

First tensor elements raised to powers from second tensor, element-wise.

This function follows the api from numpy.power

See: https://numpy.org/doc/stable/reference/generated/numpy.power.html

dot(a, b)[source]¶

Returns the dot product of two tensors.

This function follows the api from numpy.dot

See: https://numpy.org/doc/stable/reference/generated/numpy.dot.html

prod(a, axis=0)[source]¶

Return the product of all elements.

See: https://numpy.org/doc/stable/reference/generated/numpy.prod.html

pi(type_as=None)[source]¶

Return the value of pi.

See: https://numpy.org/doc/stable/reference/constants.html

chunk(a, chunk_num, axis=0)[source]¶

Split the tensor into a list of sub-tensors.

See: https://numpy.org/doc/stable/reference/generated/numpy.array_split.html

randperm(length)[source]¶

Returns a random permutation of integers from 0 to length - 1.

See: https://numpy.org/doc/stable/reference/random/generated/numpy.random.permutation.html

roll(a, shift, axis=None)[source]¶

Roll array elements along a given axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.roll.html

choice(a, size, replace=False)[source]¶

Generates a random sample from a given 1-D array.

See: https://numpy.org/doc/stable/reference/random/generated/numpy.random.choice.html

topk(a, topk, axis=-1)[source]¶

Returns the indices of the topk elements along a given axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.argpartition.html

dstack(a)[source]¶

Stack arrays in sequence along the third axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.dstack.html

vstack(a)[source]¶

Stack arrays in sequence vertically (row wise).

See: https://numpy.org/doc/stable/reference/generated/numpy.vstack.html

hstack(a)[source]¶

Stack arrays in sequence horizontally (column wise).

See: https://numpy.org/doc/stable/reference/generated/numpy.hstack.html

stack(arrays, axis=0)[source]¶

Joins a sequence of tensors along a new dimension.

This function follows the api from numpy.stack

See: https://numpy.org/doc/stable/reference/generated/numpy.stack.html

where(condition, x=None, y=None)[source]¶

Returns elements chosen from x or y depending on condition.

This function follows the api from numpy.where

See: https://numpy.org/doc/stable/reference/generated/numpy.where.html

copy(a)[source]¶

Returns a copy of the given tensor.

This function follows the api from numpy.copy

See: https://numpy.org/doc/stable/reference/generated/numpy.copy.html

repeat(a, repeats, axis=None)[source]¶

Repeats elements of a tensor.

This function follows the api from numpy.repeat

See: https://numpy.org/doc/stable/reference/generated/numpy.repeat.html

sort2(a, axis=-1, descending=False)[source]¶

Return the sorted array and the indices to sort the array

See: https://pytorch.org/docs/stable/generated/torch.sort.html

coo_matrix(data, rows, cols, shape=None, type_as=None)[source]¶

Creates a sparse tensor in COOrdinate format.

This function follows the api from scipy.sparse.coo_matrix

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.coo_matrix.html

issparse(a)[source]¶

Checks whether or not the input tensor is a sparse tensor.

This function follows the api from scipy.sparse.issparse

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.issparse.html

eliminate_zeros(a, threshold=0.0)[source]¶

Removes entries smaller than the given threshold from the sparse tensor.

This function follows the api from scipy.sparse.csr_matrix.eliminate_zeros

See: https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.csr_matrix.eliminate_zeros.html

todense(a)[source]¶

Converts a sparse tensor to a dense tensor.

This function follows the api from scipy.sparse.csr_matrix.toarray

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.toarray.html

dtype_device(a)[source]¶: Returns the dtype and the device of the given tensor.

class spateo.alignment.methods.TorchBackend[source]¶

Bases: Backend

PyTorch implementation of the backend

__name__ is “torch”
__type__ is torch.Tensor

__name__ = 'torch'¶

__type__¶

__type_list__ = None¶

rng_ = None¶

ValFunction¶

_to_numpy(a)[source]¶: Returns the numpy version of a tensor

_from_numpy(a, type_as=None)[source]¶: Creates a tensor cloning a numpy array, with the given precision (defaulting to input’s precision) and the given device (in case of GPUs)

zeros(shape, type_as=None)[source]¶

Creates a tensor full of zeros.

This function follows the api from numpy.zeros

See: https://numpy.org/doc/stable/reference/generated/numpy.zeros.html

einsum(subscripts, *operands)[source]¶

Evaluates the Einstein summation convention on the operands.

This function follows the api from numpy.einsum

See: https://numpy.org/doc/stable/reference/generated/numpy.einsum.html

mean(a, axis=None)[source]¶

Computes the arithmetic mean of a tensor along given dimensions.

This function follows the api from numpy.mean

See: https://numpy.org/doc/stable/reference/generated/numpy.mean.html

full(shape, fill_value, type_as=None)[source]¶

Creates a tensor with given shape, filled with given value.

This function follows the api from numpy.full

See: https://numpy.org/doc/stable/reference/generated/numpy.full.html

sqrt(a)[source]¶

Returns the non-ngeative square root of a tensor, element-wise.

This function follows the api from numpy.sqrt

See: https://numpy.org/doc/stable/reference/generated/numpy.sqrt.html

ones(shape, type_as=None)[source]¶

Creates a tensor full of ones.

This function follows the api from numpy.ones

See: https://numpy.org/doc/stable/reference/generated/numpy.ones.html

arange(stop, start=0, step=1, type_as=None)[source]¶

Returns evenly spaced values within a given interval.

This function follows the api from numpy.arange

See: https://numpy.org/doc/stable/reference/generated/numpy.arange.html

maximum(a, b)[source]¶

Returns element-wise maximum of array elements.

This function follows the api from numpy.maximum

See: https://numpy.org/doc/stable/reference/generated/numpy.maximum.html

minimum(a, b)[source]¶

Returns element-wise minimum of array elements.

This function follows the api from numpy.minimum

See: https://numpy.org/doc/stable/reference/generated/numpy.minimum.html

max(a, axis=None, keepdims=False)[source]¶

Returns the maximum of an array or maximum along given dimensions.

This function follows the api from numpy.amax

See: https://numpy.org/doc/stable/reference/generated/numpy.amax.html

min(a, axis=None, keepdims=False)[source]¶

Returns the maximum of an array or maximum along given dimensions.

This function follows the api from numpy.amin

See: https://numpy.org/doc/stable/reference/generated/numpy.amin.html

eye(N, M=None, type_as=None)[source]¶

Creates the identity matrix of given size.

This function follows the api from numpy.eye

See: https://numpy.org/doc/stable/reference/generated/numpy.eye.html

argsort(a, axis=-1)[source]¶

Returns the indices that would sort a tensor.

This function follows the api from numpy.argsort

See: https://numpy.org/doc/stable/reference/generated/numpy.argsort.html

exp(a)[source]¶

log(a)[source]¶

Computes the natural logarithm, element-wise.

This function follows the api from numpy.log

See: https://numpy.org/doc/stable/reference/generated/numpy.log.html

concatenate(arrays, axis=0)[source]¶

Joins a sequence of tensors along an existing dimension.

This function follows the api from numpy.concatenate

See: https://numpy.org/doc/stable/reference/generated/numpy.concatenate.html

sum(a, axis=None, keepdims=False)[source]¶

Sums tensor elements over given dimensions.

This function follows the api from numpy.sum

See: https://numpy.org/doc/stable/reference/generated/numpy.sum.html

data(a, type_as=None)[source]¶

unique(a, return_index=False, return_inverse=False, axis=None)[source]¶

Finds unique elements of given tensor.

This function follows the api from numpy.unique

See: https://numpy.org/doc/stable/reference/generated/numpy.unique.html

unsqueeze(a, axis=-1)[source]¶

multiply(a, b)[source]¶

power(a, exponents)[source]¶

First tensor elements raised to powers from second tensor, element-wise.

This function follows the api from numpy.power

See: https://numpy.org/doc/stable/reference/generated/numpy.power.html

dot(a, b)[source]¶

Returns the dot product of two tensors.

This function follows the api from numpy.dot

See: https://numpy.org/doc/stable/reference/generated/numpy.dot.html

prod(a, axis=0)[source]¶

Return the product of all elements.

See: https://numpy.org/doc/stable/reference/generated/numpy.prod.html

pi(type_as=None)[source]¶

Return the value of pi.

See: https://numpy.org/doc/stable/reference/constants.html

chunk(a, chunk_num, axis=0)[source]¶

Split the tensor into a list of sub-tensors.

See: https://numpy.org/doc/stable/reference/generated/numpy.array_split.html

randperm(length)[source]¶

Returns a random permutation of integers from 0 to length - 1.

See: https://numpy.org/doc/stable/reference/random/generated/numpy.random.permutation.html

roll(a, shift, axis=None)[source]¶

Roll array elements along a given axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.roll.html

choice(a, size, replace=False)[source]¶

Generates a random sample from a given 1-D array.

See: https://numpy.org/doc/stable/reference/random/generated/numpy.random.choice.html

topk(a, topk, axis=-1)[source]¶

Returns the indices of the topk elements along a given axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.argpartition.html

dstack(a)[source]¶

Stack arrays in sequence along the third axis.

See: https://numpy.org/doc/stable/reference/generated/numpy.dstack.html

vstack(a)[source]¶

Stack arrays in sequence vertically (row wise).

See: https://numpy.org/doc/stable/reference/generated/numpy.vstack.html

hstack(a)[source]¶

Stack arrays in sequence horizontally (column wise).

See: https://numpy.org/doc/stable/reference/generated/numpy.hstack.html

stack(arrays, axis=0)[source]¶

Joins a sequence of tensors along a new dimension.

This function follows the api from numpy.stack

See: https://numpy.org/doc/stable/reference/generated/numpy.stack.html

where(condition, x=None, y=None)[source]¶

Returns elements chosen from x or y depending on condition.

This function follows the api from numpy.where

See: https://numpy.org/doc/stable/reference/generated/numpy.where.html

copy(a)[source]¶

Returns a copy of the given tensor.

This function follows the api from numpy.copy

See: https://numpy.org/doc/stable/reference/generated/numpy.copy.html

repeat(a, repeats, axis=None)[source]¶

Repeats elements of a tensor.

This function follows the api from numpy.repeat

See: https://numpy.org/doc/stable/reference/generated/numpy.repeat.html

sort2(a, axis=-1, descending=False)[source]¶

Return the sorted array and the indices to sort the array

See: https://pytorch.org/docs/stable/generated/torch.sort.html

coo_matrix(data, rows, cols, shape=None, type_as=None)[source]¶

Creates a sparse tensor in COOrdinate format.

This function follows the api from scipy.sparse.coo_matrix

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.coo_matrix.html

issparse(a)[source]¶

Checks whether or not the input tensor is a sparse tensor.

This function follows the api from scipy.sparse.issparse

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.issparse.html

eliminate_zeros(a, threshold=0.0)[source]¶

Removes entries smaller than the given threshold from the sparse tensor.

This function follows the api from scipy.sparse.csr_matrix.eliminate_zeros

See: https://docs.scipy.org/doc/scipy-0.14.0/reference/generated/scipy.sparse.csr_matrix.eliminate_zeros.html

todense(a)[source]¶

Converts a sparse tensor to a dense tensor.

This function follows the api from scipy.sparse.csr_matrix.toarray

See: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.csr_matrix.toarray.html

dtype_device(a)[source]¶: Returns the dtype and the device of the given tensor.

spateo.alignment.methods.align_preprocess(samples: List[anndata.AnnData], rep_layer: str | List[str] = 'X', rep_field: str | List[str] = 'layer', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', label_transfer_dict: dict | List[dict] | None = None, normalize_c: bool = False, normalize_g: bool = False, dtype: str = 'float64', device: str = 'cpu', verbose: bool = True) → Tuple[ot.backend.TorchBackend | ot.backend.NumpyBackend, torch.Tensor | numpy.ndarray, List[List[numpy.ndarray | torch.Tensor]], List[numpy.ndarray | torch.Tensor], torch.Tensor | numpy.ndarray, torch.Tensor | numpy.ndarray, torch.Tensor | numpy.ndarray][source]¶

Preprocess the data before alignment.

Parameters:

samples List[AnnData]: A list of AnnData objects containing the data samples.
genes Optional[Union[list, np.ndarray]], optional: Genes used for calculation. If None, use all common genes for calculation. Default is None.
spatial_key str, optional: The key in .obsm that corresponds to the raw spatial coordinates. Default is “spatial”.
layer str, optional: If ‘X’, uses sample.X to calculate dissimilarity between spots, otherwise uses the representation given by sample.layers[layer]. Default is “X”.
use_rep Optional[Union[str, List[str]]], optional: Specify the representation to use. If None, do not use the representation.
rep_type Optional[Union[str, List[str]]], optional: Specify the type of representation. Accept types: “obs” and “obsm”. If None, use the “obsm” type.
normalize_c bool, optional: Whether to normalize spatial coordinates. Default is False.
normalize_g bool, optional: Whether to normalize gene expression. Default is False.
dtype str, optional: The floating-point number type. Only float32 and float64 are allowed. Default is “float64”.
device str, optional: The device used to run the program. Can specify the GPU to use, e.g., ‘0’. Default is “cpu”.
verbose bool, optional: If True, print progress updates. Default is True.

Returns:

A tuple containing the following elements: - backend: The backend used for computations (TorchBackend or NumpyBackend). - type_as: The type used for computations which contains the dtype and device. - exp_layers: A list of processed expression layers. - spatial_coords: A list of spatial coordinates. - normalize_scales: Optional scaling factors for normalization. - normalize_means: Optional mean values for normalization.

Return type:

Tuple

Raises:

ValueError – If the specified representation is not found in the attributes of the AnnData objects.
AssertionError – If the spatial coordinate dimensions are different.

spateo.alignment.methods.cal_dist(X_A: numpy.ndarray | torch.Tensor, X_B: numpy.ndarray | torch.Tensor, use_gpu: bool = True, chunk_num: int = 1, return_gpu: bool = True) → numpy.ndarray | torch.Tensor[source]¶

Calculate the distance between two vectors

Parameters:

X_A Union[np.ndarray, torch.Tensor]: The first input vector with shape n x d
X_B Union[np.ndarray, torch.Tensor]: The second input vector with shape m x d
use_gpu bool, optional: Whether to use GPU for chunk. Defaults to True.
chunk_num int, optional: The number of chunks. The larger the number, the smaller the GPU memory usage, but the slower the calculation speed. Defaults to 1.

Returns:

Distance matrix of two vectors with shape n x m.

Return type:

Union[np.ndarray, torch.Tensor]

spateo.alignment.methods.cal_dot(mat1: numpy.ndarray | torch.Tensor, mat2: numpy.ndarray | torch.Tensor, use_chunk: bool = False, use_gpu: bool = True, chunk_num: int = 20) → numpy.ndarray | torch.Tensor[source]¶

Calculate the matrix multiplication of two matrices

Parameters:

mat1 Union[np.ndarray, torch.Tensor]: The first input matrix with shape n x d
mat2 Union[np.ndarray, torch.Tensor]: The second input matrix with shape d x m. We suppose m << n and does not require chunk.
use_chunk bool, optional: Whether to use chunk to reduce the GPU memory usage. Note that if set to ``True’’ it will slow down the calculation. Defaults to False.
use_gpu bool, optional: Whether to use GPU for chunk. Defaults to True.
chunk_num int, optional: The number of chunks. The larger the number, the smaller the GPU memory usage, but the slower the calculation speed. Defaults to 20.

Returns:

Matrix multiplication result with shape n x m

Return type:

Union[np.ndarray, torch.Tensor]

spateo.alignment.methods.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[source]¶

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', 'euclidean', 'euc', 'cos', or 'cosine'.

Returns:: The dissimilarity matrix of two feature samples.
Return type:: Union[np.ndarray, torch.Tensor]

class spateo.alignment.methods.Morpho_pairwise(sampleA: anndata.AnnData, sampleB: anndata.AnnData, rep_layer: str | List[str] = 'X', rep_field: str | List[str] = 'layer', genes: List[str] | numpy.ndarray | torch.Tensor | None = None, spatial_key: str = 'spatial', key_added: str = 'align_spatial', iter_key_added: str | None = None, save_concrete_iter: bool = False, vecfld_key_added: str | None = None, dissimilarity: str | List[str] = 'kl', probability_type: str | List[str] = 'gauss', probability_parameters: float | List[float] | None = None, label_transfer_dict: dict | List[dict] | None = None, nn_init: bool = True, init_transform: bool = True, allow_flip: bool = False, init_layer: str = 'X', init_field: str = 'layer', nn_init_top_K: int = 10, nn_init_weight: float = 1.0, max_iter: int = 200, nonrigid_start_iter: int = 80, SVI_mode: bool = True, batch_size: int | None = None, pre_compute_dist: bool = True, sparse_calculation_mode: bool = False, sparse_top_k: int = 1024, lambdaVF: int | float = 100.0, beta: int | float = 0.01, K: int | float = 15, kernel_type: str = 'euc', sigma2_init_scale: int | float | None = 0.1, sigma2_end: int | float | None = None, gamma_a: float = 1.0, gamma_b: float = 1.0, kappa: float | numpy.ndarray = 1.0, partial_robust_level: float = 10, normalize_c: bool = True, normalize_g: bool = False, separate_mean: bool = True, separate_scale: bool = False, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True, guidance_pair: List[numpy.ndarray] | numpy.ndarray | None = None, guidance_effect: bool | str | None = False, guidance_weight: float = 1.0, use_chunk: bool = False, chunk_capacity: float = 1.0, return_mapping: bool = False)[source]¶

A class to align two spatial transcriptomics AnnData objects using the Spateo alignment algorithm.

sampleA¶

The first AnnData object that acts as the reference.

Type:: AnnData

sampleB¶

The second AnnData object that acts as the reference.

Type:: AnnData

rep_layer¶

Representation layer(s) used for alignment. Default is “X”.

Type:: Union[str, List[str]]

rep_field¶

Representation layer field(s) in AnnData to be used for alignment. “layer” means gene expression, “obsm” means embdedding like pca or VAE, “obs” means discrete label annotation. Note that Spateo only accept one label annotation. Defaults to “layer”.

Type:: Union[str, List[str]]

genes¶

List or tensor of genes to be used for alignment. For example, you can input the genes you are interested or spatially variabe genes here. Defaults to None.

Type:: Optional[Union[List[str], torch.Tensor]]

spatial_key¶

Key in .obsm of AnnData corresponding to the spatial coordinates. Defaults to “spatial”.

Type:: str

key_added¶

Key under which the aligned spatial coordinates are added in .obsm. Defaults to “align_spatial”.

Type:: str

iter_key_added¶

Key under which to store intermediate iteration results in .uns. Defaults to None.

Type:: Optional[str]

save_concrete_iter¶

Whether to save more concrete intermediate iteration results. Default is False.

Type:: bool

vecfld_key_added¶

Key under which to store vector field results in .uns. Defaults to None.

Type:: Optional[str]

dissimilarity¶

Measure(s) of pairwise dissimilarity of each observation to be used. Defaults to “kl”.

Type:: Union[str, List[str]]

probability_type¶

Type(s) of probability distribution used. Defaults to “gauss”.

Type:: Union[str, List[str]]

probability_parameters¶

Parameters for the probability distribution. Defaults to None.

Type:: Optional[Union[float, List[float]]]

label_transfer_dict¶

Dictionary that stores the label transfer probability. Defaults to None.

Type:: Optional[Union[dict, List[dict]]]

nn_init¶

Whether to use nearest neighbor matching to initialize the alignment. Default is True.

Type:: bool

allow_flip¶

Whether to allow flipping of coordinates. Default is False.

Type:: bool

init_layer¶

Layer for initialize alignment. Defaults to “X”.

Type:: str

init_field¶

Layer field for initialize alignment. Defaults to ‘layer’.

Type:: str

nn_init_weight¶

Weight for nn_init guidance. Larger means that the nn_init guidance has more impact on the alignment, vice versa. Default is 1.0.

Type:: float

nn_init_top_K¶

The number of top K nearest neighbors to consider in the nn_init. Defaults to 10.

Type:: int, optional

guidance_pair¶

List of guidance pairs for alignment. Default is None.

Type:: Optional[Union[List[np.ndarray], np.ndarray]]

guidance_effect¶

Effect of guidance for the transformation. Valid value: False, “rigid”, “nonrigid”, and “both”. Default is False.

Type:: Optional[Union[bool, str]]

guidance_weight¶

Weight for guidance. Larger means that the guidance has more impact on the alignment, vice versa. Default is 1.

Type:: float

max_iter¶

Maximum number of iterations. Defaults to 200.

Type:: int

SVI_mode¶

Whether to use Stochastic Variational Inference mode. Default is True.

Type:: bool

batch_size¶

Size of the mini-batch of SVI. Default is 1000.

Type:: int

pre_compute_dist¶

Whether to precompute the distance matrix when using SVI mode. This will significantly speed up the calculation process but will also take more (GPU) memory. Default is True.

Type:: bool

sparse_calculation_mode¶

Whether to use sparse matrix calculation. This will significantly reduce the (GPU) memory but will also slow down the speed. Default is False.

Type:: bool

sparse_top_k¶

The top k elements to keep in sparse calculation mode. Default is 1024.

Type:: int

use_chunk¶

Whether to use chunking in calculations. This will reduce the (GPU) memory but will also slow down the speed. Default is False.

Type:: bool

chunk_capacity¶

Chunk size scale to the chunk_base.

Type:: float

lambdaVF¶

Regularization parameter for the vector field of the non-rigid transformation. Smaller means that non-rigid deformation gets fewer constraints, then deformation can be larger and more flexible, vice versa. Default is 1e2. Recommended setting range [1e-1, 1e4].

Type:: Union[int, float]

beta¶

Length-scale of the SE kernel. Larger means less correlation between points and more flexible non-rigid deformation, and vice versa. Default is 0.01. Recommended setting range [1e-4, 1e0].

Type:: Union[int, float]

K¶

Number of sparse inducing points used for Nyström approximation for the kernel. Default is 15.

Type:: Union[int, float]

kernel_type¶

Type of kernel used. Default is “euc”.

Type:: str

sigma2_init_scale¶

Initial value for the spatial dispersion level. Default is 0.1.

Type:: Optional[Union[int, float]]

partial_robust_level¶

Robust level of partial alignment. Default is 25.

Type:: float

normalize_c¶

Whether to normalize spatial coordinates. Default is True.

Type:: bool

normalize_g¶

Whether to normalize gene expression. Default is True.

Type:: bool

dtype¶

Data type for computations. Default is “float32”.

Type:: str

device¶

Device used to run the program. Default is “cpu”.

Type:: str

verbose¶

Whether to print verbose messages. Default is True.

Type:: bool

verbose¶

sampleA¶

sampleB¶

rep_layer¶

rep_field¶

genes¶

spatial_key¶

key_added¶

iter_key_added¶

save_concrete_iter¶

vecfld_key_added¶

dissimilarity¶

probability_type¶

probability_parameters¶

label_transfer_dict¶

nn_init¶

init_transform¶

nn_init_top_K¶

max_iter¶

allow_flip¶

init_layer¶

init_field¶

SVI_mode¶

batch_size¶

pre_compute_dist¶

sparse_calculation_mode¶

sparse_top_k¶

beta¶

lambdaVF¶

K¶

kernel_type¶

kernel_bandwidth¶

sigma2_init_scale¶

sigma2_end¶

partial_robust_level¶

normalize_c¶

normalize_g¶

separate_mean¶

separate_scale¶

dtype¶

device¶

guidance_pair¶

guidance_effect¶

guidance_weight¶

use_chunk¶

chunk_capacity¶

nn_init_weight¶

gamma_a¶

gamma_b¶

kappa¶

nonrigid_start_iter¶

return_mapping¶

run()[source]¶

Run the pairwise alignment process for spatial transcriptomics data.

Steps involved: 1. Perform coarse rigid alignment if nearest neighbor (nn) initialization is enabled. 2. Calculate the pairwise distance matrix for representations if pre-computation is enabled or not in SVI mode. 3. Initialize iteration variables and structures. 4. Perform iterative variational updates for alignment, including assignment P, gamma, alpha, sigma2, rigid and non-rigid updates. 5. Retrieve the full cell-cell assignment after the iterative process and calculate the optimal rigid transformation

Returns:: The final cell-cell assignment matrix.
Return type:: np.ndarray

_check()[source]¶

Validate and initialize various attributes for the Morpho_pairwise object.

This method performs several checks and initializations, including: - Representation layers and fields in AnnData objects - Spatial keys in AnnData objects - Label transfer dictionaries - Dissimilarity metrics - Probability types and parameters - Initialization layers and fields - Guidance effects

Raises:

ValueError – If any of the validations fail or required attributes are missing.
KeyError – If the specified spatial key is not found in the AnnData objects.

_align_preprocess(dtype: str = 'float32', device: str = 'cpu')[source]¶

Preprocess the data for alignment.

This method performs several preprocessing steps, including: - Determining the backend (CPU/GPU) for computation. - Extracting common genes from the samples. - Extracting gene expression or representations from the samples. - Checking and generating the label transfer matrix from the dictionary. - Extracting and normalizing spatial coordinates. - Normalizing gene expression if required. - Preprocessing guidance pairs if provided.

Parameters:

dtype str, optional: The data type for computations. Defaults to “float32”.
device str, optional: The device used for computation (e.g., “cpu” or “cuda:0”). Defaults to “cpu”.

Raises:

AssertionError – If the spatial coordinate dimensions of the samples are different.

_guidance_pair_preprocess()[source]¶

Preprocess the guidance pairs for alignment.

This method converts the guidance pairs to the backend type (e.g., NumPy, Torch) and normalizes them if required.

The normalization is based on the means and scales of the spatial coordinates.

Raises:: ValueError – If self.guidance_pair is not properly formatted.

_normalize_coords()[source]¶

Normalize the spatial coordinates of the samples.

This method normalizes the spatial coordinates of the samples to have zero mean and unit variance. It can normalize the coordinates separately or globally based on the provided arguments.

Raises:: AssertionError – If the dimensionality of the coordinates does not match.

_normalize_exps()[source]¶

Normalize the gene expression matrices.

This method normalizes the gene expression matrices for the samples if the representation field is ‘layer’ and the dissimilarity metric is not ‘kl’. The normalization ensures that the matrices have a consistent scale across the samples.

Raises:: ValueError – If the normalization scale cannot be calculated.

_initialize_variational_variables()[source]¶

Initialize variational variables for the alignment process.

This method sets initial guesses for various parameters, initializes variational variables, and configures the Stochastic Variational Inference (SVI) mode if enabled.

Parameters:

sigma2_init_scale float, optional: Initial scaling factor for sigma2. Defaults to 1.0.

Raises:

ValueError – If any initialization fails.

_init_probability_parameters(subsample: int = 20000)[source]¶

Initialize probability parameters for the alignment process.

This method calculates initial values for probability parameters based on the provided subsampling size and the specified dissimilarity and probability types.

Parameters:

subsample int, optional: The number of subsamples to use for initialization. Defaults to 20000.

Raises:

ValueError – If an unsupported probability type is encountered.

_construct_kernel(inducing_variables_num, sampling_method)[source]¶

Construct the kernel matrix for the alignment process.

This method generates inducing variables from the spatial coordinates, constructs the sparse kernel matrix, and handles different kernel types. It raises an error if the kernel type is not implemented.

Parameters:

inducing_variables_num int: Number of inducing variables to sample.
sampling_method str: Method used for sampling the inducing variables.

Raises:

NotImplementedError – If the specified kernel type is not implemented.

_update_batch(iter: int)[source]¶

Update the batch for Stochastic Variational Inference (SVI).

This method updates the batch indices and step size for each iteration during the SVI process. It ensures that the batch permutation is rolled to provide a new batch for each iteration.

Parameters:

iter int: The current iteration number.

Raises:

ValueError – If batch size exceeds the number of available data points.

_coarse_rigid_alignment(n_sampling=20000)[source]¶

Perform coarse rigid alignment between two sets of spatial coordinates.

This method performs downsampling, voxelization, and matching pairs construction based on brute force mutual K-nearest neighbors (K-NN). It calculates the similarity distance based on gene expression and performs a coarse alignment using inlier estimation. Optionally, it allows flipping the data for better alignment.

Parameters:

n_sampling int, optional: The number of samples to use for downsampling. Defaults to 20000.

Raises:

ValueError – If any required representation is not found in the AnnData objects.
RuntimeError – If coarse rigid alignment fails after reducing top_K.

_save_iter(iter: int)[source]¶

Save the current iteration’s alignment results.

This method saves the current transformed coordinates and the sigma2 value for the specified iteration. It normalizes the coordinates if normalization is enabled.

Parameters:

iter int: The current iteration number.

Raises:

KeyError – If key_added or “sigma2” key is not found in iter_added.

_update_assignment_P()[source]¶

Update the assignment matrix P.

This method calculates the assignment matrix P, which represents the probability of cells in the sampleB are generated by the cells in sampleA. It considers both spatial and expression / representation distances and updates variational parameters accordingly.

Parameters:

None

Raises:

ValueError – If any required representation is not found in the AnnData objects.

_update_gamma()[source]¶

Update the gamma parameter.

This method updates the gamma parameter based on the current state of the alignment process. It adjusts gamma using the digamma function (_psi) and ensures that gamma remains within the range [0.01, 0.99].

_update_alpha()[source]¶

Update the gamma parameter.

_update_nonrigid()[source]¶

Update the non-rigid transformation parameters.

This method updates the non-rigid transformation parameters using the current state of the alignment process. It computes the Sigma inverse matrix, the PXB term, and updates the variational parameters for the non-rigid alignment.

_update_rigid()[source]¶

Update the rigid transformation parameters.

This method updates the rigid transformation parameters using the current state of the alignment process. It solves for rotation and translation using the SVD formula and incorporates guidance and nearest neighbor initialization if applicable.

_update_sigma2(iter: int)[source]¶

Update the sigma2 parameter.

This method updates the sigma2 parameter based on the current state of the alignment process. It ensures that sigma2 remains above a certain threshold to prevent numerical instability.

Parameters:

iter int: The current iteration number.

Raises:

ValueError – If sigma2 is not properly updated.

_get_optimal_R()[source]¶

Compute the optimal rotation matrix R and translation vector t.

This method computes the optimal rotation matrix and translation vector for aligning the coordinates of sample A to sample B. It uses the SVD formula to determine the optimal rotation and ensures that the transformation maintains the correct orientation.

Raises:: ValueError – If the SVD decomposition fails or if the determinant check fails.

_wrap_output()[source]¶

Wrap the output after the alignment process.

This method denormalizes the aligned coordinates, converts them to numpy arrays, and saves them in the instance. It also prepares a dictionary containing the transformation parameters and metadata if vecfld_key_added is not None.

class spateo.alignment.methods.Mesh_correction(slices: List[anndata.AnnData], z_heights: List | numpy.ndarray, mesh: pyvista.PolyData, spatial_key: str = 'spatial', key_added: str = 'align_spatial', normalize_spatial: bool = False, init_rotation: numpy.ndarray | None = np.array([0.0, 0.0, 0.0]), init_translation: numpy.ndarray | None = 0.0, init_scaling: numpy.ndarray | None = 1.0, max_rotation_angle: float = 180, max_translation_scale: float = 0.5, max_scaling: float = 1.5, min_rotation_angle: float = 10, min_translation_scale: float = 1, min_scaling: float = 1.1, label_num: int = 15, fastpd_iter: int = 100, max_iter: int = 10, anneal_rate: float = 0.7, multi_processing: bool = False, subsample_slices: int | None = None, verbose: bool = False)[source]¶

A class to perform 3D reconstruction correction from slices using a mesh.

slices¶

A list of aligned slices by Spateo or other methods.

Type:: List[AnnData]

z_heights¶

The z-coordinates for each slice.

Type:: Union[List, np.ndarray]

mesh¶

The mesh used for correction.

Type:: PolyData

spatial_key¶

The key to access spatial coordinates in the AnnData objects. The spatial coordinates under this key should be pre-aligned.

Type:: str

key_added¶

The key under which the corrected spatial coordinates will be added.

Type:: str

normalize_spatial¶

Flag indicating if spatial coordinates will be normalized.

Type:: bool

init_rotation¶

Initial rotation angles (in degrees) for the correction.

Type:: np.ndarray

init_translation¶

Initial translation vector for the correction.

Type:: np.ndarray

init_scaling¶

Initial scaling factor for the correction.

Type:: np.ndarray

max_rotation_angle¶

Maximum rotation angle allowed during the correction process.

Type:: float

max_translation_scale¶

Maximum translation scale allowed during the correction process.

Type:: float

max_scaling¶

Maximum scaling factor allowed during the correction process.

Type:: float

label_num¶

Number of labels used for optimization.

Type:: int

fastpd_iter¶

Number of iterations for the fastPD algorithm.

Type:: int

max_iter¶

Maximum number of iterations for the correction process.

Type:: int

anneal_rate¶

Annealing rate for the optimization process.

Type:: float

multi_processing¶

Flag indicating if multiprocessing will be used for the correction process.

Type:: bool

n_slices¶

slices_spatial¶

z_heights¶

mesh¶

key_added¶

normalize_spatial¶

max_rotation_angle¶

max_translation_scale¶

max_scaling¶

min_rotation_angle¶

min_translation_scale¶

min_scaling¶

label_num¶

fastpd_iter¶

max_iter¶

anneal_rate¶

multi_processing¶

subsample_slices¶

verbose¶

contours¶

set_init_parameters(init_rotation: numpy.ndarray | None = np.array([0.0, 0.0, 0.0]), init_translation: numpy.ndarray | None = 0.0, init_scaling: numpy.ndarray | None = 1.0)[source]¶

Sets the initial transformation parameters for the mesh.

Parameters:

init_rotation Optional[np.ndarray], optional: Initial rotation angles (in degrees) for the mesh. Defaults to np.array([0., 0., 0.]).
init_translation Optional[np.ndarray], optional: Initial translation vector for the mesh. Defaults to 0.
init_scaling Optional[np.ndarray], optional: Initial scaling factor for the mesh. Defaults to 1.

normalize_mesh_spatial_coordinates()[source]¶

Normalizes the spatial coordinates of the mesh to align with the slices’ spatial scale.

This method calculates the scaling factor based on the maximum spatial extent of the slices and the z-height range, then applies this scaling to the mesh points. It also centers the mesh points along the z-axis to match the mean z-height of the slices.

extract_contours(method: Literal['opencv', 'alpha_shape'] = 'alpha_shape', n_sampling: int | None = None, smoothing: bool = True, window_size: int = 5, filter_contours: bool = True, contour_filter_threshold: int = 20, opencv_kwargs: Dict | None = None, alpha_shape_kwargs: Dict | None = None)[source]¶

Extracts contours of slices using the specified method.

Parameters:

method Literal["opencv", "alpha_shape"], optional: Method to extract contours. Defaults to “alpha_shape”.
n_sampling Optional[int], optional: Number of points to sample from each slice. Defaults to None.
smoothing bool, optional: Whether to smooth the contours. Defaults to True.
window_size int, optional: Window size for contour smoothing. Defaults to 5.
filter_contours bool, optional: Whether to filter the contours based on the threshold. Defaults to True.
contour_filter_threshold int, optional: Threshold for filtering contours based on the number of points. Defaults to 20.
opencv_kwargs Optional[Dict], optional: Additional arguments for the OpenCV method. Defaults to None.
alpha_shape_kwargs Optional[Dict], optional: Additional arguments for the alpha shape method. Defaults to None.

run_discrete_optimization() → None[source]¶: Runs the discrete optimization process to find the best transformation parameters.

discrete_optimization_step() → Tuple[float, numpy.ndarray][source]¶

Performs a discrete optimization step to find the best transformation.

Returns:: The loss and the best transformation found.
Return type:: Tuple[float, np.ndarray]

generate_labels() → numpy.ndarray[source]¶

Generates discrete labels for rotation, translation, and scaling.

Returns:: An array of discrete transformation labels.
Return type:: np.ndarray

perform_correction()[source]¶: Performs the correction using the best transformation found.

spateo.alignment.methods.generalized_procrustes_analysis(X, Y, pi)[source]¶

Finds and applies optimal rotation between spatial coordinates of two layers (may also do a reflection).

Parameters:

X: np array of spatial coordinates.
Y: np array of spatial coordinates.
pi: mapping between the two layers output by PASTE.

Returns:

Aligned spatial coordinates of X, Y and the mapping relations.

spateo.alignment.methods.paste_center_align(init_center_sample: anndata.AnnData, samples: List[anndata.AnnData], layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', lmbda: numpy.ndarray | None = None, alpha: float = 0.1, n_components: int = 15, threshold: float = 0.001, max_iter: int = 10, numItermax: int = 200, numItermaxEmd: int = 100000, dissimilarity: str = 'kl', norm: bool = False, random_seed: int | None = None, pis_init: List[numpy.ndarray] | None = None, distributions: List[numpy.ndarray] | None = None, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True) → Tuple[anndata.AnnData, List[numpy.ndarray]][source]¶

Computes center alignment of slices.

Parameters:

init_center_sample: Sample to use as the initialization for center alignment; Make sure to include gene expression and spatial information.
samples: List of samples to use in the center alignment.
layer: If ‘X’, uses sample.X to calculate dissimilarity between spots, otherwise uses the representation given by sample.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.
lmbda: List of probability weights assigned to each slice; If None, use uniform weights.
alpha: Alignment tuning parameter. Note: 0 <= alpha <= 1. When α = 0 only the gene expression data is taken into account, while when α =1 only the spatial coordinates are taken into account.
n_components: Number of components in NMF decomposition.
threshold: Threshold for convergence of W and H during NMF decomposition.
max_iter: Maximum number of iterations for our center alignment algorithm.
numItermax: Max number of iterations for cg during FGW-OT.
numItermaxEmd: Max number of iterations for emd during FGW-OT.
dissimilarity: Expression dissimilarity measure: 'kl' or 'euclidean'.
norm: If True, scales spatial distances such that neighboring spots are at distance 1. Otherwise, spatial distances remain unchanged.
random_seed: Set random seed for reproducibility.
pis_init: Initial list of mappings between ‘A’ and ‘slices’ to solver. Otherwise, default will automatically calculate mappings.
distributions: Distributions of spots for each slice. Otherwise, default is uniform.
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.

Returns:

Inferred center sample with full and low dimensional representations (W, H) of the gene expression matrix.
List of pairwise alignment mappings of the center sample (rows) to each input sample (columns).

spateo.alignment.methods.paste_pairwise_align(sampleA: anndata.AnnData, sampleB: anndata.AnnData, layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'spatial', alpha: float = 0.1, dissimilarity: str = 'kl', G_init=None, a_distribution=None, b_distribution=None, norm: bool = False, numItermax: int = 200, numItermaxEmd: int = 100000, dtype: str = 'float32', device: str = 'cpu', verbose: bool = True) → Tuple[numpy.ndarray, int | None][source]¶

Calculates and returns optimal alignment of two slices.

Parameters:

sampleA: Sample A to align.
sampleB: Sample B to align.
layer: If ‘X’, uses sample.X to calculate dissimilarity between spots, otherwise uses the representation given by sample.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.
alpha: Alignment tuning parameter. Note: 0 <= alpha <= 1. When α = 0 only the gene expression data is taken into account, while when α =1 only the spatial coordinates are taken into account.
dissimilarity: Expression dissimilarity measure: 'kl' or 'euclidean'.
G_init: Initial mapping to be used in FGW-OT, otherwise default is uniform mapping.
a_distribution: Distribution of sampleA spots, otherwise default is uniform.
b_distribution: Distribution of sampleB spots, otherwise default is uniform.
norm: If True, scales spatial distances such that neighboring spots are at distance 1. Otherwise, spatial distances remain unchanged.
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.

Returns:

Alignment of spots. obj: Objective function output of FGW-OT.

Return type:

spateo.alignment.methods._chunk[source]¶

spateo.alignment.methods._data[source]¶

spateo.alignment.methods._dot[source]¶

spateo.alignment.methods._mul[source]¶

spateo.alignment.methods._pi[source]¶

spateo.alignment.methods._power[source]¶

spateo.alignment.methods._prod[source]¶

spateo.alignment.methods._unsqueeze[source]¶

Calculate the distance between all pairs of samples in matrices X and Y using the specified metric.

Parameters:

X np.ndarray or torch.Tensor: Matrix with shape (N, D), where each row represents a sample.
Y np.ndarray or torch.Tensor: Matrix with shape (M, D), where each row represents a sample.
metric str, optional: The metric to use for calculating distances. Options are ‘euc’, ‘euclidean’, ‘square_euc’, ‘square_euclidean’, ‘kl’, ‘sym_kl’, ‘cos’, ‘cosine’, ‘label’. Default is ‘euc’.
label_transfer Optional[np.ndarray or torch.Tensor], optional: Matrix with shape (K, L) containing the label transfer cost. Required if metric is ‘label’. Default is None.

Returns:

Pairwise distance matrix with shape (N, M).

Return type:

np.ndarray or torch.Tensor

Raises:

AssertionError – If the number of features in X and Y do not match. If metric is not one of the supported metrics. If label_transfer is required but not provided.

spateo.alignment.methods.check_backend(device: str = 'cpu', dtype: str = 'float32', verbose: bool = True)[source]¶

Check the proper backend for the device.

Parameters:

device: Equipment used to run the program. You can also set the specified GPU for running. E.g.: ‘0’.
dtype: The floating-point number type. Only float32 and float64.
verbose: If True, print progress updates.

Returns:

The proper backend. type_as: The type_as.device is the device used to run the program and the type_as.dtype is the floating-point number type.

Return type:

backend

spateo.alignment.methods.check_exp(sample: anndata.AnnData, layer: str = 'X') → numpy.ndarray[source]¶

Check expression matrix.

Parameters:

sample AnnData: An AnnData object containing the sample data.
layer str, optional: The key in .layers that corresponds to the expression matrix. Defaults to “X”.

Returns:

The expression matrix.

Raises:

KeyError – If the specified layer is not found in sample.layers.

spateo.alignment.methods.con_K(X: numpy.ndarray | torch.Tensor, Y: numpy.ndarray | torch.Tensor, beta: int | float = 0.01) → numpy.ndarray | torch.Tensor[source]¶

con_K constructs the Squared Exponential (SE) kernel, where K(i,j)=k(X_i,Y_j)=exp(-beta*||X_i-Y_j||^2).

Parameters:

X: The first vector Xinmathbb{R}^{N imes d}
Y: The second vector Xinmathbb{R}^{M imes d}
beta: The length-scale of the SE kernel.
use_chunk bool, optional: Whether to use chunk to reduce the GPU memory usage. Note that if set to ``True’’ it will slow down the calculation. Defaults to False.

Returns:

The kernel Kinmathbb{R}^{N imes M}

Return type:

spateo.alignment.methods.empty_cache(device: str = 'cpu')[source]¶

spateo.alignment.methods.filter_common_genes(*genes, verbose: bool = True) → list[source]¶

Filters for the intersection of genes between all samples.

Parameters:

genes: List of genes.
verbose: If True, print progress updates.

spateo.alignment.methods.generate_label_transfer_dict(cat1: List[str], cat2: List[str], positive_pairs: List[Dict[str, List[str] | float]] | None = None, negative_pairs: List[Dict[str, List[str] | float]] | None = None, default_positve_value: float = 10.0) → Dict[str, Dict[str, float]][source]¶

Generate a label transfer dictionary with normalized values.

Parameters:

cat1 List[str]: List of categories from the first dataset.
cat2 List[str]: List of categories from the second dataset.
positive_pairs Optional[List[Dict[str, Union[List[str], float]]]], optional: List of positive pairs with transfer values. Each dictionary should have ‘left’, ‘right’, and ‘value’ keys. Defaults to None.
negative_pairs Optional[List[Dict[str, Union[List[str], float]]]], optional: List of negative pairs with transfer values. Each dictionary should have ‘left’, ‘right’, and ‘value’ keys. Defaults to None.
default_positive_value float, optional: Default value for positive pairs if none are provided. Defaults to 10.0.

Returns:

A normalized label transfer dictionary.

Return type:

Dict[str, Dict[str, float]]

spateo.alignment.methods.intersect_lsts[source]¶