translate - SeqAn API Documentation

# fn() translate
translate sequences of Dna or Rna into amino acid alphabet, optionally with frames

Defined in | <seqan/translation.h>
Signature | `int translate(target, source[, frames][, geneticCode][, TParallelism]) int translate(target, source[, frames][, geneticCodeSpec][, TParallelism])`

## Parameters

`target` | The amino acid sequence(s). StringSet of AminoAcid or String of AminoAcid if source is a single string and frames is `SINGLE_FRAME`.
`source` | Source sequences String or StringSet. If the value type is not Dna, Dna5, Rna, Rna5 then it is converted to Dna5.
`frame` | The TranslationFrames, defaults to SINGLE_FRAME.
`geneticCode` | The GeneticCode to use, defaults to `GeneticCode<CANONICAL>` (use to specify GeneticCode at compile-time)
`geneticCodeSpec` | The GeneticCodeSpec to use (use to specify GenetiCode at run-time)
`TParallelism` | Whether to use SMP or not, see ParallelismTags .

## Return Values

`int` | 0 on success, and -1 on incompatible parameters (e.g. multiple frames but target type not StringSet).

## Detailed Description

If OpenMP is supported by platform and TParallelism is not specified as "Serial", translation will be parallelized. The only exception is when doing single-frame translation of a single string -- which is never parallelized.

The translation process is fastest when using ConcatDirect-StringSets for both input and output StringSets and when not having to convert the alphabet of the source, i.e. feeding AminoAcid-Strings, not CharStrings (although the latter is possible).

Please note that specifying the GeneticCode at compile time avoids having unrequired conversion tables in memory.

### Example

    StringSet<Dna5String> dnaSeqs;

    // do something that fills up dnaSeqs, e.g. read from file or assign

    StringSet<String<AminoAcid>, Owner<ConcatDirect<> > > aaSeqs;

    translate(aaSeqs, dnaSeqs, SIX_FRAME);

    // do something with the aaSeqs

## Data Races

If not stated otherwise, concurrent invocation is not guaranteed to be thread-safe.

## See Also

- GeneticCode
- TranslationFrames

#### Dox Sources

    /*!
     * @fn translate
     *
     * @headerfile <seqan/translation.h>
     *
     * @brief translate sequences of Dna or Rna into amino acid alphabet, optionally
     *        with frames
     *
     * @signature int translate(target, source[, frames][, geneticCode][,
     *            TParallelism])
     * @signature int translate(target, source[, frames][, geneticCodeSpec][,
     *            TParallelism])
     *
     * @param[out] target The amino acid sequence(s). @link StringSet @endlink of
     *                    @link AminoAcid @endlink or @link String @endlink of @link
     *                    AminoAcid @endlink if source is a single string and frames
     *                    is <tt>SINGLE_FRAME</tt>.
     * @param[in] source Source sequences @link String @endlink or @link StringSet
     *                   @endlink. If the value type is not Dna, Dna5, Rna, Rna5
     *                   then it is converted to Dna5.
     * @param[in] frame The @link TranslationFrames @endlink, defaults to
     *                  SINGLE_FRAME.
     * @param[in] geneticCode The @link GeneticCode @endlink to use, defaults to
     *                        <tt>GeneticCode&lt;CANONICAL&gt;</tt> (use to specify
     *                        GeneticCode at compile-time)
     * @param[in] geneticCodeSpec The @link GeneticCodeSpec @endlink to use (use to
     *                            specify GenetiCode at run-time)
     * @param[in] TParallelism Whether to use SMP or not, see @link ParallelismTags
     *                         @endlink .
     *
     * @return int 0 on success, and -1 on incompatible parameters (e.g. multiple
     *             frames but target type not StringSet).
     *
     * If OpenMP is supported by platform and TParallelism is not specified as
     * "Serial", translation will be parallelized. The only exception is when doing
     * single-frame translation of a single string -- which is never parallelized.
     *
     * The translation process is fastest when using ConcatDirect-StringSets for
     * both input and output StringSets and when not having to convert the alphabet
     * of the source, i.e. feeding AminoAcid-Strings, not CharStrings (although the
     * latter is possible).
     *
     * Please note that specifying the GeneticCode at compile time avoids having
     * unrequired conversion tables in memory.
     *
     * @section Example
     *
     * @code{.cpp}
     * StringSet<Dna5String> dnaSeqs;
     *
     * // do something that fills up dnaSeqs, e.g. read from file or assign
     *
     * StringSet<String<AminoAcid>, Owner<ConcatDirect<> > > aaSeqs;
     *
     * translate(aaSeqs, dnaSeqs, SIX_FRAME);
     *
     * // do something with the aaSeqs
     * @endcode
     *
     *
     * @see TranslationFrames
     * @see GeneticCode
     */