Python based lipid BILayer molecular simulation analysis Toolkit

PyBILT is a Python toolkit developed to analyze molecular simulation trajectories of lipid bilayers systems. The toolkit includes a variety of analyses from various lipid bilayer molecular simulation publications.

The analyses include:

• Mean Squared Displacement (MSD)
• Diffusion coefficent estimators (from MSD curves) - includes Einstein relation, linear fit, and anomalous diffusion fit.
• Area per lipid estimators
• Bilayer thickness
• Displacement Vector (flow) maps and correlations
• Deuterium order parameter
• Orientation parameters
• Mass and Electron Density Estimators
• and more!

Install

Core dependencies

PyBILT has the following core dependencies:

• MDAnalysis > 1.0
• NumPy
• SciPy
• Matplotlib
• Seaborn
• six
• future

Python version support

The pybilt package has been tested using Anaconda Python 3.7 and MDAnalysis=1.1.1.

pip install

You can install the latest version of the pybilt package using pip sourced from the GitHub repo:

pip install -e git+https://github.com/LoLab-VU/[email protected]#egg=pybilt

However, this will not automatically install the core dependencies. You will have to do that separately:

pip install MDAnalysis numpy scipy matplotlib seaborn six future

conda install

First make sure you have the conda-forge channel in your channel list; that is the channel from which MDAnalysis is installed. You can use the following command to add it to the bottom of your channel list:

conda config --append channels conda-forge

Then you can install the pybilt package from the blakeaw Anaconda Cloud channel,

conda install -c blakeaw pybilt

The core dependencies will be automatically installed.

Recommended additional software

The following software is not required for the basic operation of PyBILT, but provides extra capabilities and features when installed.

pytest

The pybilt test suite is designed to be run with pytest, so if you want to run the tests then you will need to install pytest.

Jupyter

PyBILT comes with a set of Jupyter IPython notebooks which supplement the doc pages. If you want to run these notebooks locally then you will need to intall Jupyter (or at least the IPython kernel).

Note that the notebooks have not been updated for Python 3 yet.

sphinx, sphinx_rtd_theme, and recommonmark

If you want to build local versions of doc pages install the following additional packages:

• sphinx
• sphinx_rtd_theme
• recommonmark

Documentation and Usage

Quick overview of PyBILT

PyBILT is composed of 2 primary analysis packages:

• bilayer_analyzer -- The bilayer_analyzer is an analysis package that is designed to analyze (quasi) planar lipid bilayer systems. It is accessed through the BilayerAnalyzer object, which can be imported via: from pybilt.bilayer_analyzer import BilayerAnalyzer. The BilayerAnalyzer features automatic dynamic unwrapping of coordinates and leaflet detection. The bilayer_analyzer works on a multiple-representation model, whereby the various analyses are conducted using different representations of the bilayer lipids. Bilayer lipids can be represented using the following four representations:
  • All atom
  • Centers-of-mass -- Each lipid (or selection of atoms from each lipid) is reduced to a center-of-mass.
  • Grid (or lipid grid) -- The lipids are mapped to two-dimensional grids (one for each leaflet) in the style of the GridMAT-MD method
  • Vectors - Each lipid is converted to a vector representation using select reference atoms (or sets of reference atoms) that are used to compute the head and tail of the vector; e.g., a lipid tail atom to lipid head atom, or P-N vectors.

The bilayer_analyzer features various types of analyses and the use of different representations is handled internally based the requirements and design of each analysis type. See the documentation for list of analyses that can be added to intances of the BilayerAnalyzer.

• mda_tools -- This package includes various modules and functions for directly analyzing and operating on MDAnalysis trajectories and objects. e.g. functions to compute density profiles.

Additional packages include:

• lipid_grid -- The lipid grid module can be used construct "lipid grid" grid representations of lipid bilayers, which can be used to accurately estimate quantities such as area per lipid.

• com_trajectory -- This module can be used to construct a center of mass trajectory (COMTraj) out of an MDAnalysis trajectory, which is useful for computing quantities like mean squared displacement. The COMTraj is designed to work with bilayers.

• plot_generation -- This module has several pre-written plotting functions (using matplotlib and seaborn) for some of the properties that can be computed from functions in the other modules. e.g. mean squared displacement and area per lipid.

Docs

Visit the PyBILT docs on Read the Docs. Docs can also be viewed offline/locally by opening the PyBILT/docs/build/html/index.html file from the repo in a web browser; however, this build of the docs is not updated often.

Jupyter IPython notebooks

In addition to the Docs, there are currently a few Jupyter IPython notebooks that provide some examples and show some basic usage (these have not been updated/tested for/with python 3 yet); updates and more of these are in the pipeline.

Contact

To report problems or bugs please open a GitHub Issue. Additionally, any comments, suggestions, or feature requests for PyBILT can also be submitted as a GitHub Issue.

Contributing

If you would like to contribute directly to PyBILT's development please

1. Fork the repo (https://github.com/LoLab-VU/PyBILT/fork)
2. Create a new branch for your feature (git checkout -b feature/foo_bar)
3. Create test code for your feature
4. Once your feature passes its own test, run all the tests using pytest (python -m pytest)
5. Once your feature passes all the tests, commit your changes (git commit -am 'Add the foo_bar feature.')
6. Push to the branch (git push origin feature/foo_bar)
7. Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details

Acknowledgments

• A special thanks to James Pino (https://github.com/JamesPino) for his inciteful comments and suggestions that have helped improve the quality of this code, and thanks to him for pointing out some very useful coding tools.
• Thanks to my advisors, Carlos F. Lopez and Arvind Ramanathan, for catalyzing this project and for providing me with the space and means to pursue it.

Citing

If you use the PyBILT software as a part of your research, please cite the its use. You can export the PyBILT software citation in your preferred format from its Zenodo DOI entry.

Also, please cite the following references as appropriate for scientific/research software used with/via PyBILT:

MDAnalysis

See: https://www.mdanalysis.org/pages/citations/

Packages from the SciPy ecosystem

These include NumPy, SciPy, and Matplotlib for which references can be obtained from: https://www.scipy.org/citing.html

seaborn

Reference can be exported from the seaborn Zeondo DOI entry

Jupyter

See: jupyter/jupyter#190

IPython

See: https://ipython.org/citing.html