Customizing modules in Tentacle

Tentacle is constructed using a modular approach making it easy to customize and modify. A common modification or addition to Tentacle could be to add support for an additional mapping software.

Creating/modifying mapper modules

Within the Tentacle folder structure, the mapper modules are located in $TENTACLE_ROOT/tentacle/mappers. If Tentacle was installed using pip into a virtualenv, the mapper modules must be placed (or symlinked) in $TENTACLE_VENV/lib/python2.7/site-packages/tentacle/mappers so that Tentacle can find them. Do not forget to add an import line in the tentacle/mappers/__init__.py as well!

Mapper modules inherit from the base mapper class, as seen in the example mapper modules that are provided with Tentacle. To create a new mapper module, copy one of the others, change the filename and modify it to suit your mapper. Make sure that the mapper you want to use is available in your PATH variable.

Another important aspect to consider when adding support for an additional mapper is that there needs to be a parser that can extract the information Tentacle requires from the mapper’s output files. All such parsers are located in the submodule tentacle.parsers. See Parsers.

Generic mapper class for Tentacle

Generic mapping module for Tentacle.

This module contains a class meant for subclassing to produce functional mapping modules for Tentacle. Read the docstrings and compare with other mapping modules to enable support for other mappers with Tentacle.

class tentacle.mappers.mapper.Mapper(logger, mapper)

Bases: object

A generic mapper class.

The mapper class has several methods that require custom implementations for each specific mapper. See examples of other mapper modules that subclass this class on how this can be done.

Note

This class must be subclassed and customized to produce a functional mapping module.

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

Can be used to perform a quick sanity check of the output file before continuing with the rest of the pipeline.

Note

This method must be customized in a subclass.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

Args:

local_files (namedtuple): A tuple with three fields containing

node-local filenames. Fields: ‘reads’, ‘contigs’, ‘annotations’.

options (Namespace): A Namespace from ArgpumentParser.parse_args with

all arguments parsed from the command line (incl. non-mapper-related).

Returns:

mapper_call (list): A shlex.split()-style list of the mapper call.

output_filename (str): A string with the output filename.

Note

This method must be customized in a subclass.

For examples on how to customize this method, please refer to one of the other modules available in tentacle.mappers.

static create_argparser()

Initializes an argparser for arguments relevant for the mapper.

Args:

None

Returns:

parser: an initalized argparse.ArgumentParser with an argument_group

with options for this specific mapper.

It is recommended to only utilize long options and prepend option names with the mapper to minimize risk of overloading other options from other argument parsers (e.g. write –blastOption instead of just –option if you are adding a module for BLAST).

prepare_reads(remote_files, local_files, options)

Transfer and prepare reads.

Contains all logic for preparing reads, including; determining format (FASTA/FASTQ), detects compression (gzip), performs quality filtering (FASTX), and FASTQ-to-FASTA conversion (seqtk).

Args:

remote_files (namedtuple): Contains fields; ‘contigs’, ‘reads’, ‘annotations’.

local_files (namedtuple): Contains fields; ‘contigs’, ‘reads’, ‘annotations’.

options (Namespace): Parsed arguments from the Tentacle command line.

Returns:

local_files (namedtuple): Updated with new filename of the prepared reads.

Raises:

PipelineError: If any part of the quality control/conversion pipeline

malfunctions.

Note

This method normally does NOT require modification.

prepare_references(remote_files, local_files, options, rebase_to_local_tmp=None)

Transfers and prepares reference DB for the mapper.

Calls tentacle.mapping_utils.gunzip_copy() to transfer the references to the compute node.

Args:

remote_files (namedtuple): Contains fields; ‘contigs’, ‘reads’, ‘annotations’.

local_files (namedtuple): Contains fields; ‘contigs’, ‘reads’, ‘annotations’.

options (Namespace): Parsed arguments from the Tentacle command line.

Kwargs:

rebase_to_local_tmp (function): An optional function, used only in special cases,

see e.g. tentacle.mappers.gem.

Returns:

local_files (namedtuple): Updated with new filename of transferred references.

Note

This method normally does NOT require modification.

run_mapper(local_files, options)

Runs mapper.

Args:

remote_files (namedtuple): Contains fields; ‘contigs’, ‘reads’, ‘annotations’.

options (Namespace): A Namespace from ArgpumentParser.parse_args with

all arguments parsed from the command line (incl. non-mapper-related).

Returns:

output_filename (str): Filename of mapping results.

Raises:

MapperError: If the mapper does not return with returncode 0.

Note

This method normally does NOT require modification.

Specific mapper classes for Tentacle

Here is a list of the implemented mapper classes that comes with Tentacle by default.

BLASTN

class tentacle.mappers.blastn.Blastn(logger, mapper_name)

Bases: tentacle.mappers.mapper.Mapper

Blast

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

static create_argparser()

Creates a parser for mapping options.

prepare_references(remote_files, local_files, options, rebase_to_local_tmp=None)

Transfers and prepares reference DB for blast.

GEM

class tentacle.mappers.gem.Gem(logger, mapper_name)

Bases: tentacle.mappers.mapper.Mapper

GEM

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

static create_argparser()

Creates a parser for mapping options.

prepare_references(remote_files, local_files, options, rebase_to_local_tmp)

Transfers and prepares reference DB for GEM.

pBLAT

class tentacle.mappers.pblat.Pblat(logger, mapper='pblat')

Bases: tentacle.mappers.mapper.Mapper

Pblat

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

static create_argparser()

Creates and returns a parser for mapping options.

RazerS3

class tentacle.mappers.razers3.Razers3(logger, mapper='razers3')

Bases: tentacle.mappers.mapper.Mapper

RazerS3

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

static create_argparser()

Creates a parser for mapping options.

USEARCH

class tentacle.mappers.usearch.Usearch(logger, mapper_name)

Bases: tentacle.mappers.mapper.Mapper

USEARCH

assert_mapping_results(output_filename)

Makes a quick check that the mapping appears successful.

construct_mapper_call(local_files, options)

Parses options and creates a mapper call (python list) that can be used with Popen.

static create_argparser()

Creates a parser for mapping options.

prepare_references(remote_files, local_files, options, rebase_to_local_tmp=None)

Transfers and prepares reference DB for usearch.