data¶
Auxiliary functions for reweighting ensembles.
Functions¶
|
Check formatting and units in input experimental SAXS data file. |
|
Correct experimental error of input experimental data file using BIFT. |
|
Apply the Bayesian Maximum Entropy (BME) algorithm. |
|
Apply Bayesian/Maximum Entropy (BME) reweighting on calculated+experimental data. |
|
Average the SAXS intensities for uniform and reweighted calculated SAXS data. |
|
Attempt to read data from file, else calculate it using provided function. |
Attempt to read reweighting data from output directory, returning None if not found. |
Module Contents¶
- ensemblify.reweighting.data.process_exp_saxs_data(experimental_data_path)¶
Check formatting and units in input experimental SAXS data file.
If values for q are in Ångstrom, they are converted to nanometer. Any q-values above 5nm^(-1) are removed, as SAXS calculations are not reliable in that range.
- Parameters:
experimental_data_path (
str) – Path to experimental SAXS data file.- Returns:
Path to experimental SAXS data file with any applied changes.
- Return type:
str
- ensemblify.reweighting.data.correct_exp_saxs_error(experimental_data_path)¶
Correct experimental error of input experimental data file using BIFT.
Bayesian Indirect Fourier Transformation (BIFT) can identify whether the experimental error in small-angle scattering data is over- or underestimated. The error values are then scaled accordingly.
- Reference:
Larsen, A.H. and Pedersen, M.C. (2021), Experimental noise in small-angle scattering can be assessed using the Bayesian indirect Fourier transformation. J. Appl. Cryst., 54: 1281-1289. https://doi.org/10.1107/S1600576721006877
- Parameters:
experimental_data_path (
str) – Path to experimental SAXS data file.- Returns:
Path to experimental SAXS data file with corrected errors.
- Return type:
str
- ensemblify.reweighting.data.bme(theta, exp_files, calc_files, output_dir, exp_types)¶
Apply the Bayesian Maximum Entropy (BME) algorithm.
Uses the provided value for the theta parameter, and possibly applies iterative BME according to the type of experimental data used.
- Reference:
Bottaro S, Bengtsen T, Lindorff-Larsen K. Integrating Molecular Simulation and Experimental Data: A Bayesian/Maximum Entropy Reweighting Approach. Methods Mol Biol. 2020;2112:219-240. doi: 10.1007/978-1-0716-0270-6_15. PMID: 32006288.
- Parameters:
theta (
int) – Value for the theta parameter to be used in BME algorithm.exp_files (
str | list[str]) – Path to .dat file with experimental SAXS curve.calc_file (
str | list[str]) – Path to .dat file with SAXS curves calculated for each conformer of an ensemble.output_dir (
str) – Path to directory where all the files resulting from the reweighting procedure will be stored.exp_types (
str | None | list[str|None]) – Type(s) of experimental data provided. If a list is provided, it must follow the same order as the exp_files list.calc_files (str | list[str])
- Returns:
- int:
Value for the theta parameter used in BME algorithm (same as input).
- tuple[float, float, float]:
- float:
The value for the chisquare of fitting the ensemble with uniform weights to the experimental data.
- float:
The value for the chisquare of fitting the reweighted ensemble to the experimental data.
- float:
The fraction of effective frames being used in the reweighted ensemble.
- np.ndarray:
An array containing the new weights of the ensemble, one for each frame.
- Return type:
tuple[int, tuple[float, float, float], np.ndarray]
- ensemblify.reweighting.data.bme_ensemble_reweighting(exp_data, exp_type, calc_data, thetas, output_dir)¶
Apply Bayesian/Maximum Entropy (BME) reweighting on calculated+experimental data.
The algorithm is applied using different theta values and the results for each value are stored.
- Reference:
Bottaro S, Bengtsen T, Lindorff-Larsen K. Integrating Molecular Simulation and Experimental Data: A Bayesian/Maximum Entropy Reweighting Approach. Methods Mol Biol. 2020;2112:219-240. doi: 10.1007/978-1-0716-0270-6_15. PMID: 32006288.
- Parameters:
exp_data (
str | list[str]) – Path to .dat file(s) with experimental data.exp_type (
str | list[str]) – Type(s) of experimental data. If a list is provided, it must follow the same order as the exp_data list.calc_saxs_file (
str) – Path to .dat file(s) with experimental data calculated from a conformational ensemble.thetas (
list[int]) – Values of theta to try when applying BME.output_dir (
str) – Path to directory where output files from reweighting protocol will be stored.calc_data (str | list[str])
- Returns:
- stats (np.ndarray):
An array where each row corresponds to a different theta value with columns (chi2_before,chi2_after,phi) where:
- chi2_before:
The value for the chisquare of fitting the ensemble with uniform weights to the experimental data.
- chi2_after:
The value for the chisquare of fitting the reweighted ensemble to the experimental data.
- phi:
The fraction of effective frames being used in the reweighted ensemble.
- weights (np.ndarray):
An array where each row corresponds to a different theta value with columns containing the set of weights of the ensemble, one for each frame.
- Return type:
tuple[np.ndarray,np.ndarray]
- ensemblify.reweighting.data.average_saxs_profiles(exp_saxs_file, calc_saxs_file, rw_calc_saxs_file, weights)¶
Average the SAXS intensities for uniform and reweighted calculated SAXS data. The uniform data is then scaled and offset by linear regression fitting to experimental data.
- Parameters:
exp_saxs_file (
str) – Path to .dat file with experimental SAXS data.calc_saxs_file (
str) – Path to .dat file with SAXS data calculated from a conformational ensemble.rw_calc_saxs_file (
str) – Path to .dat file with SAXS data calculated from a conformational ensemble considering the weights (from iBME) for each frame.weights (
np.ndarray) – Array resulting from iBME with weights for each data point. Defaults to uniform weights.
- Returns:
- i_prior (float):
an array of SAXS intensities averaged over all the frames of a SAXS data file calculated from a conformational ensemble with uniform weights.
- i_post (float):
an array of SAXS intensities averaged over all the frames of a SAXS data file calculated from a conformational ensemble with the provided set of weights.
- Return type:
tuple[float,float]
- ensemblify.reweighting.data.attempt_read_calculated_data(data, data_msg_tag, calc_fn, *args, **kwargs)¶
Attempt to read data from file, else calculate it using provided function.
If data is given directly as a DataFrame, it is simply returned. Otherwise, it is either read from file or calculated using the provided function and arguments.
- Parameters:
data (
pd.DataFrame | str | None) – A DataFrame with the desired data, the path to the data in .csv format or None.data_msg_tag (
str) – String identifier for which data we are working with so prints to console are correct.calc_fn (
Callable) – An object with a __call__ method, e.g. a function to be used in calculating the data if it is not provided.
- Returns:
Desired data in DataFrame format.
- Return type:
pd.DataFrame
- ensemblify.reweighting.data.attempt_read_reweighting_data(reweighting_output_directory, trajectory_id, exp_type)¶
Attempt to read reweighting data from output directory, returning None if not found.
- Parameters:
reweighting_output_directory (
str) – Directory where data should be searched.trajectory_id (
str) – Prefix for filenames to look for in directory.exp_type (
list[str]) – Type(s) of experimental data used in reweighting, provided in the same order as the experimental data files provided in reweighting.
- Returns:
- list[str | None] | None:
The path(s) to experimental data file(s) (if found) or None (if not found).
- list[str | None] | None:
The path(s) to calculated data file(s) (if found) or None (if not found).
- np.ndarray | None:
The array of BME theta values (if found) or None (if not found).
- np.ndarray | None:
The BME fitting statistics (if found) or None (if not found).
- np.ndarray | None:
The set of BME weights (if found) or None (if not found).
- Return type:
tuple[list[str | None] | None, list[str | None] | None, np.ndarray | None, np.ndarray | None, np.ndarray | None]