# Copyright 2018 by Adhemar Zerlotini. All rights reserved.
#
# This file is part of the Biopython distribution and governed by your
# choice of the "Biopython License Agreement" or the "BSD 3-Clause License".
# Please see the LICENSE file that should have been included as part of this
# package.
"""Bio.SearchIO support for InterProScan output formats.

This module adds support for parsing InterProScan XML output.
The InterProScan is available as a command line program or on
EMBL-EBI's web page.
Bio.SearchIO.InterproscanIO was tested on the following version:

- versions: 5.26-65.0 (interproscan-model-2.1.xsd)

More information about InterProScan are available through these links:
- Publication: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3998142/
- Web interface: https://www.ebi.ac.uk/interpro/search/sequence-search
- Documentation: https://github.com/ebi-pf-team/interproscan/wiki


Supported format
================

Bio.SearchIO.InterproscanIO supports the following format:

- XML   - 'interproscan-xml' - parsing


interproscan-xml
================

The interproscan-xml parser follows the InterProScan XML described here:
https://github.com/ebi-pf-team/interproscan/wiki/OutputFormats

+--------------+--------------------+----------------------------------------+
| Object       | Attribute          | XML Element                            |
+==============+====================+========================================+
| QueryResult  | target             | `InterPro`                             |
|              +--------------------+----------------------------------------+
|              | program            | `InterProScan`                         |
|              +--------------------+----------------------------------------+
|              | version            | `protein-matches.interproscan-version` |
+--------------+--------------------+----------------------------------------+
| Hit          | accession          | `signature.name`                       |
|              +--------------------+----------------------------------------+
|              | id                 | `signature.ac`                         |
|              +--------------------+----------------------------------------+
|              | description        | `signature.desc`                       |
|              +--------------------+----------------------------------------+
|              | dbxrefs            | `IPR:entry.ac`                         |
|              |                    | `go-xref.id`                           |
|              |                    | `pathway-xref.db:pathway-xref.id`      |
|              +--------------------+----------------------------------------+
|              | attributes         |                                        |
|              | ['Target']         | `*-match` / `*-location`               |
|              | ['Target version'] | `signature-library-release.library`    |
|              | ['Hit type']       | `signature-library-release.version`    |
+--------------+--------------------+----------------------------------------+
| HSP          | bitscore           | `*-location.score`                     |
|              +--------------------+----------------------------------------+
|              | evalue             | `*-location.evalue`                    |
+--------------+--------------------+----------------------------------------+
| HSPFragment  | query_start        | `*-location.start`                     |
| (also via    +--------------------+----------------------------------------+
| HSP)         | query_end          | `*-location.end`                       |
|              +--------------------+----------------------------------------+
|              | hit_start          | `*-location.hmm-start`                 |
|              +--------------------+----------------------------------------+
|              | hit_end            | `*-location.hmm-end`                   |
|              +--------------------+----------------------------------------+
|              | query              | `sequence`                             |
+--------------+--------------------+----------------------------------------+

InterProScan XML files may contain a match with multiple locations or multiple
matches to the same protein with a single location. In both cases, the match
is uniquely stored as a HIT object and the locations as HSP objects.

`HSP.*start == *start - 1` (Since every start position is 0-based in Biopython)
`HSP.aln_span ==  query-end - query-start`

The types of matches or locations (eg. hmmer3-match, hmmer3-location,
coils-match, panther-location) are stored in hit.attributes['Hit type'].
For instance, for every 'phobious-match', there will be a 'phobious-location'.
Therefore, Hit.type will store the string excluding '-match' or '-location'
('phobious', in this example).
"""

from .interproscan_xml import InterproscanXmlParser

# if not used as a module, run the doctest
if __name__ == "__main__":
    from Bio._utils import run_doctest
    run_doctest()