scviva.tools.harreman.HarremanHotspotAccessor

scviva.tools.harreman.HarremanHotspotAccessor#

class scviva.tools.harreman.HarremanHotspotAccessor(ha)[source]#

Hotspot analysis methods accessible as ha.hs.<method>.

Created automatically by HarremanAnalysis; users do not instantiate it directly.

Parameters:: ha (HarremanAnalysis) – The analysis object whose AnnData is used when adata is not passed.

Methods table

`calculate_module_scores`([adata, device, verbose])	Calculate module scores for gene modules across cells.
`calculate_super_module_scores`([adata, ...])	Calculate super-module scores for gene super-modules across cells.
`compute_local_autocorrelation`([adata, ...])	Compute gene-level spatial autocorrelation using spatial weights and centered expression.
`compute_local_correlation`([adata, genes, ...])	Computes pairwise local correlation between selected genes using a spatial weight matrix.
`compute_top_scoring_modules`([adata, sd, ...])	Identify the top-scoring module (or super-module) for each cell.
`create_modules`([adata, min_gene_threshold, ...])	Perform hierarchical clustering on gene-gene local correlation Z-scores to assign gene modules.
`integrate_vision_hotspot_results`([adata, ...])	Integrate VISION signature scoring with Hotspot module assignments.

Methods

HarremanHotspotAccessor.calculate_module_scores(adata: AnnData | None = None, *, device: device | str = 'auto', verbose: bool | None = False) → None#

Calculate module scores for gene modules across cells.

Forwards to calculate_module_scores(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Annotated data object (AnnData). Required fields in adata.uns: - ‘layer_key’: name of the layer from which to extract the expression matrix - ‘model’: statistical model used to normalize expression (e.g., ‘DANB’, ‘normal’) - ‘umi_counts’: total UMI counts per cell - ‘gene_modules_dict’: dictionary mapping module IDs (as strings) to lists of gene names
device (torch.device, optional) – Device to use for computation (e.g., CUDA or CPU). Defaults to GPU if available.
verbose (bool, optional (default: False)) – Whether to print progress and status messages.

Returns:

The following results are stored in the AnnData object: - adata.obsm[‘module_scores’]: (cells x modules) DataFrame with per-cell module scores - adata.varm[‘gene_loadings’]: (genes x modules) DataFrame with gene loadings per module - adata.uns[‘gene_modules’]: dictionary mapping module names to gene lists

Return type:

None

HarremanHotspotAccessor.calculate_super_module_scores(adata: AnnData | None = None, *, super_module_dict: dict = None, device: device | str = 'auto', verbose: bool | None = False) → None#

Calculate super-module scores for gene super-modules across cells.

Forwards to calculate_super_module_scores(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Annotated data object (AnnData). Required fields in adata.uns: - ‘layer_key’: name of the layer from which to extract the expression matrix - ‘model’: statistical model used to normalize expression (e.g., ‘DANB’, ‘normal’) - ‘umi_counts’: total UMI counts per cell - ‘gene_modules’: dictionary mapping module IDs (as strings) to lists of gene names
super_module_dict (dict) – Dictionary with super-module IDs (integers) as keys and lists of associated modules (as integers) as values.
device (torch.device, optional) – Device to use for computation (e.g., CUDA or CPU). Defaults to GPU if available.
verbose (bool, optional (default: False)) – Whether to print progress and status messages.

Returns:

The following results are stored in the AnnData object:

adata.obsm[‘super_module_scores’]: (cells x super-modules) DataFrame with per-cell super-module activity scores
adata.varm[‘gene_loadings_sm’]: (genes x super-modules) DataFrame with gene loadings for each super-module
adata.uns[‘gene_modules_sm’]: dictionary mapping super-module names to gene lists

Return type:

None

Compute gene-level spatial autocorrelation using spatial weights and centered expression.

Forwards to compute_local_autocorrelation(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Annotated data object (AnnData). Requires obsp[“weights”] for the spatial graph.
layer_key (str or "use_raw", optional) – Key in adata.layers to use for expression data. Use “use_raw” to access adata.raw.
database_varm_key (str, optional) – Key in adata.varm used for filtering genes that are part of the transporter or ligand-receptor database.
model (str, optional) – Normalization model to use for centering gene expression. Options include “none”, “normal”, “bernoulli”, or “danb”.
genes (list, optional) – List of gene names to include in the analysis. If None, all genes are used or selected via metabolic/pathway filters.
use_metabolic_genes (bool, optional (default: False)) – If True, restricts analysis to metabolic genes as defined for the selected species.
species ({"mouse", "human"}, optional (default: "mouse")) – Species used to select the correct metabolic gene list if use_metabolic_genes=True.
umi_counts_obs_key (str, optional) – Key in adata.obs with total UMI counts per cell. If None, inferred from the expression matrix.
permutation_test (bool, optional (default: False)) – Whether to compute an empirical p-value and null distribution by permuting the data.
M (int, optional (default: 1000)) – Number of permutations to perform if permutation_test is True.
seed (int, optional (default: 42)) – Random seed for permutation reproducibility.
check_analytic_null (bool, optional (default: False)) – Whether to evaluate Z-scores under an analytic null distribution using permutation Z-scores.
device (int, str, or torch.device, optional (default: "auto")) – Device to use for computation. If “auto” or a device index, this is resolved with scvi.model._utils.parse_device_args().
accelerator (str, optional (default: "auto")) – Accelerator type to use when resolving device.
verbose (bool, optional (default: False)) – Whether to print progress and status messages.

Returns:

The results are stored in adata.uns[“gene_autocorrelation_results”] as a DataFrame.

Return type:

None

Computes pairwise local correlation between selected genes using a spatial weight matrix.

Forwards to compute_local_correlation(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Annotated data object (AnnData). Required keys in adata.uns: - ‘gene_autocorrelation_results’ (if genes is None) - ‘layer_key’: layer in adata to extract counts from - ‘model’: statistical model to use for centering (e.g., ‘DANB’, ‘normal’) - ‘umi_counts’: per-cell UMI counts - optionally ‘sample_key’: key in adata.obs to use for per-sample normalization
genes (list, optional) – List of genes to include in the correlation analysis. If None, selects genes with FDR < 0.05 from adata.uns[‘gene_autocorrelation_results’], ordered by Z-score.
permutation_test (bool, optional (default: False)) – Whether to compute an empirical p-value and null distribution by permuting the data.
M (int, optional (default: 1000)) – Number of permutations to perform if permutation_test is True.
seed (int, optional (default: 42)) – Random seed for permutation reproducibility.
check_analytic_null (bool, optional (default: False)) – Whether to compute an analytic null distribution for the local correlation scores.
device (torch.device, optional) – PyTorch device to run computations on. Defaults to CUDA if available.
verbose (bool, optional (default: False)) – Whether to print progress and status messages.

Returns:

Results are stored in the following keys in adata.uns: lcs, lc_zs, lc_z_pvals, and lc_z_FDR.

Return type:

None

HarremanHotspotAccessor.compute_top_scoring_modules(adata: AnnData | None = None, *, sd: float | None = 1, use_super_modules: bool | None = False)#

Identify the top-scoring module (or super-module) for each cell.

Forwards to compute_top_scoring_modules(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Must contain a matrix of module or super-module scores in: - obsm['module_scores'] or - obsm['super_module_scores']
sd (float, default 1) – Standard deviation threshold to determine strong module activation. Only modules with zscore > sd are considered strictly activated.
use_super_modules (bool, default False) – If True, select among super-modules instead of standard modules.

Returns:

A Series indexed by cell, containing the name of the top-scoring module/super-module for each cell.

Return type:

pandas.Series

Perform hierarchical clustering on gene-gene local correlation Z-scores to assign gene modules.

Forwards to create_modules(). adata defaults to the AnnData held by the analysis object.

Parameters:

adata (AnnData) – Annotated data object (AnnData) containing the local correlation Z-scores in adata.uns[‘lc_zs’].
min_gene_threshold (int, optional (default: 20)) – Minimum number of genes required to define a module.
fdr_threshold (float, optional (default: 0.05)) – FDR threshold used to determine the minimum Z-score significance if z_threshold is not provided.
z_threshold (float, optional) – If provided, uses this Z-score as the cutoff for module inclusion instead of computing it from FDR.
core_only (bool, optional (default: False)) – If True, assigns only tightly correlated (core) genes to modules and leaves others unassigned.
verbose (bool, optional (default: False)) – If True, print progress messages and the elapsed time.

Returns:

The function modifies the AnnData object in place by adding the following to adata.uns: - modules: pandas Series mapping each gene to a module ID (integer, as string) - gene_modules_dict: dictionary mapping module IDs (as strings) to lists of gene names - linkage: linkage matrix from hierarchical clustering (for visualization or tree ops)

Return type:

None

HarremanHotspotAccessor.integrate_vision_hotspot_results(adata: AnnData | None = None, *, cor_method: Literal['pearson', 'spearman'] = 'pearson', use_super_modules: bool = False) → None#

Integrate VISION signature scoring with Hotspot module assignments.

Forwards to integrate_vision_hotspot_results(). adata defaults to the AnnData held by the analysis object.

Deprecated alias for ha.vs.integrate_vision_hotspot_results, kept for backward compatibility with code written before it moved to ha.vs.

Requires that VISION signature scoring has already been run (producing adata.obsm['vision_signatures'], adata.uns['norm_data_key'], and adata.uns['signature_varm_key'] — e.g. via compute_signatures()) and that Hotspot modules have been created via create_modules() and scored via calculate_module_scores() (or calculate_super_module_scores() when use_super_modules=True).

For each (signature, module) pair the function computes:

A hypergeometric enrichment test of signature gene overlap with module genes (log2 fold-enrichment, raw p-value, BH-FDR).
Pearson or Spearman correlation between per-cell signature scores and per-cell module activity scores.

An overlap signature matrix (genes present in significant signature-module intersections) is also computed and stored for downstream use.

Parameters:

adata (AnnData) –
Annotated data object. Must contain:
- obsm['vision_signatures']: per-cell signature scores produced by scviva.tools.vision.tools.signature.compute_signatures_anndata().
- uns['norm_data_key']: expression layer key used for signature scoring (None, "use_raw", or a layer name).
- uns['signature_varm_key']: key in adata.varm for the gene x signature scoring matrix.
- uns['gene_modules'] (or uns['gene_modules_sm'] when use_super_modules=True): module -> gene-list mapping produced by calculate_module_scores() / calculate_super_module_scores().
- obsm['module_scores'] (or obsm['super_module_scores']): per-cell module activity scores.
cor_method ({'pearson', 'spearman'}, default 'pearson') – Correlation method used to relate signature scores to module scores.
use_super_modules (bool, default False) – If True, use super-module gene lists and scores (gene_modules_sm / super_module_scores) instead of the standard module equivalents.

Returns:

Results are stored in-place on adata:

uns['sig_mod_enrichment_stats']: log2 fold-enrichment (signatures x modules).
uns['sig_mod_enrichment_pvals']: raw hypergeometric p-values (signatures x modules).
uns['sig_mod_enrichment_FDR']: BH-corrected FDR values (signatures x modules).
uns['sig_mod_correlation_coefs']: correlation coefficients (modules x signatures).
uns['sig_mod_correlation_pvals']: raw correlation p-values (modules x signatures).
uns['sig_mod_correlation_FDR']: BH-corrected FDR values (modules x signatures).
uns['cor_method']: the correlation method used.
varm['signatures_overlap']: binary gene x overlap-signature matrix for signature-module intersections with p < 0.05.
obsm['signature_modules_overlap']: per-cell scores for each significant signature-module overlap.

Return type:

None

scviva.tools.harreman.HarremanHotspotAccessor

Contents

scviva.tools.harreman.HarremanHotspotAccessor#