Package: teloclip
TeloclipA tool for the recovery of unassembled telomeres from soft-clipped read alignments.Table of contentsAbout TeloclipOptions and UsageInstallationRun with GitpodExample UsageOptional Quality ControlExtending contigsAlternative use casesOptionsTeloclip OptionsTeloclip-extract OptionsIssuesLicenseAbout TeloclipIn most eukaryotic species, chromosomes terminate in repetitivetelomericsequences. A complete genome assembly should ideally comprise chromosome-level contigs that possess telomeric repeats at each end. However, genome assemblers frequently fail to recover these repetitive features, instead producing contigs that terminate immediately prior to their location.Teloclip is designed to recover long-reads that can be used to extend draft contigs and resolve missing telomeres (short-read alignments may also be processed with teloclip). It does this by searching alignments of raw long-read data (i.e. Pacbio or ONP reads mapped with Minimap2) for 'clipped' alignments that occur at the ends of draft contigs. A 'clipped' alignment is produced where theendof a read is not part of its best alignment. This can occur when a read extends past the end of an assembled contig.Information about segments of a read that were aligned or clipped are stored inSAM formattedalignments as aCIGAR string. Teloclip parses these strings to determine if a read has been clipped at one or both ends of a contig.Optionally, teloclip can screen overhanging reads for telomere-associated motifs (i.e. 'TTAGGG' / 'CCCTAA') and report only those containing a match.Teloclip is based on concepts from Torsten Seemann's excellent toolsamclip. Samclip can be used to remove clipped alignments from a samfile prior to variant calling.Options and UsageInstallationThere are 4 options available for installing Teloclip locally:Clone from this repository and install as a local Python package.
This is the best way to ensure you have the latest development version.gitclonehttps://github.com/Adamtaranto/teloclip.git&&cdteloclip&&pipinstall-e.Pip install directly from this git repository.pipinstallgit+https://github.com/Adamtaranto/teloclip.gitInstall from PyPi.pipinstallteloclipInstall from Bioconda.condainstall-cbiocondateloclipVerify installation# Print version number and exit.teloclip--version# > teloclip 0.0.4# Get usage informationteloclip--helpRun with GitpodAlternatively,launch a Gitpod Workspacewithteloclip,samtools, andminimap2pre-installed.Example UsageBasic use case:First index the reference assembly# Create index of reference fastasamtoolsfaidxref.faReading alignments from SAM file# Read input from file and write output to stoutteloclip--refref.fa.faiin.sam# Read input from stdin and write stdout to fileteloclip--refref.fa.fai<in.sam>out.sam# Filter alignments from BAM file, write sorted output to filesamtoolsview-hin.bam|teloclip--refref.fa.fai|samtoolssort>out.bamStreaming SAM records from aligner# Map PacBio long-reads to ref assembly,# return alignments clipped at contig ends,# write to sorted bam.minimap2-axmap-pbref.fapacbio.fq.gz|teloclip--refref.fa.fai|samtoolssort>out.bam# Map reads to reference,# exclude unmapped reads and non-primary/supplementary alignments.# return alignments clipped at contig ends,# write to sorted bam.minimap2-axmap-pbref.fapacbio.fq.gz|samtoolsview-h-F0x2308|teloclip--refref.fa.fai|samtoolssort>out.bamReport clipped alignments containing target motifs# Report alignments which are clipped at a contig end# AND contain >=1 copy of the telomeric repeat "TTAGGG" (or its reverse complement "CCCTAA") in the clipped region.samtoolsview-hin.bam|teloclip--refref.fa.fai--motifsTTAGGG|samtoolssort>out.bam# Report alignments which are clipped at a contig end# AND contain >=1 copy of the telomeric repeat "TTAGGG" (or its reverse complement "CCCTAA") ANYWHERE in the read.samtoolsview-hin.bam|teloclip--refref.fa.fai--motifsTTAGGG--matchAny|samtoolssort>out.bam# Compress homopolymers in query motifs and clipped regions to compensate for errors in raw PacBio or ONP data.# i.e. The motif 'TTAGGGTTAGGG' becomes 'TAGTAG' and will match 'TTTTTAAAGGTTTAAGGG'.samtoolsview-hin.bam|teloclip--refref.fa.fai--motifsTTAGGGTTAGGGTTAGGGTTAGGGTTAGGG|samtoolssort>out.bamExtract clipped readsteloclip-extractwill write overhanging reads to separate fasta files for each reference contig end. The clipped region of each read is masked as lowercase in output fasta files.Collections of reads that overhang a contig end can be assembled withraconorminiasminto a single segment before being used to extend the contig.# Find clipped alignments containing motif 'TTAGGG' and write reads to separate fasta files for each reference contig end.samtoolsview-hin.bam|teloclip--refref.fa.fai--motifsTTAGGG|teloclip-extract--refIdxdata/test.fna.fai--extractReads--extractDirSplitOverhangsOptional Quality ControlAdditional filtersUsers may wish to exclude reads below a minimum length or read quality score to reduce the risk of incorrect alignments.In some cases it may be also be useful to prioritise primary alignments. This can be done by pre-filtering alignments withsamtools view. You can decode sam flagshere.# Exclude secondary alignments.samtoolsview-h-F0x100in.sam|teloclip--refref.fa.fai>noSA.samPre-corrected DataSome assembly tools, such asCanu, preform pre-correction of long-reads through iterative overlapping and correction prior to assembly. Corrected reads are trimmed based on coverage to remove low-confidence ends.This trimming step can result in loss of distal telomeric sequences and so these reads shouldNOTbe used with Teloclip.However, long-reads that have been error-corrected using Illumina data with tools such asLoRDECorHALCshould be fine.Generally speaking, raw long-reads will be fine for extending your contigs. Any errors in the extended region can be corrected with a round of polishing with short-read data usingPilon.Extending contigsBefore using terminal alignments identified by Teloclip to extend contigs you should inspect the alignments in a genome browser that displays information about clipped reads, such asIGV.Check for conflicting soft-clipped sequences. These indicate non-specific read alignments. You may need to tighten your alignment criteria or manually remove low-confidence alignments.After manually extending contigs the revised assembly should be re-polished using available long and short read data to correct indels present in the raw long-reads.Finally, validate the updated assembly by re-mapping long-read data and checking for alignments that extend into revised contig ends.Alternative use casesIllumina dataTeloclip will also work fine with aligned short read data, which has a far lower error rate than single-molecule long-read data.However, there are obvious limits to the distance that a contig may be extended with shorter reads.Teloclip does not use information from paired-reads.Merging existing assembliesYou may have assemblies for your genome generated with different assemblers/configurations or data types (i.e. Illumina, PacBio, ONT) which vary in their success in assembling individual telomeres.These alternative assemblies can be treated as pseudo-long-reads and aligned to a reference usingMinimap2.Teloclip can identify aligned contigs that can be used to extend those in the reference set.Be cautious of short contigs that may align to may repetative sub-telomeric regions and result non-specific extension of contigs.Also beware of low-complexity telomeric regions on different chromosome aligning to each other and resulting in end-to-end fusions.# Align alternative assembly contigs to reference and report overhang alignments. Ignore secondary alignments.minimap2-axasm5ref.faasm.fa|samtoolsview-h-F0x100|teloclip--refref.fa.fai|samtoolssort>asm2ref.bamCircularising Mitochondrial / Bacterial genomesUsing default settings, teloclip will report alignments with clipped regions extending past linear contig ends.Reads can be extracted from these alignments usingcirclator's bam2readsand re-aligned to an assembly graph inBandageto help identify uncircularised contigs.OptionsTeloclip OptionsRunteloclip --helpto view the programs' most commonly used options:Usage: teloclip [-h] [--version] --refIdx REFIDX [--minClip MINCLIP] [--maxBreak MAXBREAK]
                [--motifs MOTIFS] [--noRev NOREV] [--noPoly NOPOLY] [--matchAny MATCHANY]
                [samfile]

Required:
 --refIdx REFIDX       Path to fai index for reference fasta. Index fasta using `samtools faidx FASTA`

Positional arguments:
  samfile               Input SAM can be added as the first positional argument after flagged options. 
                          If not set teloclip will read from stdin.

Optional:
  --minClip            Require clip to extend past ref contig end by at least N bases.
                         Default: 1
  --maxBreak           Tolerate max N unaligned bases at contig ends. 
                         Default: 50
  --motifs             If set keep only reads containing given motif/s from a comma delimited list 
                         of strings. By default also search for reverse complement of motifs. 
                         i.e. TTAGGG,TTAAGGG will also match CCCTAA,CCCTTAA
                         Default: None
  --noRev              If set do NOT search for reverse complement of specified motifs. 
                         Default: Find motifs on both strands.
  --noPoly             If set collapse homopolymer tracks within motifs before searching overhangs.
                        i.e. "TTAGGGTTAGGGTTAGGGTTAGGGTTAGGG" -> "TAGTAGTAGTAGTAG".
                        Useful for PacBio or ONP long reads homopolymer length errors. Defaut: Off.            
  --matchAny           If set motif match may occur in unclipped region of alignment.
                         Defaut: False
  --version            Show program's version number and exit.Teloclip-extract OptionsRunteloclip-extract --helpto view the programs' most commonly used options:Usage: teloclip-extract [-h] --refIdx REFIDX [--prefix PREFIX]
                        [--extractReads] [--extractDir EXTRACTDIR]
                        [--minClip MINCLIP] [--maxBreak MAXBREAK] [--version]
                        [samfile]

positional arguments:
  samfile               If not set, will read sam from stdin.

optional arguments:
  -h, --help            Show this help message and exit
  --refIdx              Path to fai index for reference fasta. Index fasta
                        using `samtools faidx FASTA`
  --prefix              Use this prefix for output files. Default: None.
  --extractReads        If set, write overhang reads to fasta by contig.
  --extractDir
                        Write extracted reads to this directory. Default: cwd.
  --minClip             Require clip to extend past ref contig end by at least
                        N bases.
  --maxBreak            Tolerate max N unaligned bases at contig ends.
  --version             Show program's version number and exitIssuesSubmit feedback to theIssue TrackerLicenseSoftware provided under MIT license.Teloclip hex-sticker was designed by@Super_Coleider.