spateo.tdr.models.models_backbone#

Submodules#

Package Contents#

Functions#

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.

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

Update the bakcbone through interaction or input of selected nodes.

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.

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