Package: hybracter
Hybracter: Enabling Scalable, Automated, Complete and Accurate Bacterial Genome Assemblieshybracteris an automated long-read first bacterial genome assembly tool implemented in Snakemake usingSnaketool.Table of ContentsHybracter: Enabling Scalable, Automated, Complete and Accurate Bacterial Genome AssembliesTable of ContentsQuick StartDescriptionPipelineBenchmarkingv0.5.0 Updates (08 January 2024)v0.4.0 Updates (14 November 2023)v0.3.0 Updates 8 November 2023v0.2.0 Updates 26 October 2023 - Medaka, Polishing and--no_medakaDocumentationWhy Would You Run Hybracter?Other OptionsTrycyclerDragonflyeInstallationCondaPipSourceMain CommandsInput csvhybracter hybridhybracter longUsagehybracter installInstalling Dependencieshybracter hybridhybracter hybrid-singlehybracter longhybracter long-singleOutputsMain Output FilesSnakemake ProfilesAdvanced ConfigurationVersion LogSystemBugs and SuggestionsCitationQuick Starthybracteris available to install withpiporconda.You will need conda or mamba available sohybractercan install all the required dependencies.Therefore, it is recommended to installhybracterinto a conda environment as follows.mamba create -n hybracterENV -c bioconda -c conda-forge  hybracter
conda activate hybracterENV
hybracter --help
hybracter installMamba ishighly highlyrecommend. Please see thedocumentationfor more details on how to install mamba.When you runhybracterfor the first time, all the required dependencies will be installed as required, so it will take longer than usual (usually a few minutes). Every time you run it afterwards, it will be a lot faster as the dependenices will be installed.If you intend to run hybracter offline (e.g. on HPC nodes with no access to the internet), I highly recommend runninghybracter test-hybridand/orhybracter test-longon a node with internet access so hybracter can download the required dependencies. It should take 5-10 minutes. If your computer/node has internet access, please skip this step.hybracter test-hybrid --threads 8
hybracter test-long --threads 8Descriptionhybracteris designed for assembling bacterial isolate genomes using a long read first assembly approach.
It scales massively using the embarassingly parallel power of HPC and Snakemake profiles. It is designed for applications where you have isolates with Oxford Nanopore Technologies (ONT) long reads and optionally matched paired-end short reads for polishing.hybracteris desined to straddle the fine line between being as fully feature-rich as possible with as much information as you need to decide upon the best assembly, while also being a one-line automated program. In other words, as awesome as Unicycler, but updated for 2023. Perfect for lazy people like myself.hybracteris largely based off Ryan Wick'smagnificent tutorialand associatedpaper.hybracterdiffers in that it adds some additional steps regarding targeted plasmid assembly withplassembler, contig reorientation withdnaaplerand extra polishing and statistical summaries.Note: if you have Pacbio reads, as of 2023, you can runhybracter longwith--no_medakato turn off polishing, and--flyeModel pacbio-hifi. You can also probably just runFlyeorDragonflye(or of courseTrycyler) and reorient the contigs withdnaaplerwithout polishing. See Ryan Wick'sblogpostfor more details.PipelineA. Reads are quality controlled withFiltlong,Porechop,fastpand optionally contaminant removal using modules fromtrimnami.B. Long-read assembly is conducted withFlye. Each sample is classified if the chromosome(s) were assembled (marked as 'complete') or not (marked as 'incomplete') based on the given minimum chromosome length.C. For complete isolates, plasmid recovery withPlassembler.D. For all isolates, long read polishing withMedaka.E. For complete isolates, the chromosome is reorientated to begin with the dnaA gene withdnaapler.F. For all isolates, if short reads are provided, short read polishing withPolypolishandpypolca.G. For all isolates, assessment of all assemblies withALEforhybracter hybridorPyrodigalforhybracter long.H. The best assembly is selected and and output along with final assembly statistics.BenchmarkingHybracterwas benchmarked in both hybrid and long modes (specifically using thehybrid-singleandlong-singlecommands) againstUnicyclerv0.5.0 andDragonflyev1.1.2.20 samples from 4 studies with available reference genomes were benchmarked. You can see the full explanation and resultshere. You can find all the outputhere.To summarise the conclusions:Hybracter hybridwas superior to Unicycler in terms of accuracy, time taken and (slighly) in terms of plasmid recovery. It should be preferred to Unicycler.You should usehybracter longif you care about plasmids and have only long reads. It performs similarly to hybrid methods and its inclusion ofPlassemblerlargely seems to solve theproblem of long read assemblers recovering small plasmids.Hybracterin both modes is inferior to Dragonflye in terms of time though better in terms of chromosome accuracy.If you want the fastest possible chromosome assemblies for applications like species ID or sequence typing that retain a high level of accuracy, Dragonflye is a good option.Dragonflye should not be used if you care about recovering plasmids.v0.5.0 Updates (08 January 2024)Ryan Wick recently ranhybracter longon the latest Dorado v0.5.0 basecalled Nanopore reads (hisblog post). You can read a write-up of the resultshere. As a result, subsampling has been added to Hybracter.Adds subsampling using--subsample_depthusing Filtlong, based on some benchmarking of Dorado v0.5.0. Defaults to 100x of the estimated chromosome size-c.Also adds stricter criteria for complete assemblies (aka ensures that identified chromosomes must be circularised according to Flye).v0.4.0 Updates (14 November 2023)Adds--logicparameter. You have 2 choices:--logic best(the default) or--logic last.--logic bestwill runhybracteras normal and the best assembly (by ALE or pyrodigal mean length) will be selected as the final assembly.--logic lastwill force hybracter to pick the last polished round as the final assembly even if it is not the best as per ALE/pyrodigal. So forhybracter hybridthis will default to the pypolca polished round, for hybracter long it will be Medaka round 2. You may wish to use this if you want all your isolates to be consistently assembled.Adds reorientation of pre polished chromosome in case it is selected as the best assemblyAdds fixes to the chromosome comparisons - now it is much easier to interpret any changes between polishing rounds.v0.3.0 Updates 8 November 2023Upgrading and re-running hybracter is recommended.Fixes bug relating to polishing. Prior to v0.3.0, hybracter would only polish the chromosome with the entire readset. Benchmarking revealed that if there was significant similarity between chromosome and plasmids, polishing would introduce errors (my bad!)Now the entire assembly (chromosome from Flye + plasmids from Plassembler) is polished in every polishing step with improved results (the full benchmarking methodology and results is forthcoming shortly)v0.2.0 Updates 26 October 2023 - Medaka, Polishing and--no_medakaRyan Wick'sblogposton 24 October 2023 suggests that if you have new 5Hz SUP or Res (bacterial model specific) ONT reads, Medaka polishing often makes things worse! It also implies that Nanopore reads are almost good enough to assemble perfect bacterial genomes (at least with Trycycler) which is pretty awesome.Combined with the difficulty and randomness in installing Medaka from Nanopore, I have therefore decided to add a--no_medakaflag into v0.2.0.I have also set Medaka to be v1.8.0 and I do not intend to upgrade this going forward, as this is the most recent stable bioconda version that doesn't seem to cause too much grief.If you have trouble with Medaka installation, I'd therefore suggest please using--no_medaka.hybractershould still handle cases where Medaka makes assemblies worse. If Medaka makes your assembly appreciably worse,hybractershould choose the best most accurate assembly as the unpolished one in long mode.In hybrid mode, I'd still think the short read polished assemblies should be best but who knows now that Nanopore reads are getting very accurate!DocumentationDocumentation forhybracteris availablehere.Why Would You Run Hybracter?If you want the best possibleautomatedlong read only or hybrid bacterial isolate genome assembly.In other words, if you love Unicycler like I do, but want something faster and more accurate.If you need to assemble many (e.g. 10+) bacterial isolates as efficiently as possible.If you want all information about from assembly pipeline such as whether your polishing probably improved the genome, whether your assembly was likely complete, and how many plasmids you probably assembled.Other OptionsTrycyclerIf you are looking for the best possible (manual) bacterial assembly for a single isolate, please definitely useTrycyler.hybracterwill almost certainly not give you better assemblies than Trycycler. Trycycler is the gold standard for a reason.hybracteris automated, scalable, faster and requires less bioinformatics/microbial genomics expertise to run.If you use Trycycler, I would also highly recommend using (disclaimer: my own program)plassembler(which is built into hybracter) along side Trycycler to assemble small plasmids if you are especially interested in those, because long read only assemblies oftenmiss small plasmids.DragonflyeDragonflyeby the awesome @rpetit3is a good alternative for automated assembly ifhybracterdoesn't fit your needs, particuarly if you are familiar withShovill. Some pros and cons betweenhybracteranddragonflyeare listed below.dragonflyeallows for more options with regards to assemblers (it supportsMiniasmorRavenas well as Flye).On a single isolate,dragonflyeshould be faster (benchmarking coming but the Plassembler, assessment and extra polishing steps of hybracter should make it slower).hybractershould be more accurate, due to the extra round of polishing following reorientation, and integration of Plassembler (benchmarking coming).hybracterhas the advantage of scalability across multiple samples due to its Snakemake and Snaketool implementation.So if you have access to a cluster,hybracteris for you and likely faster.hybractergives more accurate plasmid assemblies because it usesplassemblerhybracterwill suggest automatically whether an assembly is 'complete' or 'incomplete'hybracterwill assess each polishing step and choose the genome most likely to be the best quality.InstallationYou will need conda andhighly recommendedmamba to runhybracter, because it is required for the installation of each compartmentalised environment (e.g. Flye will have its own environment). Please see thedocumentationfor more details on how to install mamba.Condahybracteris available to install withconda. To installhybracterinto a conda enviornment calledhybracterENV:mamba create -n hybracterENV hybracter
conda activate hybracterENV
hybracter --help
hybracter installPiphybracteris available to install withpip.You will also need conda or mamba available sohybractercan install all the required dependencies. Therefore, it is recommended to installhybracterinto a conda environment as follows.mamba create -n hybracterENV pip
conda activate hybracterENV
pip install hybracter
hybracter --help
hybracter installSourceAlternatively, the development version ofhybracter(which may include new, untested features) can be installed manually via github.git clone https://github.com/gbouras13/hybracter.git
cd hybracter
pip install -e .
hybracter --helpMain Commandshybracter hybrid: Assemble multiple genomes from isolates that have long-reads and paired-end short reads.hybracter hybrid-single: Assembles a single genome from an isolate with long-reads and paired-end short reads. It takes similar parameters toUnicycler.hybracter long: Assemble multiple genomes from isolates that have long-reads only.hybracter long-single: Assembles a single genome from an isolate with long-reads only.hybracter install: Downloads and installs the requiredplassemblerdatabase._           _                    _            
| |__  _   _| |__  _ __ __ _  ___| |_ ___ _ __ 
| '_ \| | | | '_ \| '__/ _` |/ __| __/ _ \ '__|
| | | | |_| | |_) | | | (_| | (__| ||  __/ |   
|_| |_|\__, |_.__/|_|  \__,_|\___|\__\___|_|   
       |___/


Usage: hybracter [OPTIONS] COMMAND [ARGS]...

  For more options, run: hybracter command --help

Options:
  -h, --help  Show this message and exit.

Commands:
  install        Downloads and installs the plassembler database
  hybrid         Run hybracter with hybrid long and paired end short reads
  hybrid-single  Run hybracter hybrid on 1 isolate
  long           Run hybracter with only long reads
  long-single    Run hybracter long on 1 isolate
  test-hybrid    Test hybracter hybrid
  test-long      Test hybracter long
  config         Copy the system default config file
  citation       Print the citation(s) for hybracter
  version        Print the version for hybracterInput csvhybracter hybridandhybracter longrequire an input csv file to be specified with--input. No other inputs are required.This file requires no headers.Other than the reads,hybracterrequires a value for a lower bound the minimum chromosome length for each isolate in base pairs. It must be an integer.hybracterwill denote contigs about this value as chromosome(s) and if it can recover a chromosome, it will denote the isolate as complete.In practice, I suggest choosing 90% of the estimated chromosome size for this value.e.g. forS. aureus, I'd choose 2500000,E. coli, 4000000,P. aeruginosa5500000.hybracter hybridhybracter hybridrequires an input csv file with 5 columns.Each row is a sample.Column 1 is the sample name you want for this isolate.Column 2 is the long read fastq file.Column 3 is the minimum chromosome length for that sample.Column 4 is the R1 short read fastq fileColumn 5 is the R2 short read fastq file.e.g.s_aureus_sample1,sample1_long_read.fastq.gz,2500000,sample1_SR_R1.fastq.gz,sample1_SR_R2.fastq.gz
p_aeruginosa_sample2,sample2_long_read.fastq.gz,5500000,sample2_SR_R1.fastq.gz,sample2_SR_R2.fastq.gzhybracter longhybracter longalso requires an input csv with no headers, but only 3 columns.hybracter longrequires an input csv file with 3 columns.Each row is a sample.Column 1 is the sample name you want for this isolate.Column 2 is the long read fastq file.Column 3 is the minimum chromosome length for that sample.e.g.s_aureus_sample1,sample1_long_read.fastq.gz,2500000
p_aeruginosa_sample2,sample2_long_read.fastq.gz,5500000Usagehybracter installYou will first need to install thehybracterdatabases.hybracter installAlternatively, can also specify a particular directory to store them - you will need to specify this with-d <databases directory>when you runhybracter.hybracter install -d  <databases directory>Installing DependenciesIf you have internet access on the machine or node where you are running hybracter, you can skip this step.When you runhybracterfor the first time, all the required dependencies will be installed as required, so it will take longer than usual (usually a few minutes). Every time you run it afterwards, it will be a lot faster as the dependenices will be installed.If you intend to run hybracter offline (e.g. on HPC nodes with no access to the internet), I highly recommend runninghybracter  test-hybridand/orhybracter test-longon a node with internet access so hybracter can download the required dependencies. It should take 5-10 minutes.hybracter test-hybrid 
hybracter test-long
hybracter --helpOnce that is done, runhybracter hybridorhybracter longas follows.hybracter hybridhybracter hybrid -i <input.csv> -o <output_dir> -t <threads>hybracter hybridrequires only a CSV file specified with-ior--input--no_pypolcawill turn off pypolca polishing.Use--min_lengthto specify the minimum long-read length for Filtlong.Use--min_qualityto specify the minimum long-read quality for Filtlong.You can specify a FASTA file containing contaminants with--contaminants. All long reads that map to contaminants will be filtered out.You can specify Escherichia phage lambda (a common contaminant in Nanopore library preparation) using--contaminants lambda.--skip_qcwill skip all read QC steps.You can change the--medakaModel(all available options are listed inhybracter hybrid -h)You can change the--flyeModel(all available options are listed inhybracter hybrid -h)You can turn off Medaka polishing using--no_medakaYou can turn off pypolca polishing using--no_pypolcaYou can forcehybracterto pick the last polishing round (not the best according to ALE) with--logic last.hybracterdefaults to picking the best (according to ALE) i.e.--logic best.hybracter hybrid-singlehybracter hybrid-single -l <longread FASTQ> -1 <R1 short reads FASTQ> -2 <R2 short reads FASTQ> -s <sample name> -c <chromosome size> -o <output_dir> -t <threads>  [other arguments]hybracter longhybracter long -i <input.csv> -o <output_dir> -t <threads> [other arguments]hybracter longrequires only a CSV file specified with-ior--inputUse--min_lengthto specify the minimum long-read length for Filtlong.Use--min_qualityto specify the minimum long-read quality for Filtlong.You can specify a FASTA file containing contaminants with--contaminants. All long reads that map to contaminants will be filtered.You can specify Escherichia phage lambda (a common contaminant in Nanopore library preparation) using--contaminants lambda.--skip_qcwill skip all read QC steps.You can change the--medakaModel(all available options are listed inhybracter long -h)You can change the--flyeModel(all available options are listed inhybracter long -h)You can turn off Medaka polishing using--no_medakaYou can forcehybracterto pick the last polishing round (not the best according to pyrodigal mean CDS length) with--logic last.hybracterdefaults to picking the best i.e.--logic best.hybracter long-singlehybracter long-single -l <longread FASTQ> -s <sample name> -c <chromosome size>  -o <output_dir> -t <threads>  [other arguments]Outputshybractercreates a number of output files in different formats.For more information about all possible file outputs, please see the documentation here.Main Output FilesThe main outputs are in theFINAL_OUTPUTdirectory.This directory will include:hybracter_summary.tsvfile. This gives the summary statistics for your assemblies with the following columns:SampleComplete (True or False)Total_assembly_lengthNumber_of_contigsMost_accurate_polishing_roundLongest_contig_lengthLongest_contig_coverageNumber_circular_plasmidscompleteandincompletedirectories.All samples that are denoted by hybracter to be complete will have 5 outputs in thecompletedirectory:sample_summary.tsv containing the summary statistics for that sample.sample_per_contig_stats.tsv containing the contig names, lengths, GC% and whether the contig is circular.sample_final.fasta containing the final assembly for that sample.sample_chromosome.fasta containing only the final chromosome(s) assembly for that sample.sample_plasmid.fasta containing only the final plasmid(s) assembly for that sample. Note this may be empty. If this is empty, then that sample had no plasmids.All samples that are denoted by hybracter to be incomplete will have 3 outputs in theincompletedirectory:sample_summary.tsv containing the summary statistics for that sample.sample_per_contig_stats.tsv containing the contig names, lengths, GC% and whether the contig is circular.sample_final.fasta containing the final assembly for that sample.Snakemake ProfilesI would highly highly recommend running hybracter using a Snakemake profile. Please see this blogpostfor more details. I have included an example slurm profile in the profile directory, but check out thislinkfor more detail on other HPC job scheduler profiles.hybracter hybrid --input <input.csv> --output <output_dir> --threads <threads> --profile profiles/hybracterAdvanced ConfigurationThanks to its Snakemake backend, you can modify resource requirements for each job contained withinhybracterusing the configuration file. A defauly can be created using thehybracter configcommand. This can make it even more efficient in server environment, as many jobs can be more efficiently parallelised than the default settings. For more information, please see thedocumentationVersion LogA brief description of what is new in each update ofhybractercan be found in the HISTORY.md file.Systemhybracteris tested on Linux, and on MacOS.Bugs and SuggestionsIf you come across bugs withhybracter, or would like to make any suggestions to improve the program, please open an issue or emailgeorge.bouras@adelaide.edu.au.CitationIf you use Hybracter, please cite the preprint along with core dependencies (they are also our tools!):Hybracter PreprintGeorge Bouras, Ghais Houtak, Ryan R Wick, Vijini Mallawaarachchi, Michael J. Roach, Bhavya Papudeshi, Louise M Judd, Anna E Sheppard, Robert A Edwards, Sarah Vreugde - Hybracter: Enabling Scalable, Automated, Complete and Accurate Bacterial Genome Assemblies. bioRxiv doi:https://doi.org/10.1101/2023.12.12.571215Plassembler:Bouras G., Sheppard A.E., Mallawaarachchi V., Vreugde S., Plassembler: an automated bacterial plasmid assembly tool, Bioinformatics, Volume 39, Issue 7, July 2023, btad409,https://doi.org/10.1093/bioinformatics/btad409.Dnaapler:Bouras, G., Grigson., S., Papudeshi., B., Mallawaarachchi V., Roach, M. J. (2023) Dnaapler: A tool to reorient circular microbial genomeshttps://github.com/gbouras13/dnaapler.Ryan Wick et al's Assembling the perfect bacterial genome paper, which provided the intellectual framework for hybracter:Wick RR, Judd LM, Holt KE (2023) Assembling the perfect bacterial genome using Oxford Nanopore and Illumina sequencing. PLoS Comput Biol 19(3): e1010905.https://doi.org/10.1371/journal.pcbi.1010905I would also recommend citing Hybracter's other dependencies if you can where they are used:Flye:Kolmogorov, M., Yuan, J., Lin, Y. et al. Assembly of long, error-prone reads using repeat graphs. Nat Biotechnol 37, 540–546 (2019).https://doi.org/10.1038/s41587-019-0072-8Snaketool:Roach MJ, Pierce-Ward NT, Suchecki R, Mallawaarachchi V, Papudeshi B, Handley SA, et al. (2022) Ten simple rules and a template for creating workflows-as-applications. PLoS Comput Biol 18(12): e1010705.https://doi.org/10.1371/journal.pcbi.1010705Trimnami:Roach MJ. (2023) Trimnami.https://github.com/beardymcjohnface/Trimnami.Filtlong:Wick RR (2018) Filtlong.https://github.com/rrwick/Filtlong.Porechop and Porechop_abi:Quentin Bonenfant, Laurent Noé, Hélène Touzet, Porechop_ABI: discovering unknown adapters in Oxford Nanopore Technology sequencing reads for downstream trimming, Bioinformatics Advances, Volume 3, Issue 1, 2023, vbac085,https://doi.org/10.1093/bioadv/vbac085Wick RR (2017)https://github.com/rrwick/Porechop.fastp:Shifu Chen, Yanqing Zhou, Yaru Chen, Jia Gu, fastp: an ultra-fast all-in-one FASTQ preprocessor, Bioinformatics, Volume 34, Issue 17, September 2018, Pages i884–i890,https://doi.org/10.1093/bioinformatics/bty560.ALE:Scott C. Clark, Rob Egan, Peter I. Frazier, Zhong Wang, ALE: a generic assembly likelihood evaluation framework for assessing the accuracy of genome and metagenome assemblies, Bioinformatics, Volume 29, Issue 4, February 2013, Pages 435–443,https://doi.org/10.1093/bioinformatics/bts723Medaka:Oxford Nanopore Technologies, Medaka.https://github.com/nanoporetech/medaka.Pyrodigal:Larralde, M., (2022). Pyrodigal: Python bindings and interface to Prodigal, an efficient method for gene prediction in prokaryotes. Journal of Open Source Software, 7(72), 4296,https://doi.org/10.21105/joss.04296.Polypolish:Wick RR, Holt KE (2022) Polypolish: Short-read polishing of long-read bacterial genome assemblies. PLoS Comput Biol 18(1): e1009802.https://doi.org/10.1371/journal.pcbi.1009802.Pypolca:George Bouras, Aleksey V. Zimin (2023) pypolca: Standalone Python reimplementation of the genome polishing tool POLCA.https://github.com/gbouras13/pypolca.Zimin AV, Salzberg SL (2020) The genome polishing tool POLCA makes fast and accurate corrections in genome assemblies. PLoS Comput Biol 16(6): e1007981.https://doi.org/10.1371/journal.pcbi.1007981.Snakemake:Mölder F, Jablonski KP, Letcher B et al. Sustainable data analysis with Snakemake [version 1; peer review: 1 approved, 1 approved with reservations]. F1000Research 2021, 10:33 (https://doi.org/10.12688/f1000research.29032.1).