Package: constava
ConstavaTable of contentTable of contentDescriptionInstallationPrerequisitesInstallation through PyPIInstallation from the sourceUsageExecution from the command lineExtracting backbone dihedrals from a trajectoryAnalyzing a conformational ensembleGenerating custom conformational state modelsExecution as a python libraryExtracting backbone dihedrals as a DataFrameSetting parameters and analyzing a conformational ensembleGenerating and loading conformational state modelsConstava-class parameters vs. command line argumentsLicenseAuthorsAcknowledgementsContactDescriptionConstava analyzes conformational ensembles calculating conformational state
propensities and conformational state variability. The conformational state
propensities indicate the likelihood of a residue residing in a given
conformational state, while the conformational state variability is a measure
of the residues ability to transiton between conformational states.Each conformational state is a statistical model of based on the backbone
dihedrals (phi, psi). The default models were derived from an analysis of NMR
ensembles and chemical shifts. To analyze a conformational ensemble, the phi-
and psi-angles for each conformational state in the ensemble need to be
provided.As input data Constava needs the backbone dihedral angles extracted from the
conformational ensemble. These dihedrals can be obtained using GROMACS'gmx chimodule (set--input-format=xvg) or using theconstava dihedralssubmodule, which supports a wide range of MD and structure formats.InstallationPrerequisitesPython 3.8 or higherpipInstallation through PyPIWe recommend this installation for most users.Create a virtual environment (optional but recommended):python3 -m venv constava
source constava/bin/activateInstall the python modulepip install constava(Takes about 1 minute)If the package requires to be uninstalled, runpip uninstall constava.Installation from the sourceAlternatively, you may download and install the software from the source code
directly.Clone the repository:gitclonehttps://bitbucket.org/bio2byte/constava/cdconstavaCreate a virtual environment (optional but recommended):python3-mvenvconstavasourceconstava/bin/activateBuild and install the package:# In the packages root directory do:# Build package from sourcemakebuild# Install locallymakeinstallIf the package requires to be uninstalled, runmake uninstallin the terminal
from the package's root directory.UsageThe software provides two modes of interaction. Shell user may use the software
from the command line, while users skilled in Python can import it as a module.
We provide a couple of usage examples in aColab notebook.Execution from the command lineThe software is subdevided inthree submodules:Theconstava dihedralssubmodule provides a simple way to extract backbone
dihedral angles from MD simulations or PDB ensembles. For more information
run:constava dihedrals -h. Alternatively, the backbone dihedrals may be
extracted with GROMACS'gmx chimodule.Theconstava analyzesubmodule analyzes the provided backbone dihedral angles
and infers the propensities for each residue to reside in a given
conformational state. For more information run:constava analyze -h.Theconstava fit-modelcan be used to train a custom probabilistic model of
confromational states.  The default models were derived from an analysis of NMR
ensembles and chemical shifts; they cover six conformational states:Core Helix - Exclusively alpha-helical, low backbone dynamicsSurrounding Helix - Mostly alpha-helical, high backbone dynamicsCore Sheet - Exclusively beta-sheet, low backbone dynamicsSurrounding Sheet - Mostly extended conformation, high backbone dynamicsTurn - Mostly turn, high backbone dynamicsOther - Mostly coil, high backbone dynamicsExtracting backbone dihedrals from a trajectoryTo extract dihedral angles from a trajectory theconstava dihedralssubmodule
is used.usage: constava dihedrals [-h] [-s <file.pdb>] [-f <file.xtc> [<file.xtc> ...]] [-o OUTPUT] [--selection SELECTION] [--precision PRECISION] [--degrees] [-O]

The `constava dihedrals` submodule is used to extract the backbone dihedrals
needed for the analysis from confromational ensembles. By default the results
are written out in radians as this is the preferred format for
`constava analyze`.

Note: For the first and last residue in a protein only one backbone dihedral
can be extracted. Thus, those residues are omitted by default.

optional arguments:
  -h, --help            Show this help message and exit

Input & output options:
  -s <file.pdb>, --structure <file.pdb>
                        Structure file with atomic information: [pdb, gro, tpr]
  -f <file.xtc> [<file.xtc> ...], --trajectory <file.xtc> [<file.xtc> ...]
                        Trajectory file with coordinates: [pdb, gro, trr, xtc, crd, nc]
  -o OUTPUT, --output OUTPUT
                        CSV file to write dihedral information to. (default: dihedrals.csv)

Input & output options:
  --selection SELECTION
                        Selection for the dihedral calculation. (default: 'protein')
  --precision PRECISION
                        Defines the number of decimals written for the dihedrals. (default: 5)
  --degrees             If set results are written in degrees instead of radians.
  -O, --overwrite       If set any previously generated output will be overwritten.An example:# Obtain backbone dihedrals (overwriting any existing files)constavadihedrals-O-s"2mkx.gro"-f"2mkx.xtc"-o"2mkx_dihedrals.csv"Analyzing a conformational ensembleTo analyze the backbone dihedral angles extracted from a confromational ensemble,
theconstava analyzesubmodule is used.usage: constava analyze [-h] [-i <file.csv> [<file.csv> ...]] [--input-format {auto,xvg,csv}] [-o <file.csv>] [--output-format {auto,csv,json,tsv}] [-m <file.pkl>] [--window <int> [<int> ...]]
                        [--window-series <int> [<int> ...]] [--bootstrap <int> [<int> ...]] [--bootstrap-series <int> [<int> ...]] [--bootstrap-samples <int>] [--degrees] [--precision <int>] [--seed <int>] [-v]

The `constava analyze` submodule analyzes the provided backbone dihedral angles
and infers the propensities for each residue to reside in a given 
conformational state. 

Each conformational state is a statistical model of based on the backbone 
dihedrals (phi, psi). The default models were derived from an analysis of NMR
ensembles and chemical shifts. To analyze a conformational ensemble, the phi- 
and psi-angles for each conformational state in the ensemble need to be 
provided. 

As input data the backbone dihedral angles extracted from the conformational 
ensemble need to be provided. Those can be generated using the 
`constava dihedrals` submodule (`--input-format csv`) or GROMACS'
`gmx chi` module (`--input-format xvg`).

optional arguments:
  -h, --help            Show this help message and exit

Input & output options:
  -i <file.csv> [<file.csv> ...], --input <file.csv> [<file.csv> ...]
                        Input file(s) that contain the dihedral angles.
  --input-format {auto,xvg,csv}
                        Format of the input file: {'auto', 'csv', 'xvg'}
  -o <file.csv>, --output <file.csv>
                        The file to write the results to.
  --output-format {auto,csv,json,tsv}
                        Format of output file: {'csv', 'json', 'tsv'}. (default: 'auto')

Conformational state model options:
  -m <file.pkl>, --load-model <file.pkl>
                        Load a conformational state model from the given pickled 
                        file. If not provided, the default model will be used.

Subsampling options:
  --window <int> [<int> ...]
                        Do inference using a moving reading-frame. Each reading 
                        frame consists of <int> consecutive samples. Multiple 
                        values can be provided.
  --window-series <int> [<int> ...]
                        Do inference using a moving reading-frame. Each reading 
                        frame consists of <int> consecutive samples. Return the 
                        results for every window rather than the average. This can
                        result in very large output files. Multiple values can be 
                        provided.
  --bootstrap <int> [<int> ...]
                        Do inference using <Int> samples obtained through 
                        bootstrapping. Multiple values can be provided.
  --bootstrap-series <int> [<int> ...]
                        Do inference using <Int> samples obtained through 
                        bootstrapping. Return the results for every subsample
                        rather than the average. This can result in very 
                        large output files. Multiple values can be provided.
  --bootstrap-samples <int>
                        When bootstrapping, sample <Int> times from the input data.
                        (default: 500)

Miscellaneous options:
  --degrees             Set this flag, if dihedrals in the input files are in 
                        degrees.
  --precision <int>     Sets the number of decimals in the output files.
  --seed <int>          Set random seed for bootstrap sampling
  -v, --verbose         Set verbosity level of screen output. Flag can be given 
                        multiple times (up to 2) to gradually increase output to 
                        debugging mode.An example:# Run constava with debug-level outputconstavaanalyze\-i"2mkx_dihedrals.csv"\-o"2mkx_constava.json"--output-formatjson\--window3525\-vvGenerating custom conformational state modelsTo  train a custom probabilistic model of confromational states, theconstava fit-modelsubmodule is used.usage: constava fit-model [-h] [-i <file.json>] -o <file.pkl> [--model-type {kde,grid}] [--kde-bandwidth <float>] [--grid-points <int>] [--degrees] [-v]

The `constava fit-model` submodule is used to generate the probabilistic
conformational state models used in the analysis. By default, when running
`constava analyze` these models are generated on-the-fly. In selected cases 
generating a model beforehand and loading it can be useful, though.

We provide two model types. kde-Models are the default. They are fast to fit
but may be slow in the inference in large conformational ensembles (e.g., 
long-timescale MD simulations). The idea of grid-Models is, to replace
the continuous probability density function of the kde-Model by a fixed set
of grid-points. The PDF for any sample is then estimated by linear 
interpolation between the nearest grid points. This is slightly less
accurate than the kde-Model but speeds up inference significantly.

optional arguments:
  -h, --help            Show this help message and exit

Input and output options:
  -i <file.json>, --input <file.json>
                        The data to which the new conformational state models will
                        be fitted. It should be provided as a JSON file. The 
                        top-most key should indicate the names of the 
                        conformational states. On the level below, lists of phi-/
                        psi pairs for each stat should be provided. If not provided 
                        the default data from the publication will be used.
  -o <file.pkl>, --output <file.pkl>
                        Write the generated model to a pickled file, that can be
                        loaded gain using `constava analyze --load-model`

Conformational state model options:
  --model-type {kde,grid}
                        The probabilistic conformational state model used. The 
                        default is `kde`. The alternative `grid` runs significantly
                        faster while slightly sacrificing accuracy: {'kde', 'grid'}
                        (default: 'kde')
  --kde-bandwidth <float>
                        This flag controls the bandwidth of the Gaussian kernel 
                        density estimator. (default: 0.13)
  --grid-points <int>   This flag controls how many grid points are used to 
                        describe the probability density function. Only applies if
                        `--model-type` is set to `grid`. (default: 10000)

Miscellaneous options:
  --degrees             Set this flag, if dihedrals in `model-data` are in degrees 
                        instead of radians.
  -v, --verbose         Set verbosity level of screen output. Flag can be given 
                        multiple times (up to 2) to gradually increase output to 
                        debugging mode.An example:# Generates a faster 'grid-interpolation model' using the default datasetconstavafit-model-v\-odefault_grid.pkl\--model-typegrid\--kde-bandwidth0.13\--grid-points6400Execution as a python libraryThe module provides theConstavaclass a general interface to software's
features. The only notable exception is the extraction of dihedrals,
which is done through a separate function.Extracting backbone dihedrals as a DataFrameimportpandasaspdfromconstava.utils.dihedralsimportcalculate_dihedrals# Calculate dihedrals as a DataFramedihedrals=calculate_dihedrals(structure="./2mkx.pdb",trajectory="2mkx.xtc")# Write dihedrals out as a csvdihedrals.to_csv("2mkx_dihedrals.csv",index=False,float_format="%.4f")Setting parameters and analyzing a conformational ensembleThis example code will generate an output for a protein:# Initialize Constava Python interface with parametersimportglobfromconstavaimportConstava# Define input and output filesPDBID="2mkx"input_files=glob.glob(f"./{PDBID}/ramaPhiPsi*.xvg")output_file=f"./{PDBID}_constava.csv"# Initialize Constava Python interface with parametersc=Constava(input_files=input_files,output_file=output_file,bootstrap=[3,5,10,25],input_degrees=True,verbose=2)# Alter parameters after initializationc.set_param("window",[1,3,5])# Run the calculation and write resultsc.run()This protein, with 48 residues and 100 frames per residue runs in about 1 minute.The original MD ensembles from the manuscript can be found inhttps://doi.org/10.5281/zenodo.8160755.Generating and loading conformational state modelsConformational state models are usually fitted at runtime. This is usually the
safest option to retain compatibility. Forkdemodels, refitting usually
takes less than a second and is almost neglectable. However,gridinterpolation
models take longer to generate. Thus, it makes sense to store them when
running multiple predictions on the same model.Note:Conformational state model-pickles are intended for quickly rerunning
simulations. They arenot for storing or sharing your conformational state models.
When you need to store or share a custom conformational state model, provide
the training data and and model-fitting parameters.fromconstavaimportConstava# Fit the grid-interpolation modelc=Constava(verbose=1)csmodel=c.fit_csmodel(model_type="grid",kde_bandwidth=.13,grid_points=10_201)# Write the fitted model out as a picklecsmodel.dump_pickle("grid_model.pkl")# Use the new model to analyze a confromational ensemblePDBID="2mkx"input_files=glob.glob(f"./{PDBID}_dihedrals.csv")output_file=f"./{PDBID}_constava.csv"c=Constava(input_files=input_files,output_file=output_file,model_load="grid_model.pkl",input_degrees=True,window=[1,5,10,25],verbose=1)c.run()Constava-class parameters vs. command line argumentsIn the following table, all available parameters of the Python interface (Constavaclass) and their corresponding command line arguments are listed. The defaults for
parameters in Python and command line are the same.Python parameterCommand line argumentDescriptioninput_files : List[str] or strconstava analyze --input <file> [<file> ...]Input file(s) that contain the dihedral angles.input_format : strconstava analyze --input-format <enum>Format of the input file:{'auto', 'csv', 'xvg'}output_file : strconstava analyze --output <file>The file to write the output to.output_format : strconstava analyze --output-format <enum>Format of output file:{'auto', 'csv', 'json', 'tsv'}model_type : strconstava fit-model --model-type <enum>The probabilistic conformational state model used. Default iskde. The alternativegridruns significantly faster while slightly sacrificing accuracy:{'kde', 'grid'}model_load : strconstava analyze --load-model <file>Load a conformational state model from the given pickled file.model_data : strconstava fit-model --input <file>Fit conformational state models to data provided in the given file.model_dump : strconstava fit-model --output <file>Write the generated model to a pickled file, that can be loaded again usingmodel_load.window : List[int] or intconstava analyze --window <Int>  [<Int> ...]Do inference using a moving reading-frame of  consecutive samples. Multiple values can be given as a list.window_series : List[int] or intconstava analyze --window-series <Int>  [<Int> ...]Do inference using a moving reading-frame of  consecutive samples. Return the results for every window rather than the average. Multiple values can be given as a list.bootstrap : List[int] or intconstava analyze --bootstrap <Int> [<Int>  ...]Do inference using  samples obtained through bootstrapping. Multiple values can be given as a list.bootstrap_series : List[int] or intconstava analyze --bootstrap-series <Int>  [<Int> ...]Do inference using  samples obtained through bootstrapping. Return the results for every bootstrap rather than the average. Multiple values can be given as a list.bootstrap_samples : intconstava analyze --bootstrap-samples <Int>When bootstrapping, sample  times from the input data.input_degrees : boolconstava analyze --degreesSetTrueif input files are in degrees.model_data_degrees : boolconstava fit-model --degreesSetTrueif the data given undermodel_datato is given in degrees.precision : intconstava analyze --precision <int>Sets the number of decimals in the output files. By default, 4 decimals.kde_bandwidth : floatconstava fit-model --kde-bandwidth <float>This controls the bandwidth of the Gaussian kernel density estimator.grid_points : intconstava analyze --grid-points <int>Whenmodel_typeequals 'grid', this controls how many grid points are used to describe the probability density function.seed : intconstava analyze --seed <int>Set the random seed especially for bootstrapping.verbose : intconstava <...> -v [-v]Set verbosity level of screen output.LicenseDistributed under the GNU General Public License v3 (GPLv3) License.AuthorsJose Gavalda-Garcia♠-jose.gavalda.garcia@vub.beDavid Bickel♠-david.bickel@vub.beJoel Roca-Martinez-joel.roca.martinez@vub.beDaniele Raimondi --daniele.raimondi@kuleuven.beGabriele Orlando --gabriele.orlando@kuleuven.beWim Vranken --Personal page-wim.
vranken@vub.be♠Authors contributed equally to this work.AcknowledgmentsWe thank Adrian Diazfor the invaluable help in the distribution of this software.ContactWim Vranken -wim.vranken@vub.beBio2Byte website:https://bio2byte.be/