Module 5: Subtractive Assembly¶

module_5_subassembly.nf maps Module 1 trimmed reads against the Module 4 refined MAG reference, assembles the unmapped reads, optionally bins the new assemblies, and performs a final joint Module 4 refinement. It then publishes a single final MAG database for downstream modules.

Workflow Stages¶

The workflow runs these stages in order:

1. Check or install the Module 5 tools.
2. Build a combined FASTA reference from the Module 4 refined MAG manifest.
3. Map each Module 1 sample to that reference with BBMap and retain unmapped reads.
4. Run the selected subtractive assemblers for each sample. MEGAHIT uses assembly strategy E; metaSPAdes uses strategy F.
5. Write subtractive mapping, assembly, and Module 3-compatible manifests.
6. If enabled, run a second Module 3 binning pass on the subtractive assemblies.
7. Combine the original and subtractive binning manifests and run final joint Module 4 refinement when new bins are available.
8. Build final_mag_database from the final joint refined MAGs, or from the original Module 4 refined MAGs when the second pass is disabled or produces no new MAGs.

Usage¶

Basic local execution:

nextflow run module_5_subassembly.nf \
  --working_dir ./output_samwise \
  --threads 20 \
  --megahit true \
  --metaspades true \
  --secondpass_metabat2 true \
  --secondpass_quickbin true \
  --secondpass_maxbin2 true \
  --run_second_pass_binning_refinement true

The README example also shows --coassembly_groups ./coassembly_manifest.txt. That manifest is a required input for Module 2B grouped co-assembly, not for the current Module 5 implementation: Module 5 does not declare, read, or use coassembly_groups. Supplying it to Module 5 therefore has no effect. Use the Module 2B workflow when grouped co-assemblies are required.

Prerequisites and Manifests¶

By default, Module 5 resolves these inputs under results_dir:

Override these paths with input_trimmed_manifest, input_original_binning_manifest, and input_refined_manifest. Paired reads must provide both read1 and read2; interleaved reads must provide interleaved. Relative FASTA paths in legacy manifests are resolved relative to the workflow launch directory.

The external refinement dependencies are resolved from <samwise_dir>/dependencies unless dependencies_dir is overridden. The TIGRFAM HMM, Pfam HMM, and MAGSCOT script can be supplied explicitly with tigrfam_hmm, pfam_hmm, and magscot_script.

The Module 5 tool environment contains Python, OpenJDK 17, and BBMap, plus MEGAHIT when megahit is enabled and SPAdes/metaSPAdes when metaspades is enabled. With auto_install=true, the workflow creates or repairs this environment with mamba or conda under <outdir>/conda_envs/module5_tools unless tool_env_dir is set.

Assemblers and Second Pass¶

MEGAHIT is enabled by default and metaSPAdes is disabled by default. At least one assembler must be enabled; both may be enabled together. The workflow creates one assembly job per selected assembler and sample. Assembly failures and missing/unusable contigs are recorded in summaries where possible rather than silently treated as successful assemblies.

The second pass is enabled by default and all three binners are enabled by default: MetaBAT2, QuickBin, and MaxBin2. When second pass is enabled, at least one second-pass binner must be selected. Module 3 is run with the subtractive trimmed-read and assembly manifests, and its output is combined with the original Module 3 binning manifest.

If run_second_pass_binning_refinement is false, Module 5 skips second-pass binning and final joint refinement and publishes the original Module 4 refined MAGs to final_mag_database. If second-pass binning has no subtractive assemblies or produces no new bins, the original bins are also used as the final database. A second-pass nonzero Module 3 exit is treated as non-fatal when it produces no bins; it is fatal when it produces bins but fails.

Parameters¶

SLURM Scheduler Options¶

Use the opt-in profile with -c bin/module_5_slurm.config:

nextflow run module_5_subassembly.nf \
  -c bin/module_5_slurm.config \
  --working_dir ./output_samwise \
  --slurm_account ChargeAccountID \
  --max_parallel_subassembly 8 \
  --threads 36 \
  --megahit true --metaspades true

The profile supports these scheduler parameters:

Only MAP_READS_TO_REFINED_MAGS and ASSEMBLE_SUBTRACTIVE use SLURM in this profile. Setup, reference preparation, summaries, manifest combination, and final MAG publication are local. Second-pass binning and final joint refinement are also local and use --threads on the launch host. The profile does not set a Nextflow memory directive; keep metaspades_memory_gb and bbmap_xmx within the node memory available to each task.

Outputs and Manifests¶

Module 5 publishes outputs below <outdir>:

The final database manifest is the downstream publication contract. Its final_database_mode is final_joint_refinement when new bins were refined, or original_refined_mags_only when the original Module 4 MAGs were used.

Validation and Fallback¶

final_mag_database/ is populated from the manifest selected by the final joint-refinement status. A completed status selects <final_joint_dir>/module_4_binrefinement/summary/magscot_refined_bins_manifest.tsv; skipped_no_new_mags, skipped_no_bins, or skipped_second_pass_disabled selects the original Module 4 manifest at <module4_outdir>/summary/magscot_refined_bins_manifest.tsv. A failed final joint refinement is fatal and does not fall back to an older MAG set.

The durable publication is performed after the build process by Nextflow's publishDir. If the published directory is unexpectedly empty, treat the publication as incomplete: check summary/final_mag_database_manifest.tsv, summary/final_mag_database_stats.tsv, and build_final_mag_database.log, then inspect the selected source manifest and its referenced FASTAs. Do not assume that an empty publication should be replaced with the final-joint tree. Module 6 independently falls back to Module 4 refined_bins only when Module 5's published directory is absent or contains no FASTAs; it does not use the final-joint tree as a special Module 5 fallback.