Package: plassembler
plassemblerAutomated Bacterial Plasmid Assembly Programplassembleris a program that is designed for automated & fast assembly of plasmids in  bacterial genomes that have been hybrid sequenced with long read & paired-end short read sequencing. It was originally designed for Oxford Nanopore Technologies long reads, but will also work with Pacbio reads. As of v1.3.0, it should also work well for long-read only assembled genomes (although we would still recommend getting short reads too if you can).If you are assembling a small number of bacterial genomes manually, I would recommend starting by usingTrycyclerto recover the chromosome before using Plassembler to recover plasmids, especially the small ones. If you have more genomes or want to assemble your genomes in a more automated way, trydragonflye, especially if you are used to Shovill, or even better my own pipelinehybracterthat is more appropriate for large datasets and implemented Plassembler in it.Additionally, I would recommend reading the following guides to bacterial genome assembly regardless of whether you want to use Plassembler:TrycyclerPerfect Bacterial Assembly TutorialPerfect bacterial assembly PaperQuick StartThe easiest way to installplassembleris via conda:conda install -c bioconda plassemblerFollowed by database download and installation:plassembler download -d <databse directory>And finally runplassembler:plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length>Please read theInstallationsection for more details, especially if you are an inexperienced command line user.Manuscriptplassemblerhas been recently published inBioinformatics:George Bouras, Anna E. Sheppard, Vijini Mallawaarachchi, Sarah Vreugde, Plassembler: an automated bacterial plasmid assembly tool, Bioinformatics, Volume 39, Issue 7, July 2023, btad409,https://doi.org/10.1093/bioinformatics/btad409.If you useplassembler, please see the fullCitationssection for a list of all programsplassembleruses under the hood, in order to fully recognise the creators of these tools for their work.DocumentationThe full documentation for Plassembler can be foundhere.Table of ContentsplassemblerAutomated Bacterial Plasmid Assembly ProgramQuick StartManuscriptDocumentationTable of Contentsplassemblerv1.5.0 Update New Database (21 November 2023)plassemblerv1.3.0 Updates (24 October 2023)Why Does Plassembler Exist?Why Not Just Use Unicycler?Other FeaturesQuality ControlMetagenomesInstallationCondaPipSourceUnicycler v0.5.0 Installation IssuesRunning plassemblerOutputsBenchmarkingAcknowledgementsVersion LogBugs and SuggestionsCitationsplassemblerv1.5.0 Update New Database (21 November 2023)If you upgrade to v1.5.0, you will need to update the database usingplassembler downloadPlassembler v1.5.0 incorporates a new expanded database thanks to the recent PLSDB release2023_11_03_v2. Thanks @biobradfor the heads up.plassemblerv1.3.0 Updates (24 October 2023)plassembler longshould yield improved results. It achieves this by treating long reads as both short reads (in the sense of creating a de Brujin graph based short read assembly to begin) and long reads (for scaffolding) in Unicycler.While I'd still recommend short reads if you can get them, I am now confident that if your isolate has small plasmids in the long read set,plassembler longis very likely to find and recover them.For more information, see thedocumentation.The ability to specify a--flye_assemblyand--flye_infoif you already have a Flye assembly for your long reads instead of--flye_directoryhas been added. Thanks to @incoherentian'sissueThe ability to specify a--no_copy_numberswithplassembler assembledif you just want to run some plasmids against the PLSDB has been added. Thanks to @gaworj'sissue.Why Does Plassembler Exist?In long-read assembled bacterial genomes, small plasmids are difficult to assemble correctly with long read assemblers. They commonly have circularisation issues and can be duplicated or missed (seethis,thisandthis). This recentpaperinMicrobial Genomicsby Johnson et al also suggests that long read assemblers particularly miss small plasmids.plassemblerwas therefore created as a fast automated tool to ensure plasmids are assembled correctly without duplicated regions for high-throughput uses - like Unicycler but a lot laster - and to provide some useful statistics as well (such as estimate plasmid copy numbers for both long and short read sets).As it turns out (though this wasn't a motivation for making it),plassembleralso recovers more small plasmids than the existing gold standard tool Unicycler. I think this is because it throws away chromosomal reads, similar to subsampling short reads sets which can improve recovery. As there are more plasmid reads a proportion of the overall read set, there seems to be a higher chance of recovering smaller plasmids.You can see this increase in accuracy and speed in the benchmarking results forsimulatedandrealdatasets.Plassembler also usesmashas a quick way to determine whether each assembled contig has any similar hits inPLSDB.Additionally, due to its mapping approach, Plassembler can also be used as a quality control tool for checking whether your long and short read sets come from the same isolate. This may be particularly useful if your read sets come from different extractions, or you have multiplexed many samples (& want to avoid mislabelling).Why Not Just Use Unicycler?Unicycler is awesome and still a good way to assemble plasmids from hybrid sequencing -plassembleruses it! But there are a few reasons to use plassembler instead:Time. Plassember throws away all the chromosomal reads (i.e. most of them) before running Unicycler, so it is much faster (wall clock 3-10x faster generally).Accuracy. Benchmarking has shownplassembleris better than Unicycler in terms of recovering small plasmids.plassemblerwill output only the likely plasmids, and can more easily be integrated into pipelines. You shouldn't be assembling the chromosome using Unicycleranymoresoplassemblercan get you only what is necessary from Unicycler.plassemblerwill give you summary depth and copy number stats for both long and short reads.plassemblercan be used as a quality control to check if your short and long reads come from the same sample - ifplassemblerresults in many non-circular contigs (particularly those that have no hits in PLSDB), it is likely because your read sets do not come from the same isolate! SeeQuality Control.You will get information whether each assembled contig has a similar entry inPLSDB. Especially for common pathogen species that are well represented in databases, this will likely tell you specifically what plasmid you have in your sample.Note: Especially for less commonly sequenced species, I would not suggest that that absence of a PLSDB hit is necessary meaningful, especially for circular contigs - those would likely be novel plasmids uncaptured by PLSDB.Other FeaturesAssembled mode.Thanks to a suggestion fromgaworj, assembled mode has been added to Plassembler. This allows you to calculate the copy numbers of already assembled plasmids you may have, skipping assembly.You can use this feature withplassembler assembled.Multi-mapped reads.All long reads that map to multiple contigs (mostly, reads that map to both the chromosome and plasmids, but also to multiple putative plasmids) will be extracted when using the--keep-fastqsoptions. These may be of interest if you are looking at shared mobile genetic elements.Multiple chromosome bacteria/megaplasmids/chromidsPlassembler should work with bacteria with multiple chromosomes, megaplasmids or chromids. In this case, I would treat the megaplasmids etc like chromosomes and assemble them using a long-read first approach with Trycycler or Dragonflye, as they are of approximately chromosome size.I'd still use Plassembler to recover small plasmids - for example, for  Plassembler v1.1.0 recovered the 77.5 kbp plasmiod along with a 5386bp contig (coresponding to phage phiX174, a common sequencing spike-in) in theVibrio campbellii DS40M4(see thispaperand thisbioproject).-cneeds to be smaller than the size of the largest chromosome-like element.For example, for the vibrio example, which had approximately 1.8Mbp and 3.3Mbp chromosomes , I used-c 1500000.Please seeherefor more details and an example.Phages, Phage-Plasmids and Other Extrachromosomal RepliconsIf you have sufficient hybrid sequencing data, Plassembler will theoretically recover assemblies of all non-chromosomal replicons, including phages and phage-plasmidsA good example of this is theVibrio campbellii DS40M4example, where Plassembler recovered the assembly of phage phiX174, albeit it was from sequencing spike-in contamination in that case.Quality Controlplassemblercan also be used for quality control to test whether your long and short read sets come from the same isolate, even within the same species.Please seeherefor more details and some examples.Metagenomesplassembleris not currently recommended for metagenomic datasets, because of their high diversity, leading to difficulties in recovering chromosome-length contigs for bacteria. Additionally, Unicycler is not recommended for metagenomes. However,plassemblerwas tested on a high depth very simple mock community dataset from thispaper. It worked quite nicely, recovering the 5 known plasmids, but we don't anticipate it will work as well on your data! If you try it and it works please let us know.Please seeherefor more details.InstallationPlassembler has been tested on Linux and MacOS machines.CondaThe easiest way to installplassembleris via conda - Plassembler is on bioconda.conda install -c bioconda plassembleror mamba for quicker solving:mamba install -c bioconda plassemblerThis will install all the dependencies along withplassembler.PipYou can install the Python components ofplassemblerusing pip.pip install plassemblerYou will then need to install the external dependencies separately, which can be found inbuild/environment.yamlFlye>=2.9Unicycler>=0.4.8Minimap2>=2.11fastp>=0.18.0chopper>=0.5.0mash>=2.2Raven>=1.8Samtools>=0.15.0SourceAlternatively, the development version ofplassemblercan be installed manually via github.git clone https://github.com/gbouras13/plassembler.git
cd plassembler
pip install -e .Unicycler v0.5.0 Installation Issuesplassemblerworks best with Unicycler v0.5.0. With Unicycler v0.4.8,plassemblershould still run without any issue and provide a satisfactory assembly, but you will be warned of this when you runplassembler.plassemblerwill not work with any older version of Unicycler.LinuxFor Linux environments, Unicycler v0.5.0 should be installed automaticall with theplassemblerbioconda installation.You can force it as follows:conda install -c bioconda plassembler unicycler==0.5.0or manually install Unicycler v0.5.0 after installingplassembler:conda install -c bioconda plassembler
pip3 install git+https://github.com/rrwick/Unicycler.gitMacOSFor MacOS environments, the current conda installation method will only install the latest available bioconda Unicycler version of v0.4.8.Ryan Wick (the author of Unicycler) suggests that v0.5.0 should be used, as v0.4.8 is not compatible with the latest versions of spades (seehere). This will require another installation step on MacOS.To install Unicycler v0.5.0, it is recommended that you install Unicycler from github after installing Plassembler follows:# installs plassembler into an environment called 'plassemblerENV' and activates it
conda create -n plassemblerENV plassembler
conda activate plassemblerENV
# installs Unicycler v0.5.0
pip3 install git+https://github.com/rrwick/Unicycler.gitMac M1 users may need to change some compiler settings and install from the Unicycler github repo e.g.# installs plassembler into an environment called 'plassemblerENV' and activates it
conda create -n plassemblerENV plassembler
conda activate plassemblerENV
# installs Unicycler v0.5.0
git clone https://github.com/rrwick/Unicycler.git
cd Unicycler
python3 setup.py install --makeargs "CXX=g++"Running plassemblerTo runplassembler, first you need to install the database in a directory of your chosing:plassembler download -d <database directory>Once this is finished, you can run plassembler as follows:plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length>-c will default to 1000000 if it is absent.To specify more threads:plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length> -t <threads>Plassembler defaults to 1 thread.To specify a prefix for the output files:plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length> -t <threads> -p <prefix>To specify a minimum long read length and minimum read quality Q-score for filtering withchopper:plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length> -t <threads> -p <prefix> -m <min length> -q <min quality>-m will default to 500 and -q will default to 9. Note that for some tiny plasmids, -m should be reduced or perhaps even set to 1 (see thispaper).To overwrite an existing output directory, use -fplassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length> -t <threads> -p <prefix> -m <min length> -q <min quality> -fTo use Raven instead of Flye as a long read assembler, use--use_raven.plassembler run -d <database directory> -l <long read fastq> -o <output dir> -1 < short read R1 fastq> -2 < short read R2 fastq>  -c <estimated chromosome length> -t <threads> --use_ravenPlease see thedocumentationfor more options.Usage: plassembler run [OPTIONS]

  Runs Plassembler

Options:
  -h, --help                Show this message and exit.
  -V, --version             Show the version and exit.
  -d, --database PATH       Directory of PLSDB database.  [required]
  -l, --longreads PATH      FASTQ file of long reads.  [required]
  -1, --short_one PATH      R1 short read FASTQ file.  [required]
  -2, --short_two PATH      R2 short read FASTQ file.  [required]
  -c, --chromosome INTEGER  Approximate lower-bound chromosome length of
                            bacteria (in base pairs).  [default: 1000000]
  -o, --outdir PATH         Directory to write the output to.  [default:
                            plassembler.output/]
  -m, --min_length TEXT     minimum length for filtering long reads with
                            chopper.  [default: 500]
  -q, --min_quality TEXT    minimum quality q-score for filtering long reads
                            with chopper.  [default: 9]
  -t, --threads TEXT        Number of threads.  [default: 1]
  -f, --force               Force overwrites the output directory.
  -p, --prefix TEXT         Prefix for output files. This is not required.
                            [default: plassembler]
  --skip_qc                 Skips qc (chopper and fastp).
  --pacbio_model TEXT       Pacbio model for Flye.  Must be one of pacbio-raw,
                            pacbio-corr or pacbio-hifi.  Use pacbio-raw for
                            PacBio regular CLR reads (<20 percent error),
                            pacbio-corr for PacBio reads that were corrected
                            with other methods (<3 percent error) or pacbio-
                            hifi for PacBio HiFi reads (<1 percent error).
  -r, --raw_flag            Use --nano-raw for Flye.  Designed for Guppy fast
                            configuration reads.  By default, Flye will assume
                            SUP or HAC reads and use --nano-hq.
  --keep_fastqs             Whether you want to keep FASTQ files containing
                            putative plasmid reads  and long reads that map to
                            multiple contigs (plasmid and chromosome).
  --keep_chromosome         If you want to keep the chromosome assembly.
  --use_raven               Uses Raven instead of Flye for long read assembly.
                            May be useful if you want to reduce runtime.
  --flye_directory PATH     Directory containing Flye long read assembly.
                            Needs to contain assembly_info.txt and
                            assembly_info.fasta. Allows Plassembler to Skip
                            Flye assembly step.
  --flye_assembly PATH      Path to file containing Flye long read assembly
                            FASTA. Allows Plassembler to Skip Flye assembly
                            step in conjunction with  --flye_info.
  --flye_info PATH          Path to file containing Flye long read assembly
                            info text file. Allows Plassembler to Skip Flye
                            assembly step in conjunction with
                            --flye_assembly.
  --no_chromosome           Run Plassembler assuming no chromosome can be
                            assembled. Use this if your reads only contain
                            plasmids that you would like to assemble.OutputsPlassembler will output a_plasmids.fastafile, which will contain the assembled plasmid sequence(s) in FASTA format (including long and short read copy numbers in the header), and a_plasmids.gfafile, which will contain the assembly graph from Unicycler that can be visualised inBandage.Plassembler also outputs a_summary.tsvfile, which gives the estimated copy number for each plasmid, for both short reads and long reads (see thispaperfor more details about plasmid copy numbers) and also gives each contig's top hit by mash distance in the PLSDB (if there is a hit), along with all its supporting information.Ifplassemblerfails to assemble any plasmids at all in_plasmids.fasta, all these files will still exist, but will be empty (to ensureplassemblercan be easily integrated into workflow managers like Snakemake).plassemblerwill also output a log file, aflye_outputdirectory, which contains the output from Flye (it may be useful to decide whether you need more sequencing reads, or some strange assembly artifact occured) and aunicycler_outputdirectory containing the output from Unicycler. If--use_ravenis specified, araven_outputdirectory will be present instead.BenchmarkingThe benchmarking results forsimulatedandrealdatasets are available. The full benchmarking output can be foundhere.All benchmarking was conducted on a Intel® Core™ i7-10700K CPU @ 3.80GHz on a machine running Ubuntu 20.04.6 LTS.Tldr: Plassembler is much faster than Unicycler (3-10x usually) and is more accurate because it is more likely to recover low coverage plasmids that Unicycler might miss.AcknowledgementsMany thanks are owed toRyan Wick, who not only wrote Unicycler and some other code used in Plassembler, but also gave me some initial ideas about how to approach the plasmid assembly problem originally. If you are doing any bacterial genome assembly, you should read all of his work, but if you have read this far you probably already have.Also thanks toVijini Mallawaarachchiwho helped refactor the code - if you are interested in recovering phages (especially in the metagenome context) please givephablesa go.Version LogA brief description of what is new in each update ofplassemblercan be found in the HISTORY.md file.Bugs and SuggestionsIf you come across bugs withplassembler, or would like to make any suggestions to improve the program, please open an issue or emailgeorge.bouras@adelaide.edu.au.Citationsplassemblerhas been recently published inBioinformatics:George Bouras, Anna E. Sheppard, Vijini Mallawaarachchi, Sarah Vreugde, Plassembler: an automated bacterial plasmid assembly tool, Bioinformatics, Volume 39, Issue 7, July 2023, btad409,https://doi.org/10.1093/bioinformatics/btad409.If you useplassembler, please also consider citing where relevant: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-8Li H., Minimap2: pairwise alignment for nucleotide sequences, Bioinformatics, Volume 34, Issue 18 Pages 3094–3100 (2018),https://doi.org/10.1093/bioinformatics/bty191Wick RR, Judd LM, Gorrie CL, Holt KE Unicycler: Resolving bacterial genome assemblies from short and long sequencing reads. PLoS Comput Biol 13(6): e1005595 (2017).https://doi.org/10.1371/journal.pcbi.1005595Heng Li, Bob Handsaker, Alec Wysoker, Tim Fennell, Jue Ruan, Nils Homer, Gabor Marth, Goncalo Abecasis, Richard Durbin, 1000 Genome Project Data Processing Subgroup, The Sequence Alignment/Map format and SAMtools, Bioinformatics, Volume 25, Issue 16, 15 August 2009, Pages 2078–2079,https://doi.org/10.1093/bioinformatics/btp352Wick RR, Judd LM, Wyres KL, Holt KE. Recovery of small plasmid sequences via Oxford Nanopore sequencing. Microb Genom. 2021 Aug;7(8):000631. doi: 10.1099/mgen.0.000631. PMID: 34431763; PMCID: PMC8549360.Schmartz GP, Hartung A, Hirsch P, Kern F, Fehlmann T, Müller R, Keller A, PLSDB: advancing a comprehensive database of bacterial plasmids, Nucleic Acids Research, Volume 50, Issue D1, 7 January 2022, Pages D273–D278,https://doi.org/10.1093/nar/gkab1111.Ondov, B.D., Treangen, T.J., Melsted, P. et al. Mash: fast genome and metagenome distance estimation using MinHash. Genome Biol 17, 132 (2016).https://doi.org/10.1186/s13059-016-0997-x.De Coster,W. and Rademakers,R. (2023) NanoPack2: population-scale evaluation of long-read sequencing data. Bioinformatics, 39, btad311.https://doi.org/10.1093/bioinformatics/btad311.Vaser,R. and Šikić,M. (2021) Time-and memory-efficient genome assembly with Raven. Nat. Comput. Sci., 1, 332–336.https://doi.org/10.1038/s43588-021-00073-4.Koren S, Walenz BP, Berlin K, Miller JR, Bergman NH, Phillippy AM. (2017) Canu: scalable and accurate long-read assembly via adaptive k-mer weighting and repeat separation. Genome Res. 2017 May;27(5):722-736. doi:https://doi.org/10.1101/gr.215087.116.Bouras, G., Roach, M. J., Mallawaarachchi V., Grigson., S., Papudeshi., B. (2023) Dnaapler: A tool to reorient circular microbial genomeshttps://github.com/gbouras13/dnaapler