Turning a manuscript into a reproducible genomics repository
A methods-focused article on converting outbreak manuscripts into public repositories that preserve analysis logic, assumptions, quality checks, and reusable commands.
A repository is part of the method
In pathogen genomics, the manuscript usually contains the scientific argument, but the repository contains the evidence path. A reader should be able to move from the biological question to the computational workflow without guessing which reference was used, which samples were excluded, which threshold created a masked base, or which command generated the final tree.
For outbreak work this matters because the same analysis may later be reused for a new pathogen, a new sequencing batch, or a training session. A clean repository is not decoration. It is a way of showing that the analysis was thought through, that important choices were recorded, and that another analyst could audit the logic.
What I include before I call a repository ready
My preferred structure starts with a short scientific purpose statement. The README should say what the workflow answers, what data type it expects, what outputs it produces, and what it does not claim to solve. A repository that says only how to run commands is incomplete; it must also explain why those commands exist.
The second layer is reproducibility: environment files, workflow rules, configuration templates, sample sheets, expected output paths, and citations. Snakemake is useful here because it expresses dependencies between files, commands, environments, and outputs. A dry run can show the analysis plan before compute time is spent.
- README: scientific purpose, data type, input layout, main outputs, and known limitations.
- Environment: conda or mamba file with pinned packages wherever possible.
- Config: editable sample sheet and parameters separated from workflow code.
- Workflow: one command for dry run and one command for full execution.
- Outputs: a short guide to consensus FASTA, QC tables, mutation tables, trees, and reports.
Restricted data should not block transparency
Many clinical and public-health datasets cannot be made fully public. That should not stop a repository from being useful. The solution is to separate private inputs from public logic: keep raw FASTQ paths out of the repository, provide example metadata with fake sample IDs, include small test files when allowed, and document how the real data were arranged.
For collaborators and future trainees, this communicates two things at once: the analysis is traceable, and data governance was taken seriously. In applied genomics, those two values should sit together.
A minimal command pattern
git clone https://github.com/adnanhaider81/polio-capsid-ngs-analysis.git
cd polio-capsid-ngs-analysis
mamba env create -f env/environment.yml
conda activate polio-capsid-env
make test
snakemake -s workflow/Snakefile --configfile config/config.yaml -n -c 4
snakemake -s workflow/Snakefile --configfile config/config.yaml -c 4 --printshellcmdsHow I would audit my own repository
Before sharing a repository publicly, I read it as if I were a collaborator seeing the project for the first time. I ask whether the scientific question is visible before the commands, whether the inputs are described without exposing private data, and whether the outputs are named in a way that a future reader can connect back to the manuscript figure or table.
The most useful audit is not only technical. It also checks whether the repository preserves decision points: why a depth threshold was used, why a reference was selected, why a sequence was excluded, and which step produced the final interpretation. These details are often more important than a long list of tools.
A practical reproducibility standard
For my own genomics work, a repository becomes useful when it can support three readers: the analyst who wants to rerun the workflow, the collaborator who wants to understand the analysis logic, and the trainee who wants to learn the method. The same structure can serve all three if the README, config files, workflow rules, and output guide are written together.
I also separate reproducibility from full data release. Clinical and public-health sequence data may be restricted, but the workflow logic, environment files, synthetic examples, command structure, and citation trail can still be public. That balance keeps the analysis transparent while respecting governance.
- A repository should include the purpose, not only installation steps.
- A dry run should be possible before real compute begins.
- Output folders should match the biological interpretation: QC, consensus, trees, mutations, reports.
- Restricted data should be represented by templates, synthetic examples, or documented local paths.
- Tool citations should be close to the workflow they support.