Utilities

UniCell Deconvolve - Cell Type Deconvolution For Transcriptomic Data.

ucdeconvolve.utils.assign_top_celltypes(adata: AnnData, key: str = 'ucdbase', category: Optional[str] = None, groupby: Optional[str] = None, inplace: bool = True, key_added: str = 'pred_celltype', knnsmooth_neighbors: Optional[int] = None, knnsmooth_cycles: int = 1) → Union[List[str], Dict[str, str]]

Gets top deconvolution predictions by cluster.

Parameters:

  • adata – Annotated dataset with deconvolution results stored

  • groupby – Optional variable, if not passed then the top celltype is predicted for each individual sample by row.

  • category – Which split category to use, defaults if none.

  • key – Key for deconvolution results, default key is ‘ucdbase’

  • inplace – Whether or not to attach the result to the anndata object ‘obs’ as a column

  • key_added – The key to add as a column.

  • knnsmooth_neighbors – Optional smoothing for predictions, uses neighbors graph calculated using sc.tl.neighbors. If not none, passed integer referring to number of nearest neighbors to consider for smoothing, reccomended 3.

  • knnsmooth_cycles – Number of cycles to repeat smoothing, default 1.

Returns:

celltypes – If no groupby is passed return a list of strings corresponding to the top celltype that can be used for annotation. If a group is passed, returns a dicitonary mapping group label to celltype.

Return type:

Union[List[str], Dict[str, str]]

ucdeconvolve.utils.get_base_celltypes(root: Optional[str] = None, category: Optional[str] = None, as_digraph: bool = False) → List[str]

Get UCDBase CellTypes

Return a list of UCDbase celltypes.

Parameters:

  • root – Optional root cell type, if set, returns all decendants of that celltype along the UCD celltype hierarchy.

  • category – If category is set, overrides root behavior and returns a list of all celltypes in the subset category. Must be either ‘primary’, ‘lines’, or ‘cancer’.

  • as_digraph – If true, return the underlying networkX graph that can be used to visualize result directly when calling a root node. Call root node “cell” to return all nodes in graph.

Returns:

celltypes – A list of celltypes, either all or subsets.

Return type:

List[str]

ucdeconvolve.utils.get_prebuilt_reference(reference: str, token: Optional[str] = None, cache: bool = True) → AnnData

Get Prebuilt Reference

Downloads a pre-made reference dataset.

Parameters:

  • reference – String name of prebuilt reference to get.

  • token – Optional access token, if not passed default token is retrieved from settings.

  • cache – If true, save a loaded file into cachedir and try to reload it before downloading again.

Returns:

adata – Annotated dataset object containing the prebuilt reference.

Return type:

anndata.AnnData

ucdeconvolve.utils.list_prebuilt_references(token: Optional[str] = None) → AnnData

List Prebuilt References

Lists available pre-built references

Parameters:

token – Optional access token, if not passed default token is retrieved from settings.

Returns:

adata – Annotated dataset object containing the prebuilt reference.

Return type:

anndata.AnnData

ucdeconvolve.utils.read_results(adata: AnnData, key: Optional[str] = None, category: Optional[str] = None, celltypes: Optional[Union[str, List[str]]] = None, explain_n_top_genes: Optional[int] = None) → DataFrame

Read deconvolution results from an annotated dataset and return a dataframe.

Parameters:

  • adata – Annotated dataset with deconvolution results stored.

  • key – Key for deconvolution results. If not passed, will default to searching for ‘ucdbase’, then ‘ucdselect’, and lastly ‘ucdexplain’.

  • category – Which split category to use. Defaults to ‘all’ if running non-base model. If run base and split was made, uses ‘primary’.

  • celltypes – The celltypes specifically to read results from, if None then all celltypes from explanation are read and combined in a multi-index dataframe. For ucdselect and ucdbase celltypes will subset the returned dataframe.

  • explain_n_top_genes – Number of genes to extract when reading explanations, if None then return all genes.