<commit_before>Usage
*****

Once installed, the AllosMod protocol can be run by means of a command line
tool (``allosmod``). Each component of the protocol is also a Python package,
which can be called directly from other Python software
(via ``import allosmod``).

Overview
========

Running the basic protocol consists of three steps:

#. Create a set of input files specifying the sequence to model, any
   structures to use as templates, and AllosMod parameters.

#. Run ``allosmod setup`` to verify the inputs and generate a script file.

#. Run the script file (typically on a Linux cluster) to set up the AllosMod
   energy landscape and generate Modeller input files to sample it. In some
   cases this sampling is then carried out; in others you will need to run
   Modeller on the input files.

Input files
===========

Several input files are needed to run the protocol:

 * **PDB file(s)**: all structures used to create the energy landscape
   for the simulation. 

 * **Alignment file** (should be named ``align.ali``): this should contain
   one entry for each PDB file above
   (the align code, i.e. the part after the ``>P1;`` header, should match the
   PDB filename) and another entry (named ``pm.pdb``) with the sequence to
   be simulated. This alignment file should be generated after an alignment
   procedure, as this alignment will be used to generate restraints for
   the simulation. Multiple chains can be specified by using a "/" as a
   separator, the same specifications used in MODELLER. There are many ways
   to create an alignment file including `MODELLER <http://salilab.org/modeller/tutorial/basic.html>`_ and `ClustalW <https://www.ebi.ac.uk/Tools/msa/clustalw2/>`_.
   *WARNING* Small errors in the alignment can cause big errors during a
   simulation due to energy conservation problems. Make sure there are no
   misalignments in which adjacent residues are aligned far apart in
   sequence (alignment programs often do this at the beginning or end
   of chains). 

 * **Structure list** (should be named ``list``): this contains a list of
   all the PDB files used to create the energy landscape for the simulation,
   one per line. Refer to the LIGPDB and ASPDB options in ``input.dat`` to
   define interactions in the allosteric site. 

 * **Ligand file** (optional; should be named ``lig.pdb``): this contains
   the structure of the ligand extracted from a ligand bound PDB file
   (defined by LIGPDB in ``input.dat``). A radius (rAS) around the ligand
   is used to define the allosteric site. If ``lig.pdb`` is excluded,
   AllosMod will set up a landscape with as many energy minima as are
   described by structures in the list file. 

 * **AllosMod parameter file** (should be named ``input.dat``): this contains
   one line per parameter as follows. All parameters are optional except for
   NRUNS.

NRUNS = X
    is the number of independent simulations to run. 

rAS = X
    is the radius (in Ångstroms) around the coordinates of the ligand that
    will specify the allosteric site. If the file ``lig.pdb`` is included,
    the allosteric site will be calculated using rAS and the coordinates
    in LIGPDB. Therefore, ``lig.pdb`` must be extracted from LIGPDB. 

SAMPLING = X
    can be one of:

    ``simulation`` (Default)
        A simulation is set up to be run later.

    ``moderate_am``
        Sampling is performed using a quick, unequilibrated simulation.
        This quick sampling will give a representation of the types of
        conformations that are consistent with the modeled energy landscape.
        Set "SAMPLING = simulation" to predict the relative populations
        of the conformations at equilibrium. 

    ``moderate_am_scan``
        As above, sampling is performed using a quick, unequilibrated
        simulation. In this case, simulations should be performed at high
        temperature in order to access rarely populated structures. These
        rarely populated structures are rapidly cooled using only restraints
        from adjacent residues, which does not change the global structure
        but allows helices to form etc. Rarely populated structures are 
        defined by their dissimilarity to the first structure in the
        list file (SCAN_CUTOFF percent of trajectory snapshots are outputted). 

delEmax = X
    is the maximum energy for each pairwise atomic distance contact,
    typically between 0.09 and 0.12 kcal/mol. If excluded, the value will
    be assigned according to 3.6*(number of residues/number of distance
    interactions). See paper for more details. 

LIGPDB = X
    is the PDB file used to define the allosteric site. AllosMod defines
    the allosteric site using the distance (rAS) from the effector
    (``lig.pdb``) with respect to the LIGPDB coordinates. 

ASPDB = X
    is the PDB file used to define the contacts in the allosteric site,
    i.e. the pairwise atomic distances in ASPDB are used to determine the
    nonbonded distance energy. As an example, to run an effector unbound
    simulation: 1) include the effector bound and unbound PDB files in
    ``align.ali`` and ``list``, 2) set ASPDB to the effector unbound
    PDB file, and 3) set LIGPDB to the effector bound PDB file. 

DEVIATION = X
    is the distance (in Ångstroms) that the atoms will be randomized
    when creating the initial structure (default is 1-10 Å depending on
    simulation type).

MDTEMP = X
    is the temperature (in degrees Kelvin) for the simulation (default
    is 300 K). Alternatively, set MDTEMP to "scan" and the simulation
    temperature will alternate between 300 K, 350 K, 400 K, 450 K, and
    500 K. Therefore, directory 0 will have a 300 K simulation, directory 1
    will have a 350 K simulation, and so on until directory 5 that will
    restart the sequence with a 300 K simulation.

SCAN_CUTOFF = X
    is the percent of trajectory snapshots outputted if sampling is
    moderate_am_scan. The default is 10 percent, i.e. 0.1*NRUNS structures
    will be outputted selected by differing the most from the inputted
    PDB structure.

BREAK = True/False
    is an option to include chemical frustration (Weinkam et al. 2009
    Biochemistry, p2394-2402). Chemical frustration is modeled by breaking
    all interactions involving buried, charged residues. Regions with
    many buried, charged residues will have high conformational variability. 

SCLBREAK = X
    if BREAK=True, this number is used to scale the contacts with residues
    that cause chemical frustration. 

ZCUTOFF = X
    if BREAK=True, this number is used to select which residues cause
    chemical frustration. ZCUTOFF is the z-score cut off of the distribution
    involving the number of charged contacts per residue; residues with
    a z-score above this threshold are predicted to cause chemical frustration. 

LOCRIGID = True/False
    if set to True, secondary structure, corresponding to the input PDB
    files, will have increased stability in the simulation. Increased
    stability is maintained by increasing the energy by a factor of 10
    for all C alpha-C alpha contacts between 2 and 5 residues apart. 

COARSE = True/False
    is an option to coarse grain the energy landscape by restricting the
    nonbonded distance energy to include C alpha and C beta atoms only.
    This allows very large proteins to be simulated without overwhelming
    the computer's memory. This option is automatically set to True for
    proteins over 1500 residues. 

{ADDITIONAL_RESTRAINT} {DISTANCE} {STANDARD_DEVIATION} {INDICES}
    is used to add additional restraints between residues.
    ADDITIONAL_RESTRAINT can be HARM, LOBD, or UPBD corresponding to
    distance restraints that are harmonic, lower bounded only, or upper
    bounded only, respectively. DISTANCE and STANDARD_DEVIATION corresponds
    to the distance (in Ångstroms) between two atoms in the residues
    specified in INDICES. If residue index is an amino acid, atom type
    will be CA, otherwise atom type will be the first present: N, P, C,
    or O. INDICES is a list of residue indices separated by commas.
    Restraints are added between each successive pair of indices,
    i.e. between i1 and i2, between i3 and i4, ... The residue index
    corresponds to the position in the input alignment file. Therefore,
    if there are multiple chains, the index for the first residue in the
    second chain will be one more than the index for the last residue in
    the first chain (refer to any output PDB for simplicity).

 * ***Alter residue contact energies** (optional): ``break.dat`` contains
   a list of residues whose pairwise contact energies (delEmax) will be
   scaled by a specifed value. Each line contains one residue index
   (corresponding to simulated sequence) in the first column and one
   scaling factor in the second column. For example, to reduce all
   contact energies for residue 30 by 90 %, break.dat would have one
   line with "30 0.1". break.dat is created automatically by setting
   BREAK=True, however, the user may specify any desired residues and
   scaling factors by including break.dat in a batch run. <commit_msg>Document run of 'allosmod setup'.<commit_after>Usage
*****

Once installed, the AllosMod protocol can be run by means of a command line
tool (``allosmod``). Each component of the protocol is also a Python package,
which can be called directly from other Python software
(via ``import allosmod``).

Overview
========

Running the basic protocol consists of three steps:

#. Create a set of input files specifying the sequence to model, any
   structures to use as templates, and AllosMod parameters.

#. Run ``allosmod setup`` to verify the inputs and generate a script file.

#. Run the script file (typically on a Linux cluster) to set up the AllosMod
   energy landscape and generate Modeller input files to sample it. In some
   cases this sampling is then carried out; in others you will need to run
   Modeller on the input files.

Input files
===========

Several input files are needed to run the protocol:

 * **PDB file(s)**: all structures used to create the energy landscape
   for the simulation. 

 * **Alignment file** (should be named ``align.ali``): this should contain
   one entry for each PDB file above
   (the align code, i.e. the part after the ``>P1;`` header, should match the
   PDB filename) and another entry (named ``pm.pdb``) with the sequence to
   be simulated. This alignment file should be generated after an alignment
   procedure, as this alignment will be used to generate restraints for
   the simulation. Multiple chains can be specified by using a "/" as a
   separator, the same specifications used in MODELLER. There are many ways
   to create an alignment file including `MODELLER <http://salilab.org/modeller/tutorial/basic.html>`_ and `ClustalW <https://www.ebi.ac.uk/Tools/msa/clustalw2/>`_.
   *WARNING* Small errors in the alignment can cause big errors during a
   simulation due to energy conservation problems. Make sure there are no
   misalignments in which adjacent residues are aligned far apart in
   sequence (alignment programs often do this at the beginning or end
   of chains). 

 * **Structure list** (should be named ``list``): this contains a list of
   all the PDB files used to create the energy landscape for the simulation,
   one per line. Refer to the LIGPDB and ASPDB options in ``input.dat`` to
   define interactions in the allosteric site. 

 * **Ligand file** (optional; should be named ``lig.pdb``): this contains
   the structure of the ligand extracted from a ligand bound PDB file
   (defined by LIGPDB in ``input.dat``). A radius (rAS) around the ligand
   is used to define the allosteric site. If ``lig.pdb`` is excluded,
   AllosMod will set up a landscape with as many energy minima as are
   described by structures in the list file. 

 * **AllosMod parameter file** (should be named ``input.dat``): this contains
   one line per parameter as follows. All parameters are optional except for
   NRUNS.

NRUNS = X
    is the number of independent simulations to run. 

rAS = X
    is the radius (in Ångstroms) around the coordinates of the ligand that
    will specify the allosteric site. If the file ``lig.pdb`` is included,
    the allosteric site will be calculated using rAS and the coordinates
    in LIGPDB. Therefore, ``lig.pdb`` must be extracted from LIGPDB. 

SAMPLING = X
    can be one of:

    ``simulation`` (Default)
        A simulation is set up to be run later.

    ``moderate_am``
        Sampling is performed using a quick, unequilibrated simulation.
        This quick sampling will give a representation of the types of
        conformations that are consistent with the modeled energy landscape.
        Set "SAMPLING = simulation" to predict the relative populations
        of the conformations at equilibrium. 

    ``moderate_am_scan``
        As above, sampling is performed using a quick, unequilibrated
        simulation. In this case, simulations should be performed at high
        temperature in order to access rarely populated structures. These
        rarely populated structures are rapidly cooled using only restraints
        from adjacent residues, which does not change the global structure
        but allows helices to form etc. Rarely populated structures are 
        defined by their dissimilarity to the first structure in the
        list file (SCAN_CUTOFF percent of trajectory snapshots are outputted). 

delEmax = X
    is the maximum energy for each pairwise atomic distance contact,
    typically between 0.09 and 0.12 kcal/mol. If excluded, the value will
    be assigned according to 3.6*(number of residues/number of distance
    interactions). See paper for more details. 

LIGPDB = X
    is the PDB file used to define the allosteric site. AllosMod defines
    the allosteric site using the distance (rAS) from the effector
    (``lig.pdb``) with respect to the LIGPDB coordinates. 

ASPDB = X
    is the PDB file used to define the contacts in the allosteric site,
    i.e. the pairwise atomic distances in ASPDB are used to determine the
    nonbonded distance energy. As an example, to run an effector unbound
    simulation: 1) include the effector bound and unbound PDB files in
    ``align.ali`` and ``list``, 2) set ASPDB to the effector unbound
    PDB file, and 3) set LIGPDB to the effector bound PDB file. 

DEVIATION = X
    is the distance (in Ångstroms) that the atoms will be randomized
    when creating the initial structure (default is 1-10 Å depending on
    simulation type).

MDTEMP = X
    is the temperature (in degrees Kelvin) for the simulation (default
    is 300 K). Alternatively, set MDTEMP to "scan" and the simulation
    temperature will alternate between 300 K, 350 K, 400 K, 450 K, and
    500 K. Therefore, directory 0 will have a 300 K simulation, directory 1
    will have a 350 K simulation, and so on until directory 5 that will
    restart the sequence with a 300 K simulation.

SCAN_CUTOFF = X
    is the percent of trajectory snapshots outputted if sampling is
    moderate_am_scan. The default is 10 percent, i.e. 0.1*NRUNS structures
    will be outputted selected by differing the most from the inputted
    PDB structure.

BREAK = True/False
    is an option to include chemical frustration (Weinkam et al. 2009
    Biochemistry, p2394-2402). Chemical frustration is modeled by breaking
    all interactions involving buried, charged residues. Regions with
    many buried, charged residues will have high conformational variability. 

SCLBREAK = X
    if BREAK=True, this number is used to scale the contacts with residues
    that cause chemical frustration. 

ZCUTOFF = X
    if BREAK=True, this number is used to select which residues cause
    chemical frustration. ZCUTOFF is the z-score cut off of the distribution
    involving the number of charged contacts per residue; residues with
    a z-score above this threshold are predicted to cause chemical frustration. 

LOCRIGID = True/False
    if set to True, secondary structure, corresponding to the input PDB
    files, will have increased stability in the simulation. Increased
    stability is maintained by increasing the energy by a factor of 10
    for all C alpha-C alpha contacts between 2 and 5 residues apart. 

COARSE = True/False
    is an option to coarse grain the energy landscape by restricting the
    nonbonded distance energy to include C alpha and C beta atoms only.
    This allows very large proteins to be simulated without overwhelming
    the computer's memory. This option is automatically set to True for
    proteins over 1500 residues. 

{ADDITIONAL_RESTRAINT} {DISTANCE} {STANDARD_DEVIATION} {INDICES}
    is used to add additional restraints between residues.
    ADDITIONAL_RESTRAINT can be HARM, LOBD, or UPBD corresponding to
    distance restraints that are harmonic, lower bounded only, or upper
    bounded only, respectively. DISTANCE and STANDARD_DEVIATION corresponds
    to the distance (in Ångstroms) between two atoms in the residues
    specified in INDICES. If residue index is an amino acid, atom type
    will be CA, otherwise atom type will be the first present: N, P, C,
    or O. INDICES is a list of residue indices separated by commas.
    Restraints are added between each successive pair of indices,
    i.e. between i1 and i2, between i3 and i4, ... The residue index
    corresponds to the position in the input alignment file. Therefore,
    if there are multiple chains, the index for the first residue in the
    second chain will be one more than the index for the last residue in
    the first chain (refer to any output PDB for simplicity).

 * ***Alter residue contact energies** (optional): ``break.dat`` contains
   a list of residues whose pairwise contact energies (delEmax) will be
   scaled by a specifed value. Each line contains one residue index
   (corresponding to simulated sequence) in the first column and one
   scaling factor in the second column. For example, to reduce all
   contact energies for residue 30 by 90 %, break.dat would have one
   line with "30 0.1". break.dat is created automatically by setting
   BREAK=True, however, the user may specify any desired residues and
   scaling factors by including break.dat in a batch run. 

Set up AllosMod protocol
========================

Once all the input files are prepared, run ``allosmod setup`` in the directory
containing them. The ``allosmod`` command line tool provides many subfunctions
(use ``allosmod help`` to list them all). ``allosmod setup`` will check the
input files for problems, and if they all look OK, it will generate a
script file called ``qsub.sh``. This script can be run on any Linux machine,
although it is intended to be run on an SGE cluster using the ``qsub -t 1-N``
command, where ``N`` is the value of NRUNS in ``input.dat``.

This script file will set up the AllosMod landscape. If SAMPLING in
``input.dat`` is set to 'simulation' (the default) MODELLER input files are
generated. These can then be run to perform the simulation. Otherwise, the
sampling is performed by ``qsub.sh`` itself.

#. Run ``allosmod setup`` to verify the inputs and generate a script file.

#. Run the script file (typically on a Linux cluster) to set up the AllosMod
   energy landscape and generate Modeller input files to sample it. In some
   cases this sampling is then carried out; in others you will need to run
   Modeller on the input files.

Input files
{'fraction_non_alphanumeric': 0.05264776746808838, 'fraction_numerical': 0.008458502076177783, 'mean_word_length': 3.5420256111757857, 'pattern_counts': {'":': 0, '<': 7, '<?xml version=': 0, '>': 9, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '173579', 'n_tokens_mistral': 5292, 'n_tokens_neox': 4908, 'n_words': 2844}