diff --git a/CommandLines.cpp b/CommandLines.cpp index 1da7d60..a8becb0 100644 --- a/CommandLines.cpp +++ b/CommandLines.cpp @@ -66,16 +66,16 @@ void Print_H(hifiasm_opt_t* asm_opt) fprintf(stderr, " -D FLOAT drop k-mers occurring >FLOAT*coverage times [%.1f]\n", asm_opt->high_factor); fprintf(stderr, " -N INT consider up to max(-D*coverage,-N) overlaps for each oriented read [%d]\n", asm_opt->max_n_chain); fprintf(stderr, " -r INT round of correction [%d]\n", asm_opt->number_of_round); + fprintf(stderr, " -z INT length of adapters that should be removed [%d]\n", asm_opt->adapterLen); fprintf(stderr, " Assembly:\n"); fprintf(stderr, " -a INT round of assembly cleaning [%d]\n", asm_opt->clean_round); - fprintf(stderr, " -z INT length of adapters that should be removed [%d]\n", asm_opt->adapterLen); fprintf(stderr, " -m INT pop bubbles of large_pop_bubble_size); fprintf(stderr, " -p INT pop bubbles of small_pop_bubble_size); fprintf(stderr, " -n INT remove tip unitigs composed of <=INT reads [%d]\n", asm_opt->max_short_tip); fprintf(stderr, " -x FLOAT max overlap drop ratio [%.2g]\n", asm_opt->max_drop_rate); fprintf(stderr, " -y FLOAT min overlap drop ratio [%.2g]\n", asm_opt->min_drop_rate); fprintf(stderr, " -i ignore saved read correction and overlaps\n"); - fprintf(stderr, " -u disable post join contigs step which may improve N50\n"); + fprintf(stderr, " -u disable post-join step for contigs which may improve N50\n"); fprintf(stderr, " --hom-cov INT\n"); fprintf(stderr, " homozygous read coverage [auto]\n"); fprintf(stderr, " --lowQ INT\n"); @@ -95,12 +95,12 @@ void Print_H(hifiasm_opt_t* asm_opt) fprintf(stderr, " Trio-partition:\n"); fprintf(stderr, " -1 FILE hap1/paternal k-mer dump generated by \"yak count\" []\n"); fprintf(stderr, " -2 FILE hap2/maternal k-mer dump generated by \"yak count\" []\n"); + fprintf(stderr, " -3 FILE list of hap1/paternal read names []\n"); + fprintf(stderr, " -4 FILE list of hap2/maternal read names []\n"); fprintf(stderr, " -c INT lower bound of the binned k-mer's frequency [%d]\n", asm_opt->min_cnt); fprintf(stderr, " -d INT upper bound of the binned k-mer's frequency [%d]\n", asm_opt->mid_cnt); - fprintf(stderr, " -3 FILE list of hap1/paternal read names []\n"); - fprintf(stderr, " -4 FILE list of hap2/maternal read names []\n"); fprintf(stderr, " --t-occ INT\n"); - fprintf(stderr, " force remove unitigs with >INT unexpected haplotype-specific reads;\n"); + fprintf(stderr, " forcedly remove unitigs with >INT unexpected haplotype-specific reads;\n"); fprintf(stderr, " ignore graph topology; [%d]\n", asm_opt->trio_flag_occ_thres); fprintf(stderr, " Purge-dups:\n"); @@ -131,7 +131,7 @@ void Print_H(hifiasm_opt_t* asm_opt) fprintf(stderr, " detect misjoined unitigs of >=INT in size; 0 to disable [%lu]\n", asm_opt->misjoin_len); fprintf(stderr, "Example: ./hifiasm -o NA12878.asm -t 32 NA12878.fq.gz\n"); - fprintf(stderr, "See `man ./hifiasm.1' for detailed description of these command-line options.\n"); + fprintf(stderr, "See `https://hifiasm.readthedocs.io/en/latest/' or `man ./hifiasm.1' for complete documentation.\n"); } void init_opt(hifiasm_opt_t* asm_opt) diff --git a/CommandLines.h b/CommandLines.h index 6c285c2..94417a4 100644 --- a/CommandLines.h +++ b/CommandLines.h @@ -4,7 +4,7 @@ #include #include -#define HA_VERSION "0.15.4-r349" +#define HA_VERSION "0.15.5-r350" #define VERBOSE 0 diff --git a/Purge_Dups.cpp b/Purge_Dups.cpp index 269cc9c..00c1887 100644 --- a/Purge_Dups.cpp +++ b/Purge_Dups.cpp @@ -5267,11 +5267,7 @@ uint32_t just_coverage, hap_cov_t *cov, uint32_t collect_p_trans, uint32_t colle hap_alignment_struct_pip hap_buf; long long k_mer_only, coverage_only; - if(asm_opt.pur_global_coverage != -1) - { - hap_buf.cov_threshold = asm_opt.pur_global_coverage; - } - else if(asm_opt.hom_global_coverage != -1) + if(asm_opt.hom_global_coverage != -1) { hap_buf.cov_threshold = (asm_opt.hom_global_coverage_set? (((double)asm_opt.hom_global_coverage)*((double)HOM_PEAK_RATE)):(asm_opt.hom_global_coverage)); @@ -5325,6 +5321,9 @@ uint32_t just_coverage, hap_cov_t *cov, uint32_t collect_p_trans, uint32_t colle } } if(asm_opt.hom_global_coverage == -1) asm_opt.hom_global_coverage = hap_buf.cov_threshold; + if(asm_opt.pur_global_coverage != -1) hap_buf.cov_threshold = asm_opt.pur_global_coverage; + fprintf(stderr, "[M::%s] homozygous read coverage threshold: %d\n", __func__, asm_opt.hom_global_coverage_set? + asm_opt.hom_global_coverage:(int)(((double)asm_opt.hom_global_coverage)/((double)HOM_PEAK_RATE))); fprintf(stderr, "[M::%s] purge duplication coverage threshold: %lld\n", __func__, hap_buf.cov_threshold); if(just_coverage) goto end_coverage; diff --git a/README.md b/README.md index 5d1a13c..13dd3b3 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ cd hifiasm && make # Run on test data (use -f0 for small datasets) wget https://github.com/chhylp123/hifiasm/releases/download/v0.7/chr11-2M.fa.gz ./hifiasm -o test -t4 -f0 chr11-2M.fa.gz 2> test.log -awk '/^S/{print ">"$2;print $3}' test.p_ctg.gfa > test.p_ctg.fa # get primary contigs in FASTA +awk '/^S/{print ">"$2;print $3}' test.bp.p_ctg.gfa > test.p_ctg.fa # get primary contigs in FASTA # Assemble inbred/homozygous genomes (-l0 disables duplication purging) hifiasm -o CHM13.asm -t32 -l0 CHM13-HiFi.fa.gz 2> CHM13.asm.log @@ -81,8 +81,8 @@ hifiasm -o NA12878.asm -t 32 NA12878.fq.gz ``` where `NA12878.fq.gz` provides the input reads, `-t` sets the number of CPUs in use and `-o` specifies the prefix of output files. For this example, the -primary contigs are written to `NA12878.asm.bp.p_ctg.gfa` and alternate contigs to -`NA12878.asm.bp.a_ctg.gfa`. Since v0.15, hifiasm also produces two sets of +primary contigs are written to `NA12878.asm.bp.p_ctg.gfa`. +Since v0.15, hifiasm also produces two sets of partially phased contigs at `NA12878.asm.bp.hap?.p_ctg.gfa`. This pair of files can be thought to represent the two haplotypes in a diploid genome, though with occasional switch errors. The frequency of switches is determined by the @@ -116,8 +116,8 @@ In this mode, each contig is supposed to be a haplotig, which by definition comes from one parental haplotype only. Hifiasm often puts all contigs from the same parental chromosome in one assembly. It has cleanly separated chrX and chrY for a human male dataset. Nonetheless, phasing across centromeres is -challenging. Users should not expect hifiasm to phase entire chromosomes at the -moment. Also, contigs from different parental chromosomes are randomly mixed as +challenging. Hifiasm is often able to phase entire chromosomes but it may fail +in rare cases. Also, contigs from different parental chromosomes are randomly mixed as it is just not possible to phase across chromosomes with Hi-C. Hifiasm does not perform scaffolding for now. You need to run a standalone @@ -133,7 +133,7 @@ yak count -k31 -b37 -t16 -o pat.yak paternal.fq.gz yak count -k31 -b37 -t16 -o mat.yak maternal.fq.gz hifiasm -o NA12878.asm -t 32 -1 pat.yak -2 mat.yak NA12878.fq.gz ``` -Here `NA12878.asm.hap1.p_ctg.gfa` and `NA12878.asm.hap2.p_ctg.gfa` give the two +Here `NA12878.asm.dip.hap1.p_ctg.gfa` and `NA12878.asm.dip.hap2.p_ctg.gfa` give the two haplotype assemblies. In the binning mode, hifiasm does not purge haplotig duplicates by default. Because hifiasm reuses saved overlaps, you can generate both primary/alternate assemblies and trio binning assemblies with @@ -145,32 +145,10 @@ The second command line will run much faster than the first. ### Output files -For non-trio assembly, hifiasm generates the following files: - -1. Haplotype-resolved raw [unitig][unitig] graph in [GFA][gfa] format - (*prefix*.r\_utg.gfa). This graph keeps all haplotype information, including - somatic mutations and recurrent sequencing errors. -2. Haplotype-resolved processed unitig graph without small bubbles - (*prefix*.p\_utg.gfa). Small bubbles might be caused by somatic mutations or noise in data, - which are not the real haplotype information. -3. Primary assembly [contig][unitig] graph (*prefix*.p\_ctg.gfa). This graph collapses different - haplotypes. -4. Alternate assembly contig graph (*prefix*.a\_ctg.gfa). This graph consists of all assemblies that - are discarded in primary contig graph. - -For trio assembly, hifiasm generates the following files: - -1. Haplotype-resolved raw [unitig][unitig] graph in [GFA][gfa] format - (*prefix*.r\_utg.gfa). This graph keeps all haplotype information. - -2. Phased paternal/haplotype1 contig graph (*prefix*.hap1.p\_ctg.gfa). This graph keeps the phased - paternal/haplotype1 assembly. - -3. Phased maternal/haplotype2 contig graph (*prefix*.hap2.p\_ctg.gfa). This graph keeps the phased - maternal/haplotype2 assembly. - -Hifiasm writes error corrected reads to the *prefix*.ec.bin binary file and +Hifiasm generates different types of assemblies based on the input data. +It also writes error corrected reads to the *prefix*.ec.bin binary file and writes overlaps to *prefix*.ovlp.source.bin and *prefix*.ovlp.reverse.bin. +For more details, please see the complete [documentation][tutorial_output]. ## Results @@ -226,6 +204,8 @@ non-human ones are available [here][zenodo-nonh]. [paf]: https://github.com/lh3/miniasm/blob/master/PAF.md [yak]: https://github.com/lh3/yak [tutorial]: https://hifiasm.readthedocs.io/en/latest/index.html +[tutorial_output]: https://hifiasm.readthedocs.io/en/latest/interpreting-output.html#interpreting-output + ## Getting Help diff --git a/docs/source/conf.py b/docs/source/conf.py index 6311774..4a4f792 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -38,7 +38,7 @@ copyright = u'2021, Haoyu Cheng, Heng Li' # built documents. # # The short X.Y version. -version = '0.15.5-r348' +version = '0.15.5-r350' # The full version, including alpha/beta/rc tags. release = '0.15.5' diff --git a/docs/source/faq.rst b/docs/source/faq.rst index 0ec25c7..5ca9a2b 100644 --- a/docs/source/faq.rst +++ b/docs/source/faq.rst @@ -34,19 +34,19 @@ Are diploid genomes supported? Are polyploid genomes supported? ------------------------------------- - The ``*r_utg.gfa`` and ``*p_utg.gfa`` are lossless so that they also work for polyploid genomes. However, currently the contig-generation modules of hifiasm are designed for diploid samples, which means both the partially phased assembly and the fully-phased assembly does not directly support polyploid genomes. Please use primary assembly for polyploid samples and run multiple rounds of purging steps using third-party tools such as purge_dups. + The ``*r_utg.gfa`` and ``*p_utg.gfa`` are lossless so that they also work for polyploid genomes. However, currently the contig-generation modules of hifiasm are designed for diploid samples, which means both the partially phased assembly and the fully-phased assembly does not directly support polyploid genomes. If it is set to >2, the quality of primary assembly for polyploid genomes might be improved. Please use primary assembly for polyploid samples and run multiple rounds of purging steps using third-party tools such as purge_dups. Why one Hi-C integrated assembly is larger than another one? ------------------------------------------------------------ For some samples like human male, the paternal haplotype should be larger than the maternal haplotype. However, if one assembly is much larger than another one, it should be the issues of hifiasm. To fix it, please set smaller value for ``-s`` (default: 0.55). - Another possibility is that hifiasm misidentifies coverage threshold for homozygous reads. For instance, hifiasm prints the following information during assembly without setting the option ``--purge-cov``: + Another possibility is that hifiasm misidentifies coverage threshold for homozygous reads. For instance, hifiasm prints the following information during assembly: :: - [M::purge_dups] purge duplication coverage threshold: 46 + [M::purge_dups] purge duplication coverage threshold: 36 - In this example, hifiasm identifies the coverage threshold for homozygous reads as ``46/1.25 = 36``. If it is significantly smaller than the homozygous coverage peak, hifiasm will generate two unbalanced assemblies. In this case, please set ``--purge-cov`` to homozygous coverage peak. Please note that tuning ``--purge-cov`` may affect ``*p_utg*gfa`` so that ``*hic*.bin`` should be deleted. Since v0.15.5, hifiasm can detect such changes and renew Hi-C bin files automatically. + In this example, hifiasm identifies the coverage threshold for homozygous reads as ``36``. If it is significantly smaller than the homozygous coverage peak, hifiasm will generate two unbalanced assemblies. In this case, please set ``--hom-cov`` to homozygous coverage peak. Please note that tuning ``--hom-cov`` may affect ``*p_utg*gfa`` so that ``*hic*.bin`` should be deleted. Since v0.15.5, hifiasm can detect such changes and renew Hi-C bin files automatically. @@ -57,12 +57,12 @@ For Hi-C integrated assembly, why the assembly size of both haplotypes are much [M::stat] # heterozygous bases: 645155110; # homozygous bases: 1495396634 - If most bases of a diploid sample are homozygous, the coverage threshold is wrongly determined by hifiasm. For instance, hifiasm prints the following information during assembly without setting the option ``--purge-cov``: + If most bases of a diploid sample are homozygous, the coverage threshold is wrongly determined by hifiasm. For instance, hifiasm prints the following information during assembly: :: - [M::purge_dups] purge duplication coverage threshold: 46 + [M::purge_dups] purge duplication coverage threshold: 36 - In this example, hifiasm identifies the coverage threshold for homozygous reads as ``46/1.25 = 36``. If it is much smaller than homozygous coverage peak, hifiasm thinks most reads are homozygous and assign them to both assemblies, making both of them much larger than the estimated haploid genome size. In this case, please set ``--purge-cov`` to homozygous coverage peak. Please note that tuning ``--purge-cov`` may affect ``*p_utg*gfa`` so that ``*hic*.bin`` should be deleted. Since v0.15.5, hifiasm can detect such changes and renew Hi-C bin files automatically. + In this example, hifiasm identifies the coverage threshold for homozygous reads as ``36``. If it is much smaller than homozygous coverage peak, hifiasm thinks most reads are homozygous and assign them to both assemblies, making both of them much larger than the estimated haploid genome size. In this case, please set ``--hom-cov`` to homozygous coverage peak. Please note that tuning ``--hom-cov`` may affect ``*p_utg*gfa`` so that ``*hic*.bin`` should be deleted. Since v0.15.5, hifiasm can detect such changes and renew Hi-C bin files automatically. .. _hic-iss: @@ -80,10 +80,14 @@ Why the size of primary assembly or partially phased assembly is much larger tha It could be because the estimated genome size is incorrect. Another possibility is that hifiasm does not perform enough purging. Setting smaller value for ``-s`` (default: 0.55) or turning ``--purge-cov`` should be helpful. See :ref:`loginter` for more details. +.. _p-hamming: + Why the hamming error rate or the swith error rate of trio-binning assembly is very high? --------------------------------------------------------------------------------------------------------------- In rare cases, a potential issue is that a few contigs may misjoin two haplotypes. For example, half of a contig come from mother while another half come from father. Such misjoined contigs can be fixed by manually breaking. The coordinates of problematic regions can be found by A-lines in GFA file or ``yak trioeval -e`` (see `issue 37 `_ for more details). However, if there are many misjoined contigs or the switch/hamming error rate reported by ``yak trioeval`` is very high, users should check if the parental data is correct (see `issue 130 `_ for more details). + Another possibility is that there are some unitigs in unitig graph misjoining two haplotypes. Such problematic unitigs might be ignored by the graph-binning strategy. Set smaller value for ``--t-occ`` forcedly remove unitig including unexpected haplotype-specific reads. + Why does hifiasm stuck or crash? ------------------------------------- In most cases, it is caused by the low quality HiFi reads. A good HiFi dataset should have a k-mer plot like `issue10 `_ or `issue49 `_. In contrast, low quality HiFi data often lead to weird k-mer plot like `issue93 `_. Such weird k-mer plots usually indicate insufficient coverage or presence of contaminants. See :ref:`loginter` for more details. If the HiFi data look fine, please raise an issue at the `issue page `_. @@ -98,7 +102,7 @@ Can I generate HiFi-only assembly first, and then add Hi-C or trio data later? What is the minimum read coverage required for hifiasm? ------------------------------------------------------- - Usually >=14x HiFi reads per haplotype. Higher coverage might be able to improve the contiguity of assembly. + Usually >=13x HiFi reads per haplotype. Higher coverage might be able to improve the contiguity of assembly. Why the primary assembly is more contiguous than the fully-phased assemblies and the partially phased assemblies (i.e. ``*.hap*.p_ctg.gfa``)? ---------------------------------------------------------------------------------------------------------------------------------------------------- @@ -107,3 +111,13 @@ Why the primary assembly is more contiguous than the fully-phased assemblies and When producing fully-phased assemblies and partially phased assemblies, hifiasm is designed to keep both haplotypes contiguous. It is important for many downstream applications like SV calling. +My assembly is fragmented or not contiguous enough, how do I improve it? +-------------------------------------------------------------------------- + + Raising ``-D`` or ``-N`` may improve the resolution of repetitive regions but takes longer time. These two options affect all types of assemblies and usually do not have a negative impact on the assembly quality. In contrast, ``--purge-max`` only affects primary assembly. Setting larger value for ``--purge-max`` makes primary assembly more contiguous but may collapse repeats or segmental duplications. + + If the assembly is too fragmented, users should check if HiFi data is good enough. See `Why does hifiasm stuck or crash?`_ for details. + +How do I avoid misassemblies? +-------------------------------------------------------------------------- + Set smaller value for ``--purge-max``, ``-s`` and ``-O``, or use the ``-u`` option. \ No newline at end of file diff --git a/docs/source/hic-assembly.rst b/docs/source/hic-assembly.rst index e395356..46b7854 100644 --- a/docs/source/hic-assembly.rst +++ b/docs/source/hic-assembly.rst @@ -11,6 +11,6 @@ Hifiasm can generate a pair of haplotype-resolved assemblies with paired-end Hi- In this mode, each contig is supposed to be a haplotig, which by definition comes from one parental haplotype only. Hifiasm often puts all contigs from the same parental chromosome in one assembly. It has cleanly separated chrX and chrY for a human male dataset. Nonetheless, phasing across centromeres is challenging. Hifiasm is often able to phase entire chromosomes but it may fail in rare cases. Also, contigs from different parental chromosomes are randomly mixed as it is just not possible to phase across chromosomes with Hi-C. Hifiasm does not perform scaffolding for now. You need to run a standalone scaffolder such as SALSA or 3D-DNA to scaffold phased haplotigs. -For samples with high heterozygosity rate, a common issue is that one assembly is much larger than another one. To fix this issue, please set smaller value for ``-s`` (default: 0.55). Another possibility is that hifiasm misidentifies coverage threshold for homozygous reads. In this case, please set ``--purge-cov`` to homozygous coverage peak. See :ref:`hic-iss` for more details. +For samples with high heterozygosity rate, a common issue is that one assembly is much larger than another one. To fix this issue, please set smaller value for ``-s`` (default: 0.55). Another possibility is that hifiasm misidentifies coverage threshold for homozygous reads. In this case, please set ``--hom-cov`` to homozygous coverage peak. See :ref:`hic-iss` for more details. At the first run, hifiasm saves the alignment of Hi-C reads to disk as ``*hic*.bin``. It reuses the saved results to avoid Hi-C alignment next time. Please note that ``*hic*.bin`` should be deleted when tuning any parameters affecting ``*p_utg*gfa``. Since v0.15.5, hifiasm can detect such changes and renew Hi-C bin files automatically. There are several parameters which do not change ``*p_utg*gfa``, including ``-s``, ``--seed``, ``--n-weight``, ``--n-perturb``, ``--f-perturb`` and ``--l-msjoin``. diff --git a/docs/source/interpreting-output.rst b/docs/source/interpreting-output.rst index 828746a..0b10c5c 100644 --- a/docs/source/interpreting-output.rst +++ b/docs/source/interpreting-output.rst @@ -12,9 +12,9 @@ Output files In general, hifiasm generates the following assembly graphs in the GFA format: * ```prefix`.r_utg.gfa``: haplotype-resolved raw unitig graph. This graph keeps all haplotype information. -* ```prefix`.p_utg.gfa``: haplotype-resolved processed unitig graph without small bubbles. Small bubbles might be caused by somatic mutations or noise in data, which are not the real haplotype information. Hifiasm automatically pops such small bubbles based on coverage. The option ``--purge-cov`` affects the result. See :ref:`homozygous coverage setting ` for more details. In addition, the option ``-p`` forcedly pops bubbles. +* ```prefix`.p_utg.gfa``: haplotype-resolved processed unitig graph without small bubbles. Small bubbles might be caused by somatic mutations or noise in data, which are not the real haplotype information. Hifiasm automatically pops such small bubbles based on coverage. The option ``--hom-cov`` affects the result. See :ref:`homozygous coverage setting ` for more details. In addition, the option ``-p`` forcedly pops bubbles. * ```prefix`.p_ctg.gfa``: assembly graph of primary contigs. This graph includes a complete assembly with long stretches of phased blocks. -* ```prefix`.a_ctg.gfa``: assembly graph of alternate contigs. This graph consists of all assemblies that are discarded in primary contig graph. +* ```prefix`.a_ctg.gfa``: assembly graph of alternate contigs. This graph consists of all contigs that are discarded in primary contig graph. * ```prefix`.*hap*.p_ctg.gfa``: phased contig graph. This graph keeps the phased contigs. @@ -98,5 +98,5 @@ Hifiasm prints several information for quick debugging, including: .. _homcov: * k-mer plot: showing how many k-mers appear a certain number of times. For homozygous samples, there should be one peak around read coverage. For heterozygous samples, there should two peaks, where the smaller peak is around the heterozygous read coverage and the larger peak is around the homozygous read coverage. For example, `issue10 `_ indicates the heterozygous read coverage and the homozygous read coverage are 28 and 57, respectively. `Issue49 `_ is another good example. Weird k-mer plot like `issue93 `_ is often caused by insufficient coverage or presence of contaminants. -* homozygous coverage: coverage threshold for homozygous reads. Hifiasm prints it as: ``[M::purge_dups] purge duplication coverage threshold: X``. Without setting the option ``--purge-cov``, the homozygous coverage threshold determined by hifiasm is: ``X/1.25``. If it is not around homozygous coverage, the final assembly might be either too large or too small. To fix this issue, please set ``--purge-cov`` to homozygous coverage. -* number of het/hom bases: how many bases in unitig graph are heterozygous and homozygous during Hi-C phased assembly. Hifiasm prints it as: ``[M::stat] # heterozygous bases: X; # homozygous bases: Y``. Given a heterozygous sample, if there are much more homozygous bases than heterozygous bases, hifiasm fails to identify correct coverage threshold for homozygous reads. In this case, please set ``--purge-cov`` to homozygous coverage. +* homozygous coverage: coverage threshold for homozygous reads. Hifiasm prints it as: ``[M::purge_dups] homozygous read coverage threshold: X``. If it is not around homozygous coverage, the final assembly might be either too large or too small. To fix this issue, please set ``--hom-cov`` to homozygous coverage. +* number of het/hom bases: how many bases in unitig graph are heterozygous and homozygous during Hi-C phased assembly. Hifiasm prints it as: ``[M::stat] # heterozygous bases: X; # homozygous bases: Y``. Given a heterozygous sample, if there are much more homozygous bases than heterozygous bases, hifiasm fails to identify correct coverage threshold for homozygous reads. In this case, please set ``--hom-cov`` to homozygous coverage. diff --git a/docs/source/pa-assembly.rst b/docs/source/pa-assembly.rst index 58984b9..c369a09 100644 --- a/docs/source/pa-assembly.rst +++ b/docs/source/pa-assembly.rst @@ -32,7 +32,7 @@ In this example, the partially phased contigs are written to ``NA12878.asm.bp.ha This pair of files can be thought to represent the two haplotypes in a diploid genome, though with occasional switch errors. The frequency of switches is determined by the heterozygosity of the input sample. Hifiasm also writes the primary contigs to ``NA12878.asm.bp.p_ctg.gfa``. For samples with high heterozygosity rate, a common issue is that one set of partially phased contigs is much larger than another set. To fix this issue, please set smaller value for ``-s`` (default: 0.55). Another possibility is that hifiasm misidentifies coverage threshold for homozygous reads. -In this case, please set ``--purge-cov`` to homozygous coverage. See :ref:`p-large` for more details. +In this case, please set ``--hom-cov`` to homozygous coverage. See :ref:`p-large` for more details. Produce primary/alternate assemblies @@ -42,6 +42,6 @@ To get primary/alternate assemblies, the option ``--primary`` should be set:: hifiasm -o NA12878.asm --primary -t 32 NA12878.fq.gz -The primary contigs and the alternate contigs are written to ``NA12878.asm.p_ctg.gfa`` and ``NA12878.asm.a_ctg.gfa``, respectively. For inbred or homozygous genomes, the primary/alternate assemblies can be also produced by ``-l0``. Similarly, turning ``-s`` or ``--purge-cov`` should +The primary contigs and the alternate contigs are written to ``NA12878.asm.p_ctg.gfa`` and ``NA12878.asm.a_ctg.gfa``, respectively. For inbred or homozygous genomes, the primary/alternate assemblies can be also produced by ``-l0``. Similarly, turning ``-s`` or ``--hom-cov`` should be helpful if the primary assembly is too large. See :ref:`p-large` for more details. diff --git a/docs/source/parameter-reference.rst b/docs/source/parameter-reference.rst index 7e124ca..e6b0b96 100644 --- a/docs/source/parameter-reference.rst +++ b/docs/source/parameter-reference.rst @@ -75,17 +75,34 @@ Error correction options .. _fopt: **\-f ** - Number of bits for bloom filter; 0 to disable. This bloom filter is used to filter out singleton k-mers when counting all k-mers. It takes 2\ :sup:`(INT-3)` bytes of memory. A proper setting saves memory. For small genomes, use ``-f0`` to disable the initial bloom filter which takes 16GB memory at the beginning. For genomes much larger than human, applying ``-f38`` or even ``-f39`` is preferred to save memory on k-mer counting. + Number of bits for bloom filter; 0 to disable. This bloom filter is used to filter out singleton k-mers when counting all k-mers. It takes 2\ :sup:`(INT-3)` bytes of memory. A proper setting saves memory. ``-f37`` is recommended for human assembly. For small genomes, use ``-f0`` to disable the initial bloom filter which takes 16GB memory at the beginning. For genomes much larger than human, applying ``-f38`` or even ``-f39`` is preferred to save memory on k-mer counting. + +.. _Dopt: + +**\-D ** + Drop k-mers occurring ``>FLOAT*coverage`` times. Hifiasm discards these high-frequency k-mers during error correction to reduce running time. The ``coverage`` is determined automatically by hifiasm based on k-mer plot, representing homozygous read coverage. Raising this option may improve the resolution of repetitive regions but takes longer time. + +.. _NEopt: + +**\-N ** + Consider up to ``max(-D*coverage,-N)`` overlaps for each oriented read. The ``coverage`` is determined automatically by hifiasm based on k-mer plot, representing homozygous read coverage. Raising this option may improve the resolution of repetitive regions but takes longer time. .. _ropt: **\-r ** Rounds of haplotype-aware error correction. This option affects all outputs of hifiasm. Odd rounds of correction are preferred in practice. + +.. _zopt: + +**\-z ** + Length of adapters that should be removed. This option remove ``INT`` bases from both ends of each read. Some old HiFi reads may consist of short adapters (e.g. 20bp adapter at one end). For such data, trimming short adapters would significantly improve the assembly quality. + + .. _min-hist-cnt-opt: **\-\-min-hist-cnt ** - When analyzing the k-mer spectrum, ignore counts below ``INT``. See `issue 45 `_ for example. + When analyzing the k-mer spectrum, ignore counts below ``INT``. For very low coverage of HiFi data, set smaller value for this option. See `issue 45 `_ for example. @@ -97,10 +114,6 @@ Assembly options **\-a ** Rounds of assembly graph cleaning. This option is used with ``-x`` and ``-y``. Note that unlike -r, this option does not affect error corrected reads and all-to-all overlaps. -.. _zopt: - -**\-z ** - Length of adapters that should be removed. This option remove ``INT`` bases from both ends of each read. Some old HiFi reads may consist of short adapters (e.g. 20bp adapter at one end). For such data, trimming short adapters would significantly improve the assembly quality. .. _mopt: @@ -110,7 +123,7 @@ Assembly options .. _popt: **\-p ** - Maximal probing distance for bubble popping when generating haplotype-resolved processed unitig graph without small bubbles. Bubbles longer than ``INT`` bases will not be popped. Small bubbles might be caused by somatic mutations or noise in data. Please note that hifiasm automatically pops small bubbles based on coverage, which can be tweaked by ``--purge-cov``. + Maximal probing distance for bubble popping when generating haplotype-resolved processed unitig graph without small bubbles. Bubbles longer than ``INT`` bases will not be popped. Small bubbles might be caused by somatic mutations or noise in data. Please note that hifiasm automatically pops small bubbles based on coverage, which can be tweaked by ``--hom-cov``. .. _nopt: @@ -120,13 +133,24 @@ Assembly options .. _xyopt: **\-x , \-y ** - Max and min overlap drop ratio. This option is used with ``-a``. Given a node N in the assembly graph, let max(N) be the length of the largest overlap of N. Hifiasm iteratively drops overlaps of N if their length/max(N) is below a threshold controlled by ``-x`` and ``-y``. Hifiasm applies ``-a`` rounds of short overlap removal with an increasing threshold between ``FLOAT1`` and ``FLOAT2``. + Max and min overlap drop ratio. This option is used with ``-a``. Given a node N in the assembly graph, let max(N) be the length of the longest overlap of N. Hifiasm iteratively drops overlaps of N if their length/max(N) is below a threshold controlled by ``-x`` and ``-y``. Hifiasm applies ``-a`` rounds of short overlap removal with an increasing threshold between ``FLOAT1`` and ``FLOAT2``. .. _iopt: **\-i** Ignore all bin files so that hifiasm will start again from scratch. +.. _uopt: + +**\-u** + Disable post-join step for contigs which may improve N50. The post-join step of hifiasm improves contig N50 but may introduce misassemblies. + + +.. _hom-cov-opt: + +**\-\-hom-cov ** + Homozygous read coverage inferred automatically in default. This option affects different types of outputs, including Hi-C phased assembly and HiFi-only assembly. For more details, see :ref:`hic-iss`, :ref:`p-large` and :ref:`loginter`. + .. _pri-range-opt: **\-\-pri-range ** @@ -186,6 +210,13 @@ Trio-binning options **\-c , -d ** Lower bound and upper bound of the binned k-mer's frequency. When doing trio binning, a k-mer is said to be differentiating if it occurs >= ``INT2`` times in one sample but occurs < ``INT1`` times in the other sample. + +.. _t-occ-opt: + +**\-\-t-occ ** + Forcedly remove unitig including ``>INT`` unexpected haplotype-specific reads without considering graph topology. For more details, see :ref:`p-hamming`. + + Purge duplication options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -206,13 +237,13 @@ Purge duplication options .. _purgeopt: -**\-\-purge-cov ** - Coverage upper bound of purge duplication, which is inferred automatically in default. If the coverage of a contig is higher than this bound, don't apply purge duplication. Moreover, this option also affects Hi-C phased assembly. For more details, see :ref:`hic-iss`, :ref:`p-large` and :ref:`loginter`. +**\-\-purge-max ** + Coverage upper bound of purge duplication, which is inferred automatically in default. If the coverage of a contig is higher than this bound, don't apply purge duplication. Larger value makes assembly more contiguous but may collapse repeats or segmental duplications. .. _nhapopt: **\-\-n\-hap ** - Assumption of haplotype number. + Assumption of haplotype number. If it is set to >2, the quality of primary assembly for polyploid genomes might be improved. @@ -247,4 +278,10 @@ Hi-C integration options .. _seedopt: **\-\-seed ** - RNG seed. \ No newline at end of file + RNG seed. + + +.. _l-msjoin: + +**\-\-l-msjoin ** + Detect misjoined unitigs of ``>=INT`` in size; 0 to disable. diff --git a/docs/source/trio-assembly.rst b/docs/source/trio-assembly.rst index 2533514..17d0391 100644 --- a/docs/source/trio-assembly.rst +++ b/docs/source/trio-assembly.rst @@ -24,8 +24,6 @@ The W-line and H-line reported by ``yak trioeval`` indicate switch error rate an W 26714 3029448 0.008818 H 24315 3029885 0.008025 -For this example, the switch error rate is 0.8818% and the hamming error rate is 0.8025%. +For this example, the switch error rate is 0.8818% and the hamming error rate is 0.8025%. If the hamming error rate or the swith error rate of trio-binning assembly is very high, it might be caused by hifiasm or the incorrect parental data. To fix it, see :ref:`p-hamming` for more details. -In rare cases, a potential issue is that a few contigs may misjoin two haplotypes. For example, half of a contig come from mother while another half come from father. Such misjoined contigs can be fixed by -manually breaking. The coordinates of problematic regions can be found by A-lines in GFA file or ``yak trioeval -e``. However, if there are many misjoined contigs or the switch/hamming error rate reported by ``yak trioeval`` is very high, users should check if the parental data is correct (see `example `_ for more details). diff --git a/hifiasm.1 b/hifiasm.1 index a1afd23..ecda27e 100644 --- a/hifiasm.1 +++ b/hifiasm.1 @@ -1,4 +1,4 @@ -.TH hifiasm 1 "16 April 2021" "hifiasm-0.15 (r327)" "Bioinformatics tools" +.TH hifiasm 1 "25 July 2021" "hifiasm-0.15.5 (r350)" "Bioinformatics tools" .SH NAME .PP @@ -62,7 +62,7 @@ Hifiasm is an ultrafast haplotype-resolved de novo assembler for PacBio Hifi reads. Unlike most existing assemblers, hifiasm starts from uncollapsed genome. Thus, it is able to keep the haplotype information as much as possible. The input of hifiasm is the PacBio Hifi reads in fasta/fastq format, and its -outputs consist of multiple types of assembly graph in GFA format. +outputs consist of multiple types of assembly graphs in GFA format. .SH OPTIONS @@ -104,17 +104,69 @@ Minimizer window size [51]. Number of bits for bloom filter; 0 to disable [37]. This bloom filter is used to filter out singleton k-mers when counting all k-mers. It takes .RI 2^( INT -3) -bytes of memory. A proper setting saves memory. 37 is recommended for human -assembly. +bytes of memory. A proper setting saves memory. +.BR -f37 +is recommended for human +assembly. For small genomes, use +.BR -f0 +to disable the initial bloom filter +which takes 16GB memory at the beginning. For genomes much larger +than human, applying +.BR -f38 +or even +.BR -f39 +is preferred to save memory on k-mer counting. + +.TP +.BI -D \ INT +Drop k-mers occurring +.I >FLOAT*coverage +times [5.0]. +Hifiasm discards these high-frequency k-mers +during error correction to reduce running time. +The +.I coverage +is determined automatically +by hifiasm based on k-mer plot, representing +homozygous read coverage. Raising this option +may improve the resolution of repetitive regions +but takes longer time. + +.TP +.BI -N \ INT +Consider up to +.I max(-D*coverage,-N) +overlaps for each oriented read [100]. +The +.I coverage +is determined automatically +by hifiasm based on k-mer plot, representing +homozygous read coverage. Raising this option may +improve the resolution of repetitive regions but +takes longer time. + .TP .BI -r \ INT -Rounds of haplotype-aware error corrections [3]. This option affects all outputs of hifiasm. +Rounds of haplotype-aware error corrections [3]. +This option affects all outputs of hifiasm. +Odd rounds of correction are preferred in practice. + +.TP +.BI -z \ INT +Length of adapters that should be removed [0]. This option remove +.I INT +bases from both ends of each read. +Some old Hifi reads may consist of +short adapters (e.g., 20bp adapter at one end). For such data, trimming short adapters would +significantly improve the assembly quality. .TP .BI --min-hist-cnt \ INT When analyzing the k-mer spectrum, ignore counts below -.IR INT . +.IR INT +[5]. For very low coverage of HiFi data, set smaller +value for this option. .SS Assembly options @@ -128,14 +180,6 @@ Note that unlike .BR -r , this option does not affect error corrected reads and all-to-all overlaps. -.TP -.BI -z \ INT -Length of adapters that should be removed [0]. This option remove -.I INT -bases from both ends of each read. -Some old Hifi reads may consist of -short adapters (e.g., 20bp adapter at one end). For such data, trimming short adapters would -significantly improve the assembly quality. .TP .BI -m \ INT @@ -149,10 +193,13 @@ section of this man-page. .TP .BI -p \ INT Maximal probing distance for bubble popping when generating haplotype-resolved processed unitig graph -without small bubbles [100000]. Bubbles longer than +without small bubbles [0]. Bubbles longer than .I INT -bases will not be popped. Small bubbles might be caused by somatic mutations or noise in data, which -are not the real haplotype information. For detailed description of this graph, please see the +bases will not be popped. Small bubbles might be caused by somatic mutations or noise in data. +Please note that hifiasm automatically pops small bubbles based on coverage, +which can be tweaked by +.BR --hom-cov . +For detailed description of this graph, please see the .B OUTPUTS section of this man-page. @@ -163,13 +210,13 @@ A unitig is considered small if it is composed of less than reads [3]. Hifiasm may try to remove small unitigs at various steps. .TP -.BI -x \ FLOAT, -y \ FLOAT +.BI -x \ FLOAT1, -y \ FLOAT2 Max and min overlap drop ratio [0.8, 0.2]. This option is used with -.BR -r . +.BR -a . Given a node .I N in the assembly graph, let max(N) -be the length of the largest overlap of +be the length of the longest overlap of .I N. Hifiasm iteratively drops overlaps of .I N @@ -179,17 +226,17 @@ are below a threshold controlled by and .BR -y . Hifiasm applies -.B -r +.B -a rounds of short overlap removal with an increasing threshold between -.B -x +.I FLOAT1 and -.BR -y . +.I FLOAT2. .TP .BI -i Ignore error corrected reads and overlaps saved in .IR prefix .*.bin -files. +files so that hifiasm will start again from scratch. Apart from assembly graphs, hifiasm also outputs three binary files that save all overlap information during assembly step. With these files, hifiasm can avoid the time-consuming all-to-all overlap calculation step, @@ -197,12 +244,24 @@ and do the assembly directly and quickly. This might be helpful when users want to get an optimized assembly by multiple rounds of experiments with different parameters. +.TP +.BI -u +Disable post-join step for contigs which may improve N50. +The post-join step of hifiasm improves contig N50 but may introduce misassemblies. + +.TP +.BI --hom-cov \ INT +Homozygous read coverage inferred automatically in default. This option affects different types of outputs, +including Hi-C phased assembly and HiFi-only assembly. + .TP .BI --pri-range \ INT1[,INT2] Min and max coverage cutoff of primary contigs. Keep contigs with coverage in this range at p_ctg.gfa. Inferred automatically in default. -If INT2 is not specified, it is set to infinity. +If +.I INT2 +is not specified, it is set to infinity. Set -1 to disable. .TP @@ -286,41 +345,46 @@ but occurs < .B -c times in the other sample. +.TP +.BI --t-occ \ INT +Forcedly remove unitig including > +.I INT +unexpected haplotype-specific reads +without considering graph topology [60]. + .SS Purge-dups options .TP 10 .BI -l \ INT Level of purge-dup. 0 to disable purge-dup, 1 to only purge contained haplotigs, -2 to purge all types of haplotigs, 3 to purge all types of haplotigs in most aggressive way -for high heterozygosity sample. +2 to purge all types of haplotigs, 3 to purge all types of haplotigs in most aggressive way. In default, [3] for non-trio assembly, [0] for trio assembly. For trio assembly, only level 0 and level 1 are allowed. .TP .BI -s \ FLOAT -Similarity threshold for duplicate haplotigs that should be purged [0.75 for -l1/-l2, 0.55 for -l3]. +Similarity threshold for duplicate haplotigs that should be purged [0.75 for +.BR -l1/-l2 , +0.55 for +.BR -l3 ]. .TP .BI -O \ FLOAT Min number of overlapped reads for duplicate haplotigs that should be purged [1]. .TP -.BI --purge-cov \ INT +.BI --purge-max \ INT Coverage upper bound of Purge-dups, which is inferred automatically in default. -If the coverage of a contig is higher than this bound, don't apply Purge-dups. +If the coverage of a contig is higher than this bound, don't apply Purge-dups. +Larger value makes assembly more contiguous but may collapse repeats or segmental duplications. .TP .BI --n-hap \ INT -Assumption of haplotype number. +Assumption of haplotype number. If it is set to >2, the quality of +primary assembly for polyploid genomes might be improved. -.SS Debugging options - -.TP 10 -.B --dbg-gfa -Write additional files to speed up the debugging of graph cleaning. - .SS Hi-C-partition options [experimental, not stable] @@ -347,6 +411,12 @@ phasing results but takes longer time. Fraction to flip for perturbation [0.1]. Increasing this may improves phasing results but takes longer time. +.TP +.BI --l-msjoin \ INT +Detect misjoined unitigs of >= +.I INT +in size; 0 to disable [500000]. + .TP .BI --seed \ INT RNG seed [11]. @@ -367,23 +437,29 @@ haplotype-resolved raw unitig graph. This graph keeps all haplotype information. .IR prefix .p_utg.gfa: haplotype-resolved processed unitig graph without small bubbles. Small bubbles might be caused by somatic mutations or noise in data, which are not the real -haplotype information. The size of popped small bubbles should be specified by -.BR -p . +haplotype information. Hifiasm automatically pops such small bubbles based on coverage. +The option +.BR --hom-cov +affects the result. +In addition, the option +.BR -p +forcedly pops bubbles. .TP * .IR prefix .p_ctg.gfa: -assembly graph of primary contigs. This graph collapses different haplotypes. +assembly graph of primary contigs. This graph includes a complete assembly with +long stretches of phased blocks. .TP * .IR prefix .a_ctg.gfa: -assembly graph of alternate contigs. This graph consists of all assemblies that +assembly graph of alternate contigs. This graph consists of all contigs that are discarded in primary contig graph. .TP * -.IR prefix .hap*.p_ctg.gfa: +.IR prefix .*hap*.p_ctg.gfa: phased contig graph. This graph keeps the phased assembly. .RE @@ -401,13 +477,13 @@ with trio-binning options: .TP 2 * .IR prefix .dip.hap1.p_ctg.gfa: -phased paternal/haplotype1 contig graph keeping the phased +fully phased paternal/haplotype1 contig graph keeping the phased paternal/haplotype1 assembly. .TP * .IR prefix .dip.hap2.p_ctg.gfa: -phased maternal/haplotype2 contig graph keeping the phased +fully phased maternal/haplotype2 contig graph keeping the phased maternal/haplotype2 assembly. .RE @@ -418,17 +494,25 @@ With Hi-C partition options, hifiasm outputs: .TP 2 * .IR prefix .hic.p_ctg.gfa: -assembly graph of primary contigs. This graph collapses different haplotypes. +assembly graph of primary contigs. .TP * .IR prefix .hic.hap1.p_ctg.gfa: -phased contig graph where each contig is fully phased. +fully phased contig graph where each contig is fully phased. .TP * .IR prefix .hic.hap2.p_ctg.gfa: -phased contig graph where each contig is fully phased. +fully phased contig graph where each contig is fully phased. + +.TP +* +.IR prefix .hic.a_ctg.gfa +(optional with +.BR --primary): +assembly graph of alternate contigs. + .RE @@ -439,7 +523,7 @@ files: and .B *hic.tlb.bin. Rerunning hifiasm with different Hi-C reads needs to delete these bin files -or enable +or use .BR -i . .RE @@ -449,23 +533,23 @@ Hifiasm generates the following assembly graphs only with HiFi reads: .RS 2 .TP 2 * -.IR prefix .p_ctg.gfa: -assembly graph of primary contigs. This graph collapses different haplotypes. +.IR prefix .bp.p_ctg.gfa: +assembly graph of primary contigs. .TP * .IR prefix .bp.hap1.p_ctg.gfa: -balanced contig graph where each contig is partially phased. +partially phased contig graph of haplotype1. .TP * .IR prefix .bp.hap2.p_ctg.gfa: -balanced contig graph where each contig is partially phased. +partially phased contig graph of haplotype2. .RE .PP If the option -.BR -p +.BR -l0 or .BR --primary is specified, hifiasm outputs: @@ -474,13 +558,12 @@ is specified, hifiasm outputs: .TP 2 * .IR prefix .p_ctg.gfa: -assembly graph of primary contigs. This graph collapses different haplotypes. +assembly graph of primary contigs. .TP * .IR prefix .a_ctg.gfa: -assembly graph of alternate contigs. This graph consists of all assemblies that -are discarded in primary contig graph. +assembly graph of alternate contigs. .RE