Added fixtures

README.md

@@ -4,6 +4,23 @@ Developed for reproducible & reusable molecular QTL analyses for the NIH/NIA
 Alzheimer's Disease Sequencing Project (ADSP) Functional Genomics xQTL (FunGen-xQTL)
 Project.
 
+## What the protocol covers
+
+| Stage | What it does |
+|---|---|
+| **Molecular phenotypes** | Quantify expression, splicing, methylation and polyadenylation from bulk RNA-seq, single-nuclei or array data |
+| **Data preprocessing** | Genotype QC and formatting, phenotype imputation and formatting, covariate and hidden-factor estimation |
+| **QTL association testing** | cis and trans scans with TensorQTL, quantile-regression QTL, hierarchical multiple testing |
+| **Multivariate modelling** | MASH, to borrow information across tissues and cell types |
+| **Fine-mapping and TWAS** | SuSiE, mvSuSiE, fSuSiE and SuSiE-RSS, from individual-level data or summary statistics, with TWAS weights |
+| **GWAS integration** | Colocalization (SuSiE-enloc, ColocBoost), TWAS and cTWAS, INTACT |
+| **Enrichment and validation** | Pathway analysis, GREGOR, stratified LD score regression |
+
+Not every project needs every stage. The
+[xQTL Analysis Workflow Builder](https://statfungen.github.io/xqtl-protocol/xqtl_protocol_workflow_builder.html)
+asks what you measured and what you want to find out, then shows the modules on
+that route with the commands to run them.
+
 ## Getting started
 
 | I want to... | Go to |

code/SoS/xqtl_protocol_demo.ipynb

@@ -232,7 +232,42 @@
     "\n",
     "The demo on this page runs on a desktop workstation. Production analyses typically run on an HPC cluster, and SoS supports this natively via [SoS Remote Tasks](https://vatlab.github.io/sos-docs/doc/user_guide/task_statement.html) on [configured host computers](https://vatlab.github.io/sos-docs/doc/user_guide/host_setup.html).\n",
     "\n",
-    "We provide a [toy example for running SoS pipelines on a typical HPC cluster environment](https://github.com/statfungen/xqtl-protocol/blob/main/code/misc/Job_Example.ipynb) — first-time users are encouraged to work through it before launching real jobs. It covers the host and task configuration you'll reuse for every subsequent pipeline, and it's schedule-agnostic (SLURM, LSF, SGE, PBS/Torque all work).\n"
+    "We provide a [toy example for running SoS pipelines on a typical HPC cluster environment](https://github.com/statfungen/xqtl-protocol/blob/main/code/misc/Job_Example.ipynb) — first-time users are encouraged to work through it before launching real jobs. It covers the host and task configuration you'll reuse for every subsequent pipeline, and it's schedule-agnostic (SLURM, LSF, SGE, PBS/Torque all work).\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Using your own data\n",
+    "\n",
+    "The examples above run against files committed in `tests/fixtures/`. To run the same\n",
+    "pipeline on your own study, replace those paths with your own -- the parameters do\n",
+    "not change.\n",
+    "\n",
+    "Most modules expect some combination of:\n",
+    "\n",
+    "| Parameter | What it wants |\n",
+    "|---|---|\n",
+    "| `--genoFile` | Genotypes: PLINK `.bed/.bim/.fam`, or a list of per-chromosome files |\n",
+    "| `--phenoFile` | Molecular phenotype matrix: bgzipped BED, `#chr start end ID` then one column per sample |\n",
+    "| `--covFile` | Covariates, gzipped |\n",
+    "| `--region-list` | Regions to analyse, or a region list produced by an earlier step |\n",
+    "| `--cwd` | Where outputs are written |\n",
+    "\n",
+    "Sample identifiers must match across the genotype, phenotype and covariate files.\n",
+    "Most \"no overlapping samples\" errors come from a mismatch here rather than from a\n",
+    "problem with the data itself.\n",
+    "\n",
+    "To see the parameters a module accepts:\n",
+    "\n",
+    "```bash\n",
+    "sos run pipeline/<module>.ipynb -h\n",
+    "```\n",
+    "\n",
+    "And for a set of arguments known to work, look at that module's test -- each one\n",
+    "carries a parameter set that CI runs:\n",
+    "\n",
+    "```bash\n",
+    "grep -rl 'run_sos' tests/notebooks --include='*.py'\n",
+    "```\n"
    ]
   }
  ],

tests/fixtures/mnm_regression/expected/README.md

@@ -0,0 +1,38 @@
+# mnm_regression expected outputs
+
+| file | produced by |
+|---|---|
+| `univariate_bvsr.rds` | `susie_twas` — per-context SuSiE fine-mapping (`method = "susie"`) |
+| `univariate_twas_weights.rds` | `susie_twas` — TWAS weights from the same run |
+| `protocol_example.ENSG00000283047.multicontext_bvsr.rds` | `mnm` — joint multi-context fit (`method = "mvsusie"`, carries a `jointContexts` column) |
+
+## Regenerating the multicontext result
+
+`mnm` needs the dataset built first, so run both steps together. Note two things the
+module documentation currently gets wrong: the parameter is `--prior`, not
+`--mixture-prior`, and `--transpose-covariates True` is required — without it the run
+fails with "No shared samples between phenotype and covariate file", which looks like
+a data problem but is an orientation one.
+
+```bash
+sos run pipeline/mnm_regression.ipynb qtl_dataset_construct+mnm \
+    --name protocol_example --cwd <out> \
+    --genoFile tests/fixtures/qtl_mini/protocol_example.genotype.chr22.bed \
+    --phenoFile tests/fixtures/qtl_mini/protocol_example.pheno_manifest_context.tsv \
+    --covFile tests/fixtures/qtl_mini/example_covariates.tsv \
+    --transpose-covariates True \
+    --customized-association-windows tests/fixtures/qtl_mini/association_windows.bed \
+    --region-name ENSG00000283047 --save-data --no-skip-twas-weights \
+    --phenotype-names mv_pheno \
+    --prior tests/fixtures/mash/expected/mixture_prior.EE.prior.rds \
+    --ld-reference-meta-file tests/fixtures/ld_reference/ld_meta_file.tsv \
+    --modular_script_dir code/script -j1
+```
+
+The mixture prior is a choice: `tests/fixtures/mash/expected/` also holds
+`prior.cov_ed.EE.rds`. This fixture was generated with `mixture_prior.EE.prior.rds`.
+If that is not the intended prior for the toy data, regenerate and replace.
+
+No test currently drives the `mnm` step — `test_mnm_regression` runs
+`qtl_dataset_construct+susie_twas` only — so this file is documentation of the
+expected shape rather than an asserted comparison.