Splitleafs
This tool aims to split leaflets from a bilayer. It reads a GROMACS gro file or a PDB file and print an index file with one group per leaflet.
Usage
splitleafs.py [options] < input > output.ndx splitleafs.py [options] -- input > output.ndx
If an input file if given as an argument then this file will be read; else the
program will read the standard input. The input file can be in the gro or PDB
format. The format is guessed from the content of the file Use the
--format
if you want to specify explicitly the file format.
The program writes a gromacs index file (.ndx file) on the standard output. The
index file will contain two groups called lower_leaflet
and
upper_leaflet
respectively. The groups contain the index of the reference
atoms in each leaflets (if the --keep-atom
option is used, default) or
the index of all the atoms from reference atom residues (if the
--keep-residue
is used).
Splitleafs is tested with python 2.6, 2.7, 3.2, 3.3, and pypy using Travis CI. Please see <https://travis-ci.org/jbarnoud/splitleafs> for the test status on splitleafs's current version.
Options
- --axis or -d:
- The axis normal to the membrane,
z
by default. - --atom or -a:
- The atoms of reference. Several Several atoms can be given. The format for
one reference atom is
residue_name:atom_name
, the residue name can be omitted then the atom is mentioned by its atom name only. - --keep-residue or -r:
- Write the whole residues in the index file.
- --keep-atom or -k:
- Write only the atoms of reference in the index file (default).
- --format or -f:
- The input file format. Gromacs gro files and PDB files are supported.
If
auto
is selected, then the file format is guessed from the input content.auto
by default. - --print-residue or -i:
- Print (in the
stderr
) the residue indexes of each leaflet at the end.
Examples
splitleafs.py membrane.pdb > leaflets.ndx
This command will read the membrane.pdb
file, it will guess it is a PDB file
and will write the leaflets.ndx
file with the index of the P1
atoms
split in two leaflets. Here we assume that membrane.pdb
describe a
phospholipid and that P1
is the name of the phosphorus.
If your system is different you can change the reference atom using the
--atom
option. Let's assume we have a phospholipid bilayer described within
the Martini coarse-grained force field.
Then the phospate group is represented by a bead called PO4
. If we want to
use this bead as a reference for our splitting we can use the command
splitleafs.py --atom PO4 -- membrane_martini.gro > leaflets.ndx
Notice that, in this last example, we give a gro file to the program which will guess it is not a PDB file and read it with the right file format.
If the membrane in the previous example is made of POPC lipids only, then the command is equivalent to
splitleafs.py --atom POPC:PO4 -- membrane_martini.gro > leaflets.ndx
The --atom
option can take several arguments. This can be useful in case of
an heterogeneous membrane
splitleafs.py --atom POPC:PO4 CHOL:ROH -- membrane_martini.gro > leaflets.ndx
You may need not only the phosphorus but also the whole lipid in the output
index file. Then use the --keep-residue
option
splitleafs.py --atom PO4 --keep-residue membrane_martini.gro > leaflets.ndx
In the current version, only the residue that contains the reference atom is selected. This means that if your molecules are composed of more than one residue, the others will be ignored. Most lipid representation use only one residue per lipid so this issue should not be a concern.
You might want to know how many atoms were selected in each leaflet. This is convenient to quickly check the result of the program or to know if a membrane is symmetric. These informations are written on the standard error stream so you can see them even if you redirect the output of the program in a file
lower_leaflet: 144 atoms upper_leaflet: 144 atoms The membrane is symmetric.
You might also want to know which residue is in each leaflet. You can then use
the --print-residue
option which will ouput on the standard error the residue
indexes of each leaflet
The membrane is symmetric. Residue indexes in the lower_leaflet 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 Residue indexes in the upper_leaflet 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
Use as a python module
Splitleafs is written in python and can be used as a python module. To use splitleafs this way, you need to have it in your PYTHONPATH or in your current directory. There is no proper installation procedure yet.
>>> import splitleafs
>>> with open('structure.gro') as infile
... groups = splitleafs.split_leaflets(infile, 'z',
[('DPPC','PO4'), ('DUPC', 'PO4')],
splitleafs.read_gro, False)
>>> print groups.keys()
('lower_leaflet', 'upper_leaflet')
Principle
In order to split the membrane, splitleafs calculate the geometric center of the ensemble of reference atoms. The reference atoms above this geometric center on the membrane normal are assumed to be part of the upper leaflet, the others are part of the lower leaflet. If the whole residues are kept in the output, then a residue is assumed to be part of the same leaflet as its reference atom.
Limitations
Because of the algorithm used to split the membrane, splitleafs does not work on curved or undulated membrane if the geometric center of the reference atoms is not in between the leaflets. Splitleafs does not work neither on vesicles.
You may get a wrong result if your membrane cross the periodic box in its normal dimension.
Multi-residue molecules are not supported yet. Keeping only the reference atoms
(--keep-atom
or -k
option) will work but the program does not allow to
keep the entire molecule. If the --keep-residue
(or -r
) option is used,
then only the residues that contain the reference atoms will be kept.
If several reference atoms belong to the same residue, then the leaflet of the
residue if defined by the first reference atom read in the input file. All the
reference atoms are however used for the geometric center calculation. If the
--keep-atom
(or -k
) option is used, then the group for each reference
atom is decided separately.
Contribute
Splitleafs last version is available on github where you can also report issues and do pull requests.
The program is distributed with a test suite that can be run by calling the test_splitleafs.py script. The nosetests python module is not requires but would improve the readability of the output. The nosetests modula can be installed by:
pip install nose
Then the tests can be run with:
nosetest
License
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
A copy of the GNU General Public License is available at http://www.gnu.org/licenses/gpl-3.0.html.