ensemble

Reweight a conformational ensemble using experimental data.

Functions

reweight_ensemble(trajectory, topology, trajectory_id, ...)

Apply Bayesian Maximum Entropy (BME) reweighting to a conformational ensemble.

Module Contents

ensemblify.reweighting.ensemble.reweight_ensemble(trajectory, topology, trajectory_id, exp_data, exp_type=None, output_dir=None, thetas=None, calculated_SAXS_data=None, calculated_cmatrix=None, calculated_dmatrix=None, calculated_ss_frequency=None, calculated_metrics_data=None, compare_rg=True, compare_dmax=True, compare_eed=True, compare_cmdist=None, pepsi_saxs_opt=None)

Apply Bayesian Maximum Entropy (BME) reweighting to a conformational ensemble.

If exp_type if not provided, it must be specified in the first line of the exp_data file, in the form of ‘DATA=<type>’, where <type> is one of the following: [‘CS’,’JCOUPLINGS’,’RDC’, ‘SAXS’]. Inside the output directory, a directory named trajectory_id will be created where all output files will be stored. If calculated metrics data is provided, it will not be recalculated. If data for the center mass distance is to be taken from the given calculated metrics data, the compare_cmdist mapping must be provided. The identifiers of this mapping will be matched to column names of the given DataFrame, if present.

Parameters:

  • trajectory (str) – Path to .xtc trajectory file where conformational ensemble is stored.

  • topology (str) – Path to .pdb topology file corresponding to any one frame of the ensemble.

  • trajectory_id (str) – Prefix trajectory identifier to be added to plotted traces and output files.

  • exp_data (str | list[str]) – Path(s) to .dat file(s) with experimental data with 3 columns {Label, Value, Error}.

  • exp_type (str, optional) – Type(s) of experimental data provided in the same order as exp_data. If None, the type(s) are taken from the first line of each exp_data file.

  • output_dir (str, optional) – Path to output directory. Is created if it does not exist. Defaults to current working directory. After output_dir is setup, a directory named trajectory_id is created inside it, where the interactive .html plots and reweighting output files will be stored.

  • thetas (list[int], optional) – List of values to try as the theta parameter in BME. The ensemble will be reweighted each time using a different theta value. The effect of different theta values can be analyzed in the created effective frames figure.

  • calculated_SAXS_data (np.ndarray | str, optional) – Array with calculated SAXS profiles for each conformer in the ensemble or path to this file. Number of rows must match number of different conformers in the ensemble. Number of calculated data points (columns) must match the number of experimental data points provided in exp_data. If provided, this data is used instead of back-calculating it from the ensemble. Defaults to None.

  • calculated_cmatrix (pd.DataFrame | str, optional) – DataFrame with the calculated average contact matrix for the current trajectory or path to this file in .csv format. Defaults to None, and this data is calculated anew.

  • calculated_dmatrix (pd.DataFrame | str, optional) – DataFrame with the calculated average distance matrix for the current trajectory or path to this file in .csv format. Defaults to None, and this data is calculated anew.

  • calculated_ss_frequency (pd.DataFrame | str, optional) – DataFrame with the calculated secondary structure assignment frequency matrix for the current trajectory or path to this file in .csv format. Defaults to None, and this data is calculated anew.

  • calculated_metrics_data (pd.DataFrame | str, optional) – DataFrame with calculated structural metrics (columns) for each frame of the trajectory (rows) or path to this DataFrame in .csv format. Defaults to None, and this data is calculated anew.

  • compare_rg (bool, optional) – Whether to calculate/consider the radius of gyration when comparing structural metrics between uniform and reweighted conformational ensembles. Defaults to True.

  • compare_dmax (bool, optional) – Whether to calculate/consider the maximum distance between any two alpha carbons when comparing structural metrics between uniform and reweighted conformational ensembles. Defaults to True.

  • compare_eed (bool, optional) – Whether to calculate/consider the distance from the N to C terminal when comparing structural metrics between uniform and reweighted conformational ensembles. Defaults to True.

  • compare_cmdist (bool, optional) –

    Mapping of identifiers to tuples with two selection strings for creating MDAnalysis AtomGroups, whose center mass distance will be calculated. For example:

    {‘inter_domain’ : (‘resid 1:30’, ‘resid 110:140’)}

    If None, no center mass distances are calculated or compared. See https://userguide.mdanalysis.org/stable/selections.html for more information about MDAnalysis selections. Defaults to None.

  • pepsi_saxs_opt (str, optional) – If back-calculation of SAXS data from the ensemble will be attempted, this string will be passed onto Pepsi-SAXS as additional command line options. If None, default Pepsi-SAXS options are used instead.