v4.0.0

Changelog

v4.0.0

Major version bump — reference data handling, methylation, and PGx/tertiary
analysis all changed shape relative to v3.3.1. Existing input JSONs from v3.x
will need updating.

Breaking changes

• Reference input replaced: ref_map_file (File) is gone everywhere
  (family, singleton, joint, upstream, downstream). Replaced by
  ref_name (String, default "GRCh38_GIABv3", choices ["GRCh38", "GRCh38_GIABv3"]),
  which a new unpack_container_manifest task resolves into reference-
  specific ref FASTA/index, TRGT catalog, Sawfish exclude/expected-CN BEDs,
  MethBat region TSV, Paraphase genome build, chrY depth threshold, and a
  run_starphase flag — all baked into a container manifest instead of
  user-supplied files.
• ref_name default changed "GRCh38" → "GRCh38_GIABv3" in
  family/singleton — anyone not setting ref_name explicitly now gets
  the GIAB-patched assembly (see below) instead of standard GRCh38.
• cpg_pileup → methbat_pileup: output renamed cpg_combined_bed[_index]
  → cpg_pileup_bed[_index]
• bam_statistics: per-read output removed (replaced by a pbjam-
  based equivalent under the hood), plot output remains the same.
• sawfish no longer produces CNV MAF BigWig: sv_maf_bw output
  removed workflow-wide; sawfish_discover/sawfish_call drop their
  --maf inputs.
• pbmm2 chunking control changed: max_reads_per_alignment_chunk (Int)
  replaced by use_alignment_chunking (Boolean) — chunk size is no longer
  tunable, only on/off. For input hifi_reads BAMs that are already realigned,
  chunking will be disabled.
• backend input set to "HPC" by default.
• Tertiary analysis stage removed entirely: This drops Phrank
  phenotype-based gene ranking, slivar small-variant filtering (incl.
  compound-het detection), and svpack/slivar SV annotation. All 9
  tertiary_* outputs and the tertiary_map_file input are gone.
• Pedigree fields dropped from Sample struct: Because the tertiary
  analysis was removed, fields only used by tertiary analysis: sex,
  affected, father_id, mother_id are gone. phenotypes (HPO terms)
  input removed from family/singleton.
• PharmCAT removed: pharmcat.wdl workflow deleted along with the
  pharmcat_* outputs and pharmcat_min_coverage input. StarPhase now
  emits a PharmCAT-format TSV directly (pbstarphase_tsv).

New tools / tasks

• kivvi — targeted repeat genotyping for the LPA KIV2 repeat and the
  FSHD-associated D4Z4 repeat from a standard-depth WGS BAM. New outputs:
  kivvi_kiv2_* and kivvi_d4z4_* (VCF, JSON, realigned BAM, allele plot).
  25x WGS coverage or higher, ideally 30x, is recommended for Kivvi.
• pbjam — replaces the old inline bam_stats.wdl script with the
  pbjam bam-stats CLI for read-length/quality/MAPQ/identity plots and
  summary stats. >90% wall-time reduction compared to bam_stats.
• pbsamoa — multithreaded BAM merge task (pbsamoa merge). Up to
  50% wall-time reduction compared to samtools_merge.
• methbat, major bump → 1.1.0: now also does pileup generation
  (methbat_pileup, replacing pb-cpg-tools), adding new cpg_pileup_bed[_index]
  (renamed from cpg_combined_bed[_index]) and hmcpg_pileup_bed[_index]
  (new 5hmC calls) outputs. The per-haplotype cpg_hap1_bed[_index]/
  cpg_hap2_bed[_index] and all three BigWigs (cpg_combined_bw/
  cpg_hap1_bw/cpg_hap2_bw) are dropped entirely, with no replacement.
• pbstarphase_tsv output added (PharmCAT-format TSV from StarPhase),
  for consumption by PharmCAT.
• sv_stats_plot output added — a structural variant size-distribution
  plot (DEL/INS/DUP/INV, binned by length), rendered by the existing
  bcftools sv_stats task alongside its per-type counts.

New inputs

family/singleton:

Input	Type	Default	Description
ref_name	String	"GRCh38_GIABv3"	Reference genome to use for this workflow run. Choices: GRCh38, GRCh38_GIABv3. Resolved via the container manifest into ref FASTA/index and the other per-reference files below.
trgt_tandem_repeat_bed_override	File?	none	Optional BED file to override the default TRGT tandem repeat catalog.
methbat_region_tsv_override	File?	none	Optional TSV file to override the default MethBat methylation profiling regions.
use_alignment_chunking	Boolean	true	Whether to chunk BAM files for alignment. If false, all reads are aligned in a single chunk. Chunking is always skipped when hifi_reads BAMs are already aligned.

New default reference option: GRCh38_GIABv3

ref_name can now be set to GRCh38_GIABv3, a GIAB-curated GRCh38 assembly
that patches several regions with known issues in the standard GRCh38
reference. See the GIAB mapping references README, Wagner et al. 2023, Genome Biology, and this genomeref.blogspot.com post for details.
ref_name defaults to "GRCh38_GIABv3", but can be set to "GRCh38" to use the standard GRCh38 assembly instead.

Resource tuning

• deepvariant_call_variants_cpu: default mem_gb 256 -> 28.
• deepvariant_call_variants_gpu: default mem_gb 32 → 44.
• deepvariant_postprocess_variants: default threads 2 → 8, mem_gb
  72 → 48.
• consolidate_stats: default threads 1 → 2, mem_gb 1 → 4.

Tool/container version bumps

• All containers updated to htslib/samtools/bcftools 1.23.1, Python
  3.14.5, and newer versions of their Python library dependencies.
• hiphase → 1.7.0
• paraphase → 4.0.0
• pbstarphase → 2.2.0 (PharmCAT-format output file renamed
  *.pharmcat.tsv → *.pbstarphase.tsv; PGx DB bumped 20260324 → 20260724)
• trgt → 5.1.0
• mosdepth → 0.3.14
• pbmm2 → 26.2.99
• kivvi → 1.1.0
• mitorsaw → 0.2.13

Docs / tooling

• Added docs/tools.md — a "Key Tools" reference page linking out to each
  pipeline tool's own documentation, cross-referenced from
  Tool versions and Containers for pinned versions/digests.
  docs/tools_containers.md now links each pinned tool to its GitHub
  release tag and cross-links back to the new page.
• More additions and improvements to docs to come in next minor release,
  including guidance for AWS HealthOmics.