A fast and robust toolbox for the analysis of your MD simulations of lipid membranes!

FATSLiM

License GitHub release Coverage Status Build Status DOI

FATSLiM stands for “Fast Analysis Toolbox for Simulations of Lipid Membranes” and its goal is to provide an efficient, yet robust, tool to extract physical parameters from MD trajectories.

The main objective of FATSLiM is to decrease as possible the amount of time needed to analyze MD trajectories: the ultimate goal is to process a several-gigabyte-big file is just a few minutes or less. This is why a rather important part of FATSLiM’s development is focused on code optimization and simplification in order to maximize its efficiency.

Features

  • Membrane morphology agnostic. FATSLiM can handle planar membrane as well as highly distorted bilayers or even vesicles!
  • Force field independent. FATSLiM can work with fully atomistic force fields like Slipids as well as with coarse grain ones like Martini.
  • Automated Leaflet identification. If you just need to identify which leaflet each lipid belongs to, no problem! FATSLiM will do it for you.
  • Protein compatible. You have one or several proteins embedded in your lipid membrane. Fear not! FATSLiM can handle them just fine.
  • Bilayer Thickness. Your membrane oscillates so you are not sure how to get your membrane thickness? FATSLiM is there for you.
  • Area per lipid and membrane area. You have a beautiful vesicle and want to see how the area per lipid changes between the inner and the outer leaflet? FATSLiM can help you… Of course, it can also help you with flat membranes too.
  • Fast and frugal. FATSLiM is designed to be fast while not being a memory hog. Let’s take a 16GB big trajectory (40K frames) consisting primarily of 512 lipids and ~31K water molecules. The gmx check utilities will need 7 min 16s and 12.9 MB of RAM to read the whole trajectory where FATSLiM will need 8 min 40s and 32.5 MB to analyze the trajectory and plot the thickness along the 40K frames.
  • Computationally efficient. FATSLiM scales linearly with the number of lipids for both execution time and memory. Typically for a 100-frame trajectory containing with 12000+ lipids, analysis will take less than 1 second and will need less than 256 MB of RAM.
  • Open-source. In order to maximize collaboration and ease enhancements, FATSLiM is released under the GNU General Public License, version 3, meaning that you can access and modify the source code freely.

Contribution

If you are interested in taking part in FATSLiM, you can get involved in several ways:

Fork me on GitHub

Installation

Requirements

FATSLiM is written in Python and, consequently, a Python environment with header files is required. FATSLiM is developed and daily tested with Python 2.7 to 3.5 on GNU/Linux, but it also works on Windows and Mac OS (far less tested on both, though).

FATSLiM only depends on NumPy, but, if you want to run the tests (recommended), pytest is also needed.

Computationally intensive tasks are written in Cython. Cython is not a requirement per se as C-translated code is provided but the latest version of Cython is recommended.

Obviously, a C compiler is required to compile C extensions. Additionally, openMP is strongly recommended as it is needed to enable parallelism.

Installation

From PyPI

FATSLiM can be installed using pip via the following command:

pip install fatslim

From Github

Alternatively, installation of the development version can be done directly from the git repository by, first, cloning the repo:

git clone https://github.com/FATSLiM/fatslim.git

Followed by setup.py install:

cd fatslim/
python setup.py install

Check installation

Once the installation is done, it is a good idea to run the self-test command to make sure that everything is fine:

fatslim self-test

Note: on Windows, you may need to type python <scripts_installation_path>\fatslim self-test instead, as fatslim may not be added to you PATH nor considered as en executable.

Usage

How to use FATSLiM? (2-minute guide)

FATSLiM is designed to be called using the command line, in a very similar manner as one would use git or GROMACS 5.x (i.e after the introduction of the global gmx command): using FATSLiM is done by specifying a command to the global executable fatslim.

Getting help

To display the general help (and the list of available FATSLiM commands):

fatslim help

To get help for a specific command, there are two alternatives:

  1. Using the help command:
fatslim help <command>
  1. Using the --help flag (or the short alternative -h):
fatslim <command> --help

Of course, You can also check the documentation or ask questions on the mailing list.

What do you need?

To run FATSLiM and perform analysis on your MD trajectory, you will need two or (most probably) three files:

  • a configuration file used to get atom names and residues (i.e. a poor-man version of the topology). The associated option is --conf (short alternative: -c). Currently, only .gro files are supported.

  • an index file used to specify the atoms to be used as references fot he lipids head groups. The associated option is --index (short alternative: -n). Currently, only .ndx files are supported.

  • an trajectory file that contains the coordinates. The associated option is --trajectory (short alternative: -t). Currently, .trr and .xtc files are supported. Please note that this file is optional as, if not provided, the coordinates from the configuration file will be used.

As you can see, the only file that is not required nor provided by GROMACS itself is the index file that you have to generate thanks to gmx make_ndx for example. This index file must contain at least one atom group that FATSLiM will used as reference to identify lipid head groups.

Note 1: The name of the index group to use for head groups can be specified by changing the value of the --hg-group option (by default the name “headgroups” is used).

Note 2: The index group can contain more than one atoms from the same residue. In this case, the center of geometry from the atoms will be used. It is then possible to used one atoms, one or even several moieties (e.g. phosphate + choline) as reference beads.

Examples

Here are just a few examples of what FATSLiM can do.

  • Identify membranes and save the leaflets as atom groups:
fatslim membranes -c conf.gro -t traj.xtc -n index.ndx --output-index leaflets.ndx
  • Retrieve membrane thickness and plot the calculated thickness along the trajectory:
fatslim thickness -c conf.gro -t traj.xtc -n index.ndx --plot-thickness thickness.xvg

Please note that conf.gro and index.ndx are the default name for the configuration and the index file, respectively, and may be omitted:

fatslim thickness -t traj.xtc --plot-thickness thickness.xvg
  • FATSLiM is parallelized thanks to OpenMP and will used all the available ressources by default but you can specify the number of threads to use via the --nthreads option:
fatslim thickness -t traj.xtc --plot-thickness thickness.xvg --nthreads 4
  • For each membrane property (thickness, area per lipid), raw values (i.e. calculated values for every single lipid) can be exported to .csv files (one per trajectory frame). Here is an example for the area per lipid:
fatslim apl -t traj.xtc --export-apl-raw apl_raw.csv
Documentation

Want all the gory details about FATSLiM ?

A full documentation is available on pythonhosted:

http://pythonhosted.org/fatslim/

This documentation includes:

Citing

How to cite FATSLiM ?

If you are using FATSLiM in scientific communications, please share your interest by citing the following paper:

  • S. Buchoux. FATSLiM: a fast and robust software to analyze MD simulations of membranes. Bioinformatics. Accepted, doi:10.1093/bioinformatics/btw563