Teloclip

A tool for the recovery of unassembled telomeres from raw long-reads using soft-clipped read alignments.

🎉🧬 New Release v0.3.2: Teloclip now supports automatic telomere extension!! 🧬🎉

Table of contents

• About Teloclip
• CLI Structure
• Options and Usage
• Installation
• Example Usage
• Optional Quality Control
• Options
• Main Command
• Filter Sub-command Options
• Extract Sub-command Options
• Extend Sub-command Options
• Citing Teloclip
• Publications using Teloclip
• Issues
• License

About Teloclip

In most eukaryotic species, chromosomes terminate in repetitive telomeric sequences. 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 telomeric repeats.

Teloclip is designed to scan raw long-read data for evidence that can be used to restore missing telomeres. It does this by searching alignments of raw long-read data (i.e. Pacbio or ONT reads mapped with Minimap2) for 'clipped' alignments that occur at the ends of draft contigs. A 'clipped' alignment is produced where the end of 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 in SAM formatted alignments as a CIGAR 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.

Once candidate telomeric sequences have be detected in alignment overhangs, teloclip can be used to automatically patch the missing sequence onto draft contigs.

Teloclip is based on concepts from Torsten Seemann's excellent tool samclip. Samclip can be used to remove clipped alignments from a samfile prior to variant calling.

CLI Structure

Teloclip provides three sub-commands:

• teloclip filter: Filter SAM/BAM files to identify terminal soft-clipped alignments containing potential telomeric sequences
• teloclip extract: Extract overhanging reads to separate FASTA files organized by contig and end position
• teloclip extend: Extend draft contigs using overhang analysis from soft-clipped alignments.

Options and Usage

Installation

Teloclip requires Python >= 3.8.

There are 5 options available for installing Teloclip locally:

1. Install from PyPi. This or Bioconda will get you the latest stable release.

pip install teloclip

1. Install from Bioconda.

conda install -c bioconda teloclip

1. Pip install directly from this git repository.

This is the best way to ensure you have the latest development version.

pip install git+https://github.com/Adamtaranto/teloclip.git

1. Clone from this repository and install as a local Python package.

Do this if you want to edit the code.

git clone https://github.com/Adamtaranto/teloclip.git && cd teloclip && pip install -e '.[dev]'

1. Use Docker for reproducible containerized environments.

Ideal for pipelines and reproducible workflows. No local Python installation required.

# Pull the latest image
docker pull adamtaranto/teloclip:latest

# Run teloclip
docker run --rm -v $(pwd):/data adamtaranto/teloclip:latest --version

See DOCKER.md for complete Docker usage guide and examples/nextflow/ for Nextflow integration.

Verify installation

# Print version number and exit.
teloclip --version
# > teloclip 0.3.2

# Get usage information
teloclip --help

Example Usage

Basic use case:

First index the reference assembly so teloclip knows where each contig ends.

# Create index of reference fasta
samtools faidx ref.fa

Next align your raw long reads to the reference fasta.

minimap2 -ax map-pb ref.fa pacbio_reads.fq.gz > in.sam

Loading alignments from file

Next you will need to provide alignment records to teloclip in SAM format. These can be read directly from a SAM file like this:

# Option 1: Read alignment input from sam file and write overhang-reads to stdout
teloclip filter --ref-idx ref.fa.fai in.sam

# Option 2: Read alignment input from stdin and write stdout to file
teloclip filter --ref-idx ref.fa.fai < in.sam > overhangs.sam

Alternatively, you can read and write alignment records from BAM files.

BAM files are binary SAM files, they contain all the same information but take up much less storage space.

You can use BAM files with teloclip like this:

# Read alignments from bam file, pipe sam lines to teloclip, sort overhang-read alignments and write to bam file
samtools view -h in.bam | teloclip filter --ref-idx ref.fa.fai | samtools sort > overhangs.bam

Streaming alignments from Minimap

You can also stream SAM records directly from the aligner to save disk space.

# Map PacBio long-reads to ref assembly,
# return alignments clipped at contig ends,
# write to sorted bam.
minimap2 -ax map-pb ref.fa pacbio_reads.fq.gz | teloclip filter --ref-idx ref.fa.fai | samtools sort > overhangs.bam

Report clipped alignments containing target motifs

teloclip filter has the option to report only overhanging reads that contain a known telomeric repeat sequence.

# 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.
samtools view -h in.bam | teloclip filter --ref-idx ref.fa.fai --motifs TTAGGG | samtools sort > overhangs.bam

# To change the minimum number of consecutive motif repeats required for a match, set "--min-repeats". This example will require one instance of "TTAGGGTTAGGGTTAGGG" in the overhang.
samtools view -h in.bam | teloclip filter --ref-idx ref.fa.fai --motifs TTAGGG --min-repeats 3 | samtools sort > out.bam

Matching noisy target motifs

Raw long-reads can contain errors in the length of homopolymer tracks. If the --fuzzy option is set, motifs will be converted to regex patterns that allow the number of repeated bases to vary by +/- 1. i.e. "TTAGGG" -> "T{1,3}AG{2,4}". This pattern will match TTAGG TTAGGGG TAGG TTTAGGG etc.

To reduce off target matching you can increase the minimum required number of sequential motif matches with "--min-repeats".

samtools view -h in.bam | teloclip filter --ref-idx ref.fa.fai --fuzzy --motifs TTAGGG --min-repeats 4 | samtools sort > overhangs.bam

Extract clipped reads

teloclip extract will 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.

You can inspect these reads and select candidates to manually extend contig ends.

# Find soft-clipped alignments containing motif 'TTAGGG' that overhang contig ends, write to sorted bam.
samtools view -h in.bam | teloclip filter --ref-idx ref.fa.fai --motifs TTAGGG | samtools sort > sorted_overhangs.bam

# Extract overhang reads and write to separate fasta files for each reference contig end.
# Adds overhang stats to fasta header and writes overhang region in lowercase.
# Note: Use sorted input to make processing more efficient.
samtools view -h sorted_overhangs.bam | teloclip extract --ref-idx ref.fa.fai --extract-dir split_overhangs_by_contig --include-stats --count-motifs TTAGGG --report-stats

Automatically extend missing telomeres

Use the teloclip extend tool to automatically extend contigs with missing telomeic sequences from overhang-reads identified with teloclip filter.

Before using overhangs identified by Teloclip to extend contigs you should inspect the alignments in a genome browser that displays information about clipped reads, such as IGV.

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.

Note: Circular genomes (i.e. mitochondria, chloroplasts, and nitroplasts) will always yield soft-clipped overhangs and should not be extended. We attempt to exclude these with --exclude-outliers which will skip contigs with unusually high overhang depths. You can explicitly exclude known circular contigs by providing names to --exclude-contigs.

# Create required indices (one-time setup)
samtools faidx ref.fa

# Convert SAM -> BAM, sort, and write sorted BAM
samtools view -bS overhangs.sam | samtools sort -o overhangs.sorted.bam

# Index the sorted BAM for fast access
samtools index overhangs.sorted.bam

# Use `--dry-run` option to report proposed changes without applying them.
teloclip extend overhangs.sorted.bam ref.fa \
  --output-fasta extended.fasta \
  --stats-report extension_report.txt \
  --count-motifs TTAGGG \
  --screen-terminal-bases 1000 \
  --exclude-contigs ctg_007_mitochondrial
  --dry-run

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.

The final telomere-extended assembly should be re-polished using available long and short read data to correct indels (i.e. with Medaka and Pypolca) in the raw long-read extensions.

Optional Quality Control

Additional filters

Users may wish to exclude reads below a minimum mapping quality score to reduce the risk of incorrect alignments.

Similarly, multi-mapping reads will generate secondary alignments. To exclude non-specific aligments you can pre-filtering with samtools view. You can decode sam flags here.

Note: As of version teloclip v0.3.0, filter and extract will exclude secondary alignments by default.

# Use samtools to filter reads below a MAPQ 30
samtools view -h -q 30 input.sam | teloclip filter --ref-idx ref.fa.fai > min_mapq_30.sam

# Exclude secondary alignments by filtering with samtools
# Note: Secondary alignments are filtered by default in teloclip >=v0.3.0, use '--keep-secondary' to keep.
samtools view -h -F 0x100 input.sam | teloclip filter --ref-idx ref.fa.fai > no_secondary.sam

Options

The main teloclip command provides global options and sub-commands for specific operations.

Main Command

Run teloclip --help to view the main command options:

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

  A tool for the recovery of unassembled telomeres from soft-clipped read
  alignments.

Options:
  -v, --verbose                   Enable verbose logging
  -q, --quiet                     Suppress all but error messages
  --log-level [DEBUG|INFO|WARNING|ERROR]
                                  Set specific log level
  --version                       Show the version and exit.
  --help                          Show this message and exit.

Commands:
  extend   Extend contigs using overhang analysis from soft-clipped...
  extract  Extract overhanging reads for each end of each reference contig.
  filter   Filter SAM file for clipped alignments containing unassembled...

Filter Sub-command Options

Run teloclip filter --help to view the filter command options:

```code Usage: teloclip filter [OPTIONS] [SAMFILE]

Filter SAM file for clipped alignments containing unassembled telomeric repeats.

Options: --ref-idx PATH Path to fai index for reference fasta. Index fasta using samtools faidx FASTA [required] --min-clip INTEGER Require clip to extend past ref contig end by at least N bases. Default: 1 --max-break INTEGER Tolerate max N unaligned bases before contig end. Default: 50 --motifs TEXT If set keep only reads containing given motif/s from comma delimited list of