Hotspot

Hotspot identifies informative genes (and gene modules) by measuring how well a gene's expression variation agrees with a specific cell similarity metric.

An 'informative' gene is one whose expression varies similarly among cells that are close to each other in the chosen metric space. The choice of metric determines the biological context:

• Spatial: Uses physical proximity (2D/3D) to identify spatially-varying genes.
• Lineage: Uses developmental lineage (e.g., from a tree) to identify heritable patterns of gene expression.
• Transcriptional: Uses dimensionality reduction (e.g., PCA) to identify gene modules with local correlation, useful for interpreting non-linear axes of variation.

Hotspot allows you to define cell similarity using three different approaches:

1. Latent Space / Coordinates: Use latent_obsm_key to point to a key in adata.obsm (e.g., PCA or spatial coordinates). Similarity is calculated via Euclidean distance in this space.
2. Developmental Lineage: Use tree to provide an ete3.TreeNode object representing a lineage tree where cells are leaves. Leaf names must match the cell barcodes in the counts matrix.
3. Precomputed Distances: Use distances_obsp_key to point to a Cells x Cells distance matrix stored in adata.obsp.

# Example using a tree
import ete3
tree = ete3.Tree('my_newick.txt')
root = tree.get_root()

hs = hotspot.Hotspot(
    adata,
    tree=root,
    ...
)

Install the hotspotsc package directly from PyPI.

Note: Starting from v1.0, Hotspot uses AnnData objects. If you require the legacy version (v0.9.1), you must specify the version during installation.

# Install current version (v1.0+)
pip install hotspotsc

# Install legacy version (v0.9.1)
pip install hotspotsc==0.9.1

Hotspot identifies heritable expression patterns through a two-step process:

1. Autocorrelation: It first identifies genes that show significant variation correlated with the cell metric (e.g., a lineage tree). This distinguishes genes with 'heritable' variation from those with random noise.
2. Local Correlation: It then computes correlations between these significant genes, but only within local cell neighborhoods. This captures how genes co-vary locally in the lineage space.
3. Clustering: Finally, it uses these local correlations to cluster genes into modules. This approach allows the discovery of gene sets that move together along specific lineage trajectories.

The model parameter in the Hotspot constructor defines the null model used to fit per-cell expectations for each gene (assuming no correlations). This is used to evaluate autocorrelation and local correlations.

Available options:

• danb: 'Depth-adjusted negative binomial' (NBDisp model). Recommended for UMI counts.
• bernoulli: Estimates only the detection probability for each gene using logistic regression on gene bins as a function of umi_count.
• normal: Assumes expression values are normally distributed and scaled by umi_count.
• none: Assumes values are already pre-standardized.

To start an analysis, create a hotspot.Hotspot object. You must provide an AnnData object and specify the background model, the metric space for cell similarity, and the per-cell scaling factor.

import hotspot

hs = hotspot.Hotspot(
    adata,
    layer_key="counts",
    model='danb',
    latent_obsm_key="X_pca",
    umi_counts_obs_key="total_counts"
)

Parameters:

• adata: An AnnData object containing cells and genes.
• layer_key: The key of the adata.layers containing count information.
• model: The background model for gene expression (see Alternative choices for 'model').
• latent_obsm_key: The key in adata.obsm containing the cell similarity matrix (e.g., PCA components or spatial coordinates).
• umi_counts_obs_key: The key in adata.obs containing the UMI count for each cell (used for scaling).

To group genes into modules, you must first evaluate their pair-wise local correlations. Local correlations account for associations where genes are expressed 'near' each other in the metric space, which helps resolve correlations between sparsely detected genes.

Because evaluating all pairs is computationally expensive, it is recommended to only run this on informative genes (e.g., those with FDR < 0.05).

# 1. Select informative genes
hs_genes = hs_results.loc[hs_results.FDR < 0.05].index

# 2. Compute local correlations
local_correlations = hs.compute_local_correlations(hs_genes, jobs=4)

Output: A genes x genes pandas DataFrame of Z-scores for the local correlation values. The result is also stored in hs.local_correlation_z.

To visualize these correlations, use hs.plot_local_correlations().

The K-nearest-neighbors (KNN) graph is a required step before computing autocorrelations. It defines the local neighborhood for each cell.

hs.create_knn_graph(weighted_graph=False, n_neighbors=30)

Arguments:

• weighted_graph (bool): If True, the graph has weights scaled by cell-cell distances. If False, it is a binary graph.
• n_neighbors (int): The number of neighbors per cell. Larger values increase robustness but may miss fine-grained patterns and increase runtime.
• neighborhood_factor (float): Used only when weighted_graph=True. Controls the decay of weights: exp(-distance^2/distance_N^2) where distance_N is the distance to the n_neighbors/neighborhood_factorth neighbor.

To visualize the general expression pattern of a gene module across cells, compute summary per-cell module scores.

module_scores = hs.calculate_module_scores()

Output: A pandas DataFrame (cells x modules) containing scores for each module in each cell. The result is also stored in hs.module_scores. These scores can be mapped back onto spatial or transcriptional visualizations of the cells.

Compute per-gene autocorrelations to identify genes whose expression varies according to the cell similarity metric.

hs_results = hs.compute_autocorrelations(jobs=4)

Output: A pandas DataFrame (also stored in hs.results) containing:

• Gene: Gene identifier.
• C: Scaled -1:1 autocorrelation coefficients.
• Z: Z-score for autocorrelation.
• Pval: P-values computed from Z-scores.
• FDR: Q-values (Benjamini-Hochberg procedure).

Use the jobs argument to enable parallel processing on multi-core machines.