schist.tools ============ .. py:module:: schist.tools Functions --------- .. autoapisummary:: schist.tools.draw_graph schist.tools.calculate_affinity schist.tools.cluster_consistency schist.tools.cell_stability schist.tools.cell_similarity schist.tools.label_transfer schist.tools.cr_lineages Package Contents ---------------- .. py:function:: draw_graph(adata: anndata.AnnData, layout: _Layout = 'sfdp', use_tree: bool = False, random_seed: Optional[int] = None, adjacency: Optional[scipy.sparse.spmatrix] = None, key_added_ext: Optional[str] = None, key: Optional[str] = 'schist', copy: bool = False, **kwds) Extends scanpy.tools.draw_graph function using some layouts available in graph-tool library. Three layouts are available here: - SFDP spring-block layout. - ARF spring-block layout. - Fruchterman-Reingold spring-block layout. Fruchterman-Reingold is already available in scanpy, but here can be used to render the nested model tree. In order to use these plotting function, the NestedBlockState needs to be saved when building the model, so `save_state=True` needs to be set. Parameters ---------- adata Annotated data matrix. A NestedBlockState object needs to be saved layout A layout among 'sfdp', 'fr' or 'arf'. Other graph-tool layouts haven't been implemented. use_tree When this is set, the tree of the nested model is used to generate layout, otherwise the layout only accounts for the neighborhood graph. random_seed Random number to be used as seed for graph-tool adjacency Sparse adjacency matrix of the graph, defaults to `adata.uns['neighbors']['connectivities']`. key_added_ext By default, append `layout`. key The slot in `AnnData.uns` containing the state. Default is 'nsbm' copy Return a copy instead of writing to adata. **kwds Parameters of chosen igraph layout. See e.g. `fruchterman-reingold`_ [Fruchterman91]_. One of the most important ones is `maxiter`. .. _fruchterman-reingold: http://igraph.org/python/doc/igraph.Graph-class.html#layout_fruchterman_reingold Returns ------- Depending on `copy`, returns or updates `adata` with the following field. **X_draw_graph_layout** : `adata.obsm` Coordinates of graph layout. E.g. for layout='fa' (the default), the field is called 'X_draw_graph_fa' .. py:function:: calculate_affinity(adata: anndata.AnnData, level: int = 1, model_key: Optional[str] = 'nsbm', group_by: Optional[str] = None, neighbors_key: Optional[str] = 'neighbors', adjacency: Optional[scipy.sparse.spmatrix] = None, directed: bool = False, use_weights: bool = False, obsp: Optional[str] = None, back_prob: bool = False, copy: bool = False) -> Optional[anndata.AnnData] Calculate cell affinity given a partition scheme. It can be used for partitions calculated using schist or for any partition scheme, given for example by cell annotations. Parameters ---------- adata: The AnnData object. Should have been already processed with schist level: The level to calculate affinity. This parameter is effective only for Nested partitions model_key: The partition model. group_by: The key for group names used for calculations. Setting this will override level and model_key. This is effective only for NestedBlockState partitions neighbors_key Use neighbors connectivities as adjacency. If not specified, leiden looks .obsp['connectivities'] for connectivities (default storage place for pp.neighbors). If specified, leiden looks .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities. adjacency Sparse adjacency matrix of the graph, defaults to neighbors connectivities. directed Whether to treat the graph as directed or undirected. use_weights If `True`, edge weights from the graph are used in the computation (placing more emphasis on stronger edges). copy: Return a new object or do everything in place Returns ------- Depending on `copy`, returns or updates `adata` with affinity values in adata.obsm[f'CA_{model_key}_level_{level}'] .. py:function:: cluster_consistency(adata: anndata.AnnData, groups: str = None, key_added: Optional[str] = 'cluster_consistency', use_marginals: Optional[bool] = False, copy: bool = False) -> Optional[anndata.AnnData] Calculate cluster consistency at a given level Parameters ---------- adata Annotated data matrix. groups The key for clusters in adata.obs key_added The name of obs values that will be added to the adata use_marginals By default it uses cell affinities for the analysis, but if group marginals are available from the inference, those can be used here. copy Return a copy instead of writing to adata. Returns ------- Depending on `copy`, returns or updates `adata` with consistency values in adata.uns['cluster_consistency'] and adata.obs['cluster_consistency'] .. py:function:: cell_stability(adata: anndata.AnnData, model_key: Optional[str] = 'nsbm', key_added: Optional[str] = 'cell_stability', use_marginals: Optional[bool] = False, neighbors_key: Optional[str] = 'neighbors', adjacency: Optional[scipy.sparse.spmatrix] = None, directed: bool = False, use_weights: bool = False, obsp: Optional[str] = None, state: Optional = None, back_prob: bool = False, copy: bool = False) -> Optional[anndata.AnnData] Calculate cell stability given cell affinity. Parameters ---------- adata Annotated data matrix. key The prefix of CA matrices in adata.obsm to evaluate. copy Return a copy instead of writing to adata. use_marginals Whether to use marginals in place of affinities Returns ------- Depending on `copy`, returns or updates `adata` with stability values in adata.obs['cell_stability'] .. py:function:: cell_similarity(adata: anndata.AnnData, key_added: Optional[str] = 'cell_similarity', sim_type: Optional[str] = 'hub-promoted', use_weights: Optional[bool] = True, copy: bool = False, **neighbors_kwds) -> Optional[anndata.AnnData] Calculate cell similarity score based on the kNN graph. Higher scores are associated to cells mostly close to similar cells. Parameters ---------- adata Annotated data matrix. key_added The name of the entry in adata.obs with calculated values. copy Return a copy instead of writing to adata. sim_type: Similarity function. Can be one in 'dice', 'salton', 'hub-promoted','hub-suppressed', 'jaccard', 'inv-log-weight', 'resource-allocation','leight-holme-newman'. For more information check here https://graph-tool.skewed.de/static/doc/topology.html?highlight=distance#graph_tool.topology.vertex_similarity state A separate block state object Returns ------- Depending on `copy`, returns or updates `adata` with stability values in adata.obs['cell_stability'] .. py:function:: label_transfer(adata: anndata.AnnData, adata_ref: Optional[anndata.AnnData] = None, obs: Optional[str] = None, label_unk: Optional[str] = 'unknown', use_best: Optional[bool] = False, neighbors_key: Optional[str] = 'neighbors', adjacency: Optional[scipy.sparse.spmatrix] = None, directed: bool = False, use_weights: bool = False, pca_args: Optional[dict] = {}, use_rep: Optional[str] = None, harmony_args: Optional[dict] = {}, copy: bool = False) -> Optional[anndata.AnnData] Transfer annotation from one dataset to another using cell affinities. If two datasets are given, it uses harmony to perform integration and then the kNN graph. If only no reference is given, it is assumed that the only adata already contains the proper kNN graph and that labels to be reassigned have a specified value. Parameters ---------- adata: The AnnData object. adata_ref The optional reference dataset. If None, then all the needed information should be included in `adata` (i.e. the kNN graph and the labels) obs The label that needs to be transfered. Should be in `adata_ref.obs` or in `adata.obs` if no `adata_ref` is given label_unk The label for unassigned cells. If no `adata_ref` is given, this label identifies cells to be assigned in `adata`. If `adata_ref` is given, this label will be given to all cells that cannot be assigned. use_best When assigning labels, some cells may have not enough evidence and, therefore, left `unknown`. If this parameter is set to `True`, all cells will be assigned to the best possible, even if it may not be optimal neighbors_key Use neighbors connectivities as adjacency. If not specified, leiden looks .obsp['connectivities'] for connectivities (default storage place for pp.neighbors). If specified, leiden looks .obsp[.uns[neighbors_key]['connectivities_key']] for connectivities. adjacency Sparse adjacency matrix of the graph, defaults to neighbors connectivities. directed Whether to treat the graph as directed or undirected. use_weights If `True`, edge weights from the graph are used in the computation (placing more emphasis on stronger edges). pca_args Parameters to be passed to `sc.tl.pca` before harmony is issued use_rep If specified use this embedding and do not calculate a pca. Note that the embedding must be present in both datasets, with the same number of dimensions harmony_args Parameters to be passed to `sc.external.pp.harmony_integrate` copy: Return a new object or do everything in place Returns ------- Depending on `copy`, returns or updates `adata` with added labels in adata.obs[f'{label_ref}'] .. py:function:: cr_lineages(adata: anndata.AnnData, model_key: Optional[str] = 'nsbm', level: int = 1, use_affinity: bool = False) Return marginals/affinities as cellrank Lineage. Parameters ---------- adata: The AnnData object. Should have been already processed with schist model_key: The partition model used. It matches the "key_added" parameter of `scs.inference.model()`. If no key was provided when modeling, it matches the name of the model (i.e. 'nsbm', 'sbm' or 'ppbm') level: The level to consider. This parameter is effective only for Nested partitions use_weights Default mode uses cell marginals (adata.obsm['CM_{model_key}']) to work. Set this to True if affinities should be uses instead. Returns ------- A cellrank Lineage class instance, where each block model cluster corresponds to a single lineage.