king workflow separates related and unrelated samples, qc applies filtering and LD pruning, qcnoprune applies filtering without pruning, and genotypephenotypesampleoverlap retains samples represented in both the genotype and molecular phenotype data. The appropriate combination depends on cohort relatedness and on whether a pruned variant list already exists. Method reference: Manichaikul et al., 2010, Chang et al., 2015.","METAL":"This notebook runs cross-cohort meta-analysis of summary statistics with METAL on the toy protocol_example dataset. METAL is a command-line tool that takes a script documenting the input summary-statistic files, the field mapping for each, and the analysis settings. Meta-analysis here is essentially a weighted sum of Z-scores, so the same set of variants must be present across the input cohorts; the input is a list of paths to the per-cohort summary statistics to analyse together. Method reference: Willer et al., 2010.","PCA":"Population structure is the classic confounder in genetic association: if ancestry correlates with both genotype and phenotype, unadjusted tests return associations that are real but not causal. The remedy is to compute principal components of the genotype matrix and carry the leading ones as covariates. Components are computed on unrelated individuals and the remaining related samples are projected back into that space, so relatives cannot distort the axes but every sample still gets coordinates. The sequence is: remove related individuals, LD-prune the variants, run PCA on the unrelated set, then exclude PCA-space outliers. Relatedness estimation and sample QC happen upstream in GWAS_QC.ipynb. Method reference: Chang et al., 2015.","RNA_calling":"RNA-seq reads record the transcripts present in each sample. This module aligns reads to the reference genome and quantifies gene-level expression, producing the count and abundance matrices that define the molecular phenotype. Accurate alignment and consistent gene annotation are required because mapping errors can create apparent expression differences that are unrelated to biology. Method reference: Dobin et al., 2013, Li & Dewey, 2011, Chen et al., 2018, Graubert et al., 2021.","SuSiE_enloc":"This workflow processes fine-mapping results for xQTL, generated by susietwas in the mnmregression.ipynb notebook for cis xQTL, and GWAS fine-mapping results produced by susierss in the rssanalysis.ipynb notebook. It is designed to perform enrichment and colocalization analysis, particularly when fine-mapping results originate from different regions in the case of cis-xQTL and GWAS. The pipeline is capable to integrate and analyze data across these distinct regions. Originally tailored for cis-xQTL and GWAS integration, this pipeline can be applied to other pairwise integrations. An example of such application is in trans analysis, where the fine-mapped regions might be identical between trans-xQTL and GWAS, representing a special case of this broader implementation. Method reference: Wen et al., 2017.","TensorQTL":"This module tests whether inherited variants are associated with molecular phenotypes across individuals. Cis analysis focuses on variants near each feature, where regulatory effects are most interpretable, while trans analysis searches for distal effects. Covariates account for ancestry, technical variation, and other measured sources of heterogeneity. GPU acceleration makes the same association model practical across large numbers of variants and phenotypes (Taylor-Weiner et al., 2019).","VCF_QC":"Variant quality control removes genotypes that cannot support reliable regulatory mapping. The workflows normalize variant representation, restrict analysis to the intended samples and regions, remove poorly measured or uninformative variants, and harmonize identifiers before conversion to analysis-ready formats. These checks reduce false associations caused by missingness, allele inconsistencies, duplicate records, or genome-build mismatches.","apa_calling":"Most genes have more than one polyadenylation site, and which one is used shifts the length of the 3' UTR - changing which regulatory elements survive in the transcript. Treating a gene as a single expression value hides that. This step quantifies alternative polyadenylation from RNA-seq coverage with DaPars2, giving a per-sample PDUI (percentage of distal polyA site usage) that can be scanned for QTLs like any other molecular phenotype. The workflows run in order: UTRreference builds the annotation DaPars2 needs, bam2tools converts alignments to coverage, APAconfig writes the configuration file and APAmain runs the quantification.","apa_impute":"Alternative polyadenylation is quantified as PDUI, the fraction of transcripts using the distal poly(A) site. DaPars leaves gaps wherever a gene had too little coverage in a sample to call that fraction, and downstream models need a complete matrix. This step imputes those gaps with the impute package and quantile-normalises the filled matrix so samples are on a common scale. A second, optional workflow renames the sample columns from DaPars internal IDs to the names used elsewhere in the study.","bulk_expression_QC":"Sample-level quality control asks whether each RNA-seq profile represents the intended biological specimen. The module compares expression patterns, sample annotations, and technical metrics to identify swaps, outliers, or globally degraded libraries. Removing problematic samples before association testing prevents a small number of abnormal profiles from driving apparent genetic effects.","bulk_expression_normalization":"Lowly expressed genes provide little reliable information for mapping genetic effects and can add noise to association testing. This step retains genes that are consistently detected across individuals, then normalizes their expression levels so differences in sequencing depth and RNA composition do not obscure biological variation. The resulting expression matrix provides stable molecular phenotypes for downstream cis-eQTL analysis.","colocboost":"Two signals at the same locus - a QTL and a GWAS hit, or QTLs in two cell types - may share a causal variant or merely sit in the same LD block. Colocalization tries to tell those apart. Classical pairwise methods assume one causal variant per trait and compare traits two at a time, which loses power when a region has several independent signals or when the shared signal is weak in any single pair. ColocBoost treats it as a multi-task problem instead: a gradient boosting framework that couples traits as it selects causal variants, so evidence that is weak in isolation can still support a shared signal across many contexts. It scales to hundreds of traits and allows multiple causal variants per region (Cao et al., 2025).","covariate_formatting":"The association scan takes a single covariate file, but covariates arrive from several places: batch and demographic variables you supply, genotype principal components from PCA, and hidden factors estimated by covariatehiddenfactor. This step merges them, reconciles sample identifiers across the sources, and writes the combined matrix in the orientation the scan expects. When to run it. After PCA and hidden-factor estimation, immediately before QTL association testing.","covariate_hidden_factor":"Unmeasured differences in batch, cell composition, RNA quality, or other latent processes can induce correlation among molecular phenotypes. This module estimates hidden factors from the phenotype matrix after accounting for known covariates. Including these factors in the QTL model reduces confounding while preserving interpretable genetic variation. PEER provides a probabilistic factor model, while the PCA workflows estimate the number of supported components from the data (Stegle et al., 2012).","ems_prediction":"Create a tab-separated file with variant identifiers: `` variant_id 2:12345:A:T 2:67890:G:C 2:11111:T:A ``","ems_training":"Most disease-associated GWAS variants lie in non-coding regions of the genome, where they likely modulate gene expression. However, bulk-tissue eQTL studies fail to explain the majority of these variants, a phenomenon termed \"missing regulation\" (Connally et al., 2022). This gap exists because there are systematic differences between variants identified in eQTL studies versus disease GWAS (Mostafavi et al., 2022):","eoo_enrichment":"A variant set that overlaps an annotation more often than chance would predict is evidence that the annotation marks functional sequence. Counting the overlap is easy; putting an error bar on it is not, because variants are correlated along the genome and so cannot be resampled independently. This module computes an odds ratio and an enrichment statistic for each annotation, then leaves out one chromosome at a time and recomputes, using the spread across those 22 leave-one-out estimates as a block-jackknife standard error. Blocking by chromosome keeps correlated variants together rather than splitting them across resamples. When to run it. Run this module after chromosome-level enrichment inputs are available when a combined enrichment estimate and block-jackknife standard error are needed.","gene_annotation":"Molecular phenotype matrices arrive keyed only by a feature identifier, such as an ENSEMBL gene ID, a UniProt accession, or a LeafCutter intron-cluster label, but every downstream QTL step needs a genomic position to define a cis window. This module attaches those coordinates, turning a plain matrix into a coordinate-sorted, bgzipped and tabix-indexed bed.gz file. Coordinates come from a collapsed gene-model GTF, following the GTEx pipeline convention, so the annotation used here matches the one used to build the GTF in the first place. Feature IDs that the GTF does not contain are dropped rather than guessed at, which is why the row count of the output can be lower than that of the input.","generalized_TADB":"Analyses that work locus by locus need a definition of \"locus\". Using a fixed window around each gene is simple but arbitrary: regulatory contacts do not respect a fixed distance, and two genes in the same regulatory neighbourhood get analysed as if independent. Topologically associating domain boundaries give a definition grounded in chromatin architecture instead, and this step generates the boundary files that downstream region-based analyses consume. When to run it. Run this module before region-based association or fine-mapping when TAD-defined regions are preferred to fixed-width cis windows.","genotype_formatting":"Nothing here changes the genotypes; it changes how they are packaged. Tools in the protocol disagree about format - some want PLINK, some want VCF - and the association and fine-mapping steps run per region or per chromosome, so the genotype data has to be split the same way to be processed in parallel. These workflows do those conversions and splits, plus the LD matrix computation per region that summary-statistic fine-mapping needs. When to run it. Run the relevant workflow after genotype quality control and before association scanning, LD calculation, or fine-mapping that requires the corresponding genotype layout. Method reference: Chang et al., 2015.","gregor":"A set of trait-associated variants is more interpretable if you can say what kind of sequence they fall in. Enrichment testing asks whether they overlap a class of genomic feature - an annotation, a chromatin state, a set of regulatory elements - more often than chance allows, where chance has to account for the fact that variants are not exchangeable: they differ in minor allele frequency, in the number of LD proxies they carry, and in distance to the nearest gene. GREGOR builds matched control variants on exactly those properties - minor allele frequency, LD proxy count, distance to the nearest TSS, and local gene density - so the comparison is fair. Method reference: Schmidt et al., 2015.","gsea":"A list of genes is hard to interpret on its own. Over-representation testing asks whether a group contains more members of some pathway or ontology term than chance would give, turning a list of identifiers into statements about biology. This module tests each group against the KEGG database and all three Gene Ontology branches using clusterProfiler. Input ENSEMBL gene IDs are first converted to ENTREZ IDs via org.Hs.eg.db; genes without a valid ENTREZ mapping are dropped, and group associations are preserved through the conversion. KEGG over-representation then runs through enrichKEGG() and GO through enrichGO() for Biological Process, Cellular Component and Molecular Function, both applying a hypergeometric test with Benjamini-Hochberg FDR correction. Method reference: Wu et al., 2021.","intact":"INTACT combines evidence from PTWAS and fastENLOC for the same genes. It converts TWAS z-scores into Bayes factors across a grid of prior effect-size values, averages those Bayes factors, transforms the gene-level colocalization probability into a prior probability, and returns a posterior probability that integrates both sources of evidence. Run it after PTWAS and fastENLOC have been completed on a matched gene set.","ld_prune_reference":"Many downstream methods assume the variants they are handed are approximately independent. A reference genotype panel is not: neighbouring variants are correlated through linkage disequilibrium, so a raw variant list counts the same signal several times over. This step runs PLINK LD clumping (--indep-pairwise) within each LD block and then merges the survivors into a single list, which is the form mashr and similar analyses expect. Working one block at a time keeps each clumping job small and lets the blocks run in parallel. The merge step afterwards also rewrites the variant IDs into one consistent format. Synthetic-data note. The minimal working example runs on a small synthetic chr22 PLINK panel, protocolexample.ldgenotype.chr22, of 60 samples and roughly 18k variants, built from the toy genotype VCF. It is for demonstration only and is not real individual-level data.","mash_fit":"Effects estimated separately in each condition are noisy, and analysing them one condition at a time ignores that most effects are shared. MASH fits a mixture of multivariate normal distributions to the effect estimates, learning from the data which patterns of sharing actually occur - which conditions move together, and how strongly - so that individual estimates can later be shrunk towards those patterns rather than towards zero. This notebook fits the model. The data-driven prior matrices come from mixtureprior, and applying the fitted model to compute posterior estimates is mashposterior. By this point the input data have already been converted from the original association summary statistics into the MASH-format object written by mash_preprocessing. Method reference: Urbut et al., 2019.","mash_posterior":"For each input chunk (a list of matrices bhat/sbhat/Z), the posterior workflow loads the MASH model and calls mashcomputeposteriormatrices. Additional workflows compute posterior contrasts between conditions and feature-level scores (meta, fine-mapped, n-significant, and p-value pairs) from the contrast results. Fitting the mixture model and applying it are separate jobs. mashfit learns which patterns of sharing exist across conditions; this notebook applies that fitted model to each chunk of effects, shrinking noisy estimates towards the patterns the data support. Effects that look condition-specific because of noise get pulled towards the shared pattern, and genuinely specific ones do not. Method reference: Urbut et al., 2019.","mash_preprocessing":"This module constructs the three effect matrices used to learn cross-condition sharing patterns in MASH. The strong-effect matrix contains the top fine-mapped locus from each condition, the null matrix contains independent variants with small z-scores, and the random matrix samples variants from the supplied independent-variant list. Together, these matrices provide signal-rich, null, and background examples for estimating multivariate effect patterns. Run this module after genome-wide SuSiE fine-mapping results are available. Method reference: Urbut et al., 2019.","methylation_calling":"This module quantifies array-based DNA methylation using either sesame or minfi, with sesame recommended for the protocol. Both methods remove probes affected by SNPs or cross-reactivity, assess sample and probe quality, and correct assay bias before producing methylation measurements for downstream QTL analysis. The minfi workflow uses dropLociWithSnps with manual filtering, detectionP summaries, and preprocessQuantile. The sesame workflow combines quality masking (Q), sesameQC_calcStats with detection and frac_dt metrics, nonlinear dye-bias correction (D), pOOBAH detection masking (P), and noob background subtraction (B). Method reference: Zhou et al., 2018.","mixture_prior":"Genetic effects can be specific to one tissue or cell type, shared across several contexts, or similar across all contexts. MASH represents these possibilities as a mixture of covariance patterns. This module learns candidate sharing patterns, separates correlated measurement error from true effect sharing, and estimates how frequently each pattern occurs. The resulting MASH mixture prior allows downstream models to borrow information across contexts without assuming that every effect is shared (Urbut et al., 2019).","mnm_regression":"An association scan tells you a region matters; it does not tell you which variant in it is responsible, because variants in linkage disequilibrium carry nearly the same signal. SuSiE reframes the question as variable selection: it fits a sum of single effects and returns credible sets - small groups of variants, each likely to contain one causal variant - together with posterior inclusion probabilities (Wang et al., 2020). When the same locus is measured across several contexts - tissues, cell types, conditions - fine-mapping each separately throws away the shared structure. mvSuSiE learns the patterns of sharing from the data and uses them to sharpen credible sets (Zou et al., 2026).","phenotype_formatting":"Association testing and fine-mapping run per chromosome or per region, so the phenotype matrix has to be partitioned the same way before that work can be parallelised. These workflows split a phenotype BED by chromosome or by region, annotate features against TAD boundaries when region-based analysis is wanted, and accept GCT-format input as well as BED. Two further workflows trim inputs rather than split them: one subsets BAM files by coordinate, the other drops samples from a GCT matrix. The pipeline's author has flagged it as needing improvement, so treat the interface as unstable and re-check -h before relying on any option. When to run it. After phenotype QC, normalisation and imputation, and before covariate preprocessing and the association scan.","phenotype_imputation":"Missing molecular measurements can arise when a feature falls below detection or is measured unreliably in a subset of samples. This module reconstructs missing values so downstream models can use a complete phenotype matrix. Factor-based methods borrow shared structure across features, nearest-neighbour and tree methods use relationships among samples, and limit-of-detection imputation is appropriate when missingness represents low abundance (Qi et al., 2023).","pseudobulk_preprocessing":"This module prepares single-nucleus RNA-seq or ATAC-seq data for sample-level QTL analysis. It aggregates per-nucleus measurements into a pseudobulk count matrix for each cell type, harmonizes individual and sample identifiers across metadata and count matrices, then filters and normalizes the data before regressing technical covariates. The resulting residual phenotype matrix is ready for phenotype formatting and pseudobulk QTL analysis. Method reference: Hao et al., 2021.","qr_and_twas":"Standard QTL mapping models the mean: it asks whether genotype shifts average expression. That misses variants whose effect is confined to part of the distribution - acting only in highly expressing samples, or changing spread rather than centre. Quantile regression tests across the distribution instead, so those effects become visible, and the same fit yields weights that can be carried into a TWAS. For each region the workflow fits quantile regression of the molecular phenotype on genotype across the quantile grid, combines the per-quantile p-values into a single QR p-value by the Cauchy combination method, and computes quantile TWAS weights. Covariates - genotype PCs, hidden factors and fixed covariates - are regressed out, and cis or trans windows are taken from a customized association-window file when one is given, otherwise a fixed cis-window around each region is used.","qtl_association_postprocessing":"A cis scan reports a p-value for every variant against every molecular phenotype, which is not yet a result: the variants within a gene's window are correlated and the genes are many, so raw p-values overstate significance twice over. The correction is hierarchical, in three steps: local adjustment of the p-values of all cis variants within each gene, global adjustment of the minimum adjusted p-value across genes, then selection of the xQTLs whose locally adjusted p-value falls below the threshold (the eigenMT-BH procedure of Huang et al. 2018, NAR* 46(22):e133). The survivors are packaged as a QtlSumStats object with a regional FDR table, and the intermediate TensorQTL files are reorganised into an archive folder for book-keeping or deletion.","reference_data_preparation":"Every study that uses this protocol should start from the same reference files: the same genome build, the same gene annotation, the same variant lists. When those differ between steps or between cohorts, the failures are quiet ones - coordinates that shift by a base, genes that exist in one annotation and not the other, meta-analyses that silently drop variants. This notebook downloads and standardises that reference set once, so the rest of the protocol reads from a consistent source. When to run it. Run this module once, before downstream workflows that require a reference genome, gene annotation, transcript annotation, or aligner index.","rss_analysis":"Fine-mapping asks which variants in a region are consistent with a causal effect rather than merely correlated with one. SuSiE-RSS works from available summary data, specifically per-variant z-scores and an LD matrix from a reference panel, and returns credible sets with posterior inclusion probabilities (Zou et al., 2022). Results depend on ancestry and allele alignment between the study and reference panel, so the workflow can screen suspicious variants with SLALOM or DENTIST and impute missing variants with RAISS. The LD reference must retain genotypes because these checks cannot use a precomputed correlation matrix alone.","rss_ld_sketch":"This module creates a compact LD reference from whole-genome sequencing genotypes. A random projection transforms the individual-by-variant genotype matrix into a smaller stochastic genotype matrix that preserves pairwise correlation structure approximately. SuSiE-RSS can then reconstruct an approximate LD matrix from the stored PLINK2 sketch without retaining the full genotype matrix. The sketch reduces storage while keeping the variant dimension required for regional fine-mapping.","sldsc_enrichment":"Heritability is not distributed evenly across the genome. This module tests whether a functional category, such as a chromatin state, regulatory-element set, or xQTL annotation, explains more heritability than expected from its SNP count. LD-score regression separates polygenic signal from confounding by relating association statistics to the amount of linked variation each SNP tags (Bulik-Sullivan et al., 2015). Stratified LD-score regression estimates a contribution for each annotation while conditioning on overlapping baseline annotations (Finucane et al., 2015).","snRNAseq_preprocessing":"Single-nuclei RNA-seq counts arrive with artefacts that would otherwise be read as biology: dying cells with high mitochondrial content, ambient RNA carried over from the suspension, and droplets holding two nuclei rather than one. Filtering those out, and then deciding what cell type each surviving nucleus is, has to happen before any per-cell-type analysis can start. Quality control runs through SCTK and Seurat: cells are dropped on mitochondrial percent, total counts (nUMI) and detected genes (nFeature), ambient RNA is removed with decontX, and doublets are removed with a user-selected method, scds by default. Cell types are then assigned by transferring labels from an annotated reference dataset onto the filtered object. Method reference: Hao et al., 2021.","splicing_calling":"This module converts STAR-aligned RNA-seq data into splicing phenotypes using two independent approaches. LeafCutter groups introns that share splice sites and reports each intron as a fraction of its cluster, which captures exon skipping and alternative splice-site usage without requiring predefined event labels (Li et al., 2018). Psichomics instead uses STAR junction counts and a splicing annotation to quantify named events such as skipped exons and alternative first or last exons (Agostinho et al., 2019). The leafcutterpreprocessing workflow stops after junction extraction when clustering will be performed elsewhere.","splicing_normalization":"Splicing measurements quantify how frequently alternative introns or transcript events are used across individuals. This module removes poorly measured events, adjusts the retained measurements for library and sample-level effects, and produces a stable splicing phenotype matrix. Normalization is required so an sQTL reflects genetic regulation of splice choice rather than differences in sequencing depth or event detectability. Method reference: Li et al., 2018.","twas_ctwas":"A TWAS scan tests each gene's genetically predicted expression against a trait, but a significant gene is not necessarily a causal one: nearby variants with direct effects on the trait, and the predicted expression of neighbouring genes, are correlated with the gene's own eQTLs and act as confounders. cTWAS addresses this by fine-mapping genes and variants jointly within a region, so a gene is credited only for signal that its expression explains beyond the surrounding variants and genes, and reports a posterior inclusion probability rather than a p-value (Zhao et al., 2024). finemapCtwasRegions) and offers four workflows:"},METH={"phenotype_imputation":{"kind":"choose","purpose":"Fill missing values in a molecular phenotype matrix. Missingness is common in proteomics and metabolomics, and most downstream QTL tools cannot accept gaps.","how":"Start with gEBMF \u2014 the protocol's recommended default. Switch only for a specific reason: LOD if missingness is caused by an assay detection limit (low-abundance proteins or metabolites), the tree methods if you suspect strong non-linear structure between features, or mean only as a baseline to compare against.","prereq":[["bed_filter_na","Filter features by missingness rate before imputing (optional)."]],"opts":[["gEBMF","gEBMF \u2014 grouped Empirical Bayes MF",true,"Fits factors within row groups (by chromosome), borrowing structure shared across features in the same group. The protocol's recommended default.","moderate"],["EBMF","EBMF \u2014 Empirical Bayes MF",false,"Decomposes the matrix into latent factors with adaptive shrinkage, then reconstructs it. Captures global low-rank structure across all samples and features.","moderate"],["missforest","missForest",false,"Non-parametric iterative random-forest imputation; each feature is predicted from the others until values stabilise. Handles non-linear relationships but is computationally heavier.","heavy"],["missxgboost","missXGBoost",false,"Same iterative scheme with gradient-boosted trees instead of forests. Often faster and more accurate than missForest on large matrices.","moderate"],["knn","KNN \u2014 k-nearest neighbours",false,"Fills a gap with a distance-weighted average from the k most similar samples. Simple and fast; works well when samples cluster into similar profiles.","light"],["soft","SoftImpute",false,"Matrix completion by iterative soft-thresholded SVD. A good linear baseline for structured data. Note: 450K methylation took ~15 min and ~34 GB RSS.","heavy"],["mean","Mean imputation",false,"Replaces each gap with the feature mean. Fastest, but ignores all correlation structure. Use as a baseline, not a final choice.","light"],["lod","LOD \u2014 limit of detection",false,"Replaces gaps with a low constant derived from the smallest observed values. The right choice when missingness means 'below the assay's detection threshold'.","light"]],"scenarios":[["Your missingness is not random","If values are missing because they fell below an assay detection limit, the factor and tree methods will impute implausibly high values. Use LOD instead."],["Fewer samples than requested factors","--num_factor for EBMF/gEBMF must be smaller than your sample count. The protocol's toy set has 60 samples and uses --num_factor 30."],["You disabled QC","Leave QC enabled (do not pass --no-qc-prior-to-impute) so the QC matrix is available to every method."]]},"covariate_hidden_factor":{"kind":"choose","purpose":"Estimate unmeasured confounders (batch, cell composition, technical drift) from the phenotype matrix itself, after regressing out the covariates you already know about. Omitting these inflates false positives in the QTL scan.","how":"Marchenko-Pastur PCA is what the protocol uses for its main analyses \u2014 start there. Choose PEER if you need comparability with GTEx or other PEER-based studies. The other two differ only in how the number of factors is chosen, and cost more compute for it.","opts":[["Marchenko_PC","PCA + Marchenko-Pastur",true,"Regresses phenotype on known covariates, runs PCA on the residuals, and keeps the components whose eigenvalues exceed the Marchenko-Pastur random-matrix noise threshold. Used for the protocol's main analyses.","light"],["PEER","PEER (GTEx-style)",false,"Probabilistic MOFA-based factor model. Factor count follows GTEx recommendations by sample size, or fix it with --N. Pick this for comparability with GTEx.","moderate"],["PCA","PCA + Buja & Eyuboglu permutation",false,"Same PCA workflow, but factor count is chosen by permutation (--choose_k_method Buja_Eyuboglu, B=100) rather than the analytic threshold. Slower than Marchenko-Pastur for a similar answer.","moderate"],["BiCV","BiCV factor analysis (APEX)",false,"Chooses factor count by bi-cross-validation using the external APEX binary. Factor count follows GTEx recommendations. Note the APEX command options differ from APEX's own documentation.","moderate"]]},"gene_annotation":{"kind":"choose","purpose":"Attach genomic coordinates (chr/start/end) to every phenotype feature so the QTL scan knows where each feature sits and which variants are in cis.","how":"This choice is decided by the phenotype you are mapping, not by preference \u2014 the matching option is preselected below. Only the biomaRt route is a genuine alternative, for when you have no local GTF.","auto":{"bulk":"annotate_coord","sn":"annotate_coord","splice":"annotate_leafcutter_isoforms","meth":"annotate_coord","apa":"annotate_coord"},"opts":[["annotate_coord","Gene expression or protein matrix",true,"Matches each ENSEMBL gene ID against the GTF for coordinates. For proteins whose IDs look like gene_id|UniProt, pass --molecular-trait-type protein.","light"],["map_leafcutter_cluster_to_gene","LeafCutter clusters to genes",false,"Assigns LeafCutter intron clusters to genes. Run this before annotating LeafCutter isoforms. Default --map-stra site maps introns by site.","light"],["annotate_leafcutter_isoforms","LeafCutter isoforms",false,"Turns raw LeafCutter intron-excision output into a coordinate-annotated phenotype BED plus a phenotype-group file. Builds on the cluster-to-gene mapping.","light"],["annotate_psichomics_isoforms","Psichomics isoforms",false,"For psichomics quantifications, where each event ID ends in _<gene_id>.","light"],["annotate_coord_biomart","biomaRt web service",false,"Fetches coordinates from Ensembl over the network instead of a local GTF. Requires a gene_ID column and a reachable Ensembl release.","light"]],"scenarios":[["No local GTF, or you need a specific Ensembl release","Use biomaRt and set --ensembl-version. It depends on network access, so it is not reproducible on an air-gapped cluster."],["You are mapping splicing QTLs","Run clusters-to-genes first, then LeafCutter isoforms. The second depends on the first."]]},"mnm_regression":{"kind":"choose","purpose":"High-dimensional regression over a locus. A single fit yields two products the protocol uses downstream: fine-mapping results (credible sets, PIPs) and TWAS prediction weights.","how":"Several contexts or cell types \u2192 mvSuSiE (or mr.mash). Several genes sharing a locus \u2192 multi-gene. Epigenomic phenotypes with position along the genome \u2192 fSuSiE.","prereq":[["qtl_dataset_construct","Assemble the per-region dataset the models consume."]],"opts":[["susie_twas","SuSiE \u2014 univariate",true,"Univariate fine-mapping per phenotype. Also the route that produces TWAS prediction weights.","moderate"],["mnm","mvSuSiE \u2014 multivariate",false,"Multivariate across contexts, via mvSuSiE or mr.mash. Uses the mixture prior from MASH, so run MASH first. Also produces multi-context ensemble TWAS weights.","heavy"],["mnm_genes","Multi-gene",false,"Fine-maps several genes sharing a locus jointly.","heavy"],["fsusie","fSuSiE \u2014 functional",false,"Functional regression for epigenomic QTLs.","heavy"],["mvfsusie","mvfSuSiE \u2014 work in progress",false,"Multivariate functional regression; WIP placeholder.","heavy"]]},"mixture_prior":{"kind":"staged","purpose":"Build the data-driven prior (a set of covariance matrices) that MASH and mvSuSiE use to describe how QTL effects are shared across contexts.","how":"Candidate patterns describe biological effect sharing. Choose one method to estimate residual correlation, then one fitting engine to estimate the frequency of each sharing pattern. Shared preparation and diagnostics remain part of the workflow.","stages":[["Propose patterns of biological sharing","all",[["flash","FLASH factor analysis","~5-15 min."],["flash_nonneg","FLASH, non-negative constraint",""],["pca","Covariances from principal components",""],["canonical","Canonical single-condition and shared covariances",""]]],["Separate correlated noise from shared effects","one",[["vhat_identity","identity \u2014 simplest","Assumes residual errors are independent across conditions. Use it as a simple baseline, or when the conditions do not share samples or technical noise."],["vhat_simple","simple \u2014 from null z-scores","Estimates one residual-correlation matrix from null z-scores. This is the practical choice when the same samples or technical effects create correlation across conditions."],["vhat_mle","mle","Refines residual correlation by maximum likelihood using an initial prior. Use it for a second-pass analysis when the initial mixture fit is already available."],["vhat_corshrink_xcondition","corshrink, per condition","Shrinks correlations estimated from null signals. Use it when cross-condition residual correlations are expected but raw correlation estimates may be unstable."],["vhat_simple_specific","simple, per condition","Builds a positive-definite covariance estimate from null z-scores. Use it when you want a direct empirical estimate without adaptive correlation shrinkage."]]],["Estimate how often each sharing pattern occurs","one",[["ed_bovy","Extreme Deconvolution","Fits the sharing-pattern mixture with mashr Extreme Deconvolution. This is the protocol's default and the best starting point for most analyses."],["ud","Ultimate Deconvolution (udr)","Uses the udr Extreme Deconvolution update. It is an experimental alternative with known numerical issues, so compare its fit carefully with the default."],["ud_unconstrained","Ultimate Deconvolution, unconstrained","Uses the unconstrained udr TED update. Choose it only for z-scale data whose observations meet the method's independence assumptions."]]],["Inspect the learned sharing patterns","all",[["plot_U","Plot the estimated covariance patterns",""]]]],"scenarios":[["Choosing the effect model","--effect-model is EE (exchangeable effects) or EZ (exchangeable z-scores). It must match what you use downstream."]]},"RNA_calling":{"kind":"sequence","purpose":"Turn raw FASTQ into gene- and transcript-level expression matrices.","steps":[["fastqc","QC before alignment",false,""],["fastp_trim_adaptor","Trim adaptors with fastp",true,""],["STAR_align","Align reads with STAR",false,""],["rnaseqc_call","Gene-level expression with RNA-SeQC",false,""],["rsem_call","Transcript-level expression with RSEM",false,""]]},"VCF_QC":{"kind":"sequence","purpose":"Filter and annotate raw variant calls before any genotype work.","steps":[["rename_chrs","Rename chromosomes",true,"Use only if your contig naming disagrees with the reference."],["dbsnp_annotate","Annotate against dbSNP",false,""],["qc","Variant-level quality control",false,"The default path assumes DP/GQ/AD tags are present."]],"scenarios":[["Your VCF has no DP/GQ/AD tags","The notebook documents a separate QC path for data lacking these tags."]]},"GWAS_QC":{"kind":"sequence","purpose":"Sample- and variant-level QC, relatedness, and preparation of an unrelated subset for PCA.","steps":[["qc_no_prune","Basic QC, rare and common variants",false,""],["genotype_phenotype_sample_overlap","Match samples with the phenotype",false,""],["king","Kinship QC (KING)",false,"Splits samples into related and unrelated sets."],["qc","Prepare unrelated individuals and prune for PCA",false,""]]},"genotype_formatting":{"kind":"sequence","purpose":"Convert and partition genotypes into the layout the QTL scan expects.","steps":[["vcf_to_plink","VCF to PLINK",false,""],["merge_plink","Merge PLINK files",false,""],["genotype_by_chrom","Partition by chromosome",false,""]]},"splicing_normalization":{"kind":"sequence","purpose":"QC, impute and normalise LeafCutter intron-usage counts into a BED-ready phenotype table.","steps":[["leafcutter_norm","QC, then normalise",false,""],["leafcutter_qqnorm","Quantile normalisation",false,""],["psichomics_norm","Psichomics route",true,"Use instead of the LeafCutter steps if your upstream tool was psichomics."]],"scenarios":[["Use the default mean-imputation path","Run leafcutter_norm without --no_norm. It will filter features, mean-impute the remaining missing values, and quantile-normalize the matrix in one workflow, so the separate leafcutter_qqnorm command is not needed."]]},"twas_ctwas":{"kind":"sequence","purpose":"Test each molecular context for association with a GWAS trait, then jointly fine-map genes and SNPs to separate directly causal signals from correlated ones.","steps":[["twas","TWAS association test",false,"Keeps only genes whose cross-validated model reaches adjusted r\u00b2 \u2265 0.01 and p < 0.05; the rest are dropped as non-imputable."],["ctwas","cTWAS joint fine-mapping",false,""],["quantile_twas","Quantile TWAS",true,"Tests genetic efects across quantiles of the trait distribution rather than only its mean."]],"scenarios":[["Prerequisites","Needs TWAS weights from mnm_regression (the susie_twas mode), plus GWAS summary statistics and an LD matrix for the region."]]},"pseudobulk_expression_aggregation_QC_norm":{"kind":"choose","purpose":"Aggregate single-cell counts into pseudobulk matrices, then QC and normalise them.","how":"Pick the aggregation scheme that matches how your cells are labelled.","opts":[["seuratagg","Aggregate by Seurat cluster",true,"Aggregates using the cluster labels already in the Seurat object.","moderate"],["subtypeagg","Aggregate by annotated subtype",false,"Uses a curated cell-subtype annotation rather than raw clusters.","moderate"],["neuronsagg","Neuron-focused aggregation",false,"Restricts aggregation to neuronal populations.","moderate"]]},"SuSiE_enloc":{"kind":"sequence","purpose":"Estimate global enrichment between xQTL and GWAS signals, then colocalise the overlapping regions. Pairwise: one molecular phenotype against one GWAS trait.","steps":[["xqtl_gwas_enrichment","Estimate global xQTL-GWAS enrichment",false,""],["susie_coloc","Colocalise the overlapping regions",false,""]],"scenarios":[["Prerequisites","Needs xQTL fine-mapping from mnm_regression (susie_twas) and GWAS fine-mapping from rss_analysis (susie_rss). It handles the case where the xQTL and GWAS credible sets fall in different regions."]]},"colocboost":{"kind":"sequence","purpose":"Integration, not fine-mapping. Colocalises signals across many phenotypes or molecular contexts — and optionally against a GWAS trait — while allowing multiple causal variants per region. Scales to hundreds of phenotypes.","steps":[["colocboost","Multi-trait colocalisation",false,""]],"scenarios":[["Prerequisites","Needs .susie.rds fine-mapping output from mnm_regression or rss_analysis, and individual-level xQTL data from one cohort (several phenotypes, shared genotype)."],["Including GWAS summary statistics","Optional. If you do include them, an LD reference is then required."]]},"intact":{"kind":"sequence","purpose":"Combine TWAS evidence and colocalisation evidence into a single gene-level posterior probability, rather than reading the two separately.","steps":[["intact","Integrate TWAS and coloc evidence",false,""]],"scenarios":[["Prerequisites, and a caveat","Expects PTWAS and fastenloc output. Note that the fastenloc notebooks are retired to graveyard/ in this repository, so you would need to produce that input another way."]]},"eoo_enrichment":{"kind":"sequence","purpose":"Ask whether your significant variants fall inside a genomic annotation more often than chance. Reports an odds ratio per annotation with block-jackknife standard errors, leaving out one chromosome at a time.","steps":[["enrichment","Block-jackknife overlap enrichment",false,""]]},"gsea":{"kind":"sequence","purpose":"Ask which biological pathways and GO categories are over-represented in a set of genes. Works on gene groups, not variants, and compares several groups at once.","steps":[["pathway_analysis","KEGG and GO over-representation",false,"ENSEMBL IDs are converted to ENTREZ; genes without a mapping are dropped."]]},"gregor":{"kind":"sequence","purpose":"Ask whether trait-associated variants are enriched in experimentally annotated regulatory features, against a negative set matched on MAF, LD proxy, distance to TSS and gene density.","steps":[["gregor_conf","Build the GREGOR configuration",false,""],["gregor","Run enrichment",false,""],["gregor_fisher_plot","Fisher test and plot",true,""]],"scenarios":[["Reading the output","The notebook warns that some GREGOR p-values come back greater than 1, and that the p-value is less informative than the effect size here."]]},"sldsc_enrichment":{"kind":"sequence","purpose":"Ask what share of trait heritability is attributable to an annotation category, using stratified LD score regression.","steps":[["munge_sumstats_polyfun","Munge summary statistics",false,"Run before the rest."],["make_annotation_files_ldscore","Build annotation LD scores",false,""],["get_heritability","Estimate heritability and tau",false,""],["postprocess","Post-process",true,""],["meta_subset","Random-effects meta-analysis across traits",true,""]],"requirements":[["PolyFun reference resources","Steps 1 and 2 require an external PolyFun installation and a matching precomputed reference panel containing baseline-LD annotations, LD weights, allele frequencies and PLINK files. These resources are not included with the toy fixtures. Use these commands after supplying the external resources; the SuSiE-RSS workflow is the runnable fixture example."]]}},CMDLIB={"GRM":[{"wf":"grm","cmd":"sos run pipeline/GRM.ipynb grm --cwd output/grm_uf --genoFile king workflow separates related and unrelated samples, qc applies filtering and LD pruning, qcnoprune applies filtering without pruning, and genotypephenotypesampleoverlap retains samples represented in both the genotype and molecular phenotype data. The appropriate combination depends on cohort relatedness and on whether a pruned variant list already exists. Method reference: Manichaikul et al., 2010, Chang et al., 2015.","METAL":"This notebook runs cross-cohort meta-analysis of summary statistics with METAL on the toy protocol_example dataset. METAL is a command-line tool that takes a script documenting the input summary-statistic files, the field mapping for each, and the analysis settings. Meta-analysis here is essentially a weighted sum of Z-scores, so the same set of variants must be present across the input cohorts; the input is a list of paths to the per-cohort summary statistics to analyse together. Method reference: Willer et al., 2010.","PCA":"Population structure is the classic confounder in genetic association: if ancestry correlates with both genotype and phenotype, unadjusted tests return associations that are real but not causal. The remedy is to compute principal components of the genotype matrix and carry the leading ones as covariates. Components are computed on unrelated individuals and the remaining related samples are projected back into that space, so relatives cannot distort the axes but every sample still gets coordinates. The sequence is: remove related individuals, LD-prune the variants, run PCA on the unrelated set, then exclude PCA-space outliers. Relatedness estimation and sample QC happen upstream in GWAS_QC.ipynb. Method reference: Chang et al., 2015.","RNA_calling":"RNA-seq reads record the transcripts present in each sample. This module aligns reads to the reference genome and quantifies gene-level expression, producing the count and abundance matrices that define the molecular phenotype. Accurate alignment and consistent gene annotation are required because mapping errors can create apparent expression differences that are unrelated to biology. Method reference: Dobin et al., 2013, Li & Dewey, 2011, Chen et al., 2018, Graubert et al., 2021.","SuSiE_enloc":"This workflow processes fine-mapping results for xQTL, generated by susietwas in the mnmregression.ipynb notebook for cis xQTL, and GWAS fine-mapping results produced by susierss in the rssanalysis.ipynb notebook. It is designed to perform enrichment and colocalization analysis, particularly when fine-mapping results originate from different regions in the case of cis-xQTL and GWAS. The pipeline is capable to integrate and analyze data across these distinct regions. Originally tailored for cis-xQTL and GWAS integration, this pipeline can be applied to other pairwise integrations. An example of such application is in trans analysis, where the fine-mapped regions might be identical between trans-xQTL and GWAS, representing a special case of this broader implementation. Method reference: Wen et al., 2017.","TensorQTL":"This module tests whether inherited variants are associated with molecular phenotypes across individuals. Cis analysis focuses on variants near each feature, where regulatory effects are most interpretable, while trans analysis searches for distal effects. Covariates account for ancestry, technical variation, and other measured sources of heterogeneity. GPU acceleration makes the same association model practical across large numbers of variants and phenotypes (Taylor-Weiner et al., 2019).","VCF_QC":"Variant quality control removes genotypes that cannot support reliable regulatory mapping. The workflows normalize variant representation, restrict analysis to the intended samples and regions, remove poorly measured or uninformative variants, and harmonize identifiers before conversion to analysis-ready formats. These checks reduce false associations caused by missingness, allele inconsistencies, duplicate records, or genome-build mismatches.","apa_calling":"Most genes have more than one polyadenylation site, and which one is used shifts the length of the 3' UTR - changing which regulatory elements survive in the transcript. Treating a gene as a single expression value hides that. This step quantifies alternative polyadenylation from RNA-seq coverage with DaPars2, giving a per-sample PDUI (percentage of distal polyA site usage) that can be scanned for QTLs like any other molecular phenotype. The workflows run in order: UTRreference builds the annotation DaPars2 needs, bam2tools converts alignments to coverage, APAconfig writes the configuration file and APAmain runs the quantification.","apa_impute":"Alternative polyadenylation is quantified as PDUI, the fraction of transcripts using the distal poly(A) site. DaPars leaves gaps wherever a gene had too little coverage in a sample to call that fraction, and downstream models need a complete matrix. This step imputes those gaps with the impute package and quantile-normalises the filled matrix so samples are on a common scale. A second, optional workflow renames the sample columns from DaPars internal IDs to the names used elsewhere in the study.","bulk_expression_QC":"Sample-level quality control asks whether each RNA-seq profile represents the intended biological specimen. The module compares expression patterns, sample annotations, and technical metrics to identify swaps, outliers, or globally degraded libraries. Removing problematic samples before association testing prevents a small number of abnormal profiles from driving apparent genetic effects.","bulk_expression_normalization":"Lowly expressed genes provide little reliable information for mapping genetic effects and can add noise to association testing. This step retains genes that are consistently detected across individuals, then normalizes their expression levels so differences in sequencing depth and RNA composition do not obscure biological variation. The resulting expression matrix provides stable molecular phenotypes for downstream cis-eQTL analysis.","colocboost":"Two signals at the same locus - a QTL and a GWAS hit, or QTLs in two cell types - may share a causal variant or merely sit in the same LD block. Colocalization tries to tell those apart. Classical pairwise methods assume one causal variant per trait and compare traits two at a time, which loses power when a region has several independent signals or when the shared signal is weak in any single pair. ColocBoost treats it as a multi-task problem instead: a gradient boosting framework that couples traits as it selects causal variants, so evidence that is weak in isolation can still support a shared signal across many contexts. It scales to hundreds of traits and allows multiple causal variants per region (Cao et al., 2025).","covariate_formatting":"The association scan takes a single covariate file, but covariates arrive from several places: batch and demographic variables you supply, genotype principal components from PCA, and hidden factors estimated by covariatehiddenfactor. This step merges them, reconciles sample identifiers across the sources, and writes the combined matrix in the orientation the scan expects. When to run it. After PCA and hidden-factor estimation, immediately before QTL association testing.","covariate_hidden_factor":"Unmeasured differences in batch, cell composition, RNA quality, or other latent processes can induce correlation among molecular phenotypes. This module estimates hidden factors from the phenotype matrix after accounting for known covariates. Including these factors in the QTL model reduces confounding while preserving interpretable genetic variation. PEER provides a probabilistic factor model, while the PCA workflows estimate the number of supported components from the data (Stegle et al., 2012).","ems_prediction":"Create a tab-separated file with variant identifiers: `` variant_id 2:12345:A:T 2:67890:G:C 2:11111:T:A ``","ems_training":"Most disease-associated GWAS variants lie in non-coding regions of the genome, where they likely modulate gene expression. However, bulk-tissue eQTL studies fail to explain the majority of these variants, a phenomenon termed \"missing regulation\" (Connally et al., 2022). This gap exists because there are systematic differences between variants identified in eQTL studies versus disease GWAS (Mostafavi et al., 2022):","eoo_enrichment":"A variant set that overlaps an annotation more often than chance would predict is evidence that the annotation marks functional sequence. Counting the overlap is easy; putting an error bar on it is not, because variants are correlated along the genome and so cannot be resampled independently. This module computes an odds ratio and an enrichment statistic for each annotation, then leaves out one chromosome at a time and recomputes, using the spread across those 22 leave-one-out estimates as a block-jackknife standard error. Blocking by chromosome keeps correlated variants together rather than splitting them across resamples. When to run it. Run this module after chromosome-level enrichment inputs are available when a combined enrichment estimate and block-jackknife standard error are needed.","gene_annotation":"Molecular phenotype matrices arrive keyed only by a feature identifier, such as an ENSEMBL gene ID, a UniProt accession, or a LeafCutter intron-cluster label, but every downstream QTL step needs a genomic position to define a cis window. This module attaches those coordinates, turning a plain matrix into a coordinate-sorted, bgzipped and tabix-indexed bed.gz file. Coordinates come from a collapsed gene-model GTF, following the GTEx pipeline convention, so the annotation used here matches the one used to build the GTF in the first place. Feature IDs that the GTF does not contain are dropped rather than guessed at, which is why the row count of the output can be lower than that of the input.","generalized_TADB":"Analyses that work locus by locus need a definition of \"locus\". Using a fixed window around each gene is simple but arbitrary: regulatory contacts do not respect a fixed distance, and two genes in the same regulatory neighbourhood get analysed as if independent. Topologically associating domain boundaries give a definition grounded in chromatin architecture instead, and this step generates the boundary files that downstream region-based analyses consume. When to run it. Run this module before region-based association or fine-mapping when TAD-defined regions are preferred to fixed-width cis windows.","genotype_formatting":"Nothing here changes the genotypes; it changes how they are packaged. Tools in the protocol disagree about format - some want PLINK, some want VCF - and the association and fine-mapping steps run per region or per chromosome, so the genotype data has to be split the same way to be processed in parallel. These workflows do those conversions and splits, plus the LD matrix computation per region that summary-statistic fine-mapping needs. When to run it. Run the relevant workflow after genotype quality control and before association scanning, LD calculation, or fine-mapping that requires the corresponding genotype layout. Method reference: Chang et al., 2015.","gregor":"A set of trait-associated variants is more interpretable if you can say what kind of sequence they fall in. Enrichment testing asks whether they overlap a class of genomic feature - an annotation, a chromatin state, a set of regulatory elements - more often than chance allows, where chance has to account for the fact that variants are not exchangeable: they differ in minor allele frequency, in the number of LD proxies they carry, and in distance to the nearest gene. GREGOR builds matched control variants on exactly those properties - minor allele frequency, LD proxy count, distance to the nearest TSS, and local gene density - so the comparison is fair. Method reference: Schmidt et al., 2015.","gsea":"A list of genes is hard to interpret on its own. Over-representation testing asks whether a group contains more members of some pathway or ontology term than chance would give, turning a list of identifiers into statements about biology. This module tests each group against the KEGG database and all three Gene Ontology branches using clusterProfiler. Input ENSEMBL gene IDs are first converted to ENTREZ IDs via org.Hs.eg.db; genes without a valid ENTREZ mapping are dropped, and group associations are preserved through the conversion. KEGG over-representation then runs through enrichKEGG() and GO through enrichGO() for Biological Process, Cellular Component and Molecular Function, both applying a hypergeometric test with Benjamini-Hochberg FDR correction. Method reference: Wu et al., 2021.","intact":"INTACT combines evidence from PTWAS and fastENLOC for the same genes. It converts TWAS z-scores into Bayes factors across a grid of prior effect-size values, averages those Bayes factors, transforms the gene-level colocalization probability into a prior probability, and returns a posterior probability that integrates both sources of evidence. Run it after PTWAS and fastENLOC have been completed on a matched gene set.","ld_prune_reference":"Many downstream methods assume the variants they are handed are approximately independent. A reference genotype panel is not: neighbouring variants are correlated through linkage disequilibrium, so a raw variant list counts the same signal several times over. This step runs PLINK LD clumping (--indep-pairwise) within each LD block and then merges the survivors into a single list, which is the form mashr and similar analyses expect. Working one block at a time keeps each clumping job small and lets the blocks run in parallel. The merge step afterwards also rewrites the variant IDs into one consistent format. Synthetic-data note. The minimal working example runs on a small synthetic chr22 PLINK panel, protocolexample.ldgenotype.chr22, of 60 samples and roughly 18k variants, built from the toy genotype VCF. It is for demonstration only and is not real individual-level data.","mash_fit":"Effects estimated separately in each condition are noisy, and analysing them one condition at a time ignores that most effects are shared. MASH fits a mixture of multivariate normal distributions to the effect estimates, learning from the data which patterns of sharing actually occur - which conditions move together, and how strongly - so that individual estimates can later be shrunk towards those patterns rather than towards zero. This notebook fits the model. The data-driven prior matrices come from mixtureprior, and applying the fitted model to compute posterior estimates is mashposterior. By this point the input data have already been converted from the original association summary statistics into the MASH-format object written by mash_preprocessing. Method reference: Urbut et al., 2019.","mash_posterior":"For each input chunk (a list of matrices bhat/sbhat/Z), the posterior workflow loads the MASH model and calls mashcomputeposteriormatrices. Additional workflows compute posterior contrasts between conditions and feature-level scores (meta, fine-mapped, n-significant, and p-value pairs) from the contrast results. Fitting the mixture model and applying it are separate jobs. mashfit learns which patterns of sharing exist across conditions; this notebook applies that fitted model to each chunk of effects, shrinking noisy estimates towards the patterns the data support. Effects that look condition-specific because of noise get pulled towards the shared pattern, and genuinely specific ones do not. Method reference: Urbut et al., 2019.","mash_preprocessing":"This module constructs the three effect matrices used to learn cross-condition sharing patterns in MASH. The strong-effect matrix contains the top fine-mapped locus from each condition, the null matrix contains independent variants with small z-scores, and the random matrix samples variants from the supplied independent-variant list. Together, these matrices provide signal-rich, null, and background examples for estimating multivariate effect patterns. Run this module after genome-wide SuSiE fine-mapping results are available. Method reference: Urbut et al., 2019.","methylation_calling":"This module quantifies array-based DNA methylation using either sesame or minfi, with sesame recommended for the protocol. Both methods remove probes affected by SNPs or cross-reactivity, assess sample and probe quality, and correct assay bias before producing methylation measurements for downstream QTL analysis. The minfi workflow uses dropLociWithSnps with manual filtering, detectionP summaries, and preprocessQuantile. The sesame workflow combines quality masking (Q), sesameQC_calcStats with detection and frac_dt metrics, nonlinear dye-bias correction (D), pOOBAH detection masking (P), and noob background subtraction (B). Method reference: Zhou et al., 2018.","mixture_prior":"Genetic effects can be specific to one tissue or cell type, shared across several contexts, or similar across all contexts. MASH represents these possibilities as a mixture of covariance patterns. This module learns candidate sharing patterns, separates correlated measurement error from true effect sharing, and estimates how frequently each pattern occurs. The resulting MASH mixture prior allows downstream models to borrow information across contexts without assuming that every effect is shared (Urbut et al., 2019).","mnm_regression":"An association scan tells you a region matters; it does not tell you which variant in it is responsible, because variants in linkage disequilibrium carry nearly the same signal. SuSiE reframes the question as variable selection: it fits a sum of single effects and returns credible sets - small groups of variants, each likely to contain one causal variant - together with posterior inclusion probabilities (Wang et al., 2020). When the same locus is measured across several contexts - tissues, cell types, conditions - fine-mapping each separately throws away the shared structure. mvSuSiE learns the patterns of sharing from the data and uses them to sharpen credible sets (Zou et al., 2026).","phenotype_formatting":"Association testing and fine-mapping run per chromosome or per region, so the phenotype matrix has to be partitioned the same way before that work can be parallelised. These workflows split a phenotype BED by chromosome or by region, annotate features against TAD boundaries when region-based analysis is wanted, and accept GCT-format input as well as BED. Two further workflows trim inputs rather than split them: one subsets BAM files by coordinate, the other drops samples from a GCT matrix. The pipeline's author has flagged it as needing improvement, so treat the interface as unstable and re-check -h before relying on any option. When to run it. After phenotype QC, normalisation and imputation, and before covariate preprocessing and the association scan.","phenotype_imputation":"Missing molecular measurements can arise when a feature falls below detection or is measured unreliably in a subset of samples. This module reconstructs missing values so downstream models can use a complete phenotype matrix. Factor-based methods borrow shared structure across features, nearest-neighbour and tree methods use relationships among samples, and limit-of-detection imputation is appropriate when missingness represents low abundance (Qi et al., 2023).","pseudobulk_preprocessing":"This module prepares single-nucleus RNA-seq or ATAC-seq data for sample-level QTL analysis. It aggregates per-nucleus measurements into a pseudobulk count matrix for each cell type, harmonizes individual and sample identifiers across metadata and count matrices, then filters and normalizes the data before regressing technical covariates. The resulting residual phenotype matrix is ready for phenotype formatting and pseudobulk QTL analysis. Method reference: Hao et al., 2021.","qr_and_twas":"Standard QTL mapping models the mean: it asks whether genotype shifts average expression. That misses variants whose effect is confined to part of the distribution - acting only in highly expressing samples, or changing spread rather than centre. Quantile regression tests across the distribution instead, so those effects become visible, and the same fit yields weights that can be carried into a TWAS. For each region the workflow fits quantile regression of the molecular phenotype on genotype across the quantile grid, combines the per-quantile p-values into a single QR p-value by the Cauchy combination method, and computes quantile TWAS weights. Covariates - genotype PCs, hidden factors and fixed covariates - are regressed out, and cis or trans windows are taken from a customized association-window file when one is given, otherwise a fixed cis-window around each region is used.","qtl_association_postprocessing":"A cis scan reports a p-value for every variant against every molecular phenotype, which is not yet a result: the variants within a gene's window are correlated and the genes are many, so raw p-values overstate significance twice over. The correction is hierarchical, in three steps: local adjustment of the p-values of all cis variants within each gene, global adjustment of the minimum adjusted p-value across genes, then selection of the xQTLs whose locally adjusted p-value falls below the threshold (the eigenMT-BH procedure of Huang et al. 2018, NAR* 46(22):e133). The survivors are packaged as a QtlSumStats object with a regional FDR table, and the intermediate TensorQTL files are reorganised into an archive folder for book-keeping or deletion.","reference_data_preparation":"Every study that uses this protocol should start from the same reference files: the same genome build, the same gene annotation, the same variant lists. When those differ between steps or between cohorts, the failures are quiet ones - coordinates that shift by a base, genes that exist in one annotation and not the other, meta-analyses that silently drop variants. This notebook downloads and standardises that reference set once, so the rest of the protocol reads from a consistent source. When to run it. Run this module once, before downstream workflows that require a reference genome, gene annotation, transcript annotation, or aligner index.","rss_analysis":"Fine-mapping asks which variants in a region are consistent with a causal effect rather than merely correlated with one. SuSiE-RSS works from available summary data, specifically per-variant z-scores and an LD matrix from a reference panel, and returns credible sets with posterior inclusion probabilities (Zou et al., 2022). Results depend on ancestry and allele alignment between the study and reference panel, so the workflow can screen suspicious variants with SLALOM or DENTIST and impute missing variants with RAISS. The LD reference must retain genotypes because these checks cannot use a precomputed correlation matrix alone.","rss_ld_sketch":"This module creates a compact LD reference from whole-genome sequencing genotypes. A random projection transforms the individual-by-variant genotype matrix into a smaller stochastic genotype matrix that preserves pairwise correlation structure approximately. SuSiE-RSS can then reconstruct an approximate LD matrix from the stored PLINK2 sketch without retaining the full genotype matrix. The sketch reduces storage while keeping the variant dimension required for regional fine-mapping.","sldsc_enrichment":"Heritability is not distributed evenly across the genome. This module tests whether a functional category, such as a chromatin state, regulatory-element set, or xQTL annotation, explains more heritability than expected from its SNP count. LD-score regression separates polygenic signal from confounding by relating association statistics to the amount of linked variation each SNP tags (Bulik-Sullivan et al., 2015). Stratified LD-score regression estimates a contribution for each annotation while conditioning on overlapping baseline annotations (Finucane et al., 2015).","snRNAseq_preprocessing":"Single-nuclei RNA-seq counts arrive with artefacts that would otherwise be read as biology: dying cells with high mitochondrial content, ambient RNA carried over from the suspension, and droplets holding two nuclei rather than one. Filtering those out, and then deciding what cell type each surviving nucleus is, has to happen before any per-cell-type analysis can start. Quality control runs through SCTK and Seurat: cells are dropped on mitochondrial percent, total counts (nUMI) and detected genes (nFeature), ambient RNA is removed with decontX, and doublets are removed with a user-selected method, scds by default. Cell types are then assigned by transferring labels from an annotated reference dataset onto the filtered object. Method reference: Hao et al., 2021.","splicing_calling":"This module converts STAR-aligned RNA-seq data into splicing phenotypes using two independent approaches. LeafCutter groups introns that share splice sites and reports each intron as a fraction of its cluster, which captures exon skipping and alternative splice-site usage without requiring predefined event labels (Li et al., 2018). The leafcutterpreprocessing workflow stops after junction extraction when clustering will be performed elsewhere.","splicing_normalization":"Splicing measurements quantify how frequently alternative introns or transcript events are used across individuals. This module removes poorly measured events, adjusts the retained measurements for library and sample-level effects, and produces a stable splicing phenotype matrix. Normalization is required so an sQTL reflects genetic regulation of splice choice rather than differences in sequencing depth or event detectability. Method reference: Li et al., 2018.","twas_ctwas":"A TWAS scan tests each gene's genetically predicted expression against a trait, but a significant gene is not necessarily a causal one: nearby variants with direct effects on the trait, and the predicted expression of neighbouring genes, are correlated with the gene's own eQTLs and act as confounders. cTWAS addresses this by fine-mapping genes and variants jointly within a region, so a gene is credited only for signal that its expression explains beyond the surrounding variants and genes, and reports a posterior inclusion probability rather than a p-value (Zhao et al., 2024). finemapCtwasRegions) and offers four workflows:"},METH={"phenotype_imputation":{"kind":"choose","purpose":"Fill missing values in a molecular phenotype matrix. Missingness is common in proteomics and metabolomics, and most downstream QTL tools cannot accept gaps.","how":"Start with gEBMF \u2014 the protocol's recommended default. Switch only for a specific reason: LOD if missingness is caused by an assay detection limit (low-abundance proteins or metabolites), the tree methods if you suspect strong non-linear structure between features, or mean only as a baseline to compare against.","prereq":[["bed_filter_na","Filter features by missingness rate before imputing (optional)."]],"opts":[["gEBMF","gEBMF \u2014 grouped Empirical Bayes MF",true,"Fits factors within row groups (by chromosome), borrowing structure shared across features in the same group. The protocol's recommended default.","moderate"],["EBMF","EBMF \u2014 Empirical Bayes MF",false,"Decomposes the matrix into latent factors with adaptive shrinkage, then reconstructs it. Captures global low-rank structure across all samples and features.","moderate"],["missforest","missForest",false,"Non-parametric iterative random-forest imputation; each feature is predicted from the others until values stabilise. Handles non-linear relationships but is computationally heavier.","heavy"],["missxgboost","missXGBoost",false,"Same iterative scheme with gradient-boosted trees instead of forests. Often faster and more accurate than missForest on large matrices.","moderate"],["knn","KNN \u2014 k-nearest neighbours",false,"Fills a gap with a distance-weighted average from the k most similar samples. Simple and fast; works well when samples cluster into similar profiles.","light"],["soft","SoftImpute",false,"Matrix completion by iterative soft-thresholded SVD. A good linear baseline for structured data. Note: 450K methylation took ~15 min and ~34 GB RSS.","heavy"],["mean","Mean imputation",false,"Replaces each gap with the feature mean. Fastest, but ignores all correlation structure. Use as a baseline, not a final choice.","light"],["lod","LOD \u2014 limit of detection",false,"Replaces gaps with a low constant derived from the smallest observed values. The right choice when missingness means 'below the assay's detection threshold'.","light"]],"scenarios":[["Your missingness is not random","If values are missing because they fell below an assay detection limit, the factor and tree methods will impute implausibly high values. Use LOD instead."],["Fewer samples than requested factors","--num_factor for EBMF/gEBMF must be smaller than your sample count. The protocol's toy set has 60 samples and uses --num_factor 30."],["You disabled QC","Leave QC enabled (do not pass --no-qc-prior-to-impute) so the QC matrix is available to every method."]]},"covariate_hidden_factor":{"kind":"choose","purpose":"Estimate unmeasured confounders (batch, cell composition, technical drift) from the phenotype matrix itself, after regressing out the covariates you already know about. Omitting these inflates false positives in the QTL scan.","how":"Marchenko-Pastur PCA is what the protocol uses for its main analyses \u2014 start there. Choose PEER if you need comparability with GTEx or other PEER-based studies. The other two differ only in how the number of factors is chosen, and cost more compute for it.","opts":[["Marchenko_PC","PCA + Marchenko-Pastur",true,"Regresses phenotype on known covariates, runs PCA on the residuals, and keeps the components whose eigenvalues exceed the Marchenko-Pastur random-matrix noise threshold. Used for the protocol's main analyses.","light"],["PEER","PEER (GTEx-style)",false,"Probabilistic MOFA-based factor model. Factor count follows GTEx recommendations by sample size, or fix it with --N. Pick this for comparability with GTEx.","moderate"],["PCA","PCA + Buja & Eyuboglu permutation",false,"Same PCA workflow, but factor count is chosen by permutation (--choose_k_method Buja_Eyuboglu, B=100) rather than the analytic threshold. Slower than Marchenko-Pastur for a similar answer.","moderate"],["BiCV","BiCV factor analysis (APEX)",false,"Chooses factor count by bi-cross-validation using the external APEX binary. Factor count follows GTEx recommendations. Note the APEX command options differ from APEX's own documentation.","moderate"]]},"gene_annotation":{"kind":"choose","purpose":"Attach genomic coordinates (chr/start/end) to every phenotype feature so the QTL scan knows where each feature sits and which variants are in cis.","how":"This choice is decided by the phenotype you are mapping, not by preference \u2014 the matching option is preselected below. Only the biomaRt route is a genuine alternative, for when you have no local GTF.","auto":{"bulk":"annotate_coord","sn":"annotate_coord","splice":"annotate_leafcutter_isoforms","meth":"annotate_coord","apa":"annotate_coord"},"opts":[["annotate_coord","Gene expression or protein matrix",true,"Matches each ENSEMBL gene ID against the GTF for coordinates. For proteins whose IDs look like gene_id|UniProt, pass --molecular-trait-type protein.","light"],["map_leafcutter_cluster_to_gene","LeafCutter clusters to genes",false,"Assigns LeafCutter intron clusters to genes. Run this before annotating LeafCutter isoforms. Default --map-stra site maps introns by site.","light"],["annotate_leafcutter_isoforms","LeafCutter isoforms",false,"Turns raw LeafCutter intron-excision output into a coordinate-annotated phenotype BED plus a phenotype-group file. Builds on the cluster-to-gene mapping.","light"],["annotate_coord_biomart","biomaRt web service",false,"Fetches coordinates from Ensembl over the network instead of a local GTF. Requires a gene_ID column and a reachable Ensembl release.","light"]],"scenarios":[["No local GTF, or you need a specific Ensembl release","Use biomaRt and set --ensembl-version. It depends on network access, so it is not reproducible on an air-gapped cluster."],["You are mapping splicing QTLs","Run clusters-to-genes first, then LeafCutter isoforms. The second depends on the first."]]},"mnm_regression":{"kind":"choose","purpose":"High-dimensional regression over a locus. A single fit yields two products the protocol uses downstream: fine-mapping results (credible sets, PIPs) and TWAS prediction weights.","how":"Several contexts or cell types \u2192 mvSuSiE (or mr.mash). Several genes sharing a locus \u2192 multi-gene. Epigenomic phenotypes with position along the genome \u2192 fSuSiE.","prereq":[["qtl_dataset_construct","Assemble the per-region dataset the models consume."]],"opts":[["susie_twas","SuSiE \u2014 univariate",true,"Univariate fine-mapping per phenotype. Also the route that produces TWAS prediction weights.","moderate"],["mnm","mvSuSiE \u2014 multivariate",false,"Multivariate across contexts, via mvSuSiE or mr.mash. Uses the mixture prior from MASH, so run MASH first. Also produces multi-context ensemble TWAS weights.","heavy"],["mnm_genes","Multi-gene",false,"Fine-maps several genes sharing a locus jointly.","heavy"],["fsusie","fSuSiE \u2014 functional",false,"Functional regression for epigenomic QTLs.","heavy"],["mvfsusie","mvfSuSiE \u2014 work in progress",false,"Multivariate functional regression; WIP placeholder.","heavy"]]},"mixture_prior":{"kind":"staged","purpose":"Build the data-driven prior (a set of covariance matrices) that MASH and mvSuSiE use to describe how QTL effects are shared across contexts.","how":"Candidate patterns describe biological effect sharing. Choose one method to estimate residual correlation, then one fitting engine to estimate the frequency of each sharing pattern. Shared preparation and diagnostics remain part of the workflow.","stages":[["Propose patterns of biological sharing","all",[["flash","FLASH factor analysis","~5-15 min."],["flash_nonneg","FLASH, non-negative constraint",""],["pca","Covariances from principal components",""],["canonical","Canonical single-condition and shared covariances",""]]],["Separate correlated noise from shared effects","one",[["vhat_identity","identity \u2014 simplest","Assumes residual errors are independent across conditions. Use it as a simple baseline, or when the conditions do not share samples or technical noise."],["vhat_simple","simple \u2014 from null z-scores","Estimates one residual-correlation matrix from null z-scores. This is the practical choice when the same samples or technical effects create correlation across conditions."],["vhat_mle","mle","Refines residual correlation by maximum likelihood using an initial prior. Use it for a second-pass analysis when the initial mixture fit is already available."],["vhat_corshrink_xcondition","corshrink, per condition","Shrinks correlations estimated from null signals. Use it when cross-condition residual correlations are expected but raw correlation estimates may be unstable."],["vhat_simple_specific","simple, per condition","Builds a positive-definite covariance estimate from null z-scores. Use it when you want a direct empirical estimate without adaptive correlation shrinkage."]]],["Estimate how often each sharing pattern occurs","one",[["ed_bovy","Extreme Deconvolution","Fits the sharing-pattern mixture with mashr Extreme Deconvolution. This is the protocol's default and the best starting point for most analyses."],["ud","Ultimate Deconvolution (udr)","Uses the udr Extreme Deconvolution update. It is an experimental alternative with known numerical issues, so compare its fit carefully with the default."],["ud_unconstrained","Ultimate Deconvolution, unconstrained","Uses the unconstrained udr TED update. Choose it only for z-scale data whose observations meet the method's independence assumptions."]]],["Inspect the learned sharing patterns","all",[["plot_U","Plot the estimated covariance patterns",""]]]],"scenarios":[["Choosing the effect model","--effect-model is EE (exchangeable effects) or EZ (exchangeable z-scores). It must match what you use downstream."]]},"RNA_calling":{"kind":"sequence","purpose":"Turn raw FASTQ into gene- and transcript-level expression matrices.","steps":[["fastqc","QC before alignment",false,""],["fastp_trim_adaptor","Trim adaptors with fastp",true,""],["STAR_align","Align reads with STAR",false,""],["rnaseqc_call","Gene-level expression with RNA-SeQC",false,""],["rsem_call","Transcript-level expression with RSEM",false,""]]},"VCF_QC":{"kind":"sequence","purpose":"Filter and annotate raw variant calls before any genotype work.","steps":[["rename_chrs","Rename chromosomes",true,"Use only if your contig naming disagrees with the reference."],["dbsnp_annotate","Annotate against dbSNP",false,""],["qc","Variant-level quality control",false,"The default path assumes DP/GQ/AD tags are present."]],"scenarios":[["Your VCF has no DP/GQ/AD tags","The notebook documents a separate QC path for data lacking these tags."]]},"GWAS_QC":{"kind":"sequence","purpose":"Sample- and variant-level QC, relatedness, and preparation of an unrelated subset for PCA.","steps":[["qc_no_prune","Basic QC, rare and common variants",false,""],["genotype_phenotype_sample_overlap","Match samples with the phenotype",false,""],["king","Kinship QC (KING)",false,"Splits samples into related and unrelated sets."],["qc","Prepare unrelated individuals and prune for PCA",false,""]]},"genotype_formatting":{"kind":"sequence","purpose":"Convert and partition genotypes into the layout the QTL scan expects.","steps":[["vcf_to_plink","VCF to PLINK",false,""],["merge_plink","Merge PLINK files",false,""],["genotype_by_chrom","Partition by chromosome",false,""]]},"splicing_normalization":{"kind":"sequence","purpose":"QC, impute and normalise LeafCutter intron-usage counts into a BED-ready phenotype table.","steps":[["leafcutter_norm","QC, then normalise",false,""],["leafcutter_qqnorm","Quantile normalisation",false,""]],"scenarios":[["Use the default mean-imputation path","Run leafcutter_norm without --no_norm. It will filter features, mean-impute the remaining missing values, and quantile-normalize the matrix in one workflow, so the separate leafcutter_qqnorm command is not needed."]]},"twas_ctwas":{"kind":"sequence","purpose":"Test each molecular context for association with a GWAS trait, then jointly fine-map genes and SNPs to separate directly causal signals from correlated ones.","steps":[["twas","TWAS association test",false,"Keeps only genes whose cross-validated model reaches adjusted r\u00b2 \u2265 0.01 and p < 0.05; the rest are dropped as non-imputable."],["ctwas","cTWAS joint fine-mapping",false,""],["quantile_twas","Quantile TWAS",true,"Tests genetic efects across quantiles of the trait distribution rather than only its mean."]],"scenarios":[["Prerequisites","Needs TWAS weights from mnm_regression (the susie_twas mode), plus GWAS summary statistics and an LD matrix for the region."]]},"pseudobulk_expression_aggregation_QC_norm":{"kind":"choose","purpose":"Aggregate single-cell counts into pseudobulk matrices, then QC and normalise them.","how":"Pick the aggregation scheme that matches how your cells are labelled.","opts":[["seuratagg","Aggregate by Seurat cluster",true,"Aggregates using the cluster labels already in the Seurat object.","moderate"],["subtypeagg","Aggregate by annotated subtype",false,"Uses a curated cell-subtype annotation rather than raw clusters.","moderate"],["neuronsagg","Neuron-focused aggregation",false,"Restricts aggregation to neuronal populations.","moderate"]]},"SuSiE_enloc":{"kind":"sequence","purpose":"Estimate global enrichment between xQTL and GWAS signals, then colocalise the overlapping regions. Pairwise: one molecular phenotype against one GWAS trait.","steps":[["xqtl_gwas_enrichment","Estimate global xQTL-GWAS enrichment",false,""],["susie_coloc","Colocalise the overlapping regions",false,""]],"scenarios":[["Prerequisites","Needs xQTL fine-mapping from mnm_regression (susie_twas) and GWAS fine-mapping from rss_analysis (susie_rss). It handles the case where the xQTL and GWAS credible sets fall in different regions."]]},"colocboost":{"kind":"sequence","purpose":"Integration, not fine-mapping. Colocalises signals across many phenotypes or molecular contexts — and optionally against a GWAS trait — while allowing multiple causal variants per region. Scales to hundreds of phenotypes.","steps":[["colocboost","Multi-trait colocalisation",false,""]],"scenarios":[["Prerequisites","Needs .susie.rds fine-mapping output from mnm_regression or rss_analysis, and individual-level xQTL data from one cohort (several phenotypes, shared genotype)."],["Including GWAS summary statistics","Optional. If you do include them, an LD reference is then required."]]},"intact":{"kind":"sequence","purpose":"Combine TWAS evidence and colocalisation evidence into a single gene-level posterior probability, rather than reading the two separately.","steps":[["intact","Integrate TWAS and coloc evidence",false,""]],"scenarios":[["Prerequisites, and a caveat","Expects PTWAS and fastenloc output. Note that the fastenloc notebooks are retired to graveyard/ in this repository, so you would need to produce that input another way."]]},"eoo_enrichment":{"kind":"sequence","purpose":"Ask whether your significant variants fall inside a genomic annotation more often than chance. Reports an odds ratio per annotation with block-jackknife standard errors, leaving out one chromosome at a time.","steps":[["enrichment","Block-jackknife overlap enrichment",false,""]]},"gsea":{"kind":"sequence","purpose":"Ask which biological pathways and GO categories are over-represented in a set of genes. Works on gene groups, not variants, and compares several groups at once.","steps":[["pathway_analysis","KEGG and GO over-representation",false,"ENSEMBL IDs are converted to ENTREZ; genes without a mapping are dropped."]]},"gregor":{"kind":"sequence","purpose":"Ask whether trait-associated variants are enriched in experimentally annotated regulatory features, against a negative set matched on MAF, LD proxy, distance to TSS and gene density.","steps":[["gregor_conf","Build the GREGOR configuration",false,""],["gregor","Run enrichment",false,""],["gregor_fisher_plot","Fisher test and plot",true,""]],"scenarios":[["Reading the output","The notebook warns that some GREGOR p-values come back greater than 1, and that the p-value is less informative than the effect size here."]]},"sldsc_enrichment":{"kind":"sequence","purpose":"Ask what share of trait heritability is attributable to an annotation category, using stratified LD score regression.","steps":[["munge_sumstats_polyfun","Munge summary statistics",false,"Run before the rest."],["make_annotation_files_ldscore","Build annotation LD scores",false,""],["get_heritability","Estimate heritability and tau",false,""],["postprocess","Post-process",true,""],["meta_subset","Random-effects meta-analysis across traits",true,""]],"requirements":[["PolyFun reference resources","Steps 1 and 2 require an external PolyFun installation and a matching precomputed reference panel containing baseline-LD annotations, LD weights, allele frequencies and PLINK files. These resources are not included with the toy fixtures. Use these commands after supplying the external resources; the SuSiE-RSS workflow is the runnable fixture example."]]}},CMDLIB={"GRM":[{"wf":"grm","cmd":"sos run pipeline/GRM.ipynb grm --cwd output/grm_uf --genoFile ${p.lines.map(pvEsc).join('\n')}`;if(p.kind==='plink')return `${p.lines.map(pvEsc).join('\n')}`;if(p.kind==='note')return `${p.lines.map(pvEsc).join('\n')}`;
@@ -649,7 +649,7 @@ king workflow separates related and unrelated samples, qc applies filtering and LD pruning, qcnoprune applies filtering without pruning, and genotypephenotypesampleoverlap retains samples represented in both the genotype and molecular phenotype data. The appropriate combination depends on cohort relatedness and on whether a pruned variant list already exists. Method reference: Manichaikul et al., 2010, Chang et al., 2015.\",\"METAL\":\"This notebook runs cross-cohort meta-analysis of summary statistics with METAL on the toy protocol_example dataset. METAL is a command-line tool that takes a script documenting the input summary-statistic files, the field mapping for each, and the analysis settings. Meta-analysis here is essentially a weighted sum of Z-scores, so the same set of variants must be present across the input cohorts; the input is a list of paths to the per-cohort summary statistics to analyse together. Method reference: Willer et al., 2010.\",\"PCA\":\"Population structure is the classic confounder in genetic association: if ancestry correlates with both genotype and phenotype, unadjusted tests return associations that are real but not causal. The remedy is to compute principal components of the genotype matrix and carry the leading ones as covariates. Components are computed on unrelated individuals and the remaining related samples are projected back into that space, so relatives cannot distort the axes but every sample still gets coordinates. The sequence is: remove related individuals, LD-prune the variants, run PCA on the unrelated set, then exclude PCA-space outliers. Relatedness estimation and sample QC happen upstream in GWAS_QC.ipynb. Method reference: Chang et al., 2015.\",\"RNA_calling\":\"RNA-seq reads record the transcripts present in each sample. This module aligns reads to the reference genome and quantifies gene-level expression, producing the count and abundance matrices that define the molecular phenotype. Accurate alignment and consistent gene annotation are required because mapping errors can create apparent expression differences that are unrelated to biology. Method reference: Dobin et al., 2013, Li & Dewey, 2011, Chen et al., 2018, Graubert et al., 2021.\",\"SuSiE_enloc\":\"This workflow processes fine-mapping results for xQTL, generated by susietwas in the mnmregression.ipynb notebook for cis xQTL, and GWAS fine-mapping results produced by susierss in the rssanalysis.ipynb notebook. It is designed to perform enrichment and colocalization analysis, particularly when fine-mapping results originate from different regions in the case of cis-xQTL and GWAS. The pipeline is capable to integrate and analyze data across these distinct regions. Originally tailored for cis-xQTL and GWAS integration, this pipeline can be applied to other pairwise integrations. An example of such application is in trans analysis, where the fine-mapped regions might be identical between trans-xQTL and GWAS, representing a special case of this broader implementation. Method reference: Wen et al., 2017.\",\"TensorQTL\":\"This module tests whether inherited variants are associated with molecular phenotypes across individuals. Cis analysis focuses on variants near each feature, where regulatory effects are most interpretable, while trans analysis searches for distal effects. Covariates account for ancestry, technical variation, and other measured sources of heterogeneity. GPU acceleration makes the same association model practical across large numbers of variants and phenotypes (Taylor-Weiner et al., 2019).\",\"VCF_QC\":\"Variant quality control removes genotypes that cannot support reliable regulatory mapping. The workflows normalize variant representation, restrict analysis to the intended samples and regions, remove poorly measured or uninformative variants, and harmonize identifiers before conversion to analysis-ready formats. These checks reduce false associations caused by missingness, allele inconsistencies, duplicate records, or genome-build mismatches.\",\"apa_calling\":\"Most genes have more than one polyadenylation site, and which one is used shifts the length of the 3' UTR - changing which regulatory elements survive in the transcript. Treating a gene as a single expression value hides that. This step quantifies alternative polyadenylation from RNA-seq coverage with DaPars2, giving a per-sample PDUI (percentage of distal polyA site usage) that can be scanned for QTLs like any other molecular phenotype. The workflows run in order: UTRreference builds the annotation DaPars2 needs, bam2tools converts alignments to coverage, APAconfig writes the configuration file and APAmain runs the quantification.\",\"apa_impute\":\"Alternative polyadenylation is quantified as PDUI, the fraction of transcripts using the distal poly(A) site. DaPars leaves gaps wherever a gene had too little coverage in a sample to call that fraction, and downstream models need a complete matrix. This step imputes those gaps with the impute package and quantile-normalises the filled matrix so samples are on a common scale. A second, optional workflow renames the sample columns from DaPars internal IDs to the names used elsewhere in the study.\",\"bulk_expression_QC\":\"Sample-level quality control asks whether each RNA-seq profile represents the intended biological specimen. The module compares expression patterns, sample annotations, and technical metrics to identify swaps, outliers, or globally degraded libraries. Removing problematic samples before association testing prevents a small number of abnormal profiles from driving apparent genetic effects.\",\"bulk_expression_normalization\":\"Lowly expressed genes provide little reliable information for mapping genetic effects and can add noise to association testing. This step retains genes that are consistently detected across individuals, then normalizes their expression levels so differences in sequencing depth and RNA composition do not obscure biological variation. The resulting expression matrix provides stable molecular phenotypes for downstream cis-eQTL analysis.\",\"colocboost\":\"Two signals at the same locus - a QTL and a GWAS hit, or QTLs in two cell types - may share a causal variant or merely sit in the same LD block. Colocalization tries to tell those apart. Classical pairwise methods assume one causal variant per trait and compare traits two at a time, which loses power when a region has several independent signals or when the shared signal is weak in any single pair. ColocBoost treats it as a multi-task problem instead: a gradient boosting framework that couples traits as it selects causal variants, so evidence that is weak in isolation can still support a shared signal across many contexts. It scales to hundreds of traits and allows multiple causal variants per region (Cao et al., 2025).\",\"covariate_formatting\":\"The association scan takes a single covariate file, but covariates arrive from several places: batch and demographic variables you supply, genotype principal components from PCA, and hidden factors estimated by covariatehiddenfactor. This step merges them, reconciles sample identifiers across the sources, and writes the combined matrix in the orientation the scan expects. When to run it. After PCA and hidden-factor estimation, immediately before QTL association testing.\",\"covariate_hidden_factor\":\"Unmeasured differences in batch, cell composition, RNA quality, or other latent processes can induce correlation among molecular phenotypes. This module estimates hidden factors from the phenotype matrix after accounting for known covariates. Including these factors in the QTL model reduces confounding while preserving interpretable genetic variation. PEER provides a probabilistic factor model, while the PCA workflows estimate the number of supported components from the data (Stegle et al., 2012).\",\"ems_prediction\":\"Create a tab-separated file with variant identifiers: `` variant_id 2:12345:A:T 2:67890:G:C 2:11111:T:A ``\",\"ems_training\":\"Most disease-associated GWAS variants lie in non-coding regions of the genome, where they likely modulate gene expression. However, bulk-tissue eQTL studies fail to explain the majority of these variants, a phenomenon termed \\\"missing regulation\\\" (Connally et al., 2022). This gap exists because there are systematic differences between variants identified in eQTL studies versus disease GWAS (Mostafavi et al., 2022):\",\"eoo_enrichment\":\"A variant set that overlaps an annotation more often than chance would predict is evidence that the annotation marks functional sequence. Counting the overlap is easy; putting an error bar on it is not, because variants are correlated along the genome and so cannot be resampled independently. This module computes an odds ratio and an enrichment statistic for each annotation, then leaves out one chromosome at a time and recomputes, using the spread across those 22 leave-one-out estimates as a block-jackknife standard error. Blocking by chromosome keeps correlated variants together rather than splitting them across resamples. When to run it. Run this module after chromosome-level enrichment inputs are available when a combined enrichment estimate and block-jackknife standard error are needed.\",\"gene_annotation\":\"Molecular phenotype matrices arrive keyed only by a feature identifier, such as an ENSEMBL gene ID, a UniProt accession, or a LeafCutter intron-cluster label, but every downstream QTL step needs a genomic position to define a cis window. This module attaches those coordinates, turning a plain matrix into a coordinate-sorted, bgzipped and tabix-indexed bed.gz file. Coordinates come from a collapsed gene-model GTF, following the GTEx pipeline convention, so the annotation used here matches the one used to build the GTF in the first place. Feature IDs that the GTF does not contain are dropped rather than guessed at, which is why the row count of the output can be lower than that of the input.\",\"generalized_TADB\":\"Analyses that work locus by locus need a definition of \\\"locus\\\". Using a fixed window around each gene is simple but arbitrary: regulatory contacts do not respect a fixed distance, and two genes in the same regulatory neighbourhood get analysed as if independent. Topologically associating domain boundaries give a definition grounded in chromatin architecture instead, and this step generates the boundary files that downstream region-based analyses consume. When to run it. Run this module before region-based association or fine-mapping when TAD-defined regions are preferred to fixed-width cis windows.\",\"genotype_formatting\":\"Nothing here changes the genotypes; it changes how they are packaged. Tools in the protocol disagree about format - some want PLINK, some want VCF - and the association and fine-mapping steps run per region or per chromosome, so the genotype data has to be split the same way to be processed in parallel. These workflows do those conversions and splits, plus the LD matrix computation per region that summary-statistic fine-mapping needs. When to run it. Run the relevant workflow after genotype quality control and before association scanning, LD calculation, or fine-mapping that requires the corresponding genotype layout. Method reference: Chang et al., 2015.\",\"gregor\":\"A set of trait-associated variants is more interpretable if you can say what kind of sequence they fall in. Enrichment testing asks whether they overlap a class of genomic feature - an annotation, a chromatin state, a set of regulatory elements - more often than chance allows, where chance has to account for the fact that variants are not exchangeable: they differ in minor allele frequency, in the number of LD proxies they carry, and in distance to the nearest gene. GREGOR builds matched control variants on exactly those properties - minor allele frequency, LD proxy count, distance to the nearest TSS, and local gene density - so the comparison is fair. Method reference: Schmidt et al., 2015.\",\"gsea\":\"A list of genes is hard to interpret on its own. Over-representation testing asks whether a group contains more members of some pathway or ontology term than chance would give, turning a list of identifiers into statements about biology. This module tests each group against the KEGG database and all three Gene Ontology branches using clusterProfiler. Input ENSEMBL gene IDs are first converted to ENTREZ IDs via org.Hs.eg.db; genes without a valid ENTREZ mapping are dropped, and group associations are preserved through the conversion. KEGG over-representation then runs through enrichKEGG() and GO through enrichGO() for Biological Process, Cellular Component and Molecular Function, both applying a hypergeometric test with Benjamini-Hochberg FDR correction. Method reference: Wu et al., 2021.\",\"intact\":\"INTACT combines evidence from PTWAS and fastENLOC for the same genes. It converts TWAS z-scores into Bayes factors across a grid of prior effect-size values, averages those Bayes factors, transforms the gene-level colocalization probability into a prior probability, and returns a posterior probability that integrates both sources of evidence. Run it after PTWAS and fastENLOC have been completed on a matched gene set.\",\"ld_prune_reference\":\"Many downstream methods assume the variants they are handed are approximately independent. A reference genotype panel is not: neighbouring variants are correlated through linkage disequilibrium, so a raw variant list counts the same signal several times over. This step runs PLINK LD clumping (--indep-pairwise) within each LD block and then merges the survivors into a single list, which is the form mashr and similar analyses expect. Working one block at a time keeps each clumping job small and lets the blocks run in parallel. The merge step afterwards also rewrites the variant IDs into one consistent format. Synthetic-data note. The minimal working example runs on a small synthetic chr22 PLINK panel, protocolexample.ldgenotype.chr22, of 60 samples and roughly 18k variants, built from the toy genotype VCF. It is for demonstration only and is not real individual-level data.\",\"mash_fit\":\"Effects estimated separately in each condition are noisy, and analysing them one condition at a time ignores that most effects are shared. MASH fits a mixture of multivariate normal distributions to the effect estimates, learning from the data which patterns of sharing actually occur - which conditions move together, and how strongly - so that individual estimates can later be shrunk towards those patterns rather than towards zero. This notebook fits the model. The data-driven prior matrices come from mixtureprior, and applying the fitted model to compute posterior estimates is mashposterior. By this point the input data have already been converted from the original association summary statistics into the MASH-format object written by mash_preprocessing. Method reference: Urbut et al., 2019.\",\"mash_posterior\":\"For each input chunk (a list of matrices bhat/sbhat/Z), the posterior workflow loads the MASH model and calls mashcomputeposteriormatrices. Additional workflows compute posterior contrasts between conditions and feature-level scores (meta, fine-mapped, n-significant, and p-value pairs) from the contrast results. Fitting the mixture model and applying it are separate jobs. mashfit learns which patterns of sharing exist across conditions; this notebook applies that fitted model to each chunk of effects, shrinking noisy estimates towards the patterns the data support. Effects that look condition-specific because of noise get pulled towards the shared pattern, and genuinely specific ones do not. Method reference: Urbut et al., 2019.\",\"mash_preprocessing\":\"This module constructs the three effect matrices used to learn cross-condition sharing patterns in MASH. The strong-effect matrix contains the top fine-mapped locus from each condition, the null matrix contains independent variants with small z-scores, and the random matrix samples variants from the supplied independent-variant list. Together, these matrices provide signal-rich, null, and background examples for estimating multivariate effect patterns. Run this module after genome-wide SuSiE fine-mapping results are available. Method reference: Urbut et al., 2019.\",\"methylation_calling\":\"This module quantifies array-based DNA methylation using either sesame or minfi, with sesame recommended for the protocol. Both methods remove probes affected by SNPs or cross-reactivity, assess sample and probe quality, and correct assay bias before producing methylation measurements for downstream QTL analysis. The minfi workflow uses dropLociWithSnps with manual filtering, detectionP summaries, and preprocessQuantile. The sesame workflow combines quality masking (Q), sesameQC_calcStats with detection and frac_dt metrics, nonlinear dye-bias correction (D), pOOBAH detection masking (P), and noob background subtraction (B). Method reference: Zhou et al., 2018.\",\"mixture_prior\":\"Genetic effects can be specific to one tissue or cell type, shared across several contexts, or similar across all contexts. MASH represents these possibilities as a mixture of covariance patterns. This module learns candidate sharing patterns, separates correlated measurement error from true effect sharing, and estimates how frequently each pattern occurs. The resulting MASH mixture prior allows downstream models to borrow information across contexts without assuming that every effect is shared (Urbut et al., 2019).\",\"mnm_regression\":\"An association scan tells you a region matters; it does not tell you which variant in it is responsible, because variants in linkage disequilibrium carry nearly the same signal. SuSiE reframes the question as variable selection: it fits a sum of single effects and returns credible sets - small groups of variants, each likely to contain one causal variant - together with posterior inclusion probabilities (Wang et al., 2020). When the same locus is measured across several contexts - tissues, cell types, conditions - fine-mapping each separately throws away the shared structure. mvSuSiE learns the patterns of sharing from the data and uses them to sharpen credible sets (Zou et al., 2026).\",\"phenotype_formatting\":\"Association testing and fine-mapping run per chromosome or per region, so the phenotype matrix has to be partitioned the same way before that work can be parallelised. These workflows split a phenotype BED by chromosome or by region, annotate features against TAD boundaries when region-based analysis is wanted, and accept GCT-format input as well as BED. Two further workflows trim inputs rather than split them: one subsets BAM files by coordinate, the other drops samples from a GCT matrix. The pipeline's author has flagged it as needing improvement, so treat the interface as unstable and re-check -h before relying on any option. When to run it. After phenotype QC, normalisation and imputation, and before covariate preprocessing and the association scan.\",\"phenotype_imputation\":\"Missing molecular measurements can arise when a feature falls below detection or is measured unreliably in a subset of samples. This module reconstructs missing values so downstream models can use a complete phenotype matrix. Factor-based methods borrow shared structure across features, nearest-neighbour and tree methods use relationships among samples, and limit-of-detection imputation is appropriate when missingness represents low abundance (Qi et al., 2023).\",\"pseudobulk_preprocessing\":\"This module prepares single-nucleus RNA-seq or ATAC-seq data for sample-level QTL analysis. It aggregates per-nucleus measurements into a pseudobulk count matrix for each cell type, harmonizes individual and sample identifiers across metadata and count matrices, then filters and normalizes the data before regressing technical covariates. The resulting residual phenotype matrix is ready for phenotype formatting and pseudobulk QTL analysis. Method reference: Hao et al., 2021.\",\"qr_and_twas\":\"Standard QTL mapping models the mean: it asks whether genotype shifts average expression. That misses variants whose effect is confined to part of the distribution - acting only in highly expressing samples, or changing spread rather than centre. Quantile regression tests across the distribution instead, so those effects become visible, and the same fit yields weights that can be carried into a TWAS. For each region the workflow fits quantile regression of the molecular phenotype on genotype across the quantile grid, combines the per-quantile p-values into a single QR p-value by the Cauchy combination method, and computes quantile TWAS weights. Covariates - genotype PCs, hidden factors and fixed covariates - are regressed out, and cis or trans windows are taken from a customized association-window file when one is given, otherwise a fixed cis-window around each region is used.\",\"qtl_association_postprocessing\":\"A cis scan reports a p-value for every variant against every molecular phenotype, which is not yet a result: the variants within a gene's window are correlated and the genes are many, so raw p-values overstate significance twice over. The correction is hierarchical, in three steps: local adjustment of the p-values of all cis variants within each gene, global adjustment of the minimum adjusted p-value across genes, then selection of the xQTLs whose locally adjusted p-value falls below the threshold (the eigenMT-BH procedure of Huang et al. 2018, NAR* 46(22):e133). The survivors are packaged as a QtlSumStats object with a regional FDR table, and the intermediate TensorQTL files are reorganised into an archive folder for book-keeping or deletion.\",\"reference_data_preparation\":\"Every study that uses this protocol should start from the same reference files: the same genome build, the same gene annotation, the same variant lists. When those differ between steps or between cohorts, the failures are quiet ones - coordinates that shift by a base, genes that exist in one annotation and not the other, meta-analyses that silently drop variants. This notebook downloads and standardises that reference set once, so the rest of the protocol reads from a consistent source. When to run it. Run this module once, before downstream workflows that require a reference genome, gene annotation, transcript annotation, or aligner index.\",\"rss_analysis\":\"Fine-mapping asks which variants in a region are consistent with a causal effect rather than merely correlated with one. SuSiE-RSS works from available summary data, specifically per-variant z-scores and an LD matrix from a reference panel, and returns credible sets with posterior inclusion probabilities (Zou et al., 2022). Results depend on ancestry and allele alignment between the study and reference panel, so the workflow can screen suspicious variants with SLALOM or DENTIST and impute missing variants with RAISS. The LD reference must retain genotypes because these checks cannot use a precomputed correlation matrix alone.\",\"rss_ld_sketch\":\"This module creates a compact LD reference from whole-genome sequencing genotypes. A random projection transforms the individual-by-variant genotype matrix into a smaller stochastic genotype matrix that preserves pairwise correlation structure approximately. SuSiE-RSS can then reconstruct an approximate LD matrix from the stored PLINK2 sketch without retaining the full genotype matrix. The sketch reduces storage while keeping the variant dimension required for regional fine-mapping.\",\"sldsc_enrichment\":\"Heritability is not distributed evenly across the genome. This module tests whether a functional category, such as a chromatin state, regulatory-element set, or xQTL annotation, explains more heritability than expected from its SNP count. LD-score regression separates polygenic signal from confounding by relating association statistics to the amount of linked variation each SNP tags (Bulik-Sullivan et al., 2015). Stratified LD-score regression estimates a contribution for each annotation while conditioning on overlapping baseline annotations (Finucane et al., 2015).\",\"snRNAseq_preprocessing\":\"Single-nuclei RNA-seq counts arrive with artefacts that would otherwise be read as biology: dying cells with high mitochondrial content, ambient RNA carried over from the suspension, and droplets holding two nuclei rather than one. Filtering those out, and then deciding what cell type each surviving nucleus is, has to happen before any per-cell-type analysis can start. Quality control runs through SCTK and Seurat: cells are dropped on mitochondrial percent, total counts (nUMI) and detected genes (nFeature), ambient RNA is removed with decontX, and doublets are removed with a user-selected method, scds by default. Cell types are then assigned by transferring labels from an annotated reference dataset onto the filtered object. Method reference: Hao et al., 2021.\",\"splicing_calling\":\"This module converts STAR-aligned RNA-seq data into splicing phenotypes using two independent approaches. LeafCutter groups introns that share splice sites and reports each intron as a fraction of its cluster, which captures exon skipping and alternative splice-site usage without requiring predefined event labels (Li et al., 2018). Psichomics instead uses STAR junction counts and a splicing annotation to quantify named events such as skipped exons and alternative first or last exons (Agostinho et al., 2019). The leafcutterpreprocessing workflow stops after junction extraction when clustering will be performed elsewhere.\",\"splicing_normalization\":\"Splicing measurements quantify how frequently alternative introns or transcript events are used across individuals. This module removes poorly measured events, adjusts the retained measurements for library and sample-level effects, and produces a stable splicing phenotype matrix. Normalization is required so an sQTL reflects genetic regulation of splice choice rather than differences in sequencing depth or event detectability. Method reference: Li et al., 2018.\",\"twas_ctwas\":\"A TWAS scan tests each gene's genetically predicted expression against a trait, but a significant gene is not necessarily a causal one: nearby variants with direct effects on the trait, and the predicted expression of neighbouring genes, are correlated with the gene's own eQTLs and act as confounders. cTWAS addresses this by fine-mapping genes and variants jointly within a region, so a gene is credited only for signal that its expression explains beyond the surrounding variants and genes, and reports a posterior inclusion probability rather than a p-value (Zhao et al., 2024). finemapCtwasRegions) and offers four workflows:\"},METH={\"phenotype_imputation\":{\"kind\":\"choose\",\"purpose\":\"Fill missing values in a molecular phenotype matrix. Missingness is common in proteomics and metabolomics, and most downstream QTL tools cannot accept gaps.\",\"how\":\"Start with gEBMF \\u2014 the protocol's recommended default. Switch only for a specific reason: LOD if missingness is caused by an assay detection limit (low-abundance proteins or metabolites), the tree methods if you suspect strong non-linear structure between features, or mean only as a baseline to compare against.\",\"prereq\":[[\"bed_filter_na\",\"Filter features by missingness rate before imputing (optional).\"]],\"opts\":[[\"gEBMF\",\"gEBMF \\u2014 grouped Empirical Bayes MF\",true,\"Fits factors within row groups (by chromosome), borrowing structure shared across features in the same group. The protocol's recommended default.\",\"moderate\"],[\"EBMF\",\"EBMF \\u2014 Empirical Bayes MF\",false,\"Decomposes the matrix into latent factors with adaptive shrinkage, then reconstructs it. Captures global low-rank structure across all samples and features.\",\"moderate\"],[\"missforest\",\"missForest\",false,\"Non-parametric iterative random-forest imputation; each feature is predicted from the others until values stabilise. Handles non-linear relationships but is computationally heavier.\",\"heavy\"],[\"missxgboost\",\"missXGBoost\",false,\"Same iterative scheme with gradient-boosted trees instead of forests. Often faster and more accurate than missForest on large matrices.\",\"moderate\"],[\"knn\",\"KNN \\u2014 k-nearest neighbours\",false,\"Fills a gap with a distance-weighted average from the k most similar samples. Simple and fast; works well when samples cluster into similar profiles.\",\"light\"],[\"soft\",\"SoftImpute\",false,\"Matrix completion by iterative soft-thresholded SVD. A good linear baseline for structured data. Note: 450K methylation took ~15 min and ~34 GB RSS.\",\"heavy\"],[\"mean\",\"Mean imputation\",false,\"Replaces each gap with the feature mean. Fastest, but ignores all correlation structure. Use as a baseline, not a final choice.\",\"light\"],[\"lod\",\"LOD \\u2014 limit of detection\",false,\"Replaces gaps with a low constant derived from the smallest observed values. The right choice when missingness means 'below the assay's detection threshold'.\",\"light\"]],\"scenarios\":[[\"Your missingness is not random\",\"If values are missing because they fell below an assay detection limit, the factor and tree methods will impute implausibly high values. Use LOD instead.\"],[\"Fewer samples than requested factors\",\"--num_factor for EBMF/gEBMF must be smaller than your sample count. The protocol's toy set has 60 samples and uses --num_factor 30.\"],[\"You disabled QC\",\"Leave QC enabled (do not pass --no-qc-prior-to-impute) so the QC matrix is available to every method.\"]]},\"covariate_hidden_factor\":{\"kind\":\"choose\",\"purpose\":\"Estimate unmeasured confounders (batch, cell composition, technical drift) from the phenotype matrix itself, after regressing out the covariates you already know about. Omitting these inflates false positives in the QTL scan.\",\"how\":\"Marchenko-Pastur PCA is what the protocol uses for its main analyses \\u2014 start there. Choose PEER if you need comparability with GTEx or other PEER-based studies. The other two differ only in how the number of factors is chosen, and cost more compute for it.\",\"opts\":[[\"Marchenko_PC\",\"PCA + Marchenko-Pastur\",true,\"Regresses phenotype on known covariates, runs PCA on the residuals, and keeps the components whose eigenvalues exceed the Marchenko-Pastur random-matrix noise threshold. Used for the protocol's main analyses.\",\"light\"],[\"PEER\",\"PEER (GTEx-style)\",false,\"Probabilistic MOFA-based factor model. Factor count follows GTEx recommendations by sample size, or fix it with --N. Pick this for comparability with GTEx.\",\"moderate\"],[\"PCA\",\"PCA + Buja & Eyuboglu permutation\",false,\"Same PCA workflow, but factor count is chosen by permutation (--choose_k_method Buja_Eyuboglu, B=100) rather than the analytic threshold. Slower than Marchenko-Pastur for a similar answer.\",\"moderate\"],[\"BiCV\",\"BiCV factor analysis (APEX)\",false,\"Chooses factor count by bi-cross-validation using the external APEX binary. Factor count follows GTEx recommendations. Note the APEX command options differ from APEX's own documentation.\",\"moderate\"]]},\"gene_annotation\":{\"kind\":\"choose\",\"purpose\":\"Attach genomic coordinates (chr/start/end) to every phenotype feature so the QTL scan knows where each feature sits and which variants are in cis.\",\"how\":\"This choice is decided by the phenotype you are mapping, not by preference \\u2014 the matching option is preselected below. Only the biomaRt route is a genuine alternative, for when you have no local GTF.\",\"auto\":{\"bulk\":\"annotate_coord\",\"sn\":\"annotate_coord\",\"splice\":\"annotate_leafcutter_isoforms\",\"meth\":\"annotate_coord\",\"apa\":\"annotate_coord\"},\"opts\":[[\"annotate_coord\",\"Gene expression or protein matrix\",true,\"Matches each ENSEMBL gene ID against the GTF for coordinates. For proteins whose IDs look like gene_id|UniProt, pass --molecular-trait-type protein.\",\"light\"],[\"map_leafcutter_cluster_to_gene\",\"LeafCutter clusters to genes\",false,\"Assigns LeafCutter intron clusters to genes. Run this before annotating LeafCutter isoforms. Default --map-stra site maps introns by site.\",\"light\"],[\"annotate_leafcutter_isoforms\",\"LeafCutter isoforms\",false,\"Turns raw LeafCutter intron-excision output into a coordinate-annotated phenotype BED plus a phenotype-group file. Builds on the cluster-to-gene mapping.\",\"light\"],[\"annotate_psichomics_isoforms\",\"Psichomics isoforms\",false,\"For psichomics quantifications, where each event ID ends in _<gene_id>.\",\"light\"],[\"annotate_coord_biomart\",\"biomaRt web service\",false,\"Fetches coordinates from Ensembl over the network instead of a local GTF. Requires a gene_ID column and a reachable Ensembl release.\",\"light\"]],\"scenarios\":[[\"No local GTF, or you need a specific Ensembl release\",\"Use biomaRt and set --ensembl-version. It depends on network access, so it is not reproducible on an air-gapped cluster.\"],[\"You are mapping splicing QTLs\",\"Run clusters-to-genes first, then LeafCutter isoforms. The second depends on the first.\"]]},\"mnm_regression\":{\"kind\":\"choose\",\"purpose\":\"High-dimensional regression over a locus. A single fit yields two products the protocol uses downstream: fine-mapping results (credible sets, PIPs) and TWAS prediction weights.\",\"how\":\"Several contexts or cell types \\u2192 mvSuSiE (or mr.mash). Several genes sharing a locus \\u2192 multi-gene. Epigenomic phenotypes with position along the genome \\u2192 fSuSiE.\",\"prereq\":[[\"qtl_dataset_construct\",\"Assemble the per-region dataset the models consume.\"]],\"opts\":[[\"susie_twas\",\"SuSiE \\u2014 univariate\",true,\"Univariate fine-mapping per phenotype. Also the route that produces TWAS prediction weights.\",\"moderate\"],[\"mnm\",\"mvSuSiE \\u2014 multivariate\",false,\"Multivariate across contexts, via mvSuSiE or mr.mash. Uses the mixture prior from MASH, so run MASH first. Also produces multi-context ensemble TWAS weights.\",\"heavy\"],[\"mnm_genes\",\"Multi-gene\",false,\"Fine-maps several genes sharing a locus jointly.\",\"heavy\"],[\"fsusie\",\"fSuSiE \\u2014 functional\",false,\"Functional regression for epigenomic QTLs.\",\"heavy\"],[\"mvfsusie\",\"mvfSuSiE \\u2014 work in progress\",false,\"Multivariate functional regression; WIP placeholder.\",\"heavy\"]]},\"mixture_prior\":{\"kind\":\"staged\",\"purpose\":\"Build the data-driven prior (a set of covariance matrices) that MASH and mvSuSiE use to describe how QTL effects are shared across contexts.\",\"how\":\"Candidate patterns describe biological effect sharing. Choose one method to estimate residual correlation, then one fitting engine to estimate the frequency of each sharing pattern. Shared preparation and diagnostics remain part of the workflow.\",\"stages\":[[\"Propose patterns of biological sharing\",\"all\",[[\"flash\",\"FLASH factor analysis\",\"~5-15 min.\"],[\"flash_nonneg\",\"FLASH, non-negative constraint\",\"\"],[\"pca\",\"Covariances from principal components\",\"\"],[\"canonical\",\"Canonical single-condition and shared covariances\",\"\"]]],[\"Separate correlated noise from shared effects\",\"one\",[[\"vhat_identity\",\"identity \\u2014 simplest\",\"Assumes residual errors are independent across conditions. Use it as a simple baseline, or when the conditions do not share samples or technical noise.\"],[\"vhat_simple\",\"simple \\u2014 from null z-scores\",\"Estimates one residual-correlation matrix from null z-scores. This is the practical choice when the same samples or technical effects create correlation across conditions.\"],[\"vhat_mle\",\"mle\",\"Refines residual correlation by maximum likelihood using an initial prior. Use it for a second-pass analysis when the initial mixture fit is already available.\"],[\"vhat_corshrink_xcondition\",\"corshrink, per condition\",\"Shrinks correlations estimated from null signals. Use it when cross-condition residual correlations are expected but raw correlation estimates may be unstable.\"],[\"vhat_simple_specific\",\"simple, per condition\",\"Builds a positive-definite covariance estimate from null z-scores. Use it when you want a direct empirical estimate without adaptive correlation shrinkage.\"]]],[\"Estimate how often each sharing pattern occurs\",\"one\",[[\"ed_bovy\",\"Extreme Deconvolution\",\"Fits the sharing-pattern mixture with mashr Extreme Deconvolution. This is the protocol's default and the best starting point for most analyses.\"],[\"ud\",\"Ultimate Deconvolution (udr)\",\"Uses the udr Extreme Deconvolution update. It is an experimental alternative with known numerical issues, so compare its fit carefully with the default.\"],[\"ud_unconstrained\",\"Ultimate Deconvolution, unconstrained\",\"Uses the unconstrained udr TED update. Choose it only for z-scale data whose observations meet the method's independence assumptions.\"]]],[\"Inspect the learned sharing patterns\",\"all\",[[\"plot_U\",\"Plot the estimated covariance patterns\",\"\"]]]],\"scenarios\":[[\"Choosing the effect model\",\"--effect-model is EE (exchangeable effects) or EZ (exchangeable z-scores). It must match what you use downstream.\"]]},\"RNA_calling\":{\"kind\":\"sequence\",\"purpose\":\"Turn raw FASTQ into gene- and transcript-level expression matrices.\",\"steps\":[[\"fastqc\",\"QC before alignment\",false,\"\"],[\"fastp_trim_adaptor\",\"Trim adaptors with fastp\",true,\"\"],[\"STAR_align\",\"Align reads with STAR\",false,\"\"],[\"rnaseqc_call\",\"Gene-level expression with RNA-SeQC\",false,\"\"],[\"rsem_call\",\"Transcript-level expression with RSEM\",false,\"\"]]},\"VCF_QC\":{\"kind\":\"sequence\",\"purpose\":\"Filter and annotate raw variant calls before any genotype work.\",\"steps\":[[\"rename_chrs\",\"Rename chromosomes\",true,\"Use only if your contig naming disagrees with the reference.\"],[\"dbsnp_annotate\",\"Annotate against dbSNP\",false,\"\"],[\"qc\",\"Variant-level quality control\",false,\"The default path assumes DP/GQ/AD tags are present.\"]],\"scenarios\":[[\"Your VCF has no DP/GQ/AD tags\",\"The notebook documents a separate QC path for data lacking these tags.\"]]},\"GWAS_QC\":{\"kind\":\"sequence\",\"purpose\":\"Sample- and variant-level QC, relatedness, and preparation of an unrelated subset for PCA.\",\"steps\":[[\"qc_no_prune\",\"Basic QC, rare and common variants\",false,\"\"],[\"genotype_phenotype_sample_overlap\",\"Match samples with the phenotype\",false,\"\"],[\"king\",\"Kinship QC (KING)\",false,\"Splits samples into related and unrelated sets.\"],[\"qc\",\"Prepare unrelated individuals and prune for PCA\",false,\"\"]]},\"genotype_formatting\":{\"kind\":\"sequence\",\"purpose\":\"Convert and partition genotypes into the layout the QTL scan expects.\",\"steps\":[[\"vcf_to_plink\",\"VCF to PLINK\",false,\"\"],[\"merge_plink\",\"Merge PLINK files\",false,\"\"],[\"genotype_by_chrom\",\"Partition by chromosome\",false,\"\"]]},\"splicing_normalization\":{\"kind\":\"sequence\",\"purpose\":\"QC, impute and normalise LeafCutter intron-usage counts into a BED-ready phenotype table.\",\"steps\":[[\"leafcutter_norm\",\"QC, then normalise\",false,\"\"],[\"leafcutter_qqnorm\",\"Quantile normalisation\",false,\"\"],[\"psichomics_norm\",\"Psichomics route\",true,\"Use instead of the LeafCutter steps if your upstream tool was psichomics.\"]],\"scenarios\":[[\"Use the default mean-imputation path\",\"Run leafcutter_norm without --no_norm. It will filter features, mean-impute the remaining missing values, and quantile-normalize the matrix in one workflow, so the separate leafcutter_qqnorm command is not needed.\"]]},\"twas_ctwas\":{\"kind\":\"sequence\",\"purpose\":\"Test each molecular context for association with a GWAS trait, then jointly fine-map genes and SNPs to separate directly causal signals from correlated ones.\",\"steps\":[[\"twas\",\"TWAS association test\",false,\"Keeps only genes whose cross-validated model reaches adjusted r\\u00b2 \\u2265 0.01 and p < 0.05; the rest are dropped as non-imputable.\"],[\"ctwas\",\"cTWAS joint fine-mapping\",false,\"\"],[\"quantile_twas\",\"Quantile TWAS\",true,\"Tests genetic efects across quantiles of the trait distribution rather than only its mean.\"]],\"scenarios\":[[\"Prerequisites\",\"Needs TWAS weights from mnm_regression (the susie_twas mode), plus GWAS summary statistics and an LD matrix for the region.\"]]},\"pseudobulk_expression_aggregation_QC_norm\":{\"kind\":\"choose\",\"purpose\":\"Aggregate single-cell counts into pseudobulk matrices, then QC and normalise them.\",\"how\":\"Pick the aggregation scheme that matches how your cells are labelled.\",\"opts\":[[\"seuratagg\",\"Aggregate by Seurat cluster\",true,\"Aggregates using the cluster labels already in the Seurat object.\",\"moderate\"],[\"subtypeagg\",\"Aggregate by annotated subtype\",false,\"Uses a curated cell-subtype annotation rather than raw clusters.\",\"moderate\"],[\"neuronsagg\",\"Neuron-focused aggregation\",false,\"Restricts aggregation to neuronal populations.\",\"moderate\"]]},\"SuSiE_enloc\":{\"kind\":\"sequence\",\"purpose\":\"Estimate global enrichment between xQTL and GWAS signals, then colocalise the overlapping regions. Pairwise: one molecular phenotype against one GWAS trait.\",\"steps\":[[\"xqtl_gwas_enrichment\",\"Estimate global xQTL-GWAS enrichment\",false,\"\"],[\"susie_coloc\",\"Colocalise the overlapping regions\",false,\"\"]],\"scenarios\":[[\"Prerequisites\",\"Needs xQTL fine-mapping from mnm_regression (susie_twas) and GWAS fine-mapping from rss_analysis (susie_rss). It handles the case where the xQTL and GWAS credible sets fall in different regions.\"]]},\"colocboost\":{\"kind\":\"sequence\",\"purpose\":\"Integration, not fine-mapping. Colocalises signals across many phenotypes or molecular contexts — and optionally against a GWAS trait — while allowing multiple causal variants per region. Scales to hundreds of phenotypes.\",\"steps\":[[\"colocboost\",\"Multi-trait colocalisation\",false,\"\"]],\"scenarios\":[[\"Prerequisites\",\"Needs .susie.rds fine-mapping output from mnm_regression or rss_analysis, and individual-level xQTL data from one cohort (several phenotypes, shared genotype).\"],[\"Including GWAS summary statistics\",\"Optional. If you do include them, an LD reference is then required.\"]]},\"intact\":{\"kind\":\"sequence\",\"purpose\":\"Combine TWAS evidence and colocalisation evidence into a single gene-level posterior probability, rather than reading the two separately.\",\"steps\":[[\"intact\",\"Integrate TWAS and coloc evidence\",false,\"\"]],\"scenarios\":[[\"Prerequisites, and a caveat\",\"Expects PTWAS and fastenloc output. Note that the fastenloc notebooks are retired to graveyard/ in this repository, so you would need to produce that input another way.\"]]},\"eoo_enrichment\":{\"kind\":\"sequence\",\"purpose\":\"Ask whether your significant variants fall inside a genomic annotation more often than chance. Reports an odds ratio per annotation with block-jackknife standard errors, leaving out one chromosome at a time.\",\"steps\":[[\"enrichment\",\"Block-jackknife overlap enrichment\",false,\"\"]]},\"gsea\":{\"kind\":\"sequence\",\"purpose\":\"Ask which biological pathways and GO categories are over-represented in a set of genes. Works on gene groups, not variants, and compares several groups at once.\",\"steps\":[[\"pathway_analysis\",\"KEGG and GO over-representation\",false,\"ENSEMBL IDs are converted to ENTREZ; genes without a mapping are dropped.\"]]},\"gregor\":{\"kind\":\"sequence\",\"purpose\":\"Ask whether trait-associated variants are enriched in experimentally annotated regulatory features, against a negative set matched on MAF, LD proxy, distance to TSS and gene density.\",\"steps\":[[\"gregor_conf\",\"Build the GREGOR configuration\",false,\"\"],[\"gregor\",\"Run enrichment\",false,\"\"],[\"gregor_fisher_plot\",\"Fisher test and plot\",true,\"\"]],\"scenarios\":[[\"Reading the output\",\"The notebook warns that some GREGOR p-values come back greater than 1, and that the p-value is less informative than the effect size here.\"]]},\"sldsc_enrichment\":{\"kind\":\"sequence\",\"purpose\":\"Ask what share of trait heritability is attributable to an annotation category, using stratified LD score regression.\",\"steps\":[[\"munge_sumstats_polyfun\",\"Munge summary statistics\",false,\"Run before the rest.\"],[\"make_annotation_files_ldscore\",\"Build annotation LD scores\",false,\"\"],[\"get_heritability\",\"Estimate heritability and tau\",false,\"\"],[\"postprocess\",\"Post-process\",true,\"\"],[\"meta_subset\",\"Random-effects meta-analysis across traits\",true,\"\"]],\"requirements\":[[\"PolyFun reference resources\",\"Steps 1 and 2 require an external PolyFun installation and a matching precomputed reference panel containing baseline-LD annotations, LD weights, allele frequencies and PLINK files. These resources are not included with the toy fixtures. Use these commands after supplying the external resources; the SuSiE-RSS workflow is the runnable fixture example.\"]]}},CMDLIB={\"GRM\":[{\"wf\":\"grm\",\"cmd\":\"sos run pipeline/GRM.ipynb grm --cwd output/grm_uf --genoFile king workflow separates related and unrelated samples, qc applies filtering and LD pruning, qcnoprune applies filtering without pruning, and genotypephenotypesampleoverlap retains samples represented in both the genotype and molecular phenotype data. The appropriate combination depends on cohort relatedness and on whether a pruned variant list already exists. Method reference: Manichaikul et al., 2010, Chang et al., 2015.\",\"METAL\":\"This notebook runs cross-cohort meta-analysis of summary statistics with METAL on the toy protocol_example dataset. METAL is a command-line tool that takes a script documenting the input summary-statistic files, the field mapping for each, and the analysis settings. Meta-analysis here is essentially a weighted sum of Z-scores, so the same set of variants must be present across the input cohorts; the input is a list of paths to the per-cohort summary statistics to analyse together. Method reference: Willer et al., 2010.\",\"PCA\":\"Population structure is the classic confounder in genetic association: if ancestry correlates with both genotype and phenotype, unadjusted tests return associations that are real but not causal. The remedy is to compute principal components of the genotype matrix and carry the leading ones as covariates. Components are computed on unrelated individuals and the remaining related samples are projected back into that space, so relatives cannot distort the axes but every sample still gets coordinates. The sequence is: remove related individuals, LD-prune the variants, run PCA on the unrelated set, then exclude PCA-space outliers. Relatedness estimation and sample QC happen upstream in GWAS_QC.ipynb. Method reference: Chang et al., 2015.\",\"RNA_calling\":\"RNA-seq reads record the transcripts present in each sample. This module aligns reads to the reference genome and quantifies gene-level expression, producing the count and abundance matrices that define the molecular phenotype. Accurate alignment and consistent gene annotation are required because mapping errors can create apparent expression differences that are unrelated to biology. Method reference: Dobin et al., 2013, Li & Dewey, 2011, Chen et al., 2018, Graubert et al., 2021.\",\"SuSiE_enloc\":\"This workflow processes fine-mapping results for xQTL, generated by susietwas in the mnmregression.ipynb notebook for cis xQTL, and GWAS fine-mapping results produced by susierss in the rssanalysis.ipynb notebook. It is designed to perform enrichment and colocalization analysis, particularly when fine-mapping results originate from different regions in the case of cis-xQTL and GWAS. The pipeline is capable to integrate and analyze data across these distinct regions. Originally tailored for cis-xQTL and GWAS integration, this pipeline can be applied to other pairwise integrations. An example of such application is in trans analysis, where the fine-mapped regions might be identical between trans-xQTL and GWAS, representing a special case of this broader implementation. Method reference: Wen et al., 2017.\",\"TensorQTL\":\"This module tests whether inherited variants are associated with molecular phenotypes across individuals. Cis analysis focuses on variants near each feature, where regulatory effects are most interpretable, while trans analysis searches for distal effects. Covariates account for ancestry, technical variation, and other measured sources of heterogeneity. GPU acceleration makes the same association model practical across large numbers of variants and phenotypes (Taylor-Weiner et al., 2019).\",\"VCF_QC\":\"Variant quality control removes genotypes that cannot support reliable regulatory mapping. The workflows normalize variant representation, restrict analysis to the intended samples and regions, remove poorly measured or uninformative variants, and harmonize identifiers before conversion to analysis-ready formats. These checks reduce false associations caused by missingness, allele inconsistencies, duplicate records, or genome-build mismatches.\",\"apa_calling\":\"Most genes have more than one polyadenylation site, and which one is used shifts the length of the 3' UTR - changing which regulatory elements survive in the transcript. Treating a gene as a single expression value hides that. This step quantifies alternative polyadenylation from RNA-seq coverage with DaPars2, giving a per-sample PDUI (percentage of distal polyA site usage) that can be scanned for QTLs like any other molecular phenotype. The workflows run in order: UTRreference builds the annotation DaPars2 needs, bam2tools converts alignments to coverage, APAconfig writes the configuration file and APAmain runs the quantification.\",\"apa_impute\":\"Alternative polyadenylation is quantified as PDUI, the fraction of transcripts using the distal poly(A) site. DaPars leaves gaps wherever a gene had too little coverage in a sample to call that fraction, and downstream models need a complete matrix. This step imputes those gaps with the impute package and quantile-normalises the filled matrix so samples are on a common scale. A second, optional workflow renames the sample columns from DaPars internal IDs to the names used elsewhere in the study.\",\"bulk_expression_QC\":\"Sample-level quality control asks whether each RNA-seq profile represents the intended biological specimen. The module compares expression patterns, sample annotations, and technical metrics to identify swaps, outliers, or globally degraded libraries. Removing problematic samples before association testing prevents a small number of abnormal profiles from driving apparent genetic effects.\",\"bulk_expression_normalization\":\"Lowly expressed genes provide little reliable information for mapping genetic effects and can add noise to association testing. This step retains genes that are consistently detected across individuals, then normalizes their expression levels so differences in sequencing depth and RNA composition do not obscure biological variation. The resulting expression matrix provides stable molecular phenotypes for downstream cis-eQTL analysis.\",\"colocboost\":\"Two signals at the same locus - a QTL and a GWAS hit, or QTLs in two cell types - may share a causal variant or merely sit in the same LD block. Colocalization tries to tell those apart. Classical pairwise methods assume one causal variant per trait and compare traits two at a time, which loses power when a region has several independent signals or when the shared signal is weak in any single pair. ColocBoost treats it as a multi-task problem instead: a gradient boosting framework that couples traits as it selects causal variants, so evidence that is weak in isolation can still support a shared signal across many contexts. It scales to hundreds of traits and allows multiple causal variants per region (Cao et al., 2025).\",\"covariate_formatting\":\"The association scan takes a single covariate file, but covariates arrive from several places: batch and demographic variables you supply, genotype principal components from PCA, and hidden factors estimated by covariatehiddenfactor. This step merges them, reconciles sample identifiers across the sources, and writes the combined matrix in the orientation the scan expects. When to run it. After PCA and hidden-factor estimation, immediately before QTL association testing.\",\"covariate_hidden_factor\":\"Unmeasured differences in batch, cell composition, RNA quality, or other latent processes can induce correlation among molecular phenotypes. This module estimates hidden factors from the phenotype matrix after accounting for known covariates. Including these factors in the QTL model reduces confounding while preserving interpretable genetic variation. PEER provides a probabilistic factor model, while the PCA workflows estimate the number of supported components from the data (Stegle et al., 2012).\",\"ems_prediction\":\"Create a tab-separated file with variant identifiers: `` variant_id 2:12345:A:T 2:67890:G:C 2:11111:T:A ``\",\"ems_training\":\"Most disease-associated GWAS variants lie in non-coding regions of the genome, where they likely modulate gene expression. However, bulk-tissue eQTL studies fail to explain the majority of these variants, a phenomenon termed \\\"missing regulation\\\" (Connally et al., 2022). This gap exists because there are systematic differences between variants identified in eQTL studies versus disease GWAS (Mostafavi et al., 2022):\",\"eoo_enrichment\":\"A variant set that overlaps an annotation more often than chance would predict is evidence that the annotation marks functional sequence. Counting the overlap is easy; putting an error bar on it is not, because variants are correlated along the genome and so cannot be resampled independently. This module computes an odds ratio and an enrichment statistic for each annotation, then leaves out one chromosome at a time and recomputes, using the spread across those 22 leave-one-out estimates as a block-jackknife standard error. Blocking by chromosome keeps correlated variants together rather than splitting them across resamples. When to run it. Run this module after chromosome-level enrichment inputs are available when a combined enrichment estimate and block-jackknife standard error are needed.\",\"gene_annotation\":\"Molecular phenotype matrices arrive keyed only by a feature identifier, such as an ENSEMBL gene ID, a UniProt accession, or a LeafCutter intron-cluster label, but every downstream QTL step needs a genomic position to define a cis window. This module attaches those coordinates, turning a plain matrix into a coordinate-sorted, bgzipped and tabix-indexed bed.gz file. Coordinates come from a collapsed gene-model GTF, following the GTEx pipeline convention, so the annotation used here matches the one used to build the GTF in the first place. Feature IDs that the GTF does not contain are dropped rather than guessed at, which is why the row count of the output can be lower than that of the input.\",\"generalized_TADB\":\"Analyses that work locus by locus need a definition of \\\"locus\\\". Using a fixed window around each gene is simple but arbitrary: regulatory contacts do not respect a fixed distance, and two genes in the same regulatory neighbourhood get analysed as if independent. Topologically associating domain boundaries give a definition grounded in chromatin architecture instead, and this step generates the boundary files that downstream region-based analyses consume. When to run it. Run this module before region-based association or fine-mapping when TAD-defined regions are preferred to fixed-width cis windows.\",\"genotype_formatting\":\"Nothing here changes the genotypes; it changes how they are packaged. Tools in the protocol disagree about format - some want PLINK, some want VCF - and the association and fine-mapping steps run per region or per chromosome, so the genotype data has to be split the same way to be processed in parallel. These workflows do those conversions and splits, plus the LD matrix computation per region that summary-statistic fine-mapping needs. When to run it. Run the relevant workflow after genotype quality control and before association scanning, LD calculation, or fine-mapping that requires the corresponding genotype layout. Method reference: Chang et al., 2015.\",\"gregor\":\"A set of trait-associated variants is more interpretable if you can say what kind of sequence they fall in. Enrichment testing asks whether they overlap a class of genomic feature - an annotation, a chromatin state, a set of regulatory elements - more often than chance allows, where chance has to account for the fact that variants are not exchangeable: they differ in minor allele frequency, in the number of LD proxies they carry, and in distance to the nearest gene. GREGOR builds matched control variants on exactly those properties - minor allele frequency, LD proxy count, distance to the nearest TSS, and local gene density - so the comparison is fair. Method reference: Schmidt et al., 2015.\",\"gsea\":\"A list of genes is hard to interpret on its own. Over-representation testing asks whether a group contains more members of some pathway or ontology term than chance would give, turning a list of identifiers into statements about biology. This module tests each group against the KEGG database and all three Gene Ontology branches using clusterProfiler. Input ENSEMBL gene IDs are first converted to ENTREZ IDs via org.Hs.eg.db; genes without a valid ENTREZ mapping are dropped, and group associations are preserved through the conversion. KEGG over-representation then runs through enrichKEGG() and GO through enrichGO() for Biological Process, Cellular Component and Molecular Function, both applying a hypergeometric test with Benjamini-Hochberg FDR correction. Method reference: Wu et al., 2021.\",\"intact\":\"INTACT combines evidence from PTWAS and fastENLOC for the same genes. It converts TWAS z-scores into Bayes factors across a grid of prior effect-size values, averages those Bayes factors, transforms the gene-level colocalization probability into a prior probability, and returns a posterior probability that integrates both sources of evidence. Run it after PTWAS and fastENLOC have been completed on a matched gene set.\",\"ld_prune_reference\":\"Many downstream methods assume the variants they are handed are approximately independent. A reference genotype panel is not: neighbouring variants are correlated through linkage disequilibrium, so a raw variant list counts the same signal several times over. This step runs PLINK LD clumping (--indep-pairwise) within each LD block and then merges the survivors into a single list, which is the form mashr and similar analyses expect. Working one block at a time keeps each clumping job small and lets the blocks run in parallel. The merge step afterwards also rewrites the variant IDs into one consistent format. Synthetic-data note. The minimal working example runs on a small synthetic chr22 PLINK panel, protocolexample.ldgenotype.chr22, of 60 samples and roughly 18k variants, built from the toy genotype VCF. It is for demonstration only and is not real individual-level data.\",\"mash_fit\":\"Effects estimated separately in each condition are noisy, and analysing them one condition at a time ignores that most effects are shared. MASH fits a mixture of multivariate normal distributions to the effect estimates, learning from the data which patterns of sharing actually occur - which conditions move together, and how strongly - so that individual estimates can later be shrunk towards those patterns rather than towards zero. This notebook fits the model. The data-driven prior matrices come from mixtureprior, and applying the fitted model to compute posterior estimates is mashposterior. By this point the input data have already been converted from the original association summary statistics into the MASH-format object written by mash_preprocessing. Method reference: Urbut et al., 2019.\",\"mash_posterior\":\"For each input chunk (a list of matrices bhat/sbhat/Z), the posterior workflow loads the MASH model and calls mashcomputeposteriormatrices. Additional workflows compute posterior contrasts between conditions and feature-level scores (meta, fine-mapped, n-significant, and p-value pairs) from the contrast results. Fitting the mixture model and applying it are separate jobs. mashfit learns which patterns of sharing exist across conditions; this notebook applies that fitted model to each chunk of effects, shrinking noisy estimates towards the patterns the data support. Effects that look condition-specific because of noise get pulled towards the shared pattern, and genuinely specific ones do not. Method reference: Urbut et al., 2019.\",\"mash_preprocessing\":\"This module constructs the three effect matrices used to learn cross-condition sharing patterns in MASH. The strong-effect matrix contains the top fine-mapped locus from each condition, the null matrix contains independent variants with small z-scores, and the random matrix samples variants from the supplied independent-variant list. Together, these matrices provide signal-rich, null, and background examples for estimating multivariate effect patterns. Run this module after genome-wide SuSiE fine-mapping results are available. Method reference: Urbut et al., 2019.\",\"methylation_calling\":\"This module quantifies array-based DNA methylation using either sesame or minfi, with sesame recommended for the protocol. Both methods remove probes affected by SNPs or cross-reactivity, assess sample and probe quality, and correct assay bias before producing methylation measurements for downstream QTL analysis. The minfi workflow uses dropLociWithSnps with manual filtering, detectionP summaries, and preprocessQuantile. The sesame workflow combines quality masking (Q), sesameQC_calcStats with detection and frac_dt metrics, nonlinear dye-bias correction (D), pOOBAH detection masking (P), and noob background subtraction (B). Method reference: Zhou et al., 2018.\",\"mixture_prior\":\"Genetic effects can be specific to one tissue or cell type, shared across several contexts, or similar across all contexts. MASH represents these possibilities as a mixture of covariance patterns. This module learns candidate sharing patterns, separates correlated measurement error from true effect sharing, and estimates how frequently each pattern occurs. The resulting MASH mixture prior allows downstream models to borrow information across contexts without assuming that every effect is shared (Urbut et al., 2019).\",\"mnm_regression\":\"An association scan tells you a region matters; it does not tell you which variant in it is responsible, because variants in linkage disequilibrium carry nearly the same signal. SuSiE reframes the question as variable selection: it fits a sum of single effects and returns credible sets - small groups of variants, each likely to contain one causal variant - together with posterior inclusion probabilities (Wang et al., 2020). When the same locus is measured across several contexts - tissues, cell types, conditions - fine-mapping each separately throws away the shared structure. mvSuSiE learns the patterns of sharing from the data and uses them to sharpen credible sets (Zou et al., 2026).\",\"phenotype_formatting\":\"Association testing and fine-mapping run per chromosome or per region, so the phenotype matrix has to be partitioned the same way before that work can be parallelised. These workflows split a phenotype BED by chromosome or by region, annotate features against TAD boundaries when region-based analysis is wanted, and accept GCT-format input as well as BED. Two further workflows trim inputs rather than split them: one subsets BAM files by coordinate, the other drops samples from a GCT matrix. The pipeline's author has flagged it as needing improvement, so treat the interface as unstable and re-check -h before relying on any option. When to run it. After phenotype QC, normalisation and imputation, and before covariate preprocessing and the association scan.\",\"phenotype_imputation\":\"Missing molecular measurements can arise when a feature falls below detection or is measured unreliably in a subset of samples. This module reconstructs missing values so downstream models can use a complete phenotype matrix. Factor-based methods borrow shared structure across features, nearest-neighbour and tree methods use relationships among samples, and limit-of-detection imputation is appropriate when missingness represents low abundance (Qi et al., 2023).\",\"pseudobulk_preprocessing\":\"This module prepares single-nucleus RNA-seq or ATAC-seq data for sample-level QTL analysis. It aggregates per-nucleus measurements into a pseudobulk count matrix for each cell type, harmonizes individual and sample identifiers across metadata and count matrices, then filters and normalizes the data before regressing technical covariates. The resulting residual phenotype matrix is ready for phenotype formatting and pseudobulk QTL analysis. Method reference: Hao et al., 2021.\",\"qr_and_twas\":\"Standard QTL mapping models the mean: it asks whether genotype shifts average expression. That misses variants whose effect is confined to part of the distribution - acting only in highly expressing samples, or changing spread rather than centre. Quantile regression tests across the distribution instead, so those effects become visible, and the same fit yields weights that can be carried into a TWAS. For each region the workflow fits quantile regression of the molecular phenotype on genotype across the quantile grid, combines the per-quantile p-values into a single QR p-value by the Cauchy combination method, and computes quantile TWAS weights. Covariates - genotype PCs, hidden factors and fixed covariates - are regressed out, and cis or trans windows are taken from a customized association-window file when one is given, otherwise a fixed cis-window around each region is used.\",\"qtl_association_postprocessing\":\"A cis scan reports a p-value for every variant against every molecular phenotype, which is not yet a result: the variants within a gene's window are correlated and the genes are many, so raw p-values overstate significance twice over. The correction is hierarchical, in three steps: local adjustment of the p-values of all cis variants within each gene, global adjustment of the minimum adjusted p-value across genes, then selection of the xQTLs whose locally adjusted p-value falls below the threshold (the eigenMT-BH procedure of Huang et al. 2018, NAR* 46(22):e133). The survivors are packaged as a QtlSumStats object with a regional FDR table, and the intermediate TensorQTL files are reorganised into an archive folder for book-keeping or deletion.\",\"reference_data_preparation\":\"Every study that uses this protocol should start from the same reference files: the same genome build, the same gene annotation, the same variant lists. When those differ between steps or between cohorts, the failures are quiet ones - coordinates that shift by a base, genes that exist in one annotation and not the other, meta-analyses that silently drop variants. This notebook downloads and standardises that reference set once, so the rest of the protocol reads from a consistent source. When to run it. Run this module once, before downstream workflows that require a reference genome, gene annotation, transcript annotation, or aligner index.\",\"rss_analysis\":\"Fine-mapping asks which variants in a region are consistent with a causal effect rather than merely correlated with one. SuSiE-RSS works from available summary data, specifically per-variant z-scores and an LD matrix from a reference panel, and returns credible sets with posterior inclusion probabilities (Zou et al., 2022). Results depend on ancestry and allele alignment between the study and reference panel, so the workflow can screen suspicious variants with SLALOM or DENTIST and impute missing variants with RAISS. The LD reference must retain genotypes because these checks cannot use a precomputed correlation matrix alone.\",\"rss_ld_sketch\":\"This module creates a compact LD reference from whole-genome sequencing genotypes. A random projection transforms the individual-by-variant genotype matrix into a smaller stochastic genotype matrix that preserves pairwise correlation structure approximately. SuSiE-RSS can then reconstruct an approximate LD matrix from the stored PLINK2 sketch without retaining the full genotype matrix. The sketch reduces storage while keeping the variant dimension required for regional fine-mapping.\",\"sldsc_enrichment\":\"Heritability is not distributed evenly across the genome. This module tests whether a functional category, such as a chromatin state, regulatory-element set, or xQTL annotation, explains more heritability than expected from its SNP count. LD-score regression separates polygenic signal from confounding by relating association statistics to the amount of linked variation each SNP tags (Bulik-Sullivan et al., 2015). Stratified LD-score regression estimates a contribution for each annotation while conditioning on overlapping baseline annotations (Finucane et al., 2015).\",\"snRNAseq_preprocessing\":\"Single-nuclei RNA-seq counts arrive with artefacts that would otherwise be read as biology: dying cells with high mitochondrial content, ambient RNA carried over from the suspension, and droplets holding two nuclei rather than one. Filtering those out, and then deciding what cell type each surviving nucleus is, has to happen before any per-cell-type analysis can start. Quality control runs through SCTK and Seurat: cells are dropped on mitochondrial percent, total counts (nUMI) and detected genes (nFeature), ambient RNA is removed with decontX, and doublets are removed with a user-selected method, scds by default. Cell types are then assigned by transferring labels from an annotated reference dataset onto the filtered object. Method reference: Hao et al., 2021.\",\"splicing_calling\":\"This module converts STAR-aligned RNA-seq data into splicing phenotypes using two independent approaches. LeafCutter groups introns that share splice sites and reports each intron as a fraction of its cluster, which captures exon skipping and alternative splice-site usage without requiring predefined event labels (Li et al., 2018). The leafcutterpreprocessing workflow stops after junction extraction when clustering will be performed elsewhere.\",\"splicing_normalization\":\"Splicing measurements quantify how frequently alternative introns or transcript events are used across individuals. This module removes poorly measured events, adjusts the retained measurements for library and sample-level effects, and produces a stable splicing phenotype matrix. Normalization is required so an sQTL reflects genetic regulation of splice choice rather than differences in sequencing depth or event detectability. Method reference: Li et al., 2018.\",\"twas_ctwas\":\"A TWAS scan tests each gene's genetically predicted expression against a trait, but a significant gene is not necessarily a causal one: nearby variants with direct effects on the trait, and the predicted expression of neighbouring genes, are correlated with the gene's own eQTLs and act as confounders. cTWAS addresses this by fine-mapping genes and variants jointly within a region, so a gene is credited only for signal that its expression explains beyond the surrounding variants and genes, and reports a posterior inclusion probability rather than a p-value (Zhao et al., 2024). finemapCtwasRegions) and offers four workflows:\"},METH={\"phenotype_imputation\":{\"kind\":\"choose\",\"purpose\":\"Fill missing values in a molecular phenotype matrix. Missingness is common in proteomics and metabolomics, and most downstream QTL tools cannot accept gaps.\",\"how\":\"Start with gEBMF \\u2014 the protocol's recommended default. Switch only for a specific reason: LOD if missingness is caused by an assay detection limit (low-abundance proteins or metabolites), the tree methods if you suspect strong non-linear structure between features, or mean only as a baseline to compare against.\",\"prereq\":[[\"bed_filter_na\",\"Filter features by missingness rate before imputing (optional).\"]],\"opts\":[[\"gEBMF\",\"gEBMF \\u2014 grouped Empirical Bayes MF\",true,\"Fits factors within row groups (by chromosome), borrowing structure shared across features in the same group. The protocol's recommended default.\",\"moderate\"],[\"EBMF\",\"EBMF \\u2014 Empirical Bayes MF\",false,\"Decomposes the matrix into latent factors with adaptive shrinkage, then reconstructs it. Captures global low-rank structure across all samples and features.\",\"moderate\"],[\"missforest\",\"missForest\",false,\"Non-parametric iterative random-forest imputation; each feature is predicted from the others until values stabilise. Handles non-linear relationships but is computationally heavier.\",\"heavy\"],[\"missxgboost\",\"missXGBoost\",false,\"Same iterative scheme with gradient-boosted trees instead of forests. Often faster and more accurate than missForest on large matrices.\",\"moderate\"],[\"knn\",\"KNN \\u2014 k-nearest neighbours\",false,\"Fills a gap with a distance-weighted average from the k most similar samples. Simple and fast; works well when samples cluster into similar profiles.\",\"light\"],[\"soft\",\"SoftImpute\",false,\"Matrix completion by iterative soft-thresholded SVD. A good linear baseline for structured data. Note: 450K methylation took ~15 min and ~34 GB RSS.\",\"heavy\"],[\"mean\",\"Mean imputation\",false,\"Replaces each gap with the feature mean. Fastest, but ignores all correlation structure. Use as a baseline, not a final choice.\",\"light\"],[\"lod\",\"LOD \\u2014 limit of detection\",false,\"Replaces gaps with a low constant derived from the smallest observed values. The right choice when missingness means 'below the assay's detection threshold'.\",\"light\"]],\"scenarios\":[[\"Your missingness is not random\",\"If values are missing because they fell below an assay detection limit, the factor and tree methods will impute implausibly high values. Use LOD instead.\"],[\"Fewer samples than requested factors\",\"--num_factor for EBMF/gEBMF must be smaller than your sample count. The protocol's toy set has 60 samples and uses --num_factor 30.\"],[\"You disabled QC\",\"Leave QC enabled (do not pass --no-qc-prior-to-impute) so the QC matrix is available to every method.\"]]},\"covariate_hidden_factor\":{\"kind\":\"choose\",\"purpose\":\"Estimate unmeasured confounders (batch, cell composition, technical drift) from the phenotype matrix itself, after regressing out the covariates you already know about. Omitting these inflates false positives in the QTL scan.\",\"how\":\"Marchenko-Pastur PCA is what the protocol uses for its main analyses \\u2014 start there. Choose PEER if you need comparability with GTEx or other PEER-based studies. The other two differ only in how the number of factors is chosen, and cost more compute for it.\",\"opts\":[[\"Marchenko_PC\",\"PCA + Marchenko-Pastur\",true,\"Regresses phenotype on known covariates, runs PCA on the residuals, and keeps the components whose eigenvalues exceed the Marchenko-Pastur random-matrix noise threshold. Used for the protocol's main analyses.\",\"light\"],[\"PEER\",\"PEER (GTEx-style)\",false,\"Probabilistic MOFA-based factor model. Factor count follows GTEx recommendations by sample size, or fix it with --N. Pick this for comparability with GTEx.\",\"moderate\"],[\"PCA\",\"PCA + Buja & Eyuboglu permutation\",false,\"Same PCA workflow, but factor count is chosen by permutation (--choose_k_method Buja_Eyuboglu, B=100) rather than the analytic threshold. Slower than Marchenko-Pastur for a similar answer.\",\"moderate\"],[\"BiCV\",\"BiCV factor analysis (APEX)\",false,\"Chooses factor count by bi-cross-validation using the external APEX binary. Factor count follows GTEx recommendations. Note the APEX command options differ from APEX's own documentation.\",\"moderate\"]]},\"gene_annotation\":{\"kind\":\"choose\",\"purpose\":\"Attach genomic coordinates (chr/start/end) to every phenotype feature so the QTL scan knows where each feature sits and which variants are in cis.\",\"how\":\"This choice is decided by the phenotype you are mapping, not by preference \\u2014 the matching option is preselected below. Only the biomaRt route is a genuine alternative, for when you have no local GTF.\",\"auto\":{\"bulk\":\"annotate_coord\",\"sn\":\"annotate_coord\",\"splice\":\"annotate_leafcutter_isoforms\",\"meth\":\"annotate_coord\",\"apa\":\"annotate_coord\"},\"opts\":[[\"annotate_coord\",\"Gene expression or protein matrix\",true,\"Matches each ENSEMBL gene ID against the GTF for coordinates. For proteins whose IDs look like gene_id|UniProt, pass --molecular-trait-type protein.\",\"light\"],[\"map_leafcutter_cluster_to_gene\",\"LeafCutter clusters to genes\",false,\"Assigns LeafCutter intron clusters to genes. Run this before annotating LeafCutter isoforms. Default --map-stra site maps introns by site.\",\"light\"],[\"annotate_leafcutter_isoforms\",\"LeafCutter isoforms\",false,\"Turns raw LeafCutter intron-excision output into a coordinate-annotated phenotype BED plus a phenotype-group file. Builds on the cluster-to-gene mapping.\",\"light\"],[\"annotate_coord_biomart\",\"biomaRt web service\",false,\"Fetches coordinates from Ensembl over the network instead of a local GTF. Requires a gene_ID column and a reachable Ensembl release.\",\"light\"]],\"scenarios\":[[\"No local GTF, or you need a specific Ensembl release\",\"Use biomaRt and set --ensembl-version. It depends on network access, so it is not reproducible on an air-gapped cluster.\"],[\"You are mapping splicing QTLs\",\"Run clusters-to-genes first, then LeafCutter isoforms. The second depends on the first.\"]]},\"mnm_regression\":{\"kind\":\"choose\",\"purpose\":\"High-dimensional regression over a locus. A single fit yields two products the protocol uses downstream: fine-mapping results (credible sets, PIPs) and TWAS prediction weights.\",\"how\":\"Several contexts or cell types \\u2192 mvSuSiE (or mr.mash). Several genes sharing a locus \\u2192 multi-gene. Epigenomic phenotypes with position along the genome \\u2192 fSuSiE.\",\"prereq\":[[\"qtl_dataset_construct\",\"Assemble the per-region dataset the models consume.\"]],\"opts\":[[\"susie_twas\",\"SuSiE \\u2014 univariate\",true,\"Univariate fine-mapping per phenotype. Also the route that produces TWAS prediction weights.\",\"moderate\"],[\"mnm\",\"mvSuSiE \\u2014 multivariate\",false,\"Multivariate across contexts, via mvSuSiE or mr.mash. Uses the mixture prior from MASH, so run MASH first. Also produces multi-context ensemble TWAS weights.\",\"heavy\"],[\"mnm_genes\",\"Multi-gene\",false,\"Fine-maps several genes sharing a locus jointly.\",\"heavy\"],[\"fsusie\",\"fSuSiE \\u2014 functional\",false,\"Functional regression for epigenomic QTLs.\",\"heavy\"],[\"mvfsusie\",\"mvfSuSiE \\u2014 work in progress\",false,\"Multivariate functional regression; WIP placeholder.\",\"heavy\"]]},\"mixture_prior\":{\"kind\":\"staged\",\"purpose\":\"Build the data-driven prior (a set of covariance matrices) that MASH and mvSuSiE use to describe how QTL effects are shared across contexts.\",\"how\":\"Candidate patterns describe biological effect sharing. Choose one method to estimate residual correlation, then one fitting engine to estimate the frequency of each sharing pattern. Shared preparation and diagnostics remain part of the workflow.\",\"stages\":[[\"Propose patterns of biological sharing\",\"all\",[[\"flash\",\"FLASH factor analysis\",\"~5-15 min.\"],[\"flash_nonneg\",\"FLASH, non-negative constraint\",\"\"],[\"pca\",\"Covariances from principal components\",\"\"],[\"canonical\",\"Canonical single-condition and shared covariances\",\"\"]]],[\"Separate correlated noise from shared effects\",\"one\",[[\"vhat_identity\",\"identity \\u2014 simplest\",\"Assumes residual errors are independent across conditions. Use it as a simple baseline, or when the conditions do not share samples or technical noise.\"],[\"vhat_simple\",\"simple \\u2014 from null z-scores\",\"Estimates one residual-correlation matrix from null z-scores. This is the practical choice when the same samples or technical effects create correlation across conditions.\"],[\"vhat_mle\",\"mle\",\"Refines residual correlation by maximum likelihood using an initial prior. Use it for a second-pass analysis when the initial mixture fit is already available.\"],[\"vhat_corshrink_xcondition\",\"corshrink, per condition\",\"Shrinks correlations estimated from null signals. Use it when cross-condition residual correlations are expected but raw correlation estimates may be unstable.\"],[\"vhat_simple_specific\",\"simple, per condition\",\"Builds a positive-definite covariance estimate from null z-scores. Use it when you want a direct empirical estimate without adaptive correlation shrinkage.\"]]],[\"Estimate how often each sharing pattern occurs\",\"one\",[[\"ed_bovy\",\"Extreme Deconvolution\",\"Fits the sharing-pattern mixture with mashr Extreme Deconvolution. This is the protocol's default and the best starting point for most analyses.\"],[\"ud\",\"Ultimate Deconvolution (udr)\",\"Uses the udr Extreme Deconvolution update. It is an experimental alternative with known numerical issues, so compare its fit carefully with the default.\"],[\"ud_unconstrained\",\"Ultimate Deconvolution, unconstrained\",\"Uses the unconstrained udr TED update. Choose it only for z-scale data whose observations meet the method's independence assumptions.\"]]],[\"Inspect the learned sharing patterns\",\"all\",[[\"plot_U\",\"Plot the estimated covariance patterns\",\"\"]]]],\"scenarios\":[[\"Choosing the effect model\",\"--effect-model is EE (exchangeable effects) or EZ (exchangeable z-scores). It must match what you use downstream.\"]]},\"RNA_calling\":{\"kind\":\"sequence\",\"purpose\":\"Turn raw FASTQ into gene- and transcript-level expression matrices.\",\"steps\":[[\"fastqc\",\"QC before alignment\",false,\"\"],[\"fastp_trim_adaptor\",\"Trim adaptors with fastp\",true,\"\"],[\"STAR_align\",\"Align reads with STAR\",false,\"\"],[\"rnaseqc_call\",\"Gene-level expression with RNA-SeQC\",false,\"\"],[\"rsem_call\",\"Transcript-level expression with RSEM\",false,\"\"]]},\"VCF_QC\":{\"kind\":\"sequence\",\"purpose\":\"Filter and annotate raw variant calls before any genotype work.\",\"steps\":[[\"rename_chrs\",\"Rename chromosomes\",true,\"Use only if your contig naming disagrees with the reference.\"],[\"dbsnp_annotate\",\"Annotate against dbSNP\",false,\"\"],[\"qc\",\"Variant-level quality control\",false,\"The default path assumes DP/GQ/AD tags are present.\"]],\"scenarios\":[[\"Your VCF has no DP/GQ/AD tags\",\"The notebook documents a separate QC path for data lacking these tags.\"]]},\"GWAS_QC\":{\"kind\":\"sequence\",\"purpose\":\"Sample- and variant-level QC, relatedness, and preparation of an unrelated subset for PCA.\",\"steps\":[[\"qc_no_prune\",\"Basic QC, rare and common variants\",false,\"\"],[\"genotype_phenotype_sample_overlap\",\"Match samples with the phenotype\",false,\"\"],[\"king\",\"Kinship QC (KING)\",false,\"Splits samples into related and unrelated sets.\"],[\"qc\",\"Prepare unrelated individuals and prune for PCA\",false,\"\"]]},\"genotype_formatting\":{\"kind\":\"sequence\",\"purpose\":\"Convert and partition genotypes into the layout the QTL scan expects.\",\"steps\":[[\"vcf_to_plink\",\"VCF to PLINK\",false,\"\"],[\"merge_plink\",\"Merge PLINK files\",false,\"\"],[\"genotype_by_chrom\",\"Partition by chromosome\",false,\"\"]]},\"splicing_normalization\":{\"kind\":\"sequence\",\"purpose\":\"QC, impute and normalise LeafCutter intron-usage counts into a BED-ready phenotype table.\",\"steps\":[[\"leafcutter_norm\",\"QC, then normalise\",false,\"\"],[\"leafcutter_qqnorm\",\"Quantile normalisation\",false,\"\"]],\"scenarios\":[[\"Use the default mean-imputation path\",\"Run leafcutter_norm without --no_norm. It will filter features, mean-impute the remaining missing values, and quantile-normalize the matrix in one workflow, so the separate leafcutter_qqnorm command is not needed.\"]]},\"twas_ctwas\":{\"kind\":\"sequence\",\"purpose\":\"Test each molecular context for association with a GWAS trait, then jointly fine-map genes and SNPs to separate directly causal signals from correlated ones.\",\"steps\":[[\"twas\",\"TWAS association test\",false,\"Keeps only genes whose cross-validated model reaches adjusted r\\u00b2 \\u2265 0.01 and p < 0.05; the rest are dropped as non-imputable.\"],[\"ctwas\",\"cTWAS joint fine-mapping\",false,\"\"],[\"quantile_twas\",\"Quantile TWAS\",true,\"Tests genetic efects across quantiles of the trait distribution rather than only its mean.\"]],\"scenarios\":[[\"Prerequisites\",\"Needs TWAS weights from mnm_regression (the susie_twas mode), plus GWAS summary statistics and an LD matrix for the region.\"]]},\"pseudobulk_expression_aggregation_QC_norm\":{\"kind\":\"choose\",\"purpose\":\"Aggregate single-cell counts into pseudobulk matrices, then QC and normalise them.\",\"how\":\"Pick the aggregation scheme that matches how your cells are labelled.\",\"opts\":[[\"seuratagg\",\"Aggregate by Seurat cluster\",true,\"Aggregates using the cluster labels already in the Seurat object.\",\"moderate\"],[\"subtypeagg\",\"Aggregate by annotated subtype\",false,\"Uses a curated cell-subtype annotation rather than raw clusters.\",\"moderate\"],[\"neuronsagg\",\"Neuron-focused aggregation\",false,\"Restricts aggregation to neuronal populations.\",\"moderate\"]]},\"SuSiE_enloc\":{\"kind\":\"sequence\",\"purpose\":\"Estimate global enrichment between xQTL and GWAS signals, then colocalise the overlapping regions. Pairwise: one molecular phenotype against one GWAS trait.\",\"steps\":[[\"xqtl_gwas_enrichment\",\"Estimate global xQTL-GWAS enrichment\",false,\"\"],[\"susie_coloc\",\"Colocalise the overlapping regions\",false,\"\"]],\"scenarios\":[[\"Prerequisites\",\"Needs xQTL fine-mapping from mnm_regression (susie_twas) and GWAS fine-mapping from rss_analysis (susie_rss). It handles the case where the xQTL and GWAS credible sets fall in different regions.\"]]},\"colocboost\":{\"kind\":\"sequence\",\"purpose\":\"Integration, not fine-mapping. Colocalises signals across many phenotypes or molecular contexts — and optionally against a GWAS trait — while allowing multiple causal variants per region. Scales to hundreds of phenotypes.\",\"steps\":[[\"colocboost\",\"Multi-trait colocalisation\",false,\"\"]],\"scenarios\":[[\"Prerequisites\",\"Needs .susie.rds fine-mapping output from mnm_regression or rss_analysis, and individual-level xQTL data from one cohort (several phenotypes, shared genotype).\"],[\"Including GWAS summary statistics\",\"Optional. If you do include them, an LD reference is then required.\"]]},\"intact\":{\"kind\":\"sequence\",\"purpose\":\"Combine TWAS evidence and colocalisation evidence into a single gene-level posterior probability, rather than reading the two separately.\",\"steps\":[[\"intact\",\"Integrate TWAS and coloc evidence\",false,\"\"]],\"scenarios\":[[\"Prerequisites, and a caveat\",\"Expects PTWAS and fastenloc output. Note that the fastenloc notebooks are retired to graveyard/ in this repository, so you would need to produce that input another way.\"]]},\"eoo_enrichment\":{\"kind\":\"sequence\",\"purpose\":\"Ask whether your significant variants fall inside a genomic annotation more often than chance. Reports an odds ratio per annotation with block-jackknife standard errors, leaving out one chromosome at a time.\",\"steps\":[[\"enrichment\",\"Block-jackknife overlap enrichment\",false,\"\"]]},\"gsea\":{\"kind\":\"sequence\",\"purpose\":\"Ask which biological pathways and GO categories are over-represented in a set of genes. Works on gene groups, not variants, and compares several groups at once.\",\"steps\":[[\"pathway_analysis\",\"KEGG and GO over-representation\",false,\"ENSEMBL IDs are converted to ENTREZ; genes without a mapping are dropped.\"]]},\"gregor\":{\"kind\":\"sequence\",\"purpose\":\"Ask whether trait-associated variants are enriched in experimentally annotated regulatory features, against a negative set matched on MAF, LD proxy, distance to TSS and gene density.\",\"steps\":[[\"gregor_conf\",\"Build the GREGOR configuration\",false,\"\"],[\"gregor\",\"Run enrichment\",false,\"\"],[\"gregor_fisher_plot\",\"Fisher test and plot\",true,\"\"]],\"scenarios\":[[\"Reading the output\",\"The notebook warns that some GREGOR p-values come back greater than 1, and that the p-value is less informative than the effect size here.\"]]},\"sldsc_enrichment\":{\"kind\":\"sequence\",\"purpose\":\"Ask what share of trait heritability is attributable to an annotation category, using stratified LD score regression.\",\"steps\":[[\"munge_sumstats_polyfun\",\"Munge summary statistics\",false,\"Run before the rest.\"],[\"make_annotation_files_ldscore\",\"Build annotation LD scores\",false,\"\"],[\"get_heritability\",\"Estimate heritability and tau\",false,\"\"],[\"postprocess\",\"Post-process\",true,\"\"],[\"meta_subset\",\"Random-effects meta-analysis across traits\",true,\"\"]],\"requirements\":[[\"PolyFun reference resources\",\"Steps 1 and 2 require an external PolyFun installation and a matching precomputed reference panel containing baseline-LD annotations, LD weights, allele frequencies and PLINK files. These resources are not included with the toy fixtures. Use these commands after supplying the external resources; the SuSiE-RSS workflow is the runnable fixture example.\"]]}},CMDLIB={\"GRM\":[{\"wf\":\"grm\",\"cmd\":\"sos run pipeline/GRM.ipynb grm --cwd output/grm_uf --genoFile ${p.lines.map(pvEsc).join('\\n')}`;if(p.kind==='plink')return `${p.lines.map(pvEsc).join('\\n')}`;if(p.kind==='note')return `${p.lines.map(pvEsc).join('\\n')}`;\n",
@@ -659,7 +660,7 @@
" const note=`Showing ${n}${p.truncatedColumns?` of ${p.totalColumns}`:''} columns and ${rows.length} rows.`;\n",
" return `