Source: https://docs.nygen.io/CyteType/api/helpers.html
Revision: 6ce97c558d4353ff1796056a86b1e6d8b42f4b4e

Helpers
*******

The "cytetype" package also exports three helper functions.


Plot the supporting marker genes
================================

"marker_dotplot" reads the results that "CyteType.run()" stored in the
AnnData object and draws a Scanpy dot plot of the genes that support
each label, with the clusters grouped by the categories in the
results. It needs Scanpy, which is not a dependency of "cytetype".

   from cytetype import marker_dotplot

   marker_dotplot(adata, group_key="leiden")

cytetype.marker_dotplot(adata, group_key, results_prefix='cytetype', n_top_markers=3, gene_symbols=None, **kwargs)

   Dotplot of top marker genes grouped by CyteType cluster categories.

   Reads stored CyteType results from "adata.uns" and builds a
   category-grouped marker dict suitable for "sc.pl.dotplot".

   Parameters:
      * **adata** ("AnnData") – AnnData object that has been annotated
        by CyteType (results stored in "adata.uns").

      * **group_key** ("str") – The original cluster key used during
        annotation (e.g. ""leiden"").

      * **results_prefix** ("str", default: "'cytetype'") – Prefix
        used when the results were stored. Must match the
        "results_prefix" passed to "CyteType.run()".

      * **n_top_markers** ("int", default: "3") – Number of top
        supporting genes to display per cluster.

      * **gene_symbols** ("str" | "None", default: "None") – Column in
        "adata.var" containing gene symbols.  Forwarded to
        "sc.pl.dotplot" via the "gene_symbols" parameter; marker genes
        are matched to its values instead of "var_names".

      * ****kwargs** ("Any") – Additional keyword arguments forwarded
        to "sc.pl.dotplot" (e.g. "cmap", "use_raw").

   Return type:
      "Any"

   Returns:
      The return value of "sc.pl.dotplot".

   -[ Notes ]-

   Rows follow the order of the cluster categories. Labels without a
   category (e.g. ""Unknown"") are placed last. Genes come from the
   structured output’s "keySupportingGenes", falling back to
   "supportingMarkers" for jobs without it. They are matched case-
   insensitively to the names "sc.pl.dotplot" looks up (the server
   reports upper-case symbols, e.g. "CD8A" for mouse "Cd8a"). Genes
   that are not found are skipped with a warning, and categories left
   without genes are dropped.


Find marker genes in backed AnnData
===================================

"rank_genes_groups_backed" computes marker genes for an AnnData object
opened in backed mode, such as with "anndata.read_h5ad(path,
backed="r")". It reads the cells in chunks of "cell_batch_size"
instead of loading the whole matrix, compares each group with all
other cells using Welch’s t-test, and writes Scanpy-compatible results
to "adata.uns[key_added]". Pass the same key to "CyteType" as
"rank_key". Large datasets shows where it fits in a workflow.

cytetype.rank_genes_groups_backed(adata, groupby, *, use_raw=False, layer=None, n_genes=None, key_added='rank_genes_groups', cell_batch_size=5000, corr_method='benjamini-hochberg', pts=False, copy=False)

   Memory-efficient rank_genes_groups for backed/on-disk AnnData
   objects.

   Drop-in replacement for "sc.tl.rank_genes_groups" that works on
   backed "_CSRDataset" matrices by streaming cell chunks instead of
   loading the full matrix. Uses Welch’s t-test with one-vs-rest
   comparison.

   Writes scanpy-compatible output to "adata.uns[key_added]".

   Return type:
      "AnnData" | "None"


Subsample cells per cluster
===========================

"subsample_by_group" keeps at most "max_cells_per_group" randomly
chosen cells from each group and returns them as a new in-memory
AnnData object. Groups with fewer cells are kept whole, and
"random_state" makes the selection reproducible.

cytetype.subsample_by_group(adata, group_key, max_cells_per_group=1000, random_state=0)

   Subsample cells from an AnnData object, capping each group to a
   maximum count.

   Groups smaller than *max_cells_per_group* are kept intact.

   Parameters:
      * **adata** ("AnnData") – The AnnData object to subsample.

      * **group_key** ("str") – Column in "adata.obs" that defines the
        groups (e.g. cluster labels).

      * **max_cells_per_group** ("int", default: "1000") – Maximum
        number of cells to retain per group. Groups with fewer cells
        are included in full.

      * **random_state** ("int", default: "0") – Seed for reproducible
        sampling.

   Return type:
      "AnnData"

   Returns:
      "anndata.AnnData" – A new in-memory AnnData object containing at
      most *max_cells_per_group* cells per group.