Dependency installations

MDAnalysis:

The MDAnalysis Library is an object-oriented Python toolkit to analyze molecular dynamics trajectories generated by CHARMM, Gromacs, NAMD, LAMMPS, or Amber. This project is lead by Dr Oliver Beckstein. You need to download the latest 0.8.1 version, which contains the new visualization modules.

If you are interested in using this code but are unfamiliar with the installation details for MDAnalysis, there are extensive installation notes here as well as specific installation recipes. You can also see all the info for the MDAnalysis development version here.

The recent released version of MDAnalysis can be retrieved using pip:
$ pip install -U MDAnalysis
It should be very easy to install the pip package if you do not already have it for Python-based installation purposes: pip installation documentation.

Matplotlib for 2D visualization:

To create 2D graphs, you need to install Matplotlib. At the moment, the 2D streamplot module depends rather dubiously on the deprecated matplotlib.nxutils module of the Python matplotlib package, which should be installable via pip:
$ pip install matplotlib==1.2.1
There are detailed installation instructions available for matplotlib.

unfortunately, you need the version 1.2.1 of matplotlib, so if you have a newer version you will have to downgrade it.. We are working to update the code so that it can be used with the newest matplotlib version.

To check your version of matplotlib, if you have ipython:
$ ipython
In [1] import matplotlib
In [2] matplotlib.__version__
You will obtain something like:
Out [3] '1.2.1'
If your version is higher than 1.2.1 you might need to first uninstall matplotlib by doing:
$ sudo pip uninstall matplotlib
Then you can reinstall the version 1.2.1 as explained previously


MayaVi for 3D visualization:

The 2D streamplot module in MDAnalysis outputs data that is formatted for plotting with matplotlib, but as for the 3D case, the user is free to use whatever plotting program they wish (adjusting the format of the output data as needed).

At the moment, the 3D streamplot module has no special dependencies beyond those of MDAnalysis, but its data output is formatted for plotting with the Python Mayavi package. Mayavi can be installed as described in its installation documentation. In short, after installing the prerequisites listed on that page (VTK, numpy, setuptools, Traits) type:
$ easy_install "Mayavi[app]"

Plotting coloured streamlines (without or with proteins)

First, you need to check if you have all the dependencies needed to run the Python script: check here. To try the methodology on a known system, you can download the .gro files for the proteins and the leaflets l0 and/or l1 corresponding to the upper and lower leaflets. You also need to download the small trajectory files for each system: prot_800_810.xtc, l0_800_810.xtc and/or l1_800_810.xtc corresponding to the trajectory files between 800 ns and 810 ns.

Then, you need to download the python script stream_Vs_prot_2D.py. Now, if you have all the files in the same directory just type this command in your terminal:
$ python stream_Vs_prot_2D.py prot.gro prot_800_810.xtc leaflet0.gro l0_800_810.xtc "name PO4" 20 0 1160 0 1160 9 10 1 stream_test .png false 4
You will obtain the image (A) above: streamlines without proteins. If you want to see the proteins as in (B) just change the penultimate parameter from false to true.

Now, we will explain the different parameters. We would like to stress that all the information is also commented into the script, so have a look--it is not too scary...

The main function of this script is: MDAnalysis.visualization.streamlines.generate_streamlines. It is fully documented here.

Parameter1: prot.gro gro file (structure) for the protein; NB: if the parameter 16 is false not useful but still need to fill it with whatever you want

Parameter2: prot_800_810.xtc xtc file (trajectory) for the protein; NB: if the parameter 16 is false not useful but still need to fill it with whatever you want

Parameter3: leaflet0.gro gro file (structure) for the leaflet0; this parameter is mandatory. You can also use leaflet1.gro in the example above in combination with l1_800_810.xtc to try the other leaflet.

Parameter4: l0_800_810.xtc xtc file (trajectory) for the leaflet0; this parameter is mandatory. You can also use l1_800_810.xtc in the example above in combination with leaflet1.gro to try the other leaflet.

Parameter5: "name PO4" selection for MDAnalysis; by default 'name PO4' to focus on the headgroups, but you can change it to whatever you want--just have a look at the selection syntax in the documentation on the MDAnalysis website.

Parameter6: 20 resolution of the grid cells (in Angstrom). 20 is a good default value--adjust as a function of the size of your system. NB: a smaller grid resolution can lead to less atoms in the cell and sometimes strange results.

Parameter7: 0 minimal boundary value in x.

Parameter8: 1160 maximal boundary value in x.

Parameter9: 0 minimal boundary value in y.

Parameter10: 1160 maximal boundary value in y.

Parameter11: 9 frame number to begin.

Parameter12: 10 frame number to end. You can do several frames consecutively by changing parameters 11 & 12 in order, for example, to produce a movie.

Parameter13: 1 time step for the frames.

Parameter14: stream_test output file name.

Parameter15: .png the extension for the output file--here .png but it can also be .svg, etc ..

Parameter16: false false or true. To plot the protein coordinates onto the streamlines.

Parameter17: 4 number of cores used to perform the calculation.

You can also tune the script to change the color for the proteins and the streamlines. For the proteins you can change the colour, line 120, replacing the html color code. For the streamlines you can change the colormap, line 109. The whole range of colours are available here.

If you want to try the script on your own systems we recommend that you first preprocess your data: see here. If you found this script useful for your work, please cite it using the reference here.

Plotting streamlines Versus heightmap (with or without proteins)



First, if you have not done it, you need to download the different example files here. Then, you need to download the Python script stream_Vs_z_2D.py. The usage is similar to the previous script:
$ python stream_Vs_z_2D.py prot.gro prot_800_810.xtc leaflet0.gro l0_800_810.xtc "name PO4" 20 0 1160 0 1160 30 90 9 10 1 test .png false 4
More info about the parameters here. The difference with the previous script is the addition of 2 new parameters between parameters 10 and 11. These values allow defining the maximum and minimum values for z. This script uses the contourf function from matplotlib to color the graphics as a function of z values.

Parameter10_bis: 30 minimal value in z.

Parameter10_ter: 90 maximal value in z.

If you want to try the script on your own systems we recommend that you first preprocess your data: see here. If you found this script useful for your work, please cite it using the reference here.

Streamlines superimposition of the two leaflets

First, if you have not done it, you need to download the different example files here. Then, you need to download the Python script stream_l0_Vs_l1.py. The usage is similar to the previous script:
$ python stream_l0_Vs_l1.py prot.gro prot_800_810.xtc leaflet0.gro l0_800_810.xtc leaflet1.gro l1_800_810.xtc "name PO4" 20 0 1160 0 1160 9 10 1 stream_test .png false 4
More info about the parameters here. The difference with the previous scripts is the addition of 2 parameters between parameters 4 and 5.

Parameter4_bis: leaflet1.gro gro file (structure) for leaflet1; this parameter is mandatory.

Parameter4_ter: l1_800_810.xtc xtc file (trajectory) for leaflet1; this parameter is mandatory.

If you want to try the script on your own systems we recommend that you first preprocess your data: see here. If you found this script useful for your work, please cite it using the reference here.

Plotting 3D streamlines and vectors

For the moment the vesicle structure is still not available but we will update the website as soon as it will be possible to use this structure. For the moment, you can try 3D streamline visualization with the planar membrane. You can download the files here. You need to install the MDAnalysis library as well as the Mayavi program - see here. We would like to thank Svenn-Arne Dragly for his help working with Mayavi - more details here. You can also see some of Sven-Arne's work with Mayavi here and here.

The script is based on the same logic as the previous ones. The main function of this script is: MDAnalysis.visualization.streamlines_3D.generate_streamlines_3d. It is fully documented here. You can downoad the script here. First you need to use ipython to run an interactive session:
$ ipython --pylab=qt
Then, just type:
$ run streamlines_3D.py leaflet0.gro l0_800_810.xtc "name PO4" 20 0 1160 0 1160 0 160 5 4 stream
Parameter1: leaflet0.gro gro file (structure) for leaflet0; this parameter is mandatory. You can also use leaflet1.gro in the example above in combination with l1_800_810.xtc to try the other leaflet.

Parameter2: l0_800_810.xtc xtc file (trajectory) for leaflet0; this parameter is mandatory. You can also use l1_800_810.xtc in the example above in combination with leaflet1.gro to try the other leaflet.

Parameter3: "name PO4" selection for MDAnalysis--by default 'name PO4' to focus on the headgroups--but you can adjust as needed--have a look at the selection documentation on the MDAnalysis website.

Parameter4: 20 resolution of the grid cells (in Angstrom). 20 is a good default value that can be adjusted as a function of the size of your system. NB: a smaller grid resolution can lead to less atoms in the cell and sometimes strange results.

Parameter5: 0 minimal boundary value in x.

Parameter6: 1160 maximal boundary value in x.

Parameter7: 0 minimal boundary value in y.

Parameter8: 1160 maximal boundary value in y.

Parameter9: 0 minimal boundary value in z.

Parameter10: 160 maximal boundary value in z.

Parameter11: 5 starting frame number.

Parameter12: 4 number of cores used to perform the calculation.

Parameter13: stream choose between stream and vector to respectively create 3D streamlines (see A above) or vectors (see B above).

If you want to try the script on your own systems we recommend that you first preprocess your data: see here. If you found this script useful for your work, please cite it using the reference here.