FAQ¶

pca. It is the fastest and lightest, and exercises the same job hierarchy, Hotspot step, and output layout as everything else — so it validates your configuration cheaply. Then add cpca and contrapc.

The objective. cpca subtracts background covariance (\(C_t - \alpha C_b\)) with an unbounded α; contrapc whitens by it (\(C_b^{-\alpha} C_t\)) with α bounded in \([0, 1]\).

Practically: contrapc's α is comparable across datasets and it always returns α = 0 and α = 1, so results line up across perturbations. cpca's α range depends on the relative scale of the two covariances and may need max_log_alpha tuning. See Contrastive Embeddings.

Only if you suspect nonlinear structure. They cost roughly twice the memory and introduce seed dependence. Run the linear modules first; reach for kcpca when the linear embeddings look uninformative despite adequate cell numbers.

Running several is the point — the methods disagree, and a gene program recovered by three independent methods is far more credible than one seen under a single method and a single α. But start with two or three and expand once you know the per-job cost on your data.

At least 25, and realistically 50. Contrastive modules hard-fail below 25 cells in either group, so anything lower submits jobs guaranteed to fail. The shipped default of 0 exists for flexibility, not as a recommendation.

Set it in that module's config.yaml. Module values override the master. For nested blocks like resources:, the merge is shallow — specify only the keys you want to change and the rest are inherited. See Configuration.

singular for per-perturbation gene programs, which is what perturbation-level disease scoring requires. pooled for the shared perturbation response, and as a fast way to get a first result from a large screen. They answer different questions — see Analysis Modes.

The default of 10 is reasonable. For pca, check pca_variance_ratio.csv — if the last components carry negligible variance, 10 is enough. Remember contrastive modules produce 4 × n_components columns, one block per selected α.

Correct — it sizes the wrapper job, which just runs Snakemake. Analysis job memory comes from resources.mem_mb in the module's config.yaml. See the two levels.

Not as shipped. run_modules.sh wraps sbatch, and each module carries a SLURM profile. You could invoke Snakemake directly with a different executor plugin, but the default resource requests — 128 GB, 256 GB for kernel modules — make anything but a cluster impractical for real data.

Resubmit. Snakemake reruns anything with missing outputs and skips completed targets:

./run_modules.sh --submit --modules cpca

Genes that passed the FDR cutoff but did not join a cluster meeting hotspot_min_gene_threshold. It means "unassigned", not "module number minus one", and it is often the largest group. Filter it out.

Contrastive modules run four α values and concatenate. Columns are named alpha_<a>_pc_<i>, so you get 4 × n_components. See Column conventions.

gene_spectra_scores is Z-scored — use it to rank genes within a program. gene_spectra_tpm is in expression units — use it to compare a gene across programs. Using the Z-scored file for cross-program comparison is a common error.

pca, cpca, and contrapc are deterministic. The kernel modules depend on kernel_seed. cnmf aggregates random restarts and contrastivevi trains a neural model without an exposed seed — both vary between runs.

Expected — it is quadratic in the number of FDR-significant genes. Tighten hotspot_fdr_threshold, or delete these files once modules exist; the modules and scores are derived from them and do not need them retained.

The eight Snakemake modules cover stage 1 only. Stage 2 - program selection, meta-program construction, variant annotation, S-LDSC, and TRS - runs separately and is documented step by step, with the code for each step, on Disease Enrichment. The scripts are adaptations of the published PoPS and sc-linker implementations and are not redistributed here, and the resources they read - GWAS summary statistics, MAGMA results, LD panels, variant-to-gene maps - are far too large to ship.

Yes — every table in the Data Browser has a download button, and the download respects your active search filter.

The per-SNP contribution to heritability of a one standard deviation increase in the program annotation, standardized by total trait heritability so it is comparable across annotations and traits. See Step 5.

They are thresholded, not estimated as zero. The published trs column is set to 0 unless the jackknife mean is positive and the one-sided p-value is at most 0.05. Always read trs alongside pvalue.

No. The annotation is built from correlational variant-to-gene links and a gene ranking derived from GWAS signal, so a significant result says the perturbation's programs share genetic architecture with the trait. It is not a causal claim.

The test asks only whether the annotation is enriched for heritability. Depletion is not tested, so the p-value should not be interpreted as a two-sided test of any effect.

Not a perturbation. Programs were learned per perturbation, then all of them were combined into a single meta-program and scored the same way. The Data Browser marks it with an aggregate badge and leaves it out of perturbation counts. See All is not a perturbation.