spateo.alignment.methods.utils¶
Attributes¶
Functions¶
|
Check the proper backend for the device. |
|
Check and return the spatial coordinate information from an AnnData object. |
|
Check expression matrix. |
|
Check that the number of occurrences of 'obs' in the list of representation fields is no more than one. |
|
Check if specified representations exist in the .layers, .obsm, or .obs attributes of AnnData objects. |
|
Check the label transfer dictionary for consistency with given categories. |
|
Check and generate label transfer matrices for the given samples. |
|
Generate a label transfer dictionary with normalized values. |
|
Get the specified representation from the AnnData object. |
|
Filters for the intersection of genes between all samples. |
|
Normalize the spatial coordinate. |
|
Normalize the gene expression matrices. |
|
Compute the pairwise KL divergence between all pairs of samples in matrices X and Y. |
|
Compute the pairwise cosine similarity between all pairs of samples in matrices X and Y. |
|
Compute the pairwise Euclidean distance between all pairs of samples in matrices X and Y. |
|
Generate a matrix of size (N, M) by indexing into the label_transfer matrix using the values in X and Y. |
|
Calculate the distance between all pairs of samples in matrices X and Y using the specified metric. |
|
Calculate probability based on the distance matrix and specified probability type. |
|
Compute assignment matrix P and additional results based on given distances and parameters. |
|
|
|
con_K constructs the Squared Exponential (SE) kernel, where K(i,j)=k(X_i,Y_j)=exp(-beta*||X_i-Y_j||^2). |
|
Construct a k-nearest neighbor graph from the given points. |
|
Construct the kernel matrix from the given graph and inducing points. |
|
|
|
Voxelization of the data. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Module Contents¶
- spateo.alignment.methods.utils.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.utils.check_spatial_coords(sample: anndata.AnnData, spatial_key: str = 'spatial') numpy.ndarray[source]¶
Check and return the spatial coordinate information from an AnnData object.
- Parameters:
- sample AnnData
An AnnData object containing the sample data.
- spatial_key str, optional
The key in .obsm that corresponds to the raw spatial coordinates. Defaults to “spatial”.
- Returns:
The spatial coordinates.
- Return type:
np.ndarray
- Raises:
KeyError – If the specified spatial_key is not found in sample.obsm.
- spateo.alignment.methods.utils.check_exp(sample: anndata.AnnData, layer: str = 'X') numpy.ndarray[source]¶
Check expression matrix.
- spateo.alignment.methods.utils.check_obs(rep_layer: List[str], rep_field: List[str]) str | None[source]¶
Check that the number of occurrences of ‘obs’ in the list of representation fields is no more than one.
- Parameters:
- Returns:
The representation key if ‘obs’ occurs exactly once, otherwise None.
- Return type:
Optional[str]
- Raises:
ValueError – If ‘obs’ occurs more than once in the list.
- spateo.alignment.methods.utils.check_rep_layer(samples: List[anndata.AnnData], rep_layer: str | List[str] = 'X', rep_field: str | List[str] = 'layer') bool[source]¶
Check if specified representations exist in the .layers, .obsm, or .obs attributes of AnnData objects.
- Parameters:
- samples List[AnnData]
A list of AnnData objects containing the data samples.
- rep_layer Union[str, List[str]], optional
The representation layer(s) to check. Defaults to “X”.
- rep_field Union[str, List[str]], optional
The field(s) indicating the type of representation. Acceptable values are “layer”, “obsm”, and “obs”. Defaults to “layer”.
- Returns:
True if all specified representations exist in the corresponding attributes of all AnnData objects, False otherwise.
- Return type:
- Raises:
ValueError – If the specified representation is not found in the specified attribute or if the attribute type is invalid.
- spateo.alignment.methods.utils.check_label_transfer_dict(catA: List[str], catB: List[str], label_transfer_dict: Dict[str, Dict[str, float]])[source]¶
Check the label transfer dictionary for consistency with given categories.
- Parameters:
- Raises:
- spateo.alignment.methods.utils.check_label_transfer(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, type_as: torch.Tensor | numpy.ndarray, sampleA: anndata.AnnData, sampleB: anndata.AnnData, obs_key: str, label_transfer_dict: Dict[str, Dict[str, float]] | None = None) List[numpy.ndarray | torch.Tensor][source]¶
Check and generate label transfer matrices for the given samples.
- Parameters:
- nx module
Backend module (e.g., numpy or torch).
- type_as type
Type to which the output should be cast.
- samples List[AnnData]
List of AnnData objects containing the samples.
- obs_key str
The key in .obs that corresponds to the labels.
- label_transfer_dict Optional[List[Dict[str, Dict[str, float]]]], optional
List of dictionaries defining the label transfer cost between categories of each pair of samples. Defaults to None.
- Returns:
List of label transfer matrices, each as either a NumPy array or torch Tensor.
- Return type:
List[Union[np.ndarray, torch.Tensor]]
- Raises:
ValueError – If the length of label_transfer_dict does not match len(samples) - 1.
- spateo.alignment.methods.utils.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_positive_value: float = 10.0, default_negative_value: float = 1.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.
- default_negative_value float, optional
Default value for negative pairs if none are provided. Defaults to 1.0.
- Returns:
A normalized label transfer dictionary.
- Return type:
- spateo.alignment.methods.utils.get_rep(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, type_as: torch.Tensor | numpy.ndarray, sample: anndata.AnnData, rep: str = 'X', rep_field: str = 'layer', genes: list | numpy.ndarray | None = None) numpy.ndarray[source]¶
Get the specified representation from the AnnData object.
- Parameters:
- nx module
Backend module (e.g., numpy or torch).
- type_as type
Type to which the output should be cast.
- sample AnnData
The AnnData object containing the sample data.
- rep str, optional
The name of the representation to retrieve. Defaults to “X”.
- rep_field str, optional
The type of representation. Acceptable values are “layer”, “obs” and “obsm”. Defaults to “layer”.
- genes Optional[Union[list, np.ndarray]], optional
List of genes to filter if rep_field is “layer”. Defaults to None.
- Returns:
The requested representation from the AnnData object, cast to the specified type.
- Return type:
Union[np.ndarray, torch.Tensor]
- Raises:
ValueError – If rep_field is not one of the expected values.
KeyError – If the specified representation is not found in the AnnData object.
- spateo.alignment.methods.utils.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.utils.normalize_coords(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, coords: List[numpy.ndarray | torch.Tensor], verbose: bool = True, separate_scale: bool = True, separate_mean: bool = True) Tuple[List[numpy.ndarray | torch.Tensor], List[numpy.ndarray | torch.Tensor], List[numpy.ndarray | torch.Tensor]][source]¶
Normalize the spatial coordinate.
- Parameters:
- coords List[Union[np.ndarray, torch.Tensor]]
Spatial coordinates of the samples. Each element in the list can be a numpy array or a torch tensor.
- nx Union[TorchBackend, NumpyBackend], optional
The backend to use for computations. Default is NumpyBackend.
- verbose bool, optional
If True, print progress updates. Default is True.
- separate_scale bool, optional
If True, normalize each coordinate axis independently. When doing the global refinement, this weill be set to False. Default is True.
- separate_mean bool, optional
If True, normalize each coordinate axis to have zero mean independently. When doing the global refinement, this weill be set to False. Default is True.
- Returns:
A tuple containing: - coords: List of normalized spatial coordinates. - normalize_scales: List of normalization scale factors applied to each coordinate axis. - normalize_means: List of mean values used for normalization of each coordinate axis.
- Return type:
Tuple[List[Union[np.ndarray, torch.Tensor]], List[Union[np.ndarray, torch.Tensor]], List[Union[np.ndarray, torch.Tensor]]]
- spateo.alignment.methods.utils.normalize_exps(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, exp_layers: List[List[numpy.ndarray | torch.Tensor]], rep_field: str | List[str] = 'layer', verbose: bool = True) List[List[numpy.ndarray | torch.Tensor]][source]¶
Normalize the gene expression matrices.
- Parameters:
- nx Union[TorchBackend, NumpyBackend], optional
The backend to use for computations. Defaults to NumpyBackend.
- exp_layers List[List[Union[np.ndarray, torch.Tensor]]]
Gene expression and optionally the representation matrices of the samples. Each element in the list can be a numpy array or a torch tensor.
- rep_field Union[str, List[str]], optional
Field(s) indicating the type of representation. If ‘layer’, normalization can be applied. Defaults to “layer”.
- verbose bool, optional
If True, print progress updates. Default is True.
- Returns:
A list of lists containing normalized gene expression matrices. Each matrix in the list is a numpy array or a torch tensor.
- Return type:
List[List[Union[np.ndarray, torch.Tensor]]]
- spateo.alignment.methods.utils._kl_distance_backend(X: numpy.ndarray | torch.Tensor, Y: numpy.ndarray | torch.Tensor, probabilistic: bool = True, eps: float = 1e-08) numpy.ndarray | torch.Tensor[source]¶
Compute the pairwise KL divergence between all pairs of samples in matrices X and Y.
- 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.
- probabilistic bool, optional
If True, normalize the rows of X and Y to sum to 1 (to interpret them as probabilities). Default is True.
- eps float, optional
A small value to avoid division by zero. Default is 1e-8.
- Returns:
Pairwise KL divergence matrix with shape (N, M).
- Return type:
np.ndarray
- Raises:
AssertionError – If the number of features in X and Y do not match.
- spateo.alignment.methods.utils._cosine_distance_backend(X: numpy.ndarray | torch.Tensor, Y: numpy.ndarray | torch.Tensor, eps: float = 1e-08) numpy.ndarray | torch.Tensor[source]¶
Compute the pairwise cosine similarity between all pairs of samples in matrices X and Y.
- 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.
- eps float, optional
A small value to avoid division by zero. Default is 1e-8.
- Returns:
Pairwise cosine similarity 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.
- spateo.alignment.methods.utils._euc_distance_backend(X: numpy.ndarray | torch.Tensor, Y: numpy.ndarray | torch.Tensor, squared: bool = True) numpy.ndarray | torch.Tensor[source]¶
Compute the pairwise Euclidean distance between all pairs of samples in matrices X and Y.
- 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.
- squared bool, optional
If True, return squared Euclidean distances. Default is True.
- Returns:
Pairwise Euclidean 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.
- spateo.alignment.methods.utils._label_distance_backend(X: numpy.ndarray | torch.Tensor, Y: numpy.ndarray | torch.Tensor, label_transfer: numpy.ndarray | torch.Tensor) numpy.ndarray | torch.Tensor[source]¶
Generate a matrix of size (N, M) by indexing into the label_transfer matrix using the values in X and Y.
- Parameters:
- X np.ndarray or torch.Tensor
Array with shape (N, ) containing integer values ranging from 0 to K.
- Y np.ndarray or torch.Tensor
Array with shape (M, ) containing integer values ranging from 0 to L.
- label_transfer np.ndarray or torch.Tensor
Matrix with shape (K, L) containing the label transfer cost.
- Returns:
Matrix with shape (N, M) where each element is the value from label_transfer indexed by the corresponding values in X and Y.
- Return type:
np.ndarray or torch.Tensor
- Raises:
AssertionError – If the shape of X or Y is not one-dimensional or if they contain non-integer values.
- spateo.alignment.methods.utils.calc_distance(X: List[numpy.ndarray | torch.Tensor] | numpy.ndarray | torch.Tensor, Y: List[numpy.ndarray | torch.Tensor] | numpy.ndarray | torch.Tensor, metric: List[str] | str = 'euc', label_transfer: numpy.ndarray | torch.Tensor | None = None) numpy.ndarray | torch.Tensor[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.utils.calc_probability(nx, distance_matrix: numpy.ndarray | torch.Tensor, probability_type: str = 'gauss', probability_parameter: float | None = None) numpy.ndarray | torch.Tensor[source]¶
Calculate probability based on the distance matrix and specified probability type.
- Parameters:
- distance_matrix np.ndarray or torch.Tensor
The distance matrix.
- probability_type str, optional
The type of probability to calculate. Options are ‘Gauss’, ‘cos_prob’, and ‘prob’. Default is ‘Gauss’.
- probability_parameter Optional[float], optional
The parameter for the probability calculation. Required for certain probability types. Default is None.
- Returns:
The calculated probability matrix.
- Return type:
np.ndarray or torch.Tensor
- Raises:
ValueError – If probability_type is not one of the supported types or if required parameters are missing.
- spateo.alignment.methods.utils.get_P_core(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, type_as: torch.Tensor | numpy.ndarray, Dim: torch.Tensor | numpy.ndarray, spatial_dist: numpy.ndarray | torch.Tensor, exp_dist: List[numpy.ndarray | torch.Tensor], sigma2: int | float | numpy.ndarray | torch.Tensor, model_mul: numpy.ndarray | torch.Tensor, gamma: float | numpy.ndarray | torch.Tensor, samples_s: List[float] | None = None, sigma2_variance: float = 1, probability_type: str | List[str] = 'Gauss', probability_parameters: List | None = None, eps: float = 1e-08, sparse_calculation_mode: bool = False, top_k: int = -1)[source]¶
Compute assignment matrix P and additional results based on given distances and parameters.
- Parameters:
- nx module
Backend module (e.g., numpy or torch).
- type_as type
Type to which the output should be cast.
- spatial_dist np.ndarray or torch.Tensor
Spatial distance matrix.
- exp_dist List[np.ndarray or torch.Tensor]
List of expression distance matrices.
- sigma2 int, float, np.ndarray or torch.Tensor
Sigma squared value.
- alpha np.ndarray or torch.Tensor
Alpha values.
- gamma float, np.ndarray or torch.Tensor
Gamma value.
- Sigma np.ndarray or torch.Tensor
Sigma values.
- samples_s Optional[List[float]], optional
Samples. Default is None.
- sigma2_variance float, optional
Sigma squared variance. Default is 1.
- probability_type Union[str, List[str]], optional
Probability type. Default is ‘Gauss’.
- probability_parameters Optional[List[float]], optional
Probability parameters. Default is None.
- Returns:
np.ndarray or torch.Tensor – Assignment matrix P.
dict – Additional results.
- spateo.alignment.methods.utils.solve_RT_by_correspondence(X: numpy.ndarray, Y: numpy.ndarray, return_s=False)[source]¶
- spateo.alignment.methods.utils.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:
- Returns:
The kernel Kinmathbb{R}^{N imes M}
- Return type:
K
- spateo.alignment.methods.utils.construct_knn_graph(points: numpy.ndarray | torch.Tensor, knn: int = 10)[source]¶
Construct a k-nearest neighbor graph from the given points.
- Parameters:
- points
The points to construct the graph from.
- knn
The number of nearest neighbors to consider.
- Returns:
The networks graph object.
- spateo.alignment.methods.utils.con_K_graph(graph: networkx.Graph, inducing_idx: numpy.ndarray | torch.Tensor, beta: int | float = 0.01)[source]¶
Construct the kernel matrix from the given graph and inducing points.
- Parameters:
- graph
The graph object.
- inducing_idx
The indices of the inducing points.
- Returns:
The kernel matrix.
- spateo.alignment.methods.utils.voxel_data(nx: spateo.alignment.methods.backend.TorchBackend | spateo.alignment.methods.backend.NumpyBackend, coords: numpy.ndarray | torch.Tensor, gene_exp: numpy.ndarray | torch.Tensor, voxel_size: float | None = None, voxel_num: int | None = 10000)[source]¶
Voxelization of the data. :param coords: The coordinates of the data points. :type coords: np.ndarray or torch.Tensor :param gene_exp: The gene expression of the data points. :type gene_exp: np.ndarray or torch.Tensor :param voxel_size: The size of the voxel. :type voxel_size: float :param voxel_num: The number of voxels. :type voxel_num: int
- Returns:
voxel_coords (np.ndarray or torch.Tensor) – The coordinates of the voxels.
voxel_gene_exp (np.ndarray or torch.Tensor) – The gene expression of the voxels.