dance.atlas

Note

The functions in the api/atlas module are primarily backend APIs for the DANCE 2.0 Platform. For interactive usage, please visit the DANCE 2.0 Platform.

async main.get_atlas_method(atlas_id, tissue)[source]

Retrieve the best preprocessing workflows for a specific atlas dataset across different methods.

This endpoint returns the optimal preprocessing configurations for a given atlas dataset identified by its ID and tissue type, across all supported cell type annotation methods.

Parameters:

atlas_idstr

The ID of the atlas dataset to retrieve preprocessing workflows for

tissuestr

The tissue type of the atlas dataset (e.g., ‘brain’, ‘heart’, etc.)

Returns:

: dict

Dictionary containing the best preprocessing workflow configurations for the specified atlas dataset across different methods: - cta_celltypist: Best preprocessing workflow for CellTypist method - cta_scdeepsort: Best preprocessing workflow for scDeepSort method - cta_singlecellnet: Best preprocessing workflow for SingleCellNet method - cta_actinn: Best preprocessing workflow for ACTINN method - dataset_id: The atlas dataset ID

Notes:

  • The workflows are retrieved from the Cell Type Annotation Atlas Excel file

  • Supported methods include: cta_celltypist, cta_scdeepsort, cta_singlecellnet, cta_actinn

  • Each method returns its optimal preprocessing configuration in YAML format

main.get_sim(adata, tissue, sweep_dict=None, feature_name='bures', use_sim_cache=False, query_dataset=None)[source]

Analyze similarity between user query dataset and atlas datasets, returning the most similar dataset and its best preprocessing workflows.

The main purpose of this function is: given a user’s query dataset, the function returns the most similar dataset in the atlas and its best preprocessing workflows across different methods.

Parameters:

adataad.AnnData

User’s query AnnData object

tissuestr

Tissue type of the query dataset (e.g., ‘brain’, ‘heart’, etc.)

sweep_dictOptional[dict], default=None

Dictionary containing sweep configurations that have been run on the query dataset, format: {“cta_actinn”: “sweep_id1”, “cta_celltypist”: “sweep_id2”, …} Usually not provided in most cases, in which case plot2 will not be generated

feature_namestr, default=”bures”

Feature name used to evaluate similarity between query dataset and atlas datasets

use_sim_cachebool, default=False

Whether to use cached similarity matrix, can improve computation speed

query_datasetOptional[str], default=None

Cache name, used when use_sim_cache=True

Returns:

: dict

Dictionary containing the following key-value pairs: - metadata: Best preprocessing workflow configurations for the most similar dataset in atlas across different methods - plot1_png_base64: Base64 encoded plot1 (radar chart showing similarity scores of the most similar dataset using other functions except feature_name) - plot2_png_base64: Base64 encoded plot2 (showing position of found preprocessing workflows in previously run searches, None when sweep_dict=None)

Notes:

  • Plot1 displays the performance of the most similar dataset across multiple similarity metrics (in radar chart format)

  • Plot2 is only generated when sweep_dict is provided, showing the position of best preprocessing workflows in historical search results

  • Supported similarity features include: wasserstein, Hausdorff, spectral, etc.

  • Supported methods include: cta_actinn, cta_celltypist, cta_scdeepsort, cta_singlecellnet

Parameters:

  • adata (AnnData) –

  • tissue (str) –

  • sweep_dict (dict | None) –

  • feature_name (str) –

async main.run_similarity_analysis(h5ad_file=File(PydanticUndefined), tissue=Form(PydanticUndefined), feature_name=Form(metadata_sim), use_sim_cache=Form(False), query_dataset=Form(None), sweep_dict_json=Form(None))[source]

FastAPI wrapper for the get_sim function to perform similarity analysis via HTTP API.

This endpoint receives an uploaded h5ad file and analysis parameters, then calls the get_sim function to analyze similarity between the query dataset and atlas datasets. It returns the most similar dataset from the atlas along with its best preprocessing workflows and visualization plots.

Parameters:

h5ad_fileUploadFile

Uploaded .h5ad format query data file

tissuestr

Tissue type of the query dataset (e.g., ‘brain’, ‘heart’, etc.)

feature_namestr, default=”metadata_sim”

Feature name used to evaluate similarity between query and atlas datasets

use_sim_cachebool, default=False

Whether to use cached similarity matrix for faster computation

query_datasetOptional[str], default=None

Query dataset ID for cache identification

sweep_dict_jsonOptional[str], default=None

JSON string containing sweep configurations that have been run on the query dataset

Returns:

: dict

Same return format as get_sim function: - metadata: Best preprocessing workflow configurations for the most similar atlas dataset - plot1_png_base64: Base64 encoded radar chart showing similarity metrics - plot2_png_base64: Base64 encoded plot showing preprocessing workflow positions (if sweep_dict provided)

Notes:

  • This is essentially a FastAPI wrapper around the get_sim function

  • The function handles file upload, parameter processing, and temporary file cleanup

  • All core analysis logic is delegated to the get_sim function

  • Returns the same analysis results as get_sim but through HTTP API interface

Parameters:

  • h5ad_file (UploadFile) –

  • tissue (str) –

  • feature_name (str) –

  • use_sim_cache (bool) –

  • query_dataset (str | None) –

  • sweep_dict_json (str | None) –