annotate swissmodel_api.xml @ 1:f09a77e52ae5 draft default tip

planemo upload for repository https://github.com/galaxyproject/tools-iuc/main/tools/swissmodel_modelling_api commit d35c7d4dbe93451605d81b8e4fea8923e78b70ae

<tool name="SWISS-MODEL Modelling API" id="swissmodel_modelling_api" profile="25.1" version="@TOOL_VERSION@+galaxy@VERSION_SUFFIX@">
    <description>
        Fully automated protein structure homology-modelling
    </description>
    <macros>
        <token name="@TOOL_VERSION@">2.0.0</token>
        <token name="@VERSION_SUFFIX@">0</token>
    </macros>
    <xrefs>
        <xref type="bio.tools">swiss_model</xref>
    </xrefs>
    <requirements>
        <requirement type="package" version="3.11">python</requirement>
        <requirement type="package" version="2.32.5">requests</requirement>
        <credentials name="swissmodel_api_credentials" version="1.0" label="SWISS-MODEL API Credentials" description="Credentials for accessing SWISS-MODEL API">
            <secret name="swissmodel_api_token" inject_as_env="SWISSMODEL_API_TOKEN" optional="false" label="SWISS-MODEL API token" description="Token to authenticate to the SWISS-MODEL API. Can be managed on your https://swissmodel.expasy.org/login_page"/>
        </credentials>
    </requirements>
    <command detect_errors="aggressive"><![CDATA[
mkdir -p 'output_dir/'
&& python3 '$__tool_directory__/sm_api_wrapper.py'
                          $output_format.modelcif
                          $output_format.pdb
                          #if $project_title
                            --project-title '${project_title}'
                          #end if
                          #if $project_type == 'alignment'
                            --assembly-id '${assembly_id}'
                            --auth-asym-id '${auth_asym_id}'
                            --pdb-id '${pdb_id}'
                            --template-seqres-offset '${template_seqres_offset}'
                            --template-sequence '${template_sequence}'
                          #elif $project_type == 'usertemplate'
                            --template-file '${template_file}'
                          #end if
                          '${project.project_type}'
                          output_dir
                          #if $project_type == 'alignment'
                            '${target_sequence}'
                          #else
                            #for $i in $target_list
                              '${i.sequence}'
                            #end for
                          #end if
&& find output_dir -type f -name '*.gz' -exec gzip -d {} +
]]>
    </command>
    <inputs>
        <param name="project_title" type="text" value="Untitled project" optional="true" label="Project title"/>
        <conditional name="project">
            <param name="project_type" type="select" value="automodel" optional="false" label="Modelling setup" display="radio">
                <option value="automodel" selected="true">Automodel mode</option>
                <option value="alignment">Alignment mode</option>
                <option value="usertemplate">User template mode</option>
            </param>
            <!-- AutoModel Mode Options -->
            <when value="automodel">
                <repeat name="target_list" min="1"
                        help="Sequence(s) to be modelled. Add multiple sequences for hetero modelling." title="Target sequence">
                    <param name="sequence" type="text" optional="false"
                           label="Sequence"/>
                </repeat>
            </when>
            <!-- Alignment Mode Options -->
            <when value="alignment">
                <param name="target_sequence" type="text" optional="false"
                       label="Target sequence"
                       help="Target sequence as part of the alignment"/>
                <param name="pdb_id" type="text" optional="false"
                       label="PDB/ SMTL ID">
                    <help><![CDATA[
PDB ID of the template SMTL entry as found in the
<a href="https://swissmodel.expasy.org/templates/" target="_blank"> SWISS-MODEL
Template Library</a>.
                    ]]></help>
                    <validator type="regex" message="Only PDB-like IDs allowed, e.g. '1crn'.">^\d[A-Za-z0-9]{3}$</validator>
                </param>
                <param name="assembly_id" type="integer" min="0" value="0" optional="false"
                       label="Assembly ID">
                    <help><![CDATA[
Assembly ID of the template as found in the
<a href="https://swissmodel.expasy.org/templates/" target="_blank"> SWISS-MODEL
Template Library</a>.
                    ]]></help>
                </param>
                <param name="auth_asym_id" type="text" optional="false"
                       label="Chain name">
                    <help><![CDATA[
Chain name in the template assembly as found in the
<a href="https://swissmodel.expasy.org/templates/" target="_blank"> SWISS-MODEL
Template Library</a>.
                    ]]></help>
                </param>
                <param name="template_sequence" type="text" optional="false"
                       label="Template sequence"
                       help="Template sequence as part of the alignment"/>
                <param name="template_seqres_offset" type="integer" value="0" optional="false" label="Template sequence offset">
                    <help><![CDATA[
Offset of the template sequence segment with respect to the full template
sequence.
                    ]]></help>
                </param>
            </when>
            <!-- User Template Mode Options -->
            <when value="usertemplate">
                <repeat name="target_list" min="1"
                        help="Sequence(s) to be modelled. Add multiple sequences for hetero modelling." title="Target sequence">
                    <param name="sequence" type="text" optional="false"
                           label="Sequence"/>
                </repeat>
                <param name="template_file" type="data" format="txt" optional="false" label="Template coordinates file"
                       help="File with template coordinaqtes in PDB legacy format."/>
            </when>
        </conditional>
        <section name="output_format" title="Output format options">
            <param name="modelcif" type="boolean" truevalue="" falsevalue="--no-modelcif" checked="true" label="ModelCIF format"/>
            <param name="pdb" type="boolean" truevalue="--fetch-pdb" falsevalue="" checked="false" label="PDB legacy format"/>
        </section>
    </inputs>
    <outputs>
        <collection name="json_collection" type="list"
                    label="Metadata files for $project_title">
            <discover_datasets directory="output_dir/JSON" format="json" pattern="(?P&lt;name&gt;.+)\.json$"/>
        </collection>
        <collection name="pdb_collection" type="list"
                    label="PDB files for $project_title">
            <discover_datasets directory="output_dir/PDB" format="pdb" pattern="(?P&lt;name&gt;.+)\.pdb$"/>
            <filter>output_format['pdb'] == True</filter>
        </collection>
        <collection name="modelcif_collection" type="list"
                    label="ModelCIF files for $project_title">
            <discover_datasets directory="output_dir/ModelCIF" format="cif" pattern="(?P&lt;name&gt;.+)\.cif$"/>
            <filter>output_format['modelcif'] == True</filter>
        </collection>
    </outputs>
    <tests>
        <!-- w/o params, all will be empty strings, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <assert_stderr>
                <has_line line="Argument of '&lt;SEQUENCE[S]&gt;' can not be an empty"/>
            </assert_stderr>
        </test>
        <!-- with sequences, everything else empty, fail -->
        <test expect_exit_code="1" expect_failure="true">
            <conditional name="project">
                <repeat name="target_list">
                    <param name="sequence" value="MVVKAVCVINGDAKGTVFFEQESSGTPVKVSGEVCGL"/>
                </repeat>
                <repeat name="target_list">
                    <param name="sequence" value="AKGLHGFHVHEFGDNTNGCMSSGPHFNPYGKE"/>
                </repeat>
            </conditional>
            <assert_stderr>
                <has_line line="SWISS-MODEL token is not provided in credentials!"/>
            </assert_stderr>
        </test>
        <!-- alignment mode tests, as few params as possible, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <conditional name="project">
                <param name="project_type" value="alignment"/>
                <param name="assembly_id" value="0"/>
                <param name="template_seqres_offset" value="0"/>
            </conditional>
            <assert_stderr>
                <has_line line="Option '--auth-asym-id' can not be an empty string"/>
            </assert_stderr>
        </test>
        <!-- alignment mode tests, with auth_asym_id, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <conditional name="project">
                <param name="assembly_id" value="0"/>
                <param name="auth_asym_id" value="A"/>
                <param name="project_type" value="alignment"/>
                <param name="template_seqres_offset" value="0"/>
            </conditional>
            <assert_stderr>
                <has_line line="Option '--pdb-id' can not be an empty string"/>
            </assert_stderr>
        </test>
        <!-- alignment mode tests, with pdb_id, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <conditional name="project">
                <param name="assembly_id" value="0"/>
                <param name="auth_asym_id" value="A"/>
                <param name="pdb_id" value="1AKE"/>
                <param name="project_type" value="alignment"/>
                <param name="template_seqres_offset" value="0"/>
            </conditional>
            <assert_stderr>
                <has_line line="Option '--template-sequence' can not be an empty string"/>
            </assert_stderr>
        </test>
        <!-- alignment mode tests, with template_sequence, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <conditional name="project">
                <param name="assembly_id" value="0"/>
                <param name="auth_asym_id" value="A"/>
                <param name="pdb_id" value="1AKE"/>
                <param name="project_type" value="alignment"/>
                <param name="template_seqres_offset" value="0"/>
                <param name="template_sequence" value="MVVKAVCVINGDAKGTVFFEQESSGTPV"/>
            </conditional>
            <assert_stderr>
                <has_line line="Argument of '&lt;SEQUENCE[S]&gt;' can not be an empty"/>
            </assert_stderr>
        </test>
        <!-- alignment mode tests, with sequence, fail -->
        <test expect_exit_code="1" expect_failure="true">
            <conditional name="project">
                <param name="assembly_id" value="0"/>
                <param name="auth_asym_id" value="A"/>
                <param name="pdb_id" value="1AKE"/>
                <param name="project_type" value="alignment"/>
                <param name="target_sequence" value="MVVKAVCVINGDAKGTVFFEQESSGTPVKVSG"/>
                <param name="template_seqres_offset" value="0"/>
                <param name="template_sequence" value="MVVKAVCVINGDAKGTVFFEQESSGTPV"/>
            </conditional>
            <assert_stderr>
                <has_line line="SWISS-MODEL token is not provided in credentials!"/>
            </assert_stderr>
        </test>
        <!-- usertemplate mode tests, as few params as possible, fail -->
        <test expect_exit_code="2" expect_failure="true">
            <conditional name="project">
                <param name="project_type" value="usertemplate"/>
                <param name="template_file" value="model_01.pdb"/>
            </conditional>
            <assert_stderr>
                <has_line line="Argument of '&lt;SEQUENCE[S]&gt;' can not be an empty"/>
            </assert_stderr>
        </test>
        <!-- usertemplate mode tests, with sequence, fail -->
        <test expect_exit_code="1" expect_failure="true">
            <conditional name="project">
                <param name="project_type" value="usertemplate"/>
                <param name="template_file" value="model_01.pdb"/>
                <repeat name="target_list">
                    <param name="sequence" value="MVVKAVCVINGDAKGTVFFEQESSGTPVKVSGEVCGL"/>
                </repeat>
                <repeat name="target_list">
                    <param name="sequence" value="AKGLHGFHVHEFGDNTNGCMSSGPHFNPYGKE"/>
                </repeat>
            </conditional>
            <assert_stderr>
                <has_line line="SWISS-MODEL token is not provided in credentials!"/>
            </assert_stderr>
        </test>
    </tests>
    <help><![CDATA[
The SWISS-MODEL Modelling API tool gives you convenient access to homology models build by `SWISS-MODEL <https://swissmodel.expasy.org>`_ via our `API <https://swissmodel.expasy.org/docs/help#modelling_api>`_.

By default, the tool fetches model coordinates in ModelCIF format from the SWISS-MODEL API. SWISS-MODEL enriches its ModelCIF files with lots of extra information, essential for later reproduction of the computational experiment and enabling for easy deposition at archiving sites, like `Model Archive <https://modelarchive.org>`_. Output format can be toggled in the *Output format options* section for legacy PDB format, in case you are dealing with old-school tools in your workflows. Regardless of the format, output file names follow the pattern ``model_<N>.[cif|pdb]``.

The SWISS-MODEL API provides three major modelling modes: Automodel, alignment and template upload mode.

Automodel mode
--------------

This mode corresponds to the "Sequence(s)" input mode and just hitting the "Build Model" button on our `web page <https://swissmodel.expasy.org/interactive>`_.

Automodel goes from sequence(s) to structural model. A single sequence for input leads to monomers or homomers. Multiple sequences for input produces heteromers, incorporating all target sequences. Multiple sequences input is sometimes mistaken for multi-model modelling tasks but its not, to produce models for more than one target sequence, you need to run the tool for each sequence separately.

Inside an automodel job, the following happens:

1. Template search in `PDB <https://www.rcsb.org>`_ and AlphaFold DB v4 sequences
2. Template selection by estimated quality and target sequence coverage

   - gain high model confidence
   - cover as much of the target sequence, maybe by different models per region
   - employ models for equal regions if structurally diverse

3. Build models

Automodel options
~~~~~~~~~~~~~~~~~

Only one or more sequences required, that's all! Single sequence produces monomers and/ or homomers. Multiple sequences produces heteromers.


Alignment mode
--------------

This mode corresponds to the "Target-Template Alignment" input mode on our `web page <https://swissmodel.expasy.org/interactive#alignment>`_.

The alignment mode still builds a model for a target sequence and a template from the `SWISS-MODEL template library <https://swissmodel.expasy.org/templates/>`_ (**SMTL**). But instead of creating the alignment from its own template search run, SWISS-MODEL will use an alignment provided by yourself. The alignment will be mapped onto the template sequence and then a structural model will be build.

To properly map a your alignment within the SMTL, you need to provide some extra information. SWISS-MODEL needs the identifier of the template. That's a common PDB ID, it just needs to exist in the SMTL. Then you need to identify the biological assembly of the entry you want your model to be based on... which can be easily done from the SMTL page. The assembly ID comes with the SMTL ID, its the number after the PDB ID and alternative assemblies of an entry can be found at the bottom of an entry page. The last component is the chain name you used for the alignment. Be aware, the SMTL uses its own chain names, so the original PDB chain name may not work. A mapping of chain names is provided on SMTL entry pages.

Alignment mode options
~~~~~~~~~~~~~~~~~~~~~~

- Target sequence: first part of the alignment
- Template sequence: second sequence of the alignment
- Template sequence offset: position the template sequence starts at with respect to the full sequence; When using only a sub-sequence of the full sequence, it may be hard to automatically map to the right region in case of repeats, so you need to provide the offset
- PDB/ SMTL ID: PDB ID of the SMTL entry the alignment refers to
- Assembly ID: ID of the biological assembly to be used as template
- Chain name: ID of the chain to be used for modelling, needs to be the SMTL name, not the PDB name


User template mode
------------------

This mode corresponds to the "User Template" input mode on our `web page <https://swissmodel.expasy.org/interactive#structure>`_.

The user template mode builds a model for a target sequence and template coordinates provided by you instead of using a SMTL entry for coordinates. The sequence alignment between target and template sequence is still calculated by SWISS-MODEL using HHblits and BLAST, or local alignment algorithm if both methods fail. With the alignment, a structural model is build based on the provided template coordinates.

Inside a user template job, the following happens:

1. Analyse uploaded coordinates
2. Calculate alignments with HHblits & BLAST
3. Choose "better" alignment or calculate Smith-Waterman alignment
4. Build model

User template mode options
~~~~~~~~~~~~~~~~~~~~~~~~~~
- Target sequence: sequence to be modelled (post multiple for heteros)
- Template coordinate file: your template file, must be PDB formatted

Attribution/ License
~~~~~~~~~~~~~~~~~~~~

Terms of use can be found at https://swissmodel.expasy.org/docs/terms_of_use

Modelling results of SWISS-MODEL are licensed under the
`CC BY-SA 4.0 Creative Commons Attribution-ShareAlike 4.0 International License <https://creativecommons.org/licenses/by-sa/4.0/legalcode>`_.

]]>
    </help>
    <citations>
        <!-- SWISS-MODEL -->
        <citation type="doi">10.1093/nar/gky427</citation>
        <!-- ProMod3 -->
        <citation type="doi">10.1371/journal.pcbi.1008667</citation>
        <!-- QMEANDisCo -->
        <citation type="doi">10.1093/bioinformatics/btz828</citation>
        <!-- Quaternary Structure Prediction/ QSQE -->
        <citation type="doi">10.1038/s41598-017-09654-8</citation>
        <!-- lDDT -->
        <citation type="doi">10.1093/bioinformatics/btt473</citation>
    </citations>
    <creator>
        <person email="[e-mail]" familyName="Bienert" givenName="Stefan"/>
        <organization name="Swiss Institute of Bioinformatics" alternateName="SIB" url="https://www.sib.swiss"/>
        <organization name="Biozentrum, University of Basel" alternateName="Biozentrum" url="https://www.biozentrum.unibas.ch"/>
    </creator>
</tool>