scspecies.plot module

Functions to visualize scSpecies results.

scspecies.plot.label_transfer_acc(df_nns, df_sim, save_key=None)[source]

Compare balanced-accuracy of label-transfer by data-level NNs vs. scSpecies similarity-based label transfer and plot horizontal bar stacks of top-k context votes.

Parameters:

  • df_nns (pd.DataFrame) – Confusion-matrix-based accuracy of kNN transfers.

  • df_sim (pd.DataFrame) – Confusion-matrix-based accuracy using scSpecies similarity.

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.load_and_filter_pathways(gmt_path, adata, min_genes=5)[source]

Load pathway gene sets from a GMT file and filter to those with at least min_genes overlapping with adata.var_names.

Parameters:

  • gmt_path (str) – Path to the .gmt file.

  • adata (AnnData) – AnnData object with .var_names (genes).

  • min_genes (int) – Minimum number of overlapping genes to keep a pathway.

Returns:

filtered_pathways – Mapping of pathway names to lists of overlapping gene symbols.

Return type:

dict

scspecies.plot.plot_2D_representation(adata_concat, rep_key='X_umap', plot_annot='cell_type_fine', context_species='mouse', target_species='human', save_key=None)[source]

Scatter dataset representation of context vs. target in 2D (e.g., UMAP) with shared color mapping based on labels.

Parameters:

  • adata_concat (MuData) – Combined MuData with .obsm[rep_key] for both species.

  • rep_key (str, default='X_umap') – Key in .obsm for 2D coordinates.

  • plot_annot (str, default='cell_type_fine') – Observation key for the categorical annotation.

  • context_species (str, default='mouse')

  • target_species (str, default='human')

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.plot_lfc(lfc_dict, prob_delta=0.9, save_key=None)[source]

Scatter-plot Log2-Fold-change versus probability for each cell type, highlighting and annotating top up- and down-regulated genes.

Parameters:

  • lfc_dict (list) – List of LFC dataframes.

  • prob_delta (float, default=0.9) – Probability threshold for calling significant LFC.

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.plot_lfc_comparison(model, lfc_dict, save_key=None)[source]

Generate and display a grid of scatter plots comparing log₂‐fold changes estimated by scSpecies against LFC computed directly from the data.

Parameters:

  • model (scSpecies) – A trained and evaluated scSpecies model instance.

  • lfc_dict (dict of {str: pandas.DataFrame}) – List of LFC dataframes.

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.plot_prototype_sim_heatmap(df, save_key=None)[source]

Heatmap of prototype-similarity between target (rows) and context (columns) cell types, with top-2 matches annotated by rank.

Parameters:

  • df (pd.DataFrame) – Similarity matrix (target cell types × context cell types).

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.plot_similarity(adata_concat, df_neigbor, human_ind, rep_key='X_umap', plot_annot='cell_type_fine', context_species='mouse', target_species='human', save_key=None)[source]

Scatter dataset representation of context vs. target in 2D (e.g., UMAP) colored by similarity to a specified target cell.

Parameters:

  • adata_concat (MuData) – Combined MuData with .obsm[rep_key] for both species.

  • df_neigbor (pd.DataFrame) – DataFrame with columns [‘index’,’similarity_score’] for a single target cell.

  • human_ind (int) – Index of the target cell in adata_concat.

  • rep_key (str, default='X_umap') – Key in .obsm for 2D coordinates.

  • plot_annot (str, default='cell_type_fine') – Observation key for labeling the target cell.

  • context_species (str, default='mouse')

  • target_species (str, default='human')

  • save_key (str or None, default=None) – If a string, the plot will be saved to figures/{save_key}.png. If None, it will only be displayed.

scspecies.plot.return_palette(names, col_dict={})[source]

Build a color mapping for a list of labels, using predefined overrides and extending with Glasbey palette for unknowns.

Parameters:

  • names (sequence of str) – Labels to assign colors.

  • col_dict (dict, optional) – Predefined name→hex mappings.

Returns:

Mapping from each unique name in names to a hex color code.

Return type:

dict[str, str]