Tutorials & Examples¶

This page contains a series of tutorials & examples broken up into sections to help you get started with biceps. Within each subsection, you will find a tutorial with a description.
To execute these notebooks interactively, the biceps GitHub repository must be cloned. Navigate to biceps/docs/examples to find this current directory. Start a Jupyter Notebook server and open the notebook:

$ jupyter notebook

Please note that the tutorials found in both sections the workflow & additional tools use Cineromycin B as the test system. See full examples for the notebook that puts it all together.

The workflow¶

Preparation¶

Prepare input files using the biceps.Restraint.Preparation class. Here, the raw model & experimental data is organized inside a Pandas DataFrame. This class requires experimental data as well as correspondingly precomputed experimental observables from simulation. We recommend users to use MDTraj to compute all necessary experimental quantities from simulation or use our prepared functions in biceps.toolbox.

Ensemble¶

Construct a container to store state and restraint information using the biceps.Ensemble class. An ensemble will need to be instantiated for each lambda value, each with different scaled energies. Using this class, we can call on the method biceps.Ensemble.initialize_restraints to fill the container with biceps.Restraint objects for each conformational state by passing the input data and/or optional parameters.

PosteriorSampler¶

For a given ensemble, the posterior distribution can be sampled by Markov Chain Monte Carlo (MCMC) using the biceps.PosteriorSampler class. MCMC sampling is performed using the Metroplis-Hastings criterion.

Analysis¶

Predict populations of conformational states and compute the BICePs score using the biceps.Analysis class.
The analysis is comprised of two parts:
1. Using the MBAR algorithm to compute populations and BICePs scores.
2. Plot and save figures that show population and sampled nuisance parameters.

Additional tools¶

Convergence¶

The convergence of our PosteriorSampler MCMC trajectories can be checked using the biceps.Convergence class.

Multiprocessing Lambda Values¶

Run the typical biceps workflow in a fraction of the time by parallelizing lambda values with the @biceps.multiprocess(iterable=lambda_values) decorator.

Toolbox¶

A collection of methods considered to be useful outside of the typical workflow.

Full examples¶

Cineromycin B¶

Determine the solution-state conformational populations of a 14-membered macrolide antibiotic. This example contains the use of experimental scalar coupling constant alongside NOE data and is based on a previously published work by Voelz et al (DOI: 10.1002/jcc.23738).

Albocycline¶

Compute conforamtional populations of a 14-membered macrolactone. Multiprocess lambda values and sample the posterior distribution for each simultaneously. This example is based on a previously published work by Zhou et al (DOI: 10.1016/j.bmc.2018.05.017).

Apomyoglobin¶

An example using experimental HDX protetion factors and chemical shift data after obtaining the forward model. This example is base on a previously published work by Wan et al (DOI: 10.1021/acs.jctc.9b01240). Posterior sampling of ln PF forward model parameters were calculated for ubiquitin and BPTI experimental HDX protection factors (ln PF) data for ubiquitin and BPTI. More information regarding the forward model can be found here.