spateo.tdr.morphometrics¶

Submodules¶

Functions¶

`cell_directions`(→ Tuple[Optional[anndata.AnnData], ...)	Obtain the optimal mapping relationship and developmental direction between cells for samples between continuous developmental stages.
`morphofield_gp`(→ Optional[anndata.AnnData])	Calculating and predicting the vector field during development by the Gaussian Process method.
`morphofield_sparsevfc`(, inplace, ...)	Calculating and predicting the vector field during development by the Kernel method (sparseVFC).
`morphopath`(→ Optional[anndata.AnnData])	Prediction of cell developmental trajectory based on reconstructed vector field.
`morphofield_acceleration`(→ Optional[anndata.AnnData])	Calculate acceleration for each cell with the reconstructed vector field function.
`morphofield_curl`(→ Optional[anndata.AnnData])	Calculate curl for each cell with the reconstructed vector field function.
`morphofield_curvature`(→ Optional[anndata.AnnData])	Calculate curvature for each cell with the reconstructed vector field function.
`morphofield_divergence`(→ Optional[anndata.AnnData])	Calculate divergence for each cell with the reconstructed vector field function.
`morphofield_jacobian`(→ Optional[anndata.AnnData])	Calculate jacobian for each cell with the reconstructed vector field function.
`morphofield_torsion`(→ Optional[anndata.AnnData])	Calculate torsion for each cell with the reconstructed vector field function.
`morphofield_velocity`(→ Optional[anndata.AnnData])	Calculate the velocity for each cell with the reconstructed vector field function.
`model_morphology`(→ Dict[str, Union[float, Any]])	Return the basic morphological characteristics of model,
`pc_KDE`(→ Tuple[Union[pyvista.DataSet, ...)	Calculate the kernel density of a 3D point cloud model.
`pairwise_shape_similarity`(→ float)	Calculate the shape similarity of pairwise 3D point cloud models based on the eigenvectors of the 3D point cloud model subspace.

Package Contents¶

spateo.tdr.morphometrics.cell_directions(adataA: anndata.AnnData, adataB: anndata.AnnData, layer: str = 'X', genes: list | numpy.ndarray | None = None, spatial_key: str = 'align_spatial', key_added: str = 'mapping', alpha: float = 0.001, numItermax: int = 200, numItermaxEmd: int = 100000, dtype: str = 'float32', device: str = 'cpu', keep_all: bool = False, inplace: bool = True, **kwargs) → Tuple[anndata.AnnData | None, numpy.ndarray][source]¶

Obtain the optimal mapping relationship and developmental direction between cells for samples between continuous developmental stages.

Parameters:

adataA

AnnData object of sample A from continuous developmental stages.

adataB

AnnData object of sample B from continuous developmental stages.

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 spatial coordinate of each cell.

.uns. The key that will be used for the vector field key in

key_added

The key that will be used in .obsm.

X_{key_added}-The X_{key_added} that will be used for the coordinates of the cell that maps optimally in the next stage.
V_{key_added}-The V_{key_added} that will be used for the cell developmental directions.

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'

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.

inplace

Whether to copy adata or modify it inplace.

**kwargs

Additional parameters that will be passed to pairwise_align function.

Returns:

An AnnData object of sample A is updated/copied with the X_{key_added} and V_{key_added} in the .obsm attribute. A pi metrix.

spateo.tdr.morphometrics.morphofield_gp(adata: anndata.AnnData, spatial_key: str = 'align_spatial', vf_key: str = 'VecFld_morpho', NX: numpy.ndarray | None = None, grid_num: List[int] | None = None, nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculating and predicting the vector field during development by the Gaussian Process method.

Parameters:

adata: AnnData object that contains the cell coordinates of the two states after alignment.
spatial_key: The key from the .obsm that corresponds to the spatial coordinates of each cell.
vf_key: The key in .uns that corresponds to the reconstructed vector field.
key_added: The key that will be used for the vector field key in .uns.
NX: The spatial coordinates of new data point. If NX is None, generate new points based on grid_num.
grid_num: The number of grids in each dimension for generating the grid velocity. Default is [50, 50, 50].
nonrigid_only: If True, only the nonrigid part of the vector field will be calculated.
inplace: Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added dictionary in the .uns attribute.

The key_added dictionary which contains:

X: Cell coordinates of the current state. V: Developmental direction of the X. grid: Grid coordinates of current state. grid_V: Prediction of developmental direction of the grid. method: The method of learning vector field. Here method == ‘gaussian_process’.

spateo.tdr.morphometrics.morphofield_sparsevfc(adata: anndata.AnnData, spatial_key: str = 'align_spatial', V_key: str = 'V_mapping', key_added: str = 'VecFld_morpho', NX: numpy.ndarray | None = None, grid_num: List[int] | None = None, M: int = 100, lambda_: float = 0.02, lstsq_method: str = 'scipy', min_vel_corr: float = 0.8, restart_num: int = 10, restart_seed: List[int] | Tuple[int] | numpy.ndarray = (0, 100, 200, 300, 400), inplace: bool = True, **kwargs) → anndata.AnnData | None[source]¶

Calculating and predicting the vector field during development by the Kernel method (sparseVFC).

Parameters:

adata: AnnData object that contains the cell coordinates of the two states after alignment.
spatial_key: The key from the .obsm that corresponds to the spatial coordinates of each cell.
V_key: The key from the .obsm that corresponds to the developmental direction of each cell.
key_added: The key that will be used for the vector field key in .uns.
NX: The spatial coordinates of new data point. If NX is None, generate new points based on grid_num.
grid_num: The number of grids in each dimension for generating the grid velocity. Default is [50, 50, 50].
M: The number of basis functions to approximate the vector field.
lambda: Represents the trade-off between the goodness of data fit and regularization. Larger Lambda_ put more weights on regularization.
lstsq_method: The name of the linear least square solver, can be either 'scipy' or 'douin'.
min_vel_corr: The minimal threshold for the cosine correlation between input velocities and learned velocities to consider as a successful vector field reconstruction procedure. If the cosine correlation is less than this threshold and restart_num > 1, restart_num trials will be attempted with different seeds to reconstruct the vector field function. This can avoid some reconstructions to be trapped in some local optimal.
restart_num: The number of retrials for vector field reconstructions.
restart_seed: A list of seeds for each retrial. Must be the same length as restart_num or None.
inplace: Whether to copy adata or modify it inplace.
**kwargs: Additional parameters that will be passed to SparseVFC function.

Returns:

An AnnData object is updated/copied with the key_added dictionary in the .uns attribute.

The key_added dictionary which contains:

X: Current state. valid_ind: The indices of cells that have finite velocity values. X_ctrl: Sample control points of current state. ctrl_idx: Indices for the sampled control points. Y: Velocity estimates in delta t. beta: Parameter of the Gaussian Kernel for the kernel matrix (Gram matrix). V: Prediction of velocity of X. C: Finite set of the coefficients for the P: Posterior probability Matrix of inliers. VFCIndex: Indexes of inliers found by sparseVFC. sigma2: Energy change rate. grid: Grid of current state. grid_V: Prediction of velocity of the grid. iteration: Number of the last iteration. tecr_vec: Vector of relative energy changes rate comparing to previous step. E_traj: Vector of energy at each iteration. method: The method of learning vector field. Here method == ‘sparsevfc’.

Here the most important results are X, V, grid and grid_V.

X: Cell coordinates of the current state. V: Developmental direction of the X. grid: Grid coordinates of current state. grid_V: Prediction of developmental direction of the grid.

spateo.tdr.morphometrics.morphopath(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'fate_morpho', layer: str = 'X', direction: str = 'forward', interpolation_num: int = 250, t_end: int | float | None = None, average: bool = False, cores: int = 1, nonrigid_only: bool = False, inplace: bool = True, **kwargs) → anndata.AnnData | None[source]¶

Prediction of cell developmental trajectory based on reconstructed vector field.

Parameters:

adata: AnnData object that contains the reconstructed vector field function in the .uns attribute.
vf_key: The key in .uns that corresponds to the reconstructed vector field.
key_added: The key under which to add the dictionary Fate (includes t and prediction keys).
layer: Which layer of the data will be used for predicting cell fate with the reconstructed vector field function.
direction: The direction to predict the cell fate. One of the forward, backward or both string.
interpolation_num: The number of uniformly interpolated time points.
t_end: The length of the time period from which to predict cell state forward or backward over time.
average: The method to calculate the average cell state at each time step, can be one of origin or trajectory. If origin used, the average expression state from the init_cells will be calculated and the fate prediction is based on this state. If trajectory used, the average expression states of all cells predicted from the vector field function at each time point will be used. If average is False, no averaging will be applied.
cores: Number of cores to calculate path integral for predicting cell fate. If cores is set to be > 1, multiprocessing will be used to parallel the fate prediction.
nonrigid_only: If True, only the nonrigid part of the vector field will be calculated.
inplace: Whether to copy adata or modify it inplace.
**kwargs: Additional parameters that will be passed into the fate function.

Returns:

An AnnData object is updated/copied with the key_added dictionary in the .uns attribute.

The key_added dictionary which contains:

t: The time at which the cell state are predicted. prediction: Predicted cells states at different time points. Row order corresponds to the element order in

t. If init_states corresponds to multiple cells, the expression dynamics over time for each cell is concatenated by rows. That is, the final dimension of prediction is (len(t) * n_cells, n_features). n_cells: number of cells; n_features: number of genes or number of low dimensional embeddings. Of note, if the average is set to be True, the average cell state at each time point is calculated for all cells.

spateo.tdr.morphometrics.morphofield_acceleration(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'acceleration', method: str = 'analytical', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate acceleration for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the acceleration key in .obs and .obsm.

method

The method that will be used for calculating acceleration field, either 'analytical' or 'numerical'.

'analytical' method uses the analytical expressions for calculating acceleration while 'numerical' method uses numdifftools, a numerical differentiation tool, for computing acceleration. 'analytical' method is much more efficient.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs and .obsm attribute.

The key_added in the .obs which contains acceleration. The key_added in the .obsm which contains acceleration vectors.

spateo.tdr.morphometrics.morphofield_curl(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'curl', method: str = 'analytical', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate curl for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the torsion key in .obs.

method

The method that will be used for calculating torsion field, either 'analytical' or 'numerical'.

'analytical' method uses the analytical expressions for calculating torsion while 'numerical' method uses numdifftools, a numerical differentiation tool, for computing torsion. 'analytical' method is much more efficient.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs and .obsm attribute.

The key_added in the .obs which contains magnitude of curl. The key_added in the .obsm which contains curl vectors.

spateo.tdr.morphometrics.morphofield_curvature(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'curvature', formula: int = 2, method: str = 'analytical', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate curvature for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the curvature key in .obs and .obsm.

formula

Which formula of curvature will be used, there are two formulas, so formula can be either {1, 2}. By default it is 2 and returns both the curvature vectors and the norm of the curvature. The formula one only gives the norm of the curvature.

method

The method that will be used for calculating curvature field, either 'analytical' or 'numerical'.

'analytical' method uses the analytical expressions for calculating curvature while 'numerical' method uses numdifftools, a numerical differentiation tool, for computing curvature. 'analytical' method is much more efficient.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs and .obsm attribute.

The key_added in the .obs which contains curvature. The key_added in the .obsm which contains curvature vectors.

spateo.tdr.morphometrics.morphofield_divergence(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'divergence', method: str = 'analytical', vectorize_size: int | None = 1000, nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate divergence for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the acceleration key in .obs and .obsm.

method

The method that will be used for calculating acceleration field, either 'analytical' or 'numerical'.

vectorize_size

vectorize_size is used to control the number of samples computed in each vectorized batch.

If vectorize_size = 1, there’s no vectorization whatsoever.
If vectorize_size = None, all samples are vectorized.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs attribute.

The key_added in the .obs which contains divergence.

spateo.tdr.morphometrics.morphofield_jacobian(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'jacobian', method: str = 'analytical', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate jacobian for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the jacobian key in .obs and .obsm.

method

The method that will be used for calculating jacobian field, either 'analytical' or 'numerical'.

'analytical' method uses the analytical expressions for calculating jacobian while 'numerical' method uses numdifftools, a numerical differentiation tool, for computing jacobian. 'analytical' method is much more efficient.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs and .uns attribute.

The key_added in the .obs which contains jacobian. The key_added in the .uns which contains jacobian tensor.

spateo.tdr.morphometrics.morphofield_torsion(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'torsion', method: str = 'analytical', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate torsion for each cell with the reconstructed vector field function.

Parameters:

adata

AnnData object that contains the reconstructed vector field.

vf_key

The key in .uns that corresponds to the reconstructed vector field.

key_added

The key that will be used for the torsion key in .obs and .obsm.

method

The method that will be used for calculating torsion field, either 'analytical' or 'numerical'.

nonrigid_only

If True, only the nonrigid part of the vector field will be calculated.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs and .uns attribute.

The key_added in the .obs which contains torsion. The key_added in the .uns which contains torsion matrix.

spateo.tdr.morphometrics.morphofield_velocity(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'velocity', nonrigid_only: bool = False, inplace: bool = True) → anndata.AnnData | None[source]¶

Calculate the velocity for each cell with the reconstructed vector field function.

Parameters:

adata: AnnData object that contains the reconstructed vector field.
vf_key: The key in .uns that corresponds to the reconstructed vector field.
key_added: The key that will be used for the velocity key in .obsm.
nonrigid_only: If True, only the nonrigid part of the vector field will be calculated.
inplace: Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obsm attribute which contains velocities.

spateo.tdr.morphometrics.model_morphology(model: pyvista.PolyData | pyvista.UnstructuredGrid, pc: Optional[PolyData or UnstructuredGrid] = None) → Dict[str, float | Any][source]¶

Return the basic morphological characteristics of model, including model volume, model surface area, volume / surface area ratio，etc.

Parameters:

model: A reconstructed surface model or volume model.
pc: A point cloud representing the number of cells.

Returns:

A dictionary containing the following model morphological features:: morphology[‘Length(x)’]: Length (x) of model. morphology[‘Width(y)’]: Width (y) of model. morphology[‘Height(z)’]: Height (z) of model. morphology[‘Surface_area’]: Surface area of model. morphology[‘Volume’]: Volume of model. morphology[‘V/SA_ratio’]: Volume / surface area ratio of model; morphology[‘cell_density’]: Cell density of model.

Return type:

morphology

Calculate the kernel density of a 3D point cloud model.

Parameters:

pc: A point cloud model.
key_added: The key under which to add the labels.
kernel: The kernel to use. Available kernel are: * ‘gaussian’ * ‘tophat’ * ‘epanechnikov’ * ‘exponential’ * ‘linear’ * ‘cosine’
bandwidth: The bandwidth of the kernel.
colormap: Colors to use for plotting pcd. The default colormap is ‘hot_r’.
alphamap: The opacity of the colors to use for plotting pcd. The default alphamap is 1.0.
inplace: Updates model in-place.

Returns:

Reconstructed 3D point cloud, which contains the following properties:: pc[key_added], the kernel density.

plot_cmap: Recommended colormap parameter values for plotting.

Return type:

spateo.tdr.morphometrics.pairwise_shape_similarity(model1_pcs: numpy.ndarray, model2_pcs: numpy.ndarray, n_subspace: int = 20, m: int = 10, s: int = 5) → float[source]¶

Calculate the shape similarity of pairwise 3D point cloud models based on the eigenvectors of the 3D point cloud model subspace. References: Hu Xiaotong, Wang Jiandong. Similarity analysis of three-dimensional point cloud based on eigenvector of subspace.

Parameters:

model1_pcs: The coordinates of the 3D point cloud model1.
model2_pcs: The coordinates of the 3D point cloud model2.
n_subspace: The number of subspaces initially divided is ``n_subspace``**3.
m: The number of eigenvalues contained in the eigenvector is m*s.
s: The number of eigenvalues contained in the eigenvector is m*s.

Returns:

Shape similarity score.

Return type:

similarity_score