taf-haphic

TAFFISH wrapper for HapHiC, a fast, reference-independent, allele-aware Hi-C scaffolding tool for constructing chromosome-scale pseudomolecules from haplotype-resolved or collapsed genome assemblies.

This app packages HapHiC 1.0.7 and exposes the upstream haphic command through the versioned taf-haphic wrapper.

Release 1.0.7-r2 is a help-only TAFFISH update. It keeps the upstream software, Dockerfile, runtime dependencies, smoke tests, and command behavior unchanged from 1.0.7-r1, and refreshes the terminal taf-haphic --help text.

Installation

Install from the public TAFFISH Hub index:

taf update
taf install haphic

Install the exact release:

taf install haphic 1.0.7-r2

For local testing before publication:

taf install --from .

Usage

Show TAFFISH app help:

taf-haphic --help

Show the TAFFISH package version:

taf-haphic --version

Show upstream HapHiC help or version:

taf-haphic haphic --help
taf-haphic haphic --version

Check the bundled Python dependency stack:

taf-haphic haphic check

Because this app uses TAFFISH command mode, the first non-option argument is treated as the command to run inside the container. Since HapHiC itself is subcommand-driven, the recommended form is:

taf-haphic haphic <haphic-subcommand> [options...]

Use this form for HapHiC subcommands:

taf-haphic haphic pipeline asm.fa HiC.filtered.bam nchrs
taf-haphic haphic cluster asm.fa HiC.filtered.bam nchrs
taf-haphic haphic reassign asm.fa full_links.pkl mcl_inflation_1.2.clusters.txt paired_links.clm --nclusters nchrs
taf-haphic haphic sort asm.fa HT_links.pkl split_clms final_groups/group*.txt --processes 8
taf-haphic haphic build asm.fa asm.fa HiC.filtered.bam final_tours/group*.tour
taf-haphic haphic plot scaffolds.raw.agp HiC.filtered.bam
taf-haphic haphic refsort scaffolds.raw.agp asm_to_ref.paf > scaffolds.refsort.agp

Do not use taf-haphic pipeline ... as the normal form. In command mode, pipeline would be interpreted as an executable inside the container, not as a subcommand of haphic.

Included Functionality

The image includes:

haphic command and scripts
bundled modified ALLHiC executable
bundled HapHiC filter_bam, agp_to_fasta, and juicer utilities
bundled juicer_tools.1.9.9_jcuda.0.8.jar
Python 3.10 dependency stack recommended by upstream
samtools and Java for generated Juicebox helper scripts

Core HapHiC commands:

pipeline   one-command scaffolding workflow
cluster    Step 1: preprocessing and Markov clustering
reassign   Step 2: reassignment and rescue of contigs
sort       Step 3: ordering and orientation, with bundled ALLHiC optimization
build      Step 4: final scaffold/AGP/FASTA construction
plot       Hi-C contact map visualization
refsort    order/orient whole scaffolds for display using a reference PAF
check      dependency check
juicer     print guide for Juicebox visualization
allhic     call the bundled modified ALLHiC executable

Bundled utilities can be accessed through TAFFISH command mode:

taf-haphic filter_bam HiC.bam 1 --nm 3 --threads 8
taf-haphic mock_agp_file.py scaffolds.fa > scaffolds.agp
taf-haphic agp_to_fasta scaffolds.agp asm.fa > scaffolds.fa
taf-haphic juicer
taf-haphic allhic

Input Preparation

HapHiC expects a genome assembly FASTA and filtered Hi-C alignments in BAM, pairs, or bgzipped pairs format. Upstream recommends aligning Hi-C reads with BWA, removing duplicates with samblaster, and filtering with filter_bam.

This image includes HapHiC's own filter_bam, plus samtools for common BAM handling and generated Juicebox scripts. It does not bundle BWA, samblaster, chromap, minimap2, or wfmash. Those are separate alignment or preprocessing tools and can be composed explicitly with other TAFFISH apps or site-local software.

Example input-preparation sketch:

taf-bwa bwa index asm.fa
taf-bwa bwa mem -5SP -t 28 asm.fa read1.fq.gz read2.fq.gz \
  | samblaster \
  | taf-samtools samtools view - -@ 14 -S -h -b -F 3340 -o HiC.bam

taf-haphic filter_bam HiC.bam 1 --nm 3 --threads 14 \
  | taf-samtools samtools view - -b -@ 14 -o HiC.filtered.bam

Keep HapHiC's upstream warning in mind: the BAM should not be coordinate-sorted. If needed, resort by read name before running HapHiC.

Boundaries

This baseline image does not include:

BWA or samblaster for Hi-C read alignment
chromap for pairs-format generation
minimap2 or wfmash for generating refsort PAF files
3D-DNA, matlock, or external Juicebox scripts
Juicebox GUI/manual curation environment
uplot or jcvi for optional utility/simulation scripts
native linux/arm64 builds

These are not hidden dependencies of the packaged haphic command itself. They are upstream-adjacent input-preparation, visualization, benchmarking, or manual-curation tools. Use separate TAFFISH apps, site-local software, or future dedicated wrappers when those steps are needed.

Platform

This release is native linux/amd64 only. HapHiC 1.0.7 bundles several prebuilt x86-64 executables, including scripts/allhic, utils/filter_bam, utils/agp_to_fasta, and utils/juicer, and its recommended dependency stack uses MKL through sparse_dot_mkl.

For Docker and Podman, this app declares --platform linux/amd64 in src/main.taf. On Apple Silicon or other arm64 hosts, the normal command can therefore use Docker/Podman amd64 emulation without a per-run platform override:

TAFFISH_CONTAINER_BACKEND=docker \
taf-haphic haphic --version

For Podman:

TAFFISH_CONTAINER_BACKEND=podman \
taf-haphic haphic --version

This is compatibility emulation, not native linux/arm64 support. The global TAFFISH_DOCKER_RUN_ARGS and TAFFISH_PODMAN_RUN_ARGS variables are still available for local debugging or site policy, but they are not required for this app's default Docker/Podman path. Apptainer compatibility depends on the host and site configuration.

Package

name: haphic
command: taf-haphic
version: 1.0.7-r2
kind: tool
image: ghcr.io/taffish/haphic:1.0.7-r2
native platforms: linux/amd64

Validation

The smoke metadata checks:

exist: haphic, allhic, filter_bam, agp_to_fasta, juicer, mock_agp_file.py,
       python3, samtools, java
test:  haphic reports version 1.0.7
test:  haphic check imports the dependency stack
test:  core subcommand help is available
test:  mock_agp_file.py creates a small AGP file
test:  haphic refsort processes a tiny AGP/PAF/FASTA example

These checks verify the packaged command, Python dependencies, bundled helper executables, plotting/refsort command surfaces, and a small real file-processing path. They do not replace full scaffolding validation on real Hi-C data.

Upstream

• Homepage: https://github.com/zengxiaofei/HapHiC
• Source and releases: https://github.com/zengxiaofei/HapHiC
• Release: https://github.com/zengxiaofei/HapHiC/releases/tag/v1.0.7
• License: BSD-3-Clause
• Citation: Zeng et al. 2024, Nature Plants
• DOI: 10.1038/s41477-024-01755-3
• PMID: 39103456

If you use the bundled ALLHiC optimization path, also cite ALLHiC as requested by the HapHiC upstream documentation.