This section covers the installation of slamdunk . Alternatively one could also run slamdunk from out of the box Docker containers.

There are 3 different possibilities:

1. Installation with conda from the Bioconda channel (recommended)
2. Installation with pip from the Python Package Index
3. Manual installation from source-label

conda create --name <name> -c bioconda slamdunk

# Having root permissions

pip install slamdunk

# Latest development version

pip install git+https://github.com/t-neumann/slamdunk.git

# Local user only

pip install --user slamdunk
export PATH=$PATH:$HOME/.local/bin/

To analyze a given SLAMSeq dataset with slamdunk using the default parameters which worked well on datasets during development, call the all dunk using the recommended minimum set of default parameters:

slamdunk all -r <reference fasta> -b <bed file> -o <output directory> -5 12 -n 100
             -t <threads> -m -rl <maximum read length> --skip-sam files [files ...]

The input data you need and parameters you need to set yourself are the following:

This will run the entire slamdunk analysis with the most relevant output files being:

• Folder count : Tab-separated tcount files containing the SLAMSeq statistics per UTR (see Tcount file format )
• Folder filter : BAM-files with the final mapped reads for visualization and further processing

If you want to have a very quick sanity check whether your desired conversion rates have been achieved, use this alleyoop command to plot the UTR conversion rates in your sample:

alleyoop utrrates -o <output directory> -r <reference fasta> -t <threads>
                  -b <bed file> -l <maximum read length> bam [bam ...]

This will produce a plot like the following example where you can clearly see that individual conversions for a given starting base are balanced and unbiased, except for the T->C conversions in this SLAMSeq sample with longer labelling times.

Slamdunk is a modular analysis software. Modules are dubbed dunks and each dunk builds upon the results from the previous dunks.

The idea is to always process all samples with one command line call of a given dunk. Output files typically get the same name as the input files with a certain prefix (e.g. “slamdunk_mapped”). The command line interface follows the “samtools/bwa” style. Meaning that all commands are available through the central executable/script slamdunk (located in the bin directory) Wildcard characters to supply multiple files are recognized throughout slamdunk .

Available dunks are:

'map', 'filter', 'snp', 'count', 'all'

Calling a module with –help shows all possible parameters text:

usage: slamdunk all [-h] -r REFERENCEFILE -b BED [-fb FILTERBED] -o OUTPUTDIR [-5 TRIM5]
                 [-a MAXPOLYA] [-n TOPN] [-t THREADS] [-q] [-e] [-m]
                 [-mq MQ] [-mi IDENTITY] [-nm NM] [-mc COV] [-mv VAR]
                 [-mts] [-rl MAXLENGTH] [-mbq MINQUAL] [-i SAMPLEINDEX]
                 [-ss]
                 files [files ...]

positional arguments:
   files                 Single csv/tsv file (recommended) containing all
                         sample files and sample info or a list of all sample
                         BAM/FASTA(gz)/FASTQ(gz) files

optional arguments:
   -h, --help            show this help message and exit
   -r REFERENCEFILE, --reference REFERENCEFILE
                         Reference fasta file
   -b BED, --bed BED     BED file with 3'UTR coordinates
   -fb FILTERBED, --filterbed FILTERBED
                         BED file with 3'UTR coordinates to filter multimappers
   -o OUTPUTDIR, --outputDir OUTPUTDIR
                         Output directory for slamdunk run.
   -5 TRIM5, --trim-5p TRIM5
                         Number of bp removed from 5' end of all reads
                         (default: 12)
   -a MAXPOLYA, --max-polya MAXPOLYA
                         Max number of As at the 3' end of a read (default: 4)
   -n TOPN, --topn TOPN  Max. number of alignments to report per read (default:
                         1)
   -t THREADS, --threads THREADS
                         Thread number (default: 1)
   -q, --quantseq        Run plain Quantseq alignment without SLAM-seq scoring
   -e, --endtoend        Use a end to end alignment algorithm for mapping.
   -m, --multimap        Use reference to resolve multimappers (requires -n >
                         1).
   -mq MQ, --min-mq MQ   Minimum mapping quality (default: 2)
   -mi IDENTITY, --min-identity IDENTITY
                         Minimum alignment identity (default: 0.95)
   -nm NM, --max-nm NM   Maximum NM for alignments (default: -1)
   -mc COV, --min-coverage COV
                         Minimimum coverage to call variant (default: 10)
   -mv VAR, --var-fraction VAR
                         Minimimum variant fraction to call variant (default:
                         0.8)
   -mts, --multiTCStringency
                         Multiple T>C conversion required for T>C read
   -rl MAXLENGTH, --max-read-length MAXLENGTH
                         Max read length in BAM file
   -mbq MINQUAL, --min-base-qual MINQUAL
                         Min base quality for T -> C conversions (default: 27)
   -i SAMPLEINDEX, --sample-index SAMPLEINDEX
                         Run analysis only for sample <i>. Use for distributing
                         slamdunk analysis on a cluster (index is 1-based).
   -ss, --skip-sam       Output BAM while mapping. Slower but, uses less hard
                         disk.

The flow of slamdunk is to first map your reads, filter your alignments, call variants on your final alignments and use these to calculate conversion rates, counts and various statistics for your 3’UTRs.

All steps create a log file that has the same name as the output file. Typically there is one log file per sample and task (makes parallel execution easier). Command line output is limited to a minimum at the moment. If a sample is finished a ”.” is printed (very basic progress bar).

Alleyoop ( A dditional s L amdunk he L p E r tools for an Y diagn O stics O r P lots) is a collection of tools for post-processing and running diagnostics on slamdunk analyses. Similar to slamdunk , the command line interface follows the “samtools/bwa” style. Meaning that all commands are available through the central executable/script alleyoop (located in the bin directory).

MultiQC:

We implemented a module for MultiQC to support summary reports of Alleyoop modules. Currently MultiQC supports the summary , rates , utrrates , tcperreadpos and tcperutrpos commands.

alleyoop dedup [-h] -o <output directory> [-tc <# tc mutations>] [-t <threads>] bam [bam ...]

34330_An312_wt-2n_mRNA-slamseq-autoquant_0h-R1.fq_slamdunk_mapped_filtered.bam ->
34330_An312_wt-2n_mRNA-slamseq-autoquant_0h-R1.fq_slamdunk_mapped_filtered_dedup.bam

alleyoop collapse [-h] -o <output directory> [-t <threads>] tcount [tcount ...]

34330_An312_wt-2n_mRNA-slamseq-autoquant_0h-R1.fq_slamdunk_mapped_filtered_tcount.tsv ->
34330_An312_wt-2n_mRNA-slamseq-autoquant_0h-R1.fq_slamdunk_mapped_filtered_tcount_collapsed.tsv

rates

This tool computes the overall conversion rates in your reads and plots them as a barplot.

alleyoop rates [-h] -o <output directory> -r <reference fasta> [-mq <MQ cutoff>]
               [-t <threads>] bam [bam ...]

Input ¶

File	Description
Reference fasta	The reference sequence of the genome to map against in fasta format.
bam	Fastq/BAM file(s) containing the final filtered reads from slamdunk (wildcard * accepted).

Output ¶

File	Description
overallrates.csv	Tab-separated table of the overall conversion rates.
overallrates.pdf	Overall conversion rate plot file.

Below is an example plot of the overall conversion rates of the reads in a sample. One can appreciate the typical excess of T->C conversion (A->G on minus strand) of the SLAMseq technology for later labelling timepoints.

Parameters ¶

Parameter	Required	Description
-h		Prints the help.
-o	x	The output directory where all output files of this tool will be placed.
-r	x	The reference fasta file.
-mq		Minimum base quality for T->C conversions to be counted.
-t		The number of threads to use. All tools run single-threaded, so it is recommended to use as many threads as available samples.
bam	x	Fastq/BAM file(s) containing the final filtered reads. Can be multiple if multiple samples are analysed simultaneously (wildcard * is recognized).

tccontext

This tool computes the genomic context of all Ts in a read and plots them as barplot to inspect any biases in that direction.

alleyoop tccontext [-h] -o <output directory> -r <reference fasta> [-mq <MQ cutoff>]
                   [-t <threads>] bam [bam ...]

Input ¶

File	Description
Reference fasta	The reference sequence of the genome to map against in fasta format.
bam	BAM file(s) containing the final filtered reads from slamdunk (wildcard * accepted).

Output ¶

File	Description
tccontext.csv	Tab-separated table of the 5’ and 3’ T-contexts, separated by strand.
tccontext.pdf	T-context plot file.

Below is an example plot of the T-context of all reads in a sample. On top you will find the 5’ context of individual Ts, at the bottom the respective 3’ context of the individual Ts. Note, that these will not be reciprocal (see e.g. this publication ).

Parameters ¶

Parameter	Required	Description
-h		Prints the help.
-o	x	The output directory where all output files of this tool will be placed.
-r	x	The reference fasta file.
-mq		Minimum base quality for T->C conversions to be counted.
-t		The number of threads to use. All tools run single-threaded, so it is recommended to use as many threads as available samples.
bam	x	BAM file(s) containing the final filtered reads (wildcard * accepted).

utrrates

This tool checks the individual conversion rates per 3’UTR and plots them as boxplots over the entire realm of 3’UTRs. Each conversion is normalized to all possible conversions from it’s starting base e.g. A->G / (A->A + A->G + A->C + A->T).

alleyoop utrrates [-h] -o <output directory> [-r <reference fasta>] [-mq <MQ cutoff>] [-m]
                  [-t <threads>] -b <bed file> -l <maximum read length> bam [bam ...]

Input ¶

File	Description
Reference fasta	The reference sequence of the genome to map against in fasta format.
-b	Bed file with coordinates of 3’UTRs.
bam	BAM file(s) containing the final filtered reads from slamdunk (wildcard * accepted).

Output ¶

File	Description
mutationrates_utr.csv	Tab-separated table with conversion reads, one UTR per line.
mutationrates_utr.pdf	UTR conversion rate plot file.

Below is an example plot of conversion rates for all UTRs for a given sample. Typically, the individual conversions for a given starting base are balanced and unbiased, except for T->C conversions in SLAMseq samples with longer labelling times.

Parameters ¶

Parameter	Required	Description
-h		Prints the help.
-o	x	The output directory where all output files of this tool will be placed.
-r	x	The reference fasta file.
-mq		Minimum base quality for T->C conversions to be counted.
-m		Flag to activate the multiple T->C conversion stringency: Only T->C conversions in reads with more than 1 T->C conversion will be counted.
-t		The number of threads to use. All tools run single-threaded, so it is recommended to use as many threads as available samples.
-b	x	Bed file with coordinates of 3’UTRs.
-l		Maximum read length in all samples (will be automatically estimated if not set).
bam	x	BAM file(s) containing the final filtered reads (wildcard * accepted).

alleyoop snpeval [-h] -o <output directory> -s <SNP directory> -r <reference fasta> -b <bed file> [-c <coverage cutoff>]
                 [-f <variant fraction cutoff>] [-m] [-l <maximum read length>] [-q <minimum base quality>] [-t <threads>]
                 bam [bam ...]

alleyoop summary [-h] -o <output file> [-t <directory of tcount files>] bam [bam ...]

alleyoop merge [-h] -o <output file> [-c <expression>] countFiles [countFiles ...]

tcperreadpos

This tool calculates the individual mutation rates per position in a read treating T->C mutations separately. This plot can be used to search for biases along reads.

alleyoop tcperreadpos [-h] -r <reference fasta> [-s <SNP directory>]
                      [-l <maximum read length>] -o <output directory> [-mq <MQ cutoff>]
                      [-t <threads>] bam [bam ...]

Input

File	Description
Reference fasta	The reference sequence of the genome to map against in fasta format.
-s	(optional) The called variants from the snp dunk to filter false-positive T->C conversions.
bam	BAM file(s) containing the final filtered reads from slamdunk (wildcard * accepted).

Output

File	Description
tcperreadpos.csv	Tab-separated table with mutation rates, one line per read position.
tcperreadpos.pdf	Plot of the mutation rates along the reads.

Below is an example plot of mutation rates along all reads in a sample. Typically, one will see increasing error rates towards the end of a reads, as for all Illumina reads. In addition, depending on how many bases were clipped from the 5’ end of the reads, one will also observe higher error rates in the beginning of the read as illustrated in the example plot. Finally, for SLAMseq samples with longer labelling times, the overall T->C conversions in the bottom plot will begin to increase compared to the overall background in the top plot.

Parameters

Parameter	Required	Description
-h		Prints the help.
-o	x	The output directory where all output files of this tool will be placed.
-r	x	The reference fasta file.
-mq		Minimum base quality for T->C conversions to be counted.
-t		The number of threads to use. All tools run single-threaded, so it is recommended to use as many threads as available samples.
-s		The called variants from the snp dunk to filter false-positive T->C conversions.
-l		Maximum read length in all samples (will be automatically estimated if not set).
bam	x	BAM file(s) containing the final filtered reads (wildcard * accepted).

tcperutrpos

This tool calculates the individual mutation rates per position in an 3’UTR treating T->C mutations separately. This plot can be used to search for biases along UTRs. Only most 3’ 200bp of each UTR will be considered because: * Quantseq fragments are estimated have an average size of ~200bp * This way, any dynamic binning biases can be avoided

alleyoop tcperutrpos [-h] -r <reference fasta> -b <bed file> [-s <SNP directory>]
                     [-l <maximum read length>] -o <output directory> [-mq <MQ cutoff>]
                     [-t <threads>] bam [bam ...]

Input

File	Description
Reference fasta	The reference sequence of the genome to map against in fasta format.
-s	(optional) The called variants from the snp dunk to filter false-positive T->C conversions.
-b	Bed file with coordinates of 3’UTRs.
bam	BAM file(s) containing the final filtered reads from slamdunk (wildcard * accepted).

Output

File	Description
tcperutr.csv	Tab-separated table with mutation rates, one line per UTR position.
tcperutr.pdf	Plot of the mutation rates along the UTRs.

Below is an example plot of mutation rates along all UTRs in a sample. Typically, one will see increasing error rates towards the end of a UTRs. For SLAMseq samples with longer labelling times, the overall T->C conversions in the bottom plot will begin to increase compared to the overall background in the top plot.

Parameters

Parameter	Required	Description
-h		Prints the help.
-o	x	The output directory where all output files of this tool will be placed.
-r	x	The reference fasta file.
-b	x	Bed file with coordinates of 3’UTRs.
-mq		Minimum base quality for T->C conversions to be counted.
-t		The number of threads to use. All tools run single-threaded, so it is recommended to use as many threads as available samples.
-s		The called variants from the snp dunk to filter false-positive T->C conversions.
-l		Maximum read length in all samples (will be automatically estimated if not set).
bam	x	BAM file(s) containing the final filtered reads (wildcard * accepted).

alleyoop dump [-h] -r <reference fasta> -s <SNP directory> -o <output directory>
              [-mq <MQ cutoff>] [-t <threads>] bam [bam ...]

Docker enables you to run slamdunk out-of-the box wihtout caring about prerequisites and installation procedures. All you need is to install the Docker engine and run the slamdunk Docker image.

# Build Ubuntu-based image
cd slamdunk/docker/ubuntu
docker build -t <user>/<imagename> .

# View images
docker images

# All data is contained in current working directory and available under /data in the container

 docker run -m 8g -v $(pwd):/data tobneu/slamdunk slamdunk map -o /data/map -r /data/GRCm38.fa -5 5 -n 1 /data/testset.fq.gz

# Start a free t2.micro instance (small genomes only e.g. bacteria) on e.g. the us-west-1 region
docker-machine create --driver amazonec2 --amazonec2-region us-west-1 aws-slamdunk

# Start a paid t2.large instance (large genomes) on e.g. the us-west-1 region
docker-machine create --driver amazonec2 --amazonec2-region us-west-1 --amazonec2-instance-type t2.large aws-slamdunk

eval $(docker-machine env aws-slamdunk)

docker run -m 8g -v $(pwd):/data tobneu/slamdunk slamdunk map -o /data/map -r /data/GRCm38.fa -5 5 -n 1 /data/testset.fq.gz

# Shut down
docker-machine stop aws-slamdunk

# Remove
docker-machine rm -y aws-slamdunk

Version 0.3.4

Bugfixes:

• Reverse strand A->G SNP coordinates offset fixed.
• Mismatch of string to int in key search fixed for summary.

Version 0.3.3

Bugfixes:

• Mutation type bugfix in MPTagToConversion fixed
• Deduplicated bam file properly closed for indexing
• alleyoop snpeval also works now without snp sets
• Chromosome retreival fix for pysam
• dplyr dependencies removed (Bioconda)

Version 0.3.2

Changes:

• Bioconda : Slamdunk recipe added. Slamdunk now available via conda from v0.3.2!
• Symlink ngm -> nextgenmap/bin/ngm-0.5.2/ngm replaced by hard copy for bioconda-utils build compatibility.

Version 0.3.1

Changes:

• Upgrade Samtools 1.3.1 -> Samtools 1.9 for upcoming bioconda build.

Bugfixes:

• pysam-0.15.0.1 region retreival fix. (dashed chromosomes allowed now)
• NGM permission fix to allow Singularity image build directly from Docker hub.

Version 0.3.0

Changes:

• Travis-CI testing added.
• Automated versionable Docker container builds.
• Static 2 T>C conversion cutoff multiTCSTringency parameter replaced by dynamic conversion-threshold parameter
• Positional track module added to Alleyoop to produce genome-wide positional T>C conversion rate bigWigtracks
• Read-separator module added to Alleyoop to separated T>C reads from non T>C reads into bam-files.
• Docker base image set to ubuntu:18.04

Bugfixes:

• Supplementary alignment flags unset in filtered bam
• Fixed numpy version removed to satisfy pandas dependency
• Minimum baseQ filter now inclusive which is the expected behaviour
• Reference check for short chromosomes introduced
• Backwards compatibility to pysam 0.8.3 introduced

Version 0.2.4

Changes:

• License updated to AGPLv3
• Deduplicator now only marks duplicates instead of removing them. Useful for deduplication QA like dupRadar . Allows for deduplication of T>C-fraction of reads only.
• Singularity build-file branch added.

Bugfixes:

• readInRegion fixed: Switched from fetch(region=”chr:start-end” (1-based) to fetch(reference=chr, start=start, end=end) (0-based). Intervals close to the ends of a chromosome are now correctly handeled and not skipped.
• Hotfix to fix executable permissions on some R plotting scripts
• Fixed alleyoop collapse to ignore all MLE columns for now
• R package dependencies fixed for IMP cluster
• include_package_data removed for proper contrib import

Version 0.2.3

Bugfixes:

• Hotfix to include README.md in sdist packaging
• Hotfix to fix executable permissions on some R plotting scripts
• Fixed alleyoop collapse to ignore all MLE columns for now

Version 0.2.2

Changes:

• Slamdunk supports now MultiQC report creation
• Default set to local mapping
• Base-quality cutoff implemented throughout the entire slamdunk / alleyoop workflow
• BAQ computation disabled for samtools mpileup
• Dedup now supports selection of reads containing a defined # T>C conversions
• All documentation moved to gh-pages branch for slicker repo
• CPMs now normalized to filtered reads
• Docker image now build automatically to head revision
• Official webpage introduced instead of readthedocs.org hosting
• Evaluation module for count files added to splash

Bugfixes:

• PCAs for single sample working now
• Dedup working again
• Sample files may contain empty lines now

Version 0.2.1

Changes:

• PCA will be added to alleyoop summary if count folder is provided
• Reads in UTRs will be added to alleyoop summary if count folder is provided
• Comment tags added to summary, rates, utrrates, tcperreadpos, tcperutrpos to be recognized by MultiQC <http://multiqc.info/>
• NextGenMap udated to version 0.5.2
• Slamdunk now checks NextGenMap version
• Simulation module (splash) added: simulates slamdunk samples from a set of UTRs (BED file) and evalutes results computed by SlamDunk. See splash –help for more information
• -i/–sample-index is now 1-based instead of 0-based
• Columns for conversion rate confidence interval added to count files (not used yet)
• Filter summary integrated into log
• Added sample names now in globalRatePlotter

Bugfixes:

• Number of sequenced reads fixed for BAM files computed with -ss/–skip-sam option
• NextGenMap memory leak fixed

Version 0.2.0

Due to major changes v0.2.0 is not compatible with v0.1.0. Please rerun alle your samples with slamdunk 0.2.0!

Changes:

• Option to supply sample info via samplesheet instead of plain raw reads added.
• Added @RG tag to bam files containing sample info for best-practice and easier summary calculation.
• Flagstat files removed.
• –skip-sam flag added to only output bam.
• –sample-index flag implemented for cluster distribution.
• Multi-TC stringency now also available for utr rate plots.
• *stats prefixes removed from alleyoop modules.
• Alleyoop summary module implemented. Summary contains sample infos (if specified via samplesheet) and number of sequenced, mapped and filtered reads.
• Alleyoop merge module allows now merging upon column names.
• Sample info and reference + checksum now documented in tcount files.
• Version.py added.

Bugfixes :

• NGM interspersed order of multimappers fixed.
• Random seed from filter module deleted.
• Alleyoop rates display error of bars higher than ylim fixed.
• Min base quality now again propagated to all modules.
• Auto-scaling error fixed in globalRatePlotter.

Version 0.1.0

• Initial pre-release.