spateo.tdr

Subpackages

Functions

deep_intepretation(→ anndata.AnnData)

Learn a continuous mapping from space to gene expression pattern with the deep neural net model.

gp_interpolation(→ anndata.AnnData)

Learn a continuous mapping from space to gene expression pattern with the Gaussian Process method.

kernel_interpolation(→ anndata.AnnData)

Learn a continuous mapping from space to gene expression pattern with Kernel method (sparseVFC).

vtk_interpolation(→ anndata.AnnData)

Learn a continuous mapping from space to gene expression pattern with the method contained in VTK.

ElPiGraph_method(→ Tuple[numpy.ndarray, numpy.ndarray])

Generate a principal elastic tree.

PrinCurve_method(→ Tuple[numpy.ndarray, numpy.ndarray])

This is the global module that contains principal curve and nonlinear principal component analysis algorithms that

SimplePPT_method(→ Tuple[numpy.ndarray, numpy.ndarray])

Generate a simple principal tree.

backbone_scc(→ Optional[anndata.AnnData])

Spatially constrained clustering (scc) along the backbone.

construct_backbone(→ Tuple[pyvista.PolyData, float, ...)

Organ's backbone construction based on 3D point cloud model.

map_gene_to_backbone(model, tree, key[, nodes_key, ...])

Find the closest principal tree node to any point in the model through KDTree.

map_points_to_backbone(model, backbone_model[, ...])

Find the closest principal tree node to any point in the model through KDTree.

update_backbone(→ Union[pyvista.PolyData, ...)

Update the bakcbone through interaction or input of selected nodes.

construct_cells(pc, cell_size[, geometry, xyz_scale, ...])

Reconstructing cells from point clouds.

construct_pc(→ Tuple[pyvista.PolyData, Optional[str]])

Construct a point cloud model based on 3D coordinate information.

construct_surface(→ Tuple[Union[pyvista.PolyData, ...)

Surface mesh reconstruction based on 3D point cloud model.

voxelize_mesh(→ Tuple[Union[pyvista.UnstructuredGrid, ...)

Construct a volumetric mesh based on surface mesh.

voxelize_pc(→ pyvista.UnstructuredGrid)

Voxelize the point cloud.

construct_align_lines(→ Tuple[pyvista.PolyData, ...)

Construct alignment lines between models after model alignment.

construct_arrow(→ Tuple[pyvista.PolyData, Optional[str]])

Create a 3D arrow model.

construct_arrows(→ Tuple[pyvista.PolyData, Optional[str]])

Create multiple 3D arrows model.

construct_axis_line(→ Tuple[pyvista.PolyData, ...)

Construct axis line.

construct_field(→ Tuple[pyvista.PolyData, Optional[str]])

Create a 3D vector field arrows model.

construct_field_streams(model[, vf_key, ...])

Integrate a vector field to generate streamlines.

construct_genesis(→ Tuple[pyvista.MultiBlock, ...)

Reconstruction of cell-level cell developmental change model based on the cell fate prediction results. Here we only

construct_genesis_X(→ Tuple[pyvista.MultiBlock, ...)

Reconstruction of cell-level cell developmental change model based on the cell fate prediction results. Here we only

construct_line(→ Tuple[pyvista.PolyData, Optional[str]])

Create a 3D line model.

construct_lines(→ Tuple[pyvista.PolyData, Optional[str]])

Create 3D lines model.

construct_trajectory(→ Tuple[Any, Optional[str]])

Reconstruction of cell developmental trajectory model based on cell fate prediction.

construct_trajectory_X(→ Tuple[Any, Optional[str]])

Reconstruction of cell developmental trajectory model.

add_model_labels(...)

Add rgba color to each point of model based on labels.

center_to_zero(model[, inplace])

Translate the center point of the model to the (0, 0, 0).

collect_models(→ pyvista.MultiBlock)

A composite class to hold many data sets which can be iterated over.

merge_models(→ PolyData or UnstructuredGrid)

Merge all models in the models list. The format of all models must be the same.

multiblock2model(model[, message])

Merge all models in MultiBlock into one model

read_model(filename)

Read any file type supported by vtk or meshio.

rotate_model(, rotate_center, tuple] = None, inplace, ...)

Rotate the model around the rotate_center.

save_model(model, filename[, binary, texture])

Save the pvvista/vtk model to vtk/vtm file.

scale_model(→ Union[pyvista.PolyData, ...)

Scale the model around the center of the model.

translate_model(, inplace, pyvista.UnstructuredGrid, None])

Translate the mesh.

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.

interactive_box_clip(→ pyvista.MultiBlock)

Pick the interested part of a model using a 3D box widget. Only one model can be generated.

interactive_rectangle_clip(→ pyvista.MultiBlock)

Pick the interested part of a model using a 2D rectangle widget.

interactive_pick(→ pyvista.MultiBlock)

Add a checkbox button widget to pick the desired groups through the interactive window and output the picked groups.

overlap_mesh_pick(→ pyvista.PolyData)

Pick the intersection between two mesh models.

overlap_pc_pick(→ [pyvista.PolyData, pyvista.PolyData])

Pick the point cloud inside the mesh model and point cloud outside the mesh model.

overlap_pick(main_mesh, other_mesh[, main_pc, other_pc])

Add a checkbox button widget to pick the desired groups through the interactive window and output the picked groups.

three_d_pick(→ pyvista.MultiBlock)

Pick the desired groups.

interactive_slice(→ pyvista.MultiBlock)

Create a slice of the input dataset along a specified axis or

three_d_slice(, center, ...)

Create many slices of the input dataset along a specified axis or

Package Contents

spateo.tdr.deep_intepretation(source_adata: anndata.AnnData, target_points: numpy.ndarray | None = None, keys: str | list = None, spatial_key: str = 'spatial', layer: str = 'X', max_iter: int = 1000, data_batch_size: int = 2000, autoencoder_batch_size: int = 50, data_lr: float = 0.0001, autoencoder_lr: float = 0.0001, **kwargs) anndata.AnnData[source]

Learn a continuous mapping from space to gene expression pattern with the deep neural net model.

Parameters:
source_adata

AnnData object that contains spatial (numpy.ndarray) in the obsm attribute.

target_points

The spatial coordinates of new data point. If target_coords is None, generate new points based on grid_num.

keys

Gene list or info list in the obs attribute whose interpolate expression across space needs to learned.

spatial_key

The key in .obsm that corresponds to the spatial coordinate of each bucket.

layer

If 'X', uses .X, otherwise uses the representation given by .layers[layer].

max_iter

The maximum iteration the network will be trained.

data_batch_size

The size of the data sample batches to be generated in each iteration.

autoencoder_batch_size

The size of the auto-encoder training batches to be generated in each iteration. Must be no greater than batch_size. .

data_lr

The learning rate for network training.

autoencoder_lr

The learning rate for network training the auto-encoder. Will have no effect if network_dim equal data_dim.

**kwargs

Additional parameters that will be passed to the training step of the deep neural net.

Returns:

an anndata object that has interpolated expression.

Return type:

interp_adata

spateo.tdr.gp_interpolation(source_adata: anndata.AnnData, target_points: numpy.ndarray | None = None, keys: str | list = None, spatial_key: str = 'spatial', layer: str = 'X', training_iter: int = 50, device: str = 'cpu', method: Literal['SVGP', 'ExactGP'] = 'SVGP', batch_size: int = 1024, shuffle: bool = True, inducing_num: int = 512) anndata.AnnData[source]

Learn a continuous mapping from space to gene expression pattern with the Gaussian Process method.

Parameters:
source_adata

AnnData object that contains spatial (numpy.ndarray) in the obsm attribute.

target_points

The spatial coordinates of new data point. If target_coords is None, generate new points based on grid_num.

keys

Gene list or info list in the obs attribute whose interpolate expression across space needs to learned.

spatial_key

The key in .obsm that corresponds to the spatial coordinate of each bucket.

layer

If 'X', uses .X, otherwise uses the representation given by .layers[layer].

training_iter

Max number of iterations for training.

device

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

Returns:

an anndata object that has interpolated expression.

Return type:

interp_adata

spateo.tdr.kernel_interpolation(source_adata: anndata.AnnData, target_points: numpy.ndarray | None = None, keys: str | list = None, spatial_key: str = 'spatial', layer: str = 'X', lambda_: float = 0.02, lstsq_method: str = 'scipy', **kwargs) anndata.AnnData[source]

Learn a continuous mapping from space to gene expression pattern with Kernel method (sparseVFC).

Parameters:
source_adata

AnnData object that contains spatial (numpy.ndarray) in the obsm attribute.

target_points

The spatial coordinates of new data point. If target_coords is None, generate new points based on grid_num.

keys

Gene list or info list in the obs attribute whose interpolate expression across space needs to learned.

spatial_key

The key in .obsm that corresponds to the spatial coordinate of each bucket.

layer

If 'X', uses .X, otherwise uses the representation given by .layers[layer].

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.

**kwargs

Additional parameters that will be passed to SparseVFC function.

Returns:

an anndata object that has interpolated expression.

Return type:

interp_adata

spateo.tdr.vtk_interpolation(source_adata: anndata.AnnData, target_points: numpy.ndarray | None = None, keys: str | list = None, spatial_key: str = 'spatial', layer: str = 'X', radius: float | None = None, n_points: int | None = None, kernel: Literal['shepard', 'gaussian', 'linear'] = 'shepard', null_strategy: Literal[0, 1, 2] = 1, null_value: int | float = 0) anndata.AnnData[source]

Learn a continuous mapping from space to gene expression pattern with the method contained in VTK.

Parameters:
source_adata

AnnData object that contains spatial (numpy.ndarray) in the obsm attribute.

target_points

The spatial coordinates of new data point. If target_coords is None, generate new points based on grid_num.

keys

Gene list or info list in the obs attribute whose interpolate expression across space needs to learned.

spatial_key

The key in .obsm that corresponds to the spatial coordinate of each bucket.

layer

If 'X', uses .X, otherwise uses the representation given by .layers[layer].

radius

Set the radius of the point cloud. If you are generating a Gaussian distribution, then this is the standard deviation for each of x, y, and z.

n_points

Specify the number of points for the source object to hold. If n_points (number of the closest points to use) is set then radius value is ignored.

kernel

The kernel of interpolations kernel. Available kernels are: * shepard: vtkShepardKernel is an interpolations kernel that uses the method of Shepard to perform

interpolations. The weights are computed as 1/r^p, where r is the distance to a neighbor point within the kernel radius R; and p (the power parameter) is a positive exponent (typically p=2).

  • gaussian: vtkGaussianKernel is an interpolations kernel that simply returns the weights for all

    points found in the sphere defined by radius R. The weights are computed as: exp(-(s*r/R)^2) where r is the distance from the point to be interpolated to a neighboring point within R. The sharpness s simply affects the rate of fall off of the Gaussian.

  • linear: vtkLinearKernel is an interpolations kernel that averages the contributions of all points in

    the basis.

null_strategy

Specify a strategy to use when encountering a “null” point during the interpolations process.

Null points occur when the local neighborhood(of nearby points to interpolate from) is empty.

  • Case 0: an output array is created that marks points as being valid (=1) or null (invalid =0), and

    the nullValue is set as well

  • Case 1: the output data value(s) are set to the provided nullValue

  • Case 2: simply use the closest point to perform the interpolations.

null_value

see above.

Returns:

an anndata object that has interpolated expression.

Return type:

interp_adata

spateo.tdr.ElPiGraph_method(X: numpy.ndarray, NumNodes: int = 50, topology: Literal['tree', 'circle', 'curve'] = 'curve', Lambda: float = 0.01, Mu: float = 0.1, alpha: float = 0.0, FinalEnergy: Literal['Base', 'Penalized'] = 'Penalized', **kwargs) Tuple[numpy.ndarray, numpy.ndarray][source]

Generate a principal elastic tree. Reference: Albergante et al. (2020), Robust and Scalable Learning of Complex Intrinsic Dataset Geometry via ElPiGraph.

Parameters:
X

DxN, data matrix list.

NumNodes

The number of nodes of the principal graph. Use a range of 10 to 100 for ElPiGraph approach.

topology

The appropriate topology used to fit a principal graph for each dataset.

Lambda

The attractive strength of edges between nodes (constrains edge lengths)

Mu

The repulsive strength of a node’s neighboring nodes (constrains angles to be close to harmonic)

alpha

Branching penalty (penalizes number of branches for the principal tree)

FinalEnergy

Indicating the final elastic emergy associated with the configuration. Currently it can be “Base” or “Penalized”

**kwargs

Other parameters used in elpigraph.computeElasticPrincipalTree. For details, please see: https://elpigraph-python.readthedocs.io/en/latest/basics.html

Returns:

The nodes in the principal tree. edges: The edges between nodes in the principal tree.

Return type:

nodes

spateo.tdr.PrinCurve_method(X: numpy.ndarray, NumNodes: int = 50, epochs: int = 500, lr: float = 0.01, scale_factor: int | float = 1, **kwargs) Tuple[numpy.ndarray, numpy.ndarray][source]

This is the global module that contains principal curve and nonlinear principal component analysis algorithms that work to optimize a line over an entire dataset. Reference: Chen et al. (2016), Constraint local principal curve: Concept, algorithms and applications.

Parameters:
X

DxN, data matrix list.

NumNodes

Number of nodes for the construction layers. Defaults to 50. The more complex the curve, the higher this number should be.

epochs

Number of epochs to train neural network, defaults to 500.

lr

Learning rate for backprop. Defaults to .01

scale_factor

**kwargs

Other parameters used in global algorithms. For details, please see: https://github.com/artusoma/prinPy/blob/master/prinpy/glob.py

Returns:

The nodes in the principal tree. edges: The edges between nodes in the principal tree.

Return type:

nodes

spateo.tdr.SimplePPT_method(X: numpy.ndarray, NumNodes: int = 50, sigma: float | int | None = 0.1, lam: float | int | None = 1, metric: str = 'euclidean', nsteps: int = 50, err_cut: float = 0.005, seed: int | None = 1, **kwargs) Tuple[numpy.ndarray, numpy.ndarray][source]

Generate a simple principal tree. Reference: Mao et al. (2015), SimplePPT: A simple principal tree algorithm, SIAM International Conference on Data Mining.

Parameters:
X

DxN, data matrix list.

NumNodes

The number of nodes of the principal graph. Use a range of 100 to 2000 for PPT approach.

sigma

Regularization parameter.

lam

Penalty for the tree length.

metric

The metric to use to compute distances in high dimensional space. For compatible metrics, check the documentation of sklearn.metrics.pairwise_distances.

nsteps

Number of steps for the optimisation process.

err_cut

Stop algorithm if proximity of principal points between iterations less than defined value.

seed

A numpy random seed.

**kwargs

Other parameters used in simpleppt.ppt. For details, please see: https://github.com/LouisFaure/simpleppt/blob/main/simpleppt/ppt.py

Returns:

The nodes in the principal tree. edges: The edges between nodes in the principal tree.

Return type:

nodes

spateo.tdr.backbone_scc(adata: anndata.AnnData, backbone: pyvista.PolyData, genes: list | None = None, adata_nodes_key: str = 'backbone_nodes', backbone_nodes_key: str = 'updated_nodes', key_added: str | None = 'backbone_scc', layer: str | None = None, e_neigh: int = 10, s_neigh: int = 6, cluster_method: Literal['leiden', 'louvain'] = 'leiden', resolution: float | None = None, inplace: bool = True) anndata.AnnData | None[source]

Spatially constrained clustering (scc) along the backbone.

Parameters:
adata

The anndata object.

backbone

The backbone model.

genes

The list of genes that will be used to subset the data for clustering. If genes = None, all genes will be used.

adata_nodes_key

The key that corresponds to the nodes in the adata.

backbone_nodes_key

The key that corresponds to the nodes in the backbone.

key_added

adata.obs key under which to add the cluster labels.

layer

The layer that will be used to retrieve data for dimension reduction and clustering. If layer = None, .X is used.

e_neigh

the number of nearest neighbor in gene expression space.

s_neigh

the number of nearest neighbor in physical space.

cluster_method

the method that will be used to cluster the cells.

resolution

the resolution parameter of the louvain clustering algorithm.

inplace

Whether to copy adata or modify it inplace.

Returns:

An AnnData object is updated/copied with the key_added in the .obs attribute, storing the clustering results.

spateo.tdr.construct_backbone(model: pyvista.PolyData | pyvista.UnstructuredGrid, spatial_key: str | None = None, nodes_key: str = 'nodes', rd_method: Literal['ElPiGraph', 'SimplePPT', 'PrinCurve'] = 'ElPiGraph', num_nodes: int = 50, color: str = 'gainsboro', **kwargs) Tuple[pyvista.PolyData, float, str | None][source]

Organ’s backbone construction based on 3D point cloud model.

Parameters:
model

A point cloud model.

spatial_key

If spatial_key is None, the spatial coordinates are in model.points, otherwise in model[spatial_key].

nodes_key

The key that corresponds to the coordinates of the nodes in the backbone.

rd_method

The method of constructing a backbone model. Available rd_method are:

  • 'ElPiGraph': Generate a principal elastic tree.

  • 'SimplePPT': Generate a simple principal tree.

  • 'PrinCurve': This is the global module that contains principal curve and nonlinear principal

    component analysis algorithms that work to optimize a line over an entire dataset.

num_nodes

Number of nodes for the backbone model.

color

Color to use for plotting backbone model.

**kwargs

Additional parameters that will be passed to ElPiGraph_method, SimplePPT_method or PrinCurve_method function.

Returns:

A three-dims backbone model. backbone_length: The length of the backbone model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

backbone_model

spateo.tdr.map_gene_to_backbone(model: pyvista.PolyData | pyvista.UnstructuredGrid, tree: pyvista.PolyData, key: str | list, nodes_key: str | None = 'nodes', inplace: bool = False)[source]

Find the closest principal tree node to any point in the model through KDTree.

Parameters:
model

A reconstructed model contains the gene expression label.

tree

A three-dims principal tree model contains the nodes label.

key

The key that corresponds to the gene expression.

nodes_key

The key that corresponds to the coordinates of the nodes in the tree.

inplace

Updates tree model in-place.

Returns:

tree.point_data[key], the gene expression array.

Return type:

A tree, which contains the following properties

spateo.tdr.map_points_to_backbone(model: pyvista.PolyData | pyvista.UnstructuredGrid, backbone_model: pyvista.PolyData, nodes_key: str = 'nodes', key_added: str | None = 'nodes', inplace: bool = False, **kwargs)[source]

Find the closest principal tree node to any point in the model through KDTree.

Parameters:
model

The reconstructed model.

backbone_model

The constructed backbone model.

nodes_key

The key that corresponds to the coordinates of the nodes in the backbone.

key_added

The key under which to add the nodes labels.

inplace

Updates model in-place.

**kwargs

Additional parameters that will be passed to scipy.spatial.KDTree. function.

Returns:

model.point_data[key_added], the nodes labels array.

Return type:

A model, which contains the following properties

spateo.tdr.update_backbone(backbone: pyvista.PolyData, nodes_key: str = 'nodes', key_added: str = 'updated_nodes', select_nodes: list | numpy.ndarray | None = None, interactive: bool | None = True, model_size: float | list = 8.0, colormap: str = 'Spectral') pyvista.PolyData | pyvista.UnstructuredGrid[source]

Update the bakcbone through interaction or input of selected nodes.

Parameters:
backbone

The backbone model.

nodes_key

The key that corresponds to the coordinates of the nodes in the backbone.

key_added

The key under which to add the labels of new nodes.

select_nodes

Nodes that need to be retained.

interactive

Whether to delete useless nodes interactively. When interactive is True, select_nodes is invalid.

model_size

Thickness of backbone. When interactive is False, model_size is invalid.

colormap

Colormap of backbone. When interactive is False, colormap is invalid.

Returns:

The updated backbone model.

Return type:

updated_backbone

spateo.tdr.construct_cells(pc: pyvista.PolyData, cell_size: numpy.ndarray, geometry: Literal['cube', 'sphere', 'ellipsoid'] = 'cube', xyz_scale: tuple = (1, 1, 1), n_scale: tuple = (1, 1), factor: float = 0.5)[source]

Reconstructing cells from point clouds.

Parameters:
pc

A point cloud object, including pc.point_data["obs_index"].

geometry

The geometry of generating cells. Available geometry are:

  • geometry = 'cube'

  • geometry = 'sphere'

  • geometry = 'ellipsoid'

cell_size

A numpy.ndarray object including the relative radius/length size of each cell.

xyz_scale

The scale factor for the x-axis, y-axis and z-axis.

n_scale

The squareness parameter in the x-y plane adn z axis. Only works if geometry = 'ellipsoid'.

factor

Scale factor applied to scaling array.

Returns:

A cells mesh including ds_glyph.point_data[“cell_size”], ds_glyph.point_data[“cell_centroid”] and the data contained in the pc.

Return type:

ds_glyph

spateo.tdr.construct_pc(adata: anndata.AnnData, layer: str = 'X', spatial_key: str = 'spatial', groupby: str | tuple = None, key_added: str = 'groups', mask: str | int | float | list = None, colormap: str | list | dict = 'rainbow', alphamap: float | list | dict = 1.0) Tuple[pyvista.PolyData, str | None][source]

Construct a point cloud model based on 3D coordinate information.

Parameters:
adata

AnnData object.

layer

If 'X', uses .X, otherwise uses the representation given by .layers[layer].

spatial_key

The key in .obsm that corresponds to the spatial coordinate of each bucket.

groupby

The key that stores clustering or annotation information in .obs, a gene name or a list of gene names in .var.

key_added

The key under which to add the labels.

mask

The part that you don’t want to be displayed.

colormap

Colors to use for plotting pc. The default colormap is 'rainbow'.

alphamap

The opacity of the colors to use for plotting pc. The default alphamap is 1.0.

Returns:

A point cloud, which contains the following properties:

pc.point_data[key_added], the groupby information. pc.point_data[f'{key_added}_rgba'], the rgba colors of the groupby information. pc.point_data['obs_index'], the obs_index of each coordinate in the original adata.

plot_cmap: Recommended colormap parameter values for plotting.

Return type:

pc

spateo.tdr.construct_surface(pc: pyvista.PolyData, key_added: str = 'groups', label: str = 'surface', color: str | None = 'gainsboro', alpha: float | int = 1.0, uniform_pc: bool = False, uniform_pc_alpha: float | int = 0, cs_method: Literal['pyvista', 'alpha_shape', 'ball_pivoting', 'poisson', 'marching_cube'] = 'marching_cube', cs_args: dict | None = None, nsub: int | None = 3, nclus: int = 20000, smooth: int | None = 3000, scale_distance: float | int | list | tuple = None, scale_factor: float | int | list | tuple = None) Tuple[pyvista.PolyData | pyvista.UnstructuredGrid | None, pyvista.PolyData, str | None][source]

Surface mesh reconstruction based on 3D point cloud model.

Parameters:
pc

A point cloud model.

key_added

The key under which to add the labels.

label

The label of reconstructed surface mesh model.

color

Color to use for plotting mesh. The default color is 'gainsboro'.

alpha

The opacity of the color to use for plotting mesh. The default alpha is 0.8.

uniform_pc

Generates a uniform point cloud with a larger number of points.

uniform_pc_alpha

Specify alpha (or distance) value to control output of this filter.

cs_method

The methods of generating a surface mesh. Available cs_method are:

  • 'pyvista': Generate a 3D tetrahedral mesh based on pyvista.

  • 'alpha_shape': Computes a triangle mesh on the alpha shape algorithm.

  • 'ball_pivoting': Computes a triangle mesh based on the Ball Pivoting algorithm.

  • 'poisson': Computes a triangle mesh based on thee Screened Poisson Reconstruction.

  • 'marching_cube': Computes a triangle mesh based on the marching cube algorithm.

cs_args

Parameters for various surface reconstruction methods. Available cs_args are: * 'pyvista': {‘alpha’: 0} * 'alpha_shape': {‘alpha’: 2.0} * 'ball_pivoting': {‘radii’: [1]} * 'poisson': {‘depth’: 8, ‘width’=0, ‘scale’=1.1, ‘linear_fit’: False, ‘density_threshold’: 0.01} * 'marching_cube': {‘levelset’: 0, ‘mc_scale_factor’: 1, ‘dist_sample_num’: 100}

nsub

Number of subdivisions. Each subdivision creates 4 new triangles, so the number of resulting triangles is nface*4**nsub where nface is the current number of faces.

nclus

Number of voronoi clustering.

smooth

Number of iterations for Laplacian smoothing.

scale_distance

The distance by which the model is scaled. If scale_distance is float, the model is scaled same distance along the xyz axis; when the scale factor is list, the model is scaled along the xyz axis at different distance. If scale_distance is None, there will be no scaling based on distance.

scale_factor

The scale by which the model is scaled. If scale factor is float, the model is scaled along the xyz axis at the same scale; when the scale factor is list, the model is scaled along the xyz axis at different scales. If scale_factor is None, there will be no scaling based on scale factor.

Returns:

A reconstructed surface mesh, which contains the following properties:

uniform_surf.cell_data[key_added], the label array; uniform_surf.cell_data[f'{key_added}_rgba'], the rgba colors of the label array.

inside_pc: A point cloud, which contains the following properties:

inside_pc.point_data['obs_index'], the obs_index of each coordinate in the original adata. inside_pc.point_data[key_added], the groupby information. inside_pc.point_data[f'{key_added}_rgba'], the rgba colors of the groupby information.

plot_cmap: Recommended colormap parameter values for plotting.

Return type:

uniform_surf

spateo.tdr.voxelize_mesh(mesh: pyvista.PolyData | pyvista.UnstructuredGrid, voxel_pc: pyvista.PolyData | pyvista.UnstructuredGrid = None, key_added: str = 'groups', label: str = 'voxel', color: str | None = 'gainsboro', alpha: float | int = 1.0, smooth: int | None = 200) Tuple[pyvista.UnstructuredGrid | Any, str | None][source]

Construct a volumetric mesh based on surface mesh.

Parameters:
mesh

A surface mesh model.

voxel_pc

A voxel model which contains the voxel_pc.cell_data['obs_index'] and voxel_pc.cell_data[key_added].

key_added

The key under which to add the labels.

label

The label of reconstructed voxel model.

color

Color to use for plotting mesh. The default color is 'gainsboro'.

alpha

The opacity of the color to use for plotting model. The default alpha is 0.8.

smooth

The smoothness of the voxel model.

Returns:

A reconstructed voxel model, which contains the following properties:

voxel_model.cell_data[key_added], the label array; voxel_model.cell_data[f’{key_added}_rgba’], the rgba colors of the label array. voxel_model.cell_data[‘obs_index’], the cell labels if not (voxel_pc is None).

plot_cmap: Recommended colormap parameter values for plotting.

Return type:

voxel_model

spateo.tdr.voxelize_pc(pc: pyvista.PolyData, voxel_size: numpy.ndarray | None = None) pyvista.UnstructuredGrid[source]

Voxelize the point cloud.

Parameters:
pc

A point cloud model.

voxel_size

The size of the voxelized points. The shape of voxel_size is (pc.n_points, 3).

Returns:

A voxel model.

Return type:

voxel

spateo.tdr.construct_align_lines(model1_points: numpy.ndarray, model2_points: numpy.ndarray, key_added: str = 'check_alignment', label: str | list | numpy.ndarray = 'align_mapping', color: str | list | dict | numpy.ndarray = 'gainsboro', alpha: float | int | list | dict | numpy.ndarray = 1.0) Tuple[pyvista.PolyData, str | None][source]

Construct alignment lines between models after model alignment.

Parameters:
model1_points

Start location in model1 of the line.

model2_points

End location in model2 of the line.

key_added

The key under which to add the labels.

label

The label of alignment lines model.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

Alignment lines model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

model

spateo.tdr.construct_arrow(start_point: list | tuple | numpy.ndarray, direction: list | tuple | numpy.ndarray, arrow_scale: int | float | None = None, key_added: str | None = 'arrow', label: str = 'arrow', color: str = 'gainsboro', alpha: float = 1.0, **kwargs) Tuple[pyvista.PolyData, str | None][source]

Create a 3D arrow model.

Parameters:
start_point

Start location in [x, y, z] of the arrow.

direction

Direction the arrow points to in [x, y, z].

arrow_scale

Scale factor of the entire object. ‘auto’ scales to length of direction array.

key_added

The key under which to add the labels.

label

The label of arrow model.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

**kwargs

Additional parameters that will be passed to _construct_arrow function.

Returns:

Arrow model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

model

spateo.tdr.construct_arrows(start_points: numpy.ndarray, direction: numpy.ndarray = None, arrows_scale: numpy.ndarray | None = None, n_sampling: int | None = None, sampling_method: str = 'trn', factor: float = 1.0, key_added: str | None = 'arrow', label: str | list | numpy.ndarray = 'arrows', color: str | list | dict | numpy.ndarray = 'gainsboro', alpha: float | int | list | dict | numpy.ndarray = 1.0, **kwargs) Tuple[pyvista.PolyData, str | None][source]

Create multiple 3D arrows model.

Parameters:
start_points

List of Start location in [x, y, z] of the arrows.

direction

Direction the arrows points to in [x, y, z].

arrows_scale

Scale factor of the entire object.

n_sampling

n_sampling is the number of coordinates to keep after sampling. If there are too many coordinates in start_points, the generated arrows model will be too complex and unsightly, so sampling is used to reduce the number of coordinates.

sampling_method

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

factor

Scale factor applied to scaling array.

key_added

The key under which to add the labels.

label

The label of arrows models.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

**kwargs

Additional parameters that will be passed to _construct_arrow function.

Returns:

Arrows model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

model

spateo.tdr.construct_axis_line(axis_points: numpy.ndarray, key_added: str = 'axis', label: str = 'axis_line', color: str = 'gainsboro', alpha: float | int | list | dict | numpy.ndarray = 1.0) Tuple[pyvista.PolyData, str | None][source]

Construct axis line.

Parameters:
axis_points

List of points defining an axis.

key_added

The key under which to add the labels.

label

The label of axis line model.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

Axis line model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

axis_line

spateo.tdr.construct_field(model: pyvista.PolyData, vf_key: str = 'VecFld_morpho', arrows_scale_key: str | None = None, n_sampling: int | None = None, sampling_method: str = 'trn', factor: float = 1.0, key_added: str = 'v_arrows', label: str | list | numpy.ndarray = 'vector field', color: str | list | dict | numpy.ndarray = 'gainsboro', alpha: float = 1.0, **kwargs) Tuple[pyvista.PolyData, str | None][source]

Create a 3D vector field arrows model.

Parameters:
model

A model that provides coordinate information and vector information for constructing vector field models.

vf_key

The key under which are the vector information.

arrows_scale_key

The key under which are scale factor of the entire object.

n_sampling

n_sampling is the number of coordinates to keep after sampling. If there are too many coordinates in start_points, the generated arrows model will be too complex and unsightly, so sampling is used to reduce the number of coordinates.

sampling_method

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

factor

Scale factor applied to scaling array.

key_added

The key under which to add the labels.

label

The label of arrows models.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

**kwargs

Additional parameters that will be passed to construct_arrows function.

Returns:

A 3D vector field arrows model. plot_cmap: Recommended colormap parameter values for plotting.

spateo.tdr.construct_field_streams(model: pyvista.PolyData, vf_key: str = 'VecFld_morpho', source_center: Tuple[float] | None = None, source_radius: float | None = None, tip_factor: int | float = 10, tip_radius: float = 0.2, key_added: str = 'v_streams', label: str | list | numpy.ndarray = 'vector field', stream_color: str = 'gainsboro', tip_color: str = 'orangered', alpha: float = 1.0, **kwargs)[source]

Integrate a vector field to generate streamlines.

Parameters:
model

A model that provides coordinate information and vector information for constructing vector field models.

vf_key

The key under which are the active vector field information.

source_center

Length 3 tuple of floats defining the center of the source particles. Defaults to the center of the dataset.

source_radius

Float radius of the source particle cloud. Defaults to one-tenth of the diagonal of the dataset’s spatial extent.

tip_factor

Scale factor applied to scaling the tips.

tip_radius

Radius of the tips.

key_added

The key under which to add the labels.

label

The label of arrows models.

stream_color

Color to use for plotting streamlines.

tip_color

Color to use for plotting tips.

alpha

The opacity of the color to use for plotting model.

**kwargs

Additional parameters that will be passed to streamlines function.

Returns:

3D vector field streamlines model. src: The source particles as pyvista.PolyData as well as the streamlines. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

streams_model

spateo.tdr.construct_genesis(adata: anndata.AnnData, fate_key: str = 'fate_morpho', n_steps: int = 100, logspace: bool = False, t_end: int | float | None = None, key_added: str = 'genesis', label: str | list | numpy.ndarray | None = None, color: str | list | dict = 'skyblue', alpha: float | list | dict = 1.0) Tuple[pyvista.MultiBlock, str | None][source]

Reconstruction of cell-level cell developmental change model based on the cell fate prediction results. Here we only need to enter the three-dimensional coordinates of the cells at different developmental stages.

Parameters:
adata

AnnData object that contains the fate prediction in the .uns attribute.

fate_key

The key under which are the active fate information.

n_steps

The number of times steps fate prediction will take.

logspace

Whether or to sample time points linearly on log space. If not, the sorted unique set of all times points from all cell states’ fate prediction will be used and then evenly sampled up to n_steps time points.

t_end

The length of the time period from which to predict cell state forward or backward over time.

key_added

The key under which to add the labels.

label

The label of cell developmental change model. If label == None, the label will be automatically generated.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

A MultiBlock contains cell models for all stages. plot_cmap: Recommended colormap parameter values for plotting.

spateo.tdr.construct_genesis_X(stages_X: List[numpy.ndarray], n_spacing: int | None = None, key_added: str = 'genesis', label: str | list | numpy.ndarray | None = None, color: str | list | dict = 'skyblue', alpha: float | list | dict = 1.0) Tuple[pyvista.MultiBlock, str | None][source]

Reconstruction of cell-level cell developmental change model based on the cell fate prediction results. Here we only need to enter the three-dimensional coordinates of the cells at different developmental stages.

Parameters:
stages_X

The three-dimensional coordinates of the cells at different developmental stages.

n_spacing

Subdivided into n_spacing time points between two periods.

key_added

The key under which to add the labels.

label

The label of cell developmental change model. If label == None, the label will be automatically generated.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

A MultiBlock contains cell models for all stages. plot_cmap: Recommended colormap parameter values for plotting.

spateo.tdr.construct_line(start_point: list | tuple | numpy.ndarray, end_point: list | tuple | numpy.ndarray, key_added: str | None = 'line', label: str = 'line', color: str = 'gainsboro', alpha: float = 1.0) Tuple[pyvista.PolyData, str | None][source]

Create a 3D line model.

Parameters:
start_point

Start location in [x, y, z] of the line.

end_point

End location in [x, y, z] of the line.

key_added

The key under which to add the labels.

label

The label of line model.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

Line model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

model

spateo.tdr.construct_lines(points: numpy.ndarray, edges: numpy.ndarray, key_added: str | None = 'line', label: str | list | numpy.ndarray = 'lines', color: str | list | dict = 'gainsboro', alpha: float | int | list | dict = 1.0) Tuple[pyvista.PolyData, str | None][source]

Create 3D lines model.

Parameters:
points

List of points.

edges

The edges between points.

key_added

The key under which to add the labels.

label

The label of lines model.

color

Color to use for plotting model.

alpha

The opacity of the color to use for plotting model.

Returns:

Lines model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

model

spateo.tdr.construct_trajectory(adata: anndata.AnnData, fate_key: str = 'fate_develop', n_sampling: int | numpy.ndarray | None = None, sampling_method: str = 'trn', key_added: str = 'trajectory', label: str | list | numpy.ndarray | None = None, tip_factor: int | float = 5, tip_radius: float = 0.2, trajectory_color: str | list | dict = 'gainsboro', tip_color: str | list | dict = 'orangered', alpha: float = 1.0) Tuple[Any, str | None][source]

Reconstruction of cell developmental trajectory model based on cell fate prediction.

Parameters:
adata

AnnData object that contains the fate prediction in the .uns attribute.

fate_key

The key under which are the active fate information.

n_sampling

n_sampling is the number of coordinates to keep after sampling. If there are too many coordinates in start_points, the generated arrows model will be too complex and unsightly, so sampling is used to reduce the number of coordinates.

sampling_method

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

key_added

The key under which to add the labels.

label

The label of trajectory model.

tip_factor

Scale factor applied to scaling the tips.

tip_radius

Radius of the tips.

trajectory_color

Color to use for plotting trajectory model.

tip_color

Color to use for plotting tips.

alpha

The opacity of the color to use for plotting model.

Returns:

3D cell developmental trajectory model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

trajectory_model

spateo.tdr.construct_trajectory_X(cells_states: numpy.ndarray | List[numpy.ndarray], init_states: numpy.ndarray | None = None, n_sampling: int | numpy.ndarray | None = None, sampling_method: str = 'trn', key_added: str = 'trajectory', label: str | list | numpy.ndarray | None = None, tip_factor: int | float = 5, tip_radius: float = 0.2, trajectory_color: str | list | dict = 'gainsboro', tip_color: str | list | dict = 'orangered', alpha: float | list | dict = 1.0) Tuple[Any, str | None][source]

Reconstruction of cell developmental trajectory model.

Parameters:
cells_states

Three-dimensional coordinates of all cells at all times points.

init_states

Three-dimensional coordinates of all cells at the starting time point.

n_sampling

n_sampling is the number of coordinates to keep after sampling. If there are too many coordinates in start_points, the generated arrows model will be too complex and unsightly, so sampling is used to reduce the number of coordinates.

sampling_method

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

key_added

The key under which to add the labels.

label

The label of trajectory model.

tip_factor

Scale factor applied to scaling the tips.

tip_radius

Radius of the tips.

trajectory_color

Color to use for plotting trajectory model.

tip_color

Color to use for plotting tips.

alpha

The opacity of the color to use for plotting model.

Returns:

3D cell developmental trajectory model. plot_cmap: Recommended colormap parameter values for plotting.

Return type:

trajectory_model

spateo.tdr.add_model_labels(model: pyvista.PolyData | pyvista.UnstructuredGrid, labels: numpy.ndarray, key_added: str = 'groups', where: Literal['point_data', 'cell_data'] = 'cell_data', colormap: str | list | dict | numpy.ndarray = 'rainbow', alphamap: float | list | dict | numpy.ndarray = 1.0, mask_color: str | None = 'gainsboro', mask_alpha: float | None = 0.0, inplace: bool = False) Tuple[Optional[PolyData or UnstructuredGrid], Optional[Union[str]]][source]

Add rgba color to each point of model based on labels.

Parameters:
model

A reconstructed model.

labels

An array of labels of interest.

key_added

The key under which to add the labels.

where

The location where the label information is recorded in the model.

colormap

Colors to use for plotting data.

alphamap

The opacity of the color to use for plotting data.

mask_color

Color to use for plotting mask information.

mask_alpha

The opacity of the color to use for plotting mask information.

inplace

Updates model in-place.

Returns:

model.cell_data[key_added] or model.point_data[key_added], the labels array;

model.cell_data[f'{key_added}_rgba'] or model.point_data[f'{key_added}_rgba'], the rgba colors of the labels.

plot_cmap: Recommended colormap parameter values for plotting.

Return type:

A model, which contains the following properties

spateo.tdr.center_to_zero(model: pyvista.PolyData | pyvista.UnstructuredGrid, inplace: bool = False)[source]

Translate the center point of the model to the (0, 0, 0).

Parameters:
model

A 3D reconstructed model.

inplace

Updates model in-place.

Returns:

Model with center point at (0, 0, 0).

Return type:

model_z

spateo.tdr.collect_models(models: List[PolyData or UnstructuredGrid or DataSet], models_name: List[str] | None = None) pyvista.MultiBlock[source]

A composite class to hold many data sets which can be iterated over. You can think of MultiBlock like lists or dictionaries as we can iterate over this data structure by index and we can also access blocks by their string name. If the input is a dictionary, it can be iterated in the following ways:

>>> blocks = collect_models(models, models_name)
>>> for name in blocks.keys():
...     print(blocks[name])
If the input is a list, it can be iterated in the following ways:
>>> blocks = collect_models(models)
>>> for block in blocks:
...    print(block)
spateo.tdr.merge_models(models: List[PolyData or UnstructuredGrid or DataSet]) PolyData or UnstructuredGrid[source]

Merge all models in the models list. The format of all models must be the same.

spateo.tdr.multiblock2model(model, message=None)[source]

Merge all models in MultiBlock into one model

spateo.tdr.read_model(filename: str)[source]

Read any file type supported by vtk or meshio. :param filename: The string path to the file to read.

Returns:

Wrapped PyVista dataset.

spateo.tdr.rotate_model(model: pyvista.PolyData | pyvista.UnstructuredGrid, angle: list | tuple = (0, 0, 0), rotate_center: list | tuple = None, inplace: bool = False) pyvista.PolyData | pyvista.UnstructuredGrid | None[source]

Rotate the model around the rotate_center.

Parameters:
model

A 3D reconstructed model.

angle

Angles in degrees to rotate about the x-axis, y-axis, z-axis. Length 3 list or tuple.

rotate_center

Rotation center point. The default is the center of the model. Length 3 list or tuple.

inplace

Updates model in-place.

Returns:

The rotated model.

Return type:

model_r

spateo.tdr.save_model(model: pyvista.DataSet | pyvista.MultiBlock, filename: str, binary: bool = True, texture: str | numpy.ndarray = None)[source]

Save the pvvista/vtk model to vtk/vtm file. :param model: A reconstructed model. :param filename: Filename of output file. Writer type is inferred from the extension of the filename.

If model is a pyvista.MultiBlock object, please enter a filename ending with .vtm; else please enter a filename ending with .vtk.

Parameters:
binary

If True, write as binary. Otherwise, write as ASCII. Binary files write much faster than ASCII and have a smaller file size.

texture

Write a single texture array to file when using a PLY file.

Texture array must be a 3 or 4 component array with the datatype np.uint8. Array may be a cell array or a point array, and may also be a string if the array already exists in the PolyData.

If a string is provided, the texture array will be saved to disk as that name. If an array is provided, the texture array will be saved as ‘RGBA’

spateo.tdr.scale_model(model: pyvista.PolyData | pyvista.UnstructuredGrid, distance: float | int | list | tuple = None, scale_factor: float | int | list | tuple = 1, scale_center: list | tuple = None, inplace: bool = False) pyvista.PolyData | pyvista.UnstructuredGrid | None[source]

Scale the model around the center of the model.

Parameters:
model

A 3D reconstructed model.

distance

The distance by which the model is scaled. If distance is float, the model is scaled same distance along the xyz axis; when the scale factor is list, the model is scaled along the xyz axis at different distance. If distance is None, there will be no scaling based on distance.

scale_factor

The scale by which the model is scaled. If scale factor is float, the model is scaled along the xyz axis at the same scale; when the scale factor is list, the model is scaled along the xyz axis at different scales. If scale_factor is None, there will be no scaling based on scale factor.

scale_center

Scaling center. If scale factor is None, the scale_center will default to the center of the model.

inplace

Updates model in-place.

Returns:

The scaled model.

Return type:

model_s

spateo.tdr.translate_model(model: pyvista.PolyData | pyvista.UnstructuredGrid, distance: list | tuple = (0, 0, 0), inplace: bool = False) pyvista.PolyData | pyvista.UnstructuredGrid | None[source]

Translate the mesh.

Parameters:
model

A 3D reconstructed model.

distance

Distance to translate about the x-axis, y-axis, z-axis. Length 3 list or tuple.

inplace

Updates model in-place.

Returns:

The translated model.

Return type:

model_t

spateo.tdr.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.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, 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].

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.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.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, 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.

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.morphofield_acceleration(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'acceleration', method: str = 'analytical', 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.

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.morphofield_curl(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'curl', method: str = 'analytical', 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.

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.morphofield_curvature(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'curvature', formula: int = 2, method: str = 'analytical', 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.

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.morphofield_divergence(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'divergence', method: str = 'analytical', vectorize_size: int | None = 1000, 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'.

'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.

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.

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.morphofield_jacobian(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'jacobian', method: str = 'analytical', 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.

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.morphofield_torsion(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'torsion', method: str = 'analytical', 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'.

'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.

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.morphofield_velocity(adata: anndata.AnnData, vf_key: str = 'VecFld_morpho', key_added: str = 'velocity', 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.

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.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

spateo.tdr.pc_KDE(pc: pyvista.PolyData, key_added: str = 'kde', kernel: str = 'gaussian', bandwidth: float = 1.0, colormap: str | list | dict = 'hot_r', alphamap: float | list | dict = 1.0, inplace: bool = False) Tuple[pyvista.DataSet | pyvista.PolyData | None, str | None][source]

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:

pc

spateo.tdr.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

spateo.tdr.interactive_box_clip(model: pyvista.PolyData | pyvista.UnstructuredGrid | pyvista.MultiBlock, key: str = 'groups', invert: bool = False) pyvista.MultiBlock[source]

Pick the interested part of a model using a 3D box widget. Only one model can be generated.

Parameters:
model

Reconstructed 3D model.

key

The key under which are the labels.

invert

Flag on whether to flip/invert the pick.

Returns:

A MultiBlock that contains all models you picked.

Return type:

picked_model

spateo.tdr.interactive_rectangle_clip(model: pyvista.PolyData | pyvista.UnstructuredGrid | pyvista.MultiBlock, key: str = 'groups', model_style: Literal['points', 'surface', 'wireframe'] | list = 'points', model_size: float | list = 8.0, colormap: str = 'Spectral', invert: bool = False, bg_model=None) pyvista.MultiBlock[source]

Pick the interested part of a model using a 2D rectangle widget. Multiple models can be generated at the same time.

Parameters:
model

Reconstructed 3D model.

key

The key under which are the labels.

invert

Flag on whether to flip/invert the pick.

bg_model

A visualization-only background model to help clip our target model.

Returns:

A MultiBlock that contains all models you picked.

Return type:

picked_model

spateo.tdr.interactive_pick(model: pyvista.PolyData | pyvista.UnstructuredGrid | pyvista.MultiBlock, key: str = 'groups', checkbox_size: int = 27, label_size: int = 12) pyvista.MultiBlock[source]

Add a checkbox button widget to pick the desired groups through the interactive window and output the picked groups.

Parameters:
model

Reconstructed 3D model.

key

The key under which are the groups.

checkbox_size

The size of the button in number of pixels.

label_size

The font size of the checkbox labels.

Returns:

A MultiBlock that contains all models you picked.

spateo.tdr.overlap_mesh_pick(mesh1: pyvista.PolyData, mesh2: pyvista.PolyData) pyvista.PolyData[source]

Pick the intersection between two mesh models.

Parameters:
mesh1

Reconstructed 3D mesh model.

mesh2

Reconstructed 3D mesh model.

Returns:

The intersection mesh model.

Return type:

select_mesh

spateo.tdr.overlap_pc_pick(pc: pyvista.PolyData, mesh: pyvista.PolyData) [pyvista.PolyData, pyvista.PolyData][source]

Pick the point cloud inside the mesh model and point cloud outside the mesh model.

Parameters:
pc

Reconstructed 3D point cloud model corresponding to mesh.

mesh

Reconstructed 3D mesh model.

Returns:

Point cloud inside the mesh model. outside_pc: Point cloud outside the mesh model.

Return type:

inside_pc

spateo.tdr.overlap_pick(main_mesh: pyvista.PolyData, other_mesh: pyvista.PolyData, main_pc: pyvista.PolyData | None = None, other_pc: pyvista.PolyData | None = None)[source]

Add a checkbox button widget to pick the desired groups through the interactive window and output the picked groups.

Parameters:
main_mesh

Reconstructed 3D mesh model.

other_mesh

Reconstructed 3D mesh model.

main_pc

Reconstructed 3D point cloud model corresponding to main_mesh.

other_pc

Reconstructed 3D point cloud model corresponding to other_mesh.

Returns:

A MultiBlock that contains all models you picked.

spateo.tdr.three_d_pick(model: pyvista.PolyData | pyvista.UnstructuredGrid | pyvista.MultiBlock, key: str = 'groups', picked_groups: str | list = None) pyvista.MultiBlock[source]

Pick the desired groups.

spateo.tdr.interactive_slice(model: pyvista.PolyData | pyvista.UnstructuredGrid | pyvista.MultiBlock, key: str = 'groups', method: Literal['axis', 'orthogonal'] = 'axis', axis: Literal['x', 'y', 'z'] = 'x') pyvista.MultiBlock[source]

Create a slice of the input dataset along a specified axis or create three orthogonal slices through the dataset on the three cartesian planes.

Parameters:
model

Reconstructed 3D model.

key

The key under which are the labels.

method

The methods of slicing a model. Available method are: * ‘axis’: Create a slice of the input dataset along a specified axis. * ‘orthogonal’: Create three orthogonal slices through the dataset on the three cartesian planes.

axis

The axis to generate the slices along. Only works when method is ‘axis’.

Returns:

A MultiBlock that contains all models you sliced.

Return type:

sliced_model

spateo.tdr.three_d_slice(model: pyvista.PolyData | pyvista.UnstructuredGrid, method: Literal['axis', 'orthogonal', 'line'] = 'axis', n_slices: int = 10, axis: Literal['x', 'y', 'z'] = 'x', vec: tuple | list = (1, 0, 0), center: tuple | list = None) pyvista.PolyData | Tuple[pyvista.MultiBlock, pyvista.MultiBlock, pyvista.PolyData][source]

Create many slices of the input dataset along a specified axis or create three orthogonal slices through the dataset on the three cartesian planes or slice a model along a vector direction perpendicularly.

Parameters:
model

Reconstructed 3D model.

method

The methods of slicing a model. Available method are: * ‘axis’: Create many slices of the input dataset along a specified axis. * ‘orthogonal’: Create three orthogonal slices through the dataset on the three cartesian planes.

This method is usually used interactively without entering a position which slices are taken.

  • ’line’: Slice a model along a vector direction perpendicularly.

n_slices

The number of slices to create along a specified axis. Only works when method is ‘axis’ or ‘line’.

axis

The axis to generate the slices along. Only works when method is ‘axis’.

vec

The vector direction. Only works when method is ‘line’.

center

A 3-length sequence specifying the position which slices are taken. Defaults to the center of the model.

Returns:

If method is ‘axis’ or ‘orthogonal’, return a MultiBlock that contains all models you sliced; else return a tuple that contains line model, all models you sliced and intersections of slices model and line model.