Tutorial 2:
Generating a conformational ensemble with GMX and hySAS

The main purpose of hySAS is to allow an MD engine, independently of the force field, to generate a conformational ensemble that is in agreement with the experimental data. To achieve this, a potential is added to the system to discourage conformations that do not match the measured signal. Here, we propose two examples of coupling methods to introduce this energy penalty during the MD simulation.

Most of the SAS options have been discussed in Tutorial 1, here we present two additional flags: EXPINT and SCALE_EXPINT. For each QVALUE is required an EXPINT value, which consists in the experimental intensity measured at that specific momentum transfer. All the EXPINT values must be rescaled to the SAXS intensity at q = 0. To facilitate this operation, it is possible to automatically rescale all the experimental intensity entries with SCALE_EXPINT, which allows to provide the intensity at q = 0. In this way, each EXPINT is divided by SCALE_EXPINT.

In general, the more the q-values and the corresponding experimental intensities, the more intensive the calculation.

HARMONIC / LINEAR RESTRAINT

In this example, the SAXS profile is calculated using the ONEBEAD mapping, specifying a solvent electron density of 334 electrons/nm3 and a correction of 80 electrons/nm3 for the beads exposed to the solvent. The solvent-accessible surface calculation, which is required to assess the beads’ exposure to the solvent, is performed every 10 steps of the simulation. The theoretical intensity at q = 0 is defined by SCALE_EXPINT, while the experimentally determined intensity for a given QVALUE is reported by EXPINT. All the EXPINT values are rescaled by the SCALE_EXPINT value.

The STATS action is then used to calculate statistical properties between the intensities computed from the coordinates of the simulated system for each QVALUE and the corresponding experimental references defined with EXPINT. Specifically, the correlation between the in silico intensities and the experimental intensities is considered as an argument for RESTRAINT, an action from the BIAS module. As additional information useful to follow the evolution of the simulation, the radius of gyration of the system is printed every 100 steps. Additional {} brackets have been added to prevent a readability issue, they are optional to run the code. When curly brackets are used, ensure that the entire list of arguments is enclosed within one set of curly brackets.

Detailed information on STATS, RESTRAINT and GYRATION can be found in the PLUMED manual.

Click on the labels of the actions for more information on what each action computes
tested onv2.9
tested onmaster
MOLINFOThis command is used to provide information on the molecules that are present in your system. More details STRUCTUREa file in pdb format containing a reference structure=template_AA.pdb

SAXSCalculates SAXS intensity. This action has hidden defaults. More details ...
        LABELa label for the action so that its output can be referenced in the input to other actions=SAXS
        ATOMSThe atoms to be included in the calculation, e=1-11878
        ONEBEAD calculate SAXS for a single bead model
        TEMPLATE A PDB file is required for ONEBEAD mapping=template_AA.pdb
        #GPU            #This flag requires PLUMED to be compiled with Arrayfire
        SOLVDENS Density of the solvent to be used for the correction of atomistic form factors=0.334
        SOLVATION_CORRECTION Solvation layer electron density correction (ONEBEAD only)=0.080
        SOLVATION_STRIDE Number of steps between every new residues solvation estimation via LCPO (ONEBEAD only)=10
        SASA_CUTOFF SASA value to consider a residue as exposed to the solvent (ONEBEAD only)=0.7
        SCALE_EXPINT Scaling value for experimental data normalization=0.281543E+00

QVALUE1Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.00444189      EXPINT1Add an experimental value for each q value=0.279832E+00
QVALUE2Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0133257       EXPINT2Add an experimental value for each q value=0.266507E+00
QVALUE3Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0222823       EXPINT3Add an experimental value for each q value=0.241456E+00
QVALUE4Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0312965       EXPINT4Add an experimental value for each q value=0.207871E+00
QVALUE5Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0402661       EXPINT5Add an experimental value for each q value=0.170297E+00
QVALUE6Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0534267       EXPINT6Add an experimental value for each q value=0.116142E+00
QVALUE7Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0786047       EXPINT7Add an experimental value for each q value=0.427377E-01
QVALUE8Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.103746        EXPINT8Add an experimental value for each q value=0.143592E-01
QVALUE9Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.128888        EXPINT9Add an experimental value for each q value=0.775681E-02
QVALUE10Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.153991       EXPINT10Add an experimental value for each q value=0.564444E-02
QVALUE11Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.179113       EXPINT11Add an experimental value for each q value=0.395988E-02
QVALUE12Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.20428        EXPINT12Add an experimental value for each q value=0.324523E-02
QVALUE13Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.229423       EXPINT13Add an experimental value for each q value=0.321736E-02
... SAXS

#### INFO  ####
st_saxs: STATSCalculates statistical properties of a set of collective variables with respect to a set of reference values. More details ARGthe labels of the values from which the function is calculated={(SAXS\.q-.*)} PARARGthe input for this action is the scalar output from one or more other actions without derivatives={(SAXS\.exp-.*)}
rg_saxs: GYRATIONCalculate the radius of gyration, or other properties related to it. More details TYPE The type of calculation relative to the Gyration Tensor you want to perform=RADIUS ATOMSthe group of atoms that you are calculating the Gyration Tensor for=1-11878

#### RESTRAINTS ####
RESTRAINTAdds harmonic and/or linear restraints on one or more variables. More details ARGthe values the harmonic restraint acts upon=st_saxs.corr ATthe position of the restraint=1 KAPPA specifies that the restraint is harmonic and what the values of the force constants on each of the variables are=0 SLOPE specifies that the restraint is linear and what the values of the force constants on each of the variables are=-10000

#### OUT ####
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=rg_saxs STRIDE the frequency with which the quantities of interest should be output=100 FILEthe name of the file on which to output these quantities=GYRATION
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file={st_saxs.*,(SAXS\.q-.*),(SAXS\.exp-.*)} STRIDE the frequency with which the quantities of interest should be output=100 FILEthe name of the file on which to output these quantities=STAT_SAXS
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file={(SAXS\.q-.*)} STRIDE the frequency with which the quantities of interest should be output=100 FILEthe name of the file on which to output these quantities=SAXSINT
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=st_saxs.corr STRIDE the frequency with which the quantities of interest should be output=100 FILEthe name of the file on which to output these quantities=CORRELATION

METAINFERENCE

Changing the coupling method does not affect the main SAXS/SANS actions, which remain unchanged. In this example we use metainference, a Bayesian replica-averaging framework that restrain the average predicted data, in this case the SAXS signal calculated from the system coordinates, to be close to the experimental observable, generating an ensemble in accordance to the maximum entropy principle. METAINFERENCE is part of the ISDB module, see the PLUMED manual and the manuscript for full details.

Unlike the previous example, we do not use the SCALE_EXPINT flag because the EXPINT values have already been rescaled. In both the examples the maximum momentum transfer accepted for the ONEBEAD mapping is 0.3 Å-1.

Click on the labels of the actions for more information on what each action computes
tested onv2.9
tested onmaster
MOLINFOThis command is used to provide information on the molecules that are present in your system. More details STRUCTUREa file in pdb format containing a reference structure=template_AA.pdb

SAXSCalculates SAXS intensity. This action has hidden defaults. More details ...
        LABELa label for the action so that its output can be referenced in the input to other actions=saxsdata
        ATOMSThe atoms to be included in the calculation, e=1-11878
        ONEBEAD calculate SAXS for a single bead model
        TEMPLATE A PDB file is required for ONEBEAD mapping=template_AA.pdb
        #GPU            #This flag requires PLUMED to be compiled with Arrayfire
        SOLVDENS Density of the solvent to be used for the correction of atomistic form factors=0.334
        SOLVATION_CORRECTION Solvation layer electron density correction (ONEBEAD only)=0.080
        SOLVATION_STRIDE Number of steps between every new residues solvation estimation via LCPO (ONEBEAD only)=10
        SASA_CUTOFF SASA value to consider a residue as exposed to the solvent (ONEBEAD only)=0.7

        #QVALUE RANGE 0.01-0.25 (stride: 0.0150014)

        QVALUE1Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0101007       EXPINT1Add an experimental value for each q value=0.9655268182607186
        QVALUE2Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0251021       EXPINT2Add an experimental value for each q value=0.8074336052768617
        QVALUE3Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0401035       EXPINT3Add an experimental value for each q value=0.5867844124283979
        QVALUE4Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0551049       EXPINT4Add an experimental value for each q value=0.3778068043742405
        QVALUE5Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0701063       EXPINT5Add an experimental value for each q value=0.2199053983683388
        QVALUE6Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.0851077       EXPINT6Add an experimental value for each q value=0.1176236764450616
        QVALUE7Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1001091       EXPINT7Add an experimental value for each q value=0.0598961117861482
        QVALUE8Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1151105       EXPINT8Add an experimental value for each q value=0.0320698663426488
        QVALUE9Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1301119       EXPINT9Add an experimental value for each q value=0.0197961291442457
        QVALUE10Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1451133      EXPINT10Add an experimental value for each q value=0.0131910258635653
        QVALUE11Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1601147      EXPINT11Add an experimental value for each q value=0.0090075507724353
        QVALUE12Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1751161      EXPINT12Add an experimental value for each q value=0.0070054764797778
        QVALUE13Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.1901175      EXPINT13Add an experimental value for each q value=0.0060413990626627
        QVALUE14Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.2051189      EXPINT14Add an experimental value for each q value=0.0049136955389689
        QVALUE15Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.2201203      EXPINT15Add an experimental value for each q value=0.0039878840479083
        QVALUE16Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.2351217      EXPINT16Add an experimental value for each q value=0.0037107186252386
        QVALUE17Selected scattering lengths in inverse angstroms are given as QVALUE1, QVALUE2, =0.2501231      EXPINT17Add an experimental value for each q value=0.0033106578718972

        OPTSIGMAMEAN Set to NONE/SEM to manually set sigma mean, or to estimate it on the fly=SEM_MAX
        SIGMA_MAX_STEPSNumber of steps used to optimise SIGMA_MAX, before that the SIGMA_MAX value is used=500000
        AVERAGINGStride for calculation of averaged weights and sigma_mean=500
        DOSCORE activate metainference SIGMA_MEAN0starting value for the uncertainty in the mean estimate=0.5
        SCALEDATA Set to TRUE if you want to sample a scaling factor common to all values and replicas SCALE0 initial value of the scaling factor=1.0
        DSCALEmaximum MC move of the scaling factor=0.01 SCALE_PRIOR either FLAT or GAUSSIAN=GAUSSIAN
        SIGMA0 initial value of the uncertainty parameter=0.5 SIGMA_MIN minimum value of the uncertainty parameter=0.0001 SIGMA_MAX maximum value of the uncertainty parameter=0.5
        NOISETYPE functional form of the noise (GAUSS,MGAUSS,OUTLIERS,MOUTLIERS,GENERIC)=MGAUSS
... SAXS

#### METAINFERENCE ####
saxsbias: BIASVALUETakes the value of one variable and use it as a bias More details ARGthe labels of the scalar/vector arguments whose values will be used as a bias on the system={(saxsdata\.score)} STRIDEthe frequency with which the forces due to the bias should be calculated=2
ens: ENSEMBLECalculates the replica averaging of a collective variable over multiple replicas. More details ARGthe labels of the values from which the function is calculated={(saxsdata\.q-.*)}

#### STATISTICS ####
statcg: STATSCalculates statistical properties of a set of collective variables with respect to a set of reference values. More details ARGthe labels of the values from which the function is calculated={(ens.*)} PARARGthe input for this action is the scalar output from one or more other actions without derivatives={(saxsdata\.exp-.*)}

#### PRINT ####
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file={(ens.*)} STRIDE the frequency with which the quantities of interest should be output=1000 FILEthe name of the file on which to output these quantities=ENS.SAXSINT
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file={(saxsdata\.score),(saxsdata\.scale),(saxsdata\.acceptSigma),(saxsdata\.sigma.*)} STRIDE the frequency with which the quantities of interest should be output=1000 FILEthe name of the file on which to output these quantities=BAYES.SAXS
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file={(saxsdata\.q-.*)} STRIDE the frequency with which the quantities of interest should be output=1000 FILEthe name of the file on which to output these quantities=SAXSINT
PRINTPrint quantities to a file. More details ARGthe labels of the values that you would like to print to the file=statcg.* STRIDE the frequency with which the quantities of interest should be output=1000 FILEthe name of the file on which to output these quantities=ST.SAXSCG
Back to hySAS home