Development

Development

git clone https://github.com/duceppemo/QIIME2_ITS
cd QIIME2_ITS
pip install -e '.[dev]'
pytest -v

All unit tests mock external tool invocations (qiime, biom, bbduk.sh, etc.), so they run with a plain Python interpreter — no QIIME2 installation required. CI runs them on every push (see .github/workflows/tests.yml).

Releasing

1. Bump the version in pyproject.toml, src/qiime2_its/_version.py and CITATION.cff (plus its date-released); run the tests; commit and push.
2. Tag and push the tag: git tag -a vX.Y.Z -m "qiime2-its X.Y.Z" && git push origin vX.Y.Z. That triggers .github/workflows/publish.yml, which builds the package, checks that the tag matches the version in pyproject.toml, installs the wheel, and publishes it to PyPI through trusted publishing (OIDC from the pypi GitHub environment, restricted to v* tags -- no API token is stored anywhere).
3. Create the GitHub release (gh release create vX.Y.Z --title vX.Y.Z --notes-file ...).
4. scripts/sync_wiki.sh.

To test the publish workflow without publishing, run it manually from the Actions tab (workflow_dispatch): the build/check/install steps run, the publish job is skipped.

Project layout

src/qiime2_its/
  cli/                  pipeline.py, fastq_rc.py, train_unite.py, train_ncbi.py, train_fasta.py
  fastq_utils.py         fastq listing/parsing/cleaning (pure Python)
  env_checks.py           conda-env/CPU/executable sanity checks
  qiime_wrapper.py         `qiime ...` subprocess command builders
  biom_utils.py            `biom ...` subprocess command builders + taxonomy-in-BIOM merging
  itsxpress_wrapper.py     `qiime itsxpress ...` command builders
  size_filter.py           bbduk.sh command builders
  taxonomy.py              NCBI taxdump parsing + lineage-string construction
  downloader.py            generic download + tar.gz extraction
  metadata_utils.py        QIIME2 metadata TSV parsing, column eligibility
  provenance.py            run-provenance/QA metadata (run_metadata.json)
  report_data.py           parses pipeline output (.qzv/.tsv) into plain data structures
  report.py                assembles report.pdf from report_data.py's output
  timing.py                compact elapsed-time formatting ("1d2h3m4s")
tests/                    unit tests, one file per module above
validation/                real-data end-to-end validation (see Validation-Suite)

The wrapper modules (qiime_wrapper.py, itsxpress_wrapper.py, size_filter.py) each build one external-tool command per function and run it with subprocess.run(cmd, check=True). Their tests mock subprocess.run and assert the constructed argv — this catches our bugs, not whether the installed QIIME2 version still accepts that command; that's what the validation suite is for.

Editing this wiki

The GitHub wiki you're reading is a separate git repo (github.com/duceppemo/QIIME2_ITS.wiki.git) that GitHub maintains alongside this one, but its source of truth is wiki/*.md in this repo, not that repo directly — that way wiki changes go through the same review/diff/history as code changes instead of being editable, unreviewed, straight from the GitHub web UI. To change a page: edit the file under wiki/, commit it here as usual, then run scripts/sync_wiki.sh to push the current contents of wiki/ live to the GitHub wiki (it clones the wiki repo to a temp dir, mirrors wiki/*.md onto it, and pushes — nothing to set up beforehand).

Migrating from the pre-0.2 flat scripts

Versions before 0.2 shipped as standalone scripts (python qiime2_its.py ...). As of 0.2, this is an installable package with console-script entry points instead: qiime2-its, qiime2-its-rc, qiime2-its-train-unite, qiime2-its-train-ncbi, and qiime2-its-train-fasta (pip install -e . from the repository root, inside your QIIME2 conda environment). Command-line flags are otherwise unchanged. ITS extraction now goes through the qiime itsxpress plugin instead of the old standalone itsxpress CLI — install it with conda install -c bioconda -c conda-forge itsxpress followed by qiime dev refresh-cache inside your QIIME2 environment.