annotate mmpbsa_mmgbsa.xml @ 4:879662481176 draft

"planemo upload for repository https://github.com/galaxycomputationalchemistry/galaxy-tools-compchem/ commit cc13bd32ef2d80b01dc197a3ca120a4ff9f0dacc"

<tool id="mmpbsa_mmgbsa" name="MMPBSA/MMGBSA" version="@TOOL_VERSION@+galaxy@GALAXY_VERSION@">
    <description>tool for estimating ligand binding affinities</description>
    <macros>
        <import>macros.xml</import>
        <token name="@GALAXY_VERSION@">0</token>
    </macros>
    <expand macro="requirements">
        <requirement type="package" version="2.11.2">jinja2</requirement>
    </expand>
    <command detect_errors="exit_code"><![CDATA[
        python '$mmpbsa_script' '$inputs' &&
        PATH_TO_MMPBSA=\$(dirname `which MMPBSA.py`) &&
        export AMBERHOME=\$(dirname \$PATH_TO_MMPBSA) &&
        #if $input.simulation.solvatedcomplex:
            MMPBSA.py -O -i '$parameteroutfile' -sp '$input.simulation.solvatedcomplex' -cp '$input.simulation.complex' -rp '$input.simulation.receptor' -lp '$input.simulation.ligand' -y '$input.simulation.trajcomplex' -o '$resultoutfile' -do '$decompoutfile'
        #else:
            MMPBSA.py -O -i '$parameteroutfile' -cp '$input.simulation.complex' -rp '$input.simulation.receptor' -lp '$input.simulation.ligand' -y '$input.simulation.trajcomplex' -o '$resultoutfile' -do '$decompoutfile'
        #end if
    ]]></command>
    <configfiles>
        <inputs name="inputs"/>
        <configfile name="mmpbsa_script"><![CDATA[
import os
import sys
import json

from jinja2 import Environment, FileSystemLoader

input_json_path = sys.argv[1]
params = json.load(open(input_json_path, "r"))


currentpath = "$__tool_directory__"  # should work generally
template_environment = Environment(loader=FileSystemLoader(currentpath),lstrip_blocks=True, trim_blocks=True)
template = template_environment.get_template('template_mmpbsa_mmgbsa.j2')
print(params)

with open("$parameteroutfile",'w+') as f:
    f.write(template.render(params))


        ]]></configfile>
    </configfiles>
    <inputs>
        <section name="input" title="Input" expanded="true">
            <conditional name="simulation">
                <param name="simtype" type="select" label="Single or Multiple Trajectories" help="For analysis of a single complex in water choose Single. For separate complex, receptor and ligand trajectories choose Multiple.">
                    <option selected="True" value="single">Single Trajectory Protocol (STP)</option>
                    <option value="multiple">Multiple Trajectory Protocol (MTP)</option>
                </param>
                <when value="single">
                    <param format="txt" name="ligand" type="data" label="AMBER prmtop input for Ligand"/>
                    <param format="txt" name="receptor" type="data" label="AMBER prmtop input for Receptor"/>
                    <param format="txt" name="complex" type="data" label="AMBER prmtop input for Complex"/>
                    <param format="txt" optional="true" name="solvatedcomplex" type="data" label="AMBER prmtop input for Solvated Complex" help="This is optional. Not required if trajectory already has solvent removed"/>
                    <param format="netcdf" name="trajcomplex" type="data" label="NetCDF trajectory input for Complex" help="Trajectory of the (solvated) complex"/>
                </when>
                <when value="multiple">
                    <param format="txt" name="ligand" type="data" label="AMBER prmtop input for Ligand"/>
                    <param format="txt" name="receptor" type="data" label="AMBER prmtop input for Receptor"/>
                    <param format="txt" name="complex" type="data" label="AMBER prmtop input for Complex"/>
                    <param format="txt" optional="true" name="solvatedcomplex" type="data" label="AMBER prmtop input for Solvated Complex" help="This is optional. Not required if trajectory already has solvent removed"/>
                    <param format="netcdf" name="trajligand" type="data" label="NetCDF trajectory input for Ligand"/>
                    <param format="netcdf" name="trajreceptor" type="data" label="NetCDF trajectory input for Receptor"/>
                    <param format="netcdf" name="trajcomplex" type="data" label="NetCDF trajectory input for Complex"/>
                </when>
            </conditional>
        </section>
        <section name="allparams" title="General parameters" expanded="true">
            <param name="startframe" type="integer" value="1" label="First frame to analyse" min="1" max="100000000"/>
            <param name="endframe" type="integer" value="9999999" label="Final frame to analyse" min="1" max="100000000"/>
            <param name="interval" type="integer" value="1" label="Interval between frames analyzed" min="1" max="10000"/>
            <param name="entropy" type="boolean" checked="true" truevalue="1" falsevalue="0" label="Perform quasi-harmonic entropy calculation?" help="Calculate the quasi-harmonic entropy"/>
            <param name="use_sander" type="boolean" checked="false" label="Use sander" truevalue="1" falsevalue="0" help="Forces MMPBSA.py to use sander for energy calculations, even when mmpbsa_py_energy will suffice. Default behavior is to use mmpbsa_py_energy where possible."/>
            <param name="keep_files" type="boolean" checked="false" truevalue="1" falsevalue="0" label="Keep additional files?" help="If specified, temporary files will be kept and stored in a collection, which may be helpful for debugging."/>
            <param name="strip_mask" type="text" value=":WAT:Cl-:Na+" label="Strip mask" help="Enter a mask for removing unneeded atoms (water and ions) from the solvated prmtop file"/>
        </section>
        <section name="calcdetails" title="Details of calculation and parameters" expanded="true">
            <conditional name="gb_pb_calc">
                <param name="calctype" type="select" label="GB or PB calculation?" help="Calculate the electrostatic contribution to the free energy with the Poisson-Boltzmann equation or the General Born approximation">
                    <option selected="True" value="gb">General Born (GB)</option>
                    <option value="pb">Poisson-Boltzmann (PB)</option>
                </param>
                <when value="gb">
                    <param name="igb" type="select" value="5" label="GB model to use (igb)" help="5 options are available. Consult the AmberTools manual for more details. Note that some missing values (e.g. 3 and 4) are no longer supported.">
                        <!-- <option value="0">0 - no generalized Born term is used</option> -->
                        <option value="1">1 - Basic pairwise generalized Born model</option>
                        <option value="2">2 - OBC model</option>
                        <option value="5">5 - alternative OBC model</option>
                        <option value="7">7 - GBn model</option>
                        <option value="8">8 - alternative GBn model</option>
                    </param>
                    <param name="saltcon" type="float" value="0" label="Salt concentration (M)" min="0.0" max="6.0"/>
                    <param name="surfoff" type="float" value="0" label="Offset to correct (by addition) the value of the non-polar contribution to the solvation free energy term"/>
                    <!-- <param name="surften" type="float" value="0.0072" label="Surface tension">
                        <help><![CDATA[Surface tension in kcal / mol / Å<sup>2</sup>]]></help>
                    </param> -->
                    <param name="molsurf" type="boolean" checked="false" truevalue="1" falsevalue="0" label="Use the molsurf algorithm to calculate the surface area for the nonpolar solvation term?" help="The default behavior is to use LCPO (Linear Combination of Pairwise Overlaps)."/>
                    <param name="probe" type="float" value="1.4" label="Radius of the probe molecule (supposed to be the size of a solvent molecule), in Å, to use when determining the molecular surface" help="Only applicable when the molsurf algorithm is selected." min="0"/>
                    <param name="msoffset" type="float" value="0" label="Offset to apply to the individual atomic radii in the system when calculating the molsurf surface." />
                </when>
                <when value="pb">
                    <param name="istrng" type="float" value="0.15" label="Ionic strength (M)" min="0.0" max="2.0"/>
                    <param name="fillratio" type="float" value="4.0" label="Fill ratio" help="The ratio between the longest dimension of the rectangular finite-difference grid and that of the solute" min="0.0" max="10.0"/>
                    <param name="inp" type="integer" value="1" label="Nonpolar solvation method" min="1" max="2" help="1 - default"/>
                    <param name="radiopt" type="integer" value="0" label="Use optimized radii?" min="0" max="2" help="0 - default do not use these"/>
                    <param name="cavity_offset" type="float" value="-0.5692" label="Offset value used to correct non-polar free energy contribution" help="Not used for APBS"/>
                    <!-- <param name="cavity_surften" type="float" value="0.0378" label="Surface tension" help="Surface tension in kcal / mol / Ų"/> -->
                    <param name="exdi" type="float" value="80.0" label="External dielectric constant"/>
                    <param name="indi" type="float" value="1.0" label="Internal dielectric constant"/>
                    <param name="scale" type="float" value="2.0" label="Resolution of the Poisson Boltzmann grid" help="Resolution of the Poisson Boltzmann grid, equal to the reciprocal of the grid spacing."/>
                    <param name="linit" type="integer" value="1000" label="Maximum number of iterations of the linear Poisson Boltzmann equation to try"/>
                    <param name="prbrad" type="select" label="Solvent probe radius in Å">
                        <option value="1.4" selected="True">1.4</option>
                        <option value="1.6">1.6</option>
                    </param>
                    <!-- <param name="sander_apbs" type="boolean" truevalue="1" falsevalue="0" label="" help=""/> -->
                </when>
            </conditional>
            <conditional name="decomposition">
                <param name="decomposition" type="select" label="Carry out decomposition analysis?" help="Choose to carry out decomposition analysis">
                    <option selected="True" value="yes">yes</option>
                    <option value="no">no</option>
                </param>
                <when value="yes">
                    <param name="csv_format" type="boolean" checked="true" truevalue="1" falsevalue="0" label="CSV format" help="Output in CSV format; choose false for unformatted text output"/>
                    <param name="dec_verbose" type="select" value="0" label="Decomposition verbosity" help="Choose verbosity of the decomposition output file. Note that if the verbosity level selected is too high and the parser cannot find the requested information, the job will fail.">
                        <option value="0">DELTA energy, total contribution only</option>
                        <option value="1" selected="true">DELTA energy, total, sidechain, and backbone contributions</option>
                        <option value="2">Complex, Receptor, Ligand, and DELTA energies, total contribution only</option>
                        <option value="3">Complex, Receptor, Ligand, and DELTA energies, total, sidechain, and backbone contributions</option>
                    </param>
                    <param name="idecomp" type="select" value="1" label="Energy decomposition scheme to use" help="Choose an energy decomposition scheme.">
                        <option value="1">1 - Per-residue decomp with 1-4 terms added to internal potential terms</option>
                        <option value="2">2 - Per-residue decomp with 1-4 EEL added to EEL and 1-4 VDW added to VDW potential terms.</option>
                        <option value="3">3 - Pairwise decomp with 1-4 terms added to internal potential terms</option>
                        <option value="4">4 - Pairwise decomp with 1-4 EEL added to EEL and 1-4 VDW added to VDW potential terms</option>
                    </param>
                </when>
                <when value="no"/>
            </conditional>
        </section>
    </inputs>
    <outputs>
        <data format="txt" name="resultoutfile" label="${tool.name}: Statistics"/>
        <data format="txt" name="decompoutfile" label="${tool.name}: Decomposition statistics">
            <filter>calcdetails['decomposition']['decomposition'] == 'yes'</filter>
        </data>
        <data format="txt" name="parameteroutfile" label="${tool.name}: Parameter output"/>
        <collection name="tempfiles" type="list" label="${tool.name}: Temporary files">
            <filter>allparams['keep_files'] == 1</filter>
            <discover_datasets pattern="_MMPBSA(?P&lt;designation&gt;.+)" format="txt"/>
        </collection>
    </outputs>
    <tests>
        <test>
            <param name="ligand" value="ligand.prmtop" ftype="txt"/>
            <param name="receptor" value="receptor.prmtop" ftype="txt"/>
            <param name="complex" value="complex.prmtop" ftype="txt"/>
            <param name="trajcomplex" value="1err_desolvated_mini.nc" ftype="netcdf"/>
            <conditional name="allparams">
                <param name="entropy" value="0"/>
                <param name="keep_files" value="1"/>
            </conditional>
            <conditional name="gb_pb_calc">
                <param name="calctype" value="gb"/>
                <param name="igb" value="2"/>
                <param name="saltcon" value="0.100"/>
            </conditional>
            <conditional name="">
                <param name="decomposition" value="no"/>
            </conditional>
            <output name="resultoutfile">
                <assert_contents>
                <has_text text="GENERALIZED BORN:"/>
                <has_text text="DELTA TOTAL                -53."/>
                </assert_contents>
            </output>
        </test>
        <test>
            <param name="ligand" value="ligand.prmtop" ftype="txt"/>
            <param name="receptor" value="receptor.prmtop" ftype="txt"/>
            <param name="complex" value="complex.prmtop" ftype="txt"/>
            <param name="trajcomplex" value="1err_desolvated_mini.nc" ftype="netcdf"/>
            <conditional name="allparams">
                <param name="startframe" value="1"/>
                <param name="endframe" value="1"/>
                <param name="entropy" value="0"/>
            </conditional>
            <conditional name="gb_pb_calc">
                <param name="calctype" value="pb"/>
                <param name="istrng" value="0.100"/>
            </conditional>
            <conditional name="decomposition">
                <param name="decomposition" value="yes"/>
            </conditional>
            <output name="resultoutfile">
                <assert_contents>
                <has_text text="POISSON BOLTZMANN:"/>
                <has_text text="DELTA TOTAL                -47"/>
                </assert_contents>
            </output>
            <output name="decompoutfile">
                <assert_contents>
                    <has_text text="idecomp = 1: Per-residue decomp adding 1-4 interactions to Internal"/>
                    <has_text text="HIE 240,R HIE 240"/>
                    <has_text text="RAL 241,L RAL   1,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0"/>
                </assert_contents>
            </output>
        </test>
    </tests>
    <help><![CDATA[

.. class:: infomark

**What it does**

This tool calculates the Molecular Mechanics Poisson-Boltzman Surface Area (MMPBSA), which is an estimate of the binding free energy between a ligand and a receptor. It also can calculate the MMGBSA, which is a common alternative, replacing the Poisson-Boltzmann term with the General Born approximation.

.. class:: infomark

**How it works**

Prior to using this tool, simulations of the ligand complexed with the receptor must be run. This tool, which wraps AmberTools, requires a prmtop (Amber parameter topology) file for the receptor, ligand and the complex and the trajectory in netCDF format.

- Single Trajectory Estimate: A single simulation of the complex in water is run. The trajectory of this complex is used to estimate the MMPBSA or MMGBSA, depending on the options chosen.
- Multiple Trajectory Estimate: Separate simulations of the complex in water, the receptor in water and the ligand in water are run. This is useful if the ligand (or receptor) is expected to have a significantly different conformation in solution compared to in the complex, but is otherwise not recommended as it increases the uncertainty of the results. The trajectories are used to estimate the MMPBSA or MMGBSA depending on the options chosen.

If simulations were performed using the Galaxy GROMACS tools, the topology (in top format) and trajectories (in xtc format) can be converted to Amber prmtop and netcdf formats using the Convert Parameters and MDTraj file converter tools respectively.

.. class:: infomark

**Outputs created**

- The statistics file which includes all information about the frames analysed and average energies. The DELTA G binding is estimated. If negative this is a favourable binding. Note that by default the entropy contribution to binding (unfavourable) is not calculated. A normal mode analysis is needed.
- The parameter file contains the input parameters passed from Galaxy to MMPBSA.py in the expected MMPBSA input format.
- (Optional, if decomposition analysis is performed) The decomposition file contains a breakdown of each residue's contribution to the energy. For example, using the default energy decomposition scheme (1) the interaction of each residue with the rest of the system is calculated and listed.
- (Optional, if the "Keep additional files?" option is chosen) A collection containing all temporary files generated in the course of the calculation. This may be useful for debugging.

.. class:: infomark

**User guide and documentation**

- The `AmberTools Manual`_
- The `Amber Tutorial`_ on using MMPBSA.py
- There are many more complex flags available. This Galaxy wrapper only supports GB and PB binding free energies and decomposition. Parallel calculations are not supported at present.

.. _`Amber Tutorial`: http://ambermd.org/tutorials/advanced/tutorial3/py_script/index.htm
.. _`AmberTools Manual`: https://ambermd.org/doc12/Amber18.pdf

    ]]></help>
    <expand macro="citations">
        <expand macro="mmpbsa_citation"/>
    </expand>
</tool>