view release on metacpan or  search on metacpan

lib/Bio/MUST/Apps/FortyTwo/Manual.pod  view on Meta::CPAN

instead of species level).

If the inferred taxonomy for the orthologue satisfies the taxonomic filter, the
orthologue is simply added to the MSA. Otherwise, it is tagged as a contaminant
(C<c#>). When an orthologue is tagged as a contaminant, the binomial of the
organism at the origin of the taxonomic affiliation (or a higher-ranking taxon
in case of LCA inference) is further appended to its identifier (i.e.,
C<...Genus_species>). This mechanism can also be used to estimate the level of
contamination of any genome or transcriptome (see the L<"Metagenomic
mode"|"Estimation of the contamination level in metagenomic mode"> below).

Taxonomic filters are optional and require a local copy of the I<NCBI Taxonomy>
database (C<tax_dir> parameter in the C<config> file). It can be installed using
C<setup-taxdir.pl> (see L<"Installation..."|"Installation and dependencies">
below).

The logic behind decoy TOL proteomes is similar to the way C<PARA> files work
but with a twist. To be considered as uncontaminated, an orthologue must obtain
a best hit C<BLAST> bit score that is higher when compared to the sequences of
the MSA than those of the decoy TOL proteomes. However, decoy proteomes from
organisms taxonomically related to the one to which the orthologue belongs are
expected to yield very good bit scores, maybe higher than any bit score from
sequences already present in the MSA. To avoid rejecting a genuinely
uncontaminated orthologue because of this possibility, C<42> skips all decoy
hits that satisfy the taxonomic filter specified for the organism being added.

Let us take an example. Imagine that our MSAs only contain sequences from
hymenopterans (e.g., wasps and ants). If we enable decoy TOL proteomes when
adding some bees, contaminated orthologues corresponding to say, parasitic mites
such as I<Varroa destructor>, will be correctly rejected because they match some
tick protein included in I<Ixodes> decoy proteome. However, genuine bee
sequences would also be wrongly rejected because they match with the I<Apis>
decoy proteome. To avoid this, we will use a taxonomic filter to skip
Hymenoptera (or even Hexapoda) hits in decoy proteomes.

As one can see, both avenues rely on taxonomic filters. Choosing the right level
of taxonomic filtration is no easy task and often requires a bit of testing. In
short, the more distant potential contaminants are from organisms being added,
the easier it is to find an adequate taxonomic filter (see
L<"tax_filter"|"Taxonomic filters (tax_filter)"> below for details).

=head3 Alignment and MSA integration

To integrate the orthologue into the MSA, C<42> chooses the most appropriate
B<template(s)> for alignment among the closest relatives. As for taxonomic
inference, it considers each of them in turn and stops once the coverage of the
orthologue cannot be significantly improved. This allows C<42> to select a
slightly less related sequence as a template provided it aligns with a longer
part of the orthologue. By how much exactly coverage has to be improved for a
close sequence to be retained as a template can be fine-tuned with the
C<coverage_mul> parameter of the C<config> file.

Then comes the alignment itself. With nucleotide C<banks>, both C<BLAST> and
C<exonerate> aligners are available, whereas only C<BLAST> can be used with
protein C<banks>. The preferred aligner can be specified using the C<aligner>
parameter of the C<config> file.

The C<BLAST> aligner has been much improved with respect to the aligner of the
original C<forty>. It extracts all the HSPs for the selected template(s) from
the XML C<BLAST> report and uses them as guides for integrating the orthologue
fragments into the MSA. Then, once all fragments have been integrated for all
candidate organisms, it merges them into a single contiguous sequence per
orthologue. When fragments overlap, the merger gives precedence to the fragments
corresponding to the highest-scoring templates and HSPs.

When the new C<exonerate> aligner is preferred, only the longest selected
template is used. In most cases, the orthologue can be aligned as a single large
fragment. If not, C<42> emits different types of warnings depending on the exact
issue. In worst cases (e.g., C<exonerate> crashing), the orthologue cannot be
integrated, often due to structural rearrangements between the orthologue and
the template. To avoid discarding the orthologue in such cases, one can enable
C<BLAST> as a fall-back for exonerate failures by setting the C<aligner>
parameter to C<exoblast>.

Aligned orthologues are integrated into the MSA all together at the end of the
file but in the following arrangement: first by family, then by candidate
organism and then by accession. Contaminants are interspersed with genuine
orthologues but can be easily identified thanks to their tag (C<c#>).

=head3 Redundancy detection and handling

Independently of the aligner, C<42> never integrates twice the same sequence for
a given organism, even if obtained from multiple orthologues. Further, it
filters out subsequences included in sequences from the same organism that are
either already present in the MSA or that are listed in the C<NON> counterpart
of the MSA. C<NON> files are a bit like C<PARA> files (non-aligned sequences in
C<FASTA> format) except that matches must be exact. Finally, when a newly added
orthologue includes a sequence already present in the MSA for the same organism,
the latter can be either kept or removed, depending on the value of the
parameter C<ali_keep_lengthened_seqs> in the C<config> file.

=head3 C<#NEW#> tags

All newly added orthologues are tagged by a specific C<#NEW#> suffix. This tag
helps C<42> to organize the post-processing of new sequences (e.g., fragment
merging and redundancy detection) but is also useful for the end-user to
identify which sequences have been added by C<42>. Therefore any preexisting
C<#NEW#> tag is cleared when C<42> starts processing a MSA.

While automatic untagging can be disabled via the parameter
C<ali_keep_old_new_tags> in the C<config> file, one should note that such
preexisting new sequences are basically invisible to C<42>. This means that they
will not be chosen as queries for mining transcriptomes nor as templates for
aligning additional new orthologues. Moreover they will not be considered for
taxonomic analyses. That is why the recommended approach is to let this
parameter set to its default value.

=head1 Usage

=head2 Installation and dependencies

C<42> is written in I<Modern Perl> but relies on 1 to 3 external dependencies:
C<NCBI-BLAST+>, C<Exonerate> and C<CAP3>. However only BLAST is really required.
You should download and install the corresponding binaries the way you feel the
most appropriate for your system. (Alas this can be tricky.)

=over

=item L<ftp://ftp.ncbi.nlm.nih.gov/blast/executables/blast+/LATEST/>

=item L<https://www.ebi.ac.uk/about/vertebrate-genomics/software/exonerate>
(use classical v2.2.0 not newer v2.4.0)

=item L<http://seq.cs.iastate.edu/cap3.html>

=back

Most other dependencies can be handled automatically by C<cpanm>. If you cannot
(or do not want to) modify your system Perl install, you will need to setup a
C<Perlbrew> environment (L<https://perlbrew.pl/>). Below are two distinct sets
of commands that should work on C<Ubuntu> 20.04.

=head3 System Perl install

Obviously, this requires admin rights on your system:

    $ sudo su
    $ apt install zlib1g-dev                    # maybe unnecessary
    $ apt install libssl-dev                    # maybe unnecessary
    $ apt install libmodule-build-tiny-perl     # maybe unnecessary
    $ apt install ncbi-blast+
    $ apt install cpanminus
    $ cpanm Bio::FastParsers
    $ cpanm Bio::MUST::Core
    $ cpanm Bio::MUST::Drivers
    $ cpanm Bio::MUST::Apps::FortyTwo
    $ exit

If a C<cpanm> command fails, retype it with the C<--force> option:

    $ cpanm --force Bio::MUST::Drivers

Finally install a local mirror of the I<NCBI Taxonomy>:

    $ setup-taxdir.pl --taxdir=taxdump/