Commit 588258d8 authored by jdurrant's avatar jdurrant
Browse files

Initial commit of files formally on sourceforge.

parents
Copyright (c) 2014, Jacob D. Durrant
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the FreeBSD Project.
LipidWrapper 1.0
As ever larger and more complex biological systems are modeled in
silico, approximating physiological lipid bilayers with simple
planar models becomes increasingly unrealistic. When building
large-scale models of whole subcellular environments, models of
lipid membranes with carefully considered, biologically relevant
curvature are essential. We here present a computer program called
LipidWrapper, written by Jacob Durrant in the lab of Rommie E. Amaro,
capable of creating curved membrane models with geometries derived
from various possible sources, both experimental and theoretical. We
are hopeful that this utility will be a useful tool for the
computational-biology community.
Installation
============
As a python script, LipidWrapper should run on any operating system
that has python, numpy, and scipy installed, without requiring the
installation of additional software. If the user optionally wishes
to generate lipid-bilayer models from PNG images, the Python Imaging
Library must also be installed. LipidWrapper has been explicitly
tested on Scientific Linux 6.2, OS X, Windows XP, and Windows 7.
The program download includes an "examples" directory that demonstrate
how to use the software. Examples are provided showing how to generate
lipid-bilayer models wrapped around equations, PDB point files, DAE
models, and image-defined surfaces. Test PDB, DAE, and PNG files are
included.
Command-Line Parameters
=======================
Methods for creating a surface mesh
===================================
--surface_equation: Generate a surface mesh from a python-formatted
equation defining z, given x and y. The --min_x, --max_x,
--min_y, and --max_y parameters are used to specify the region
over which the function should be evaluated. The --step_x and
--step_y parameters define the x-y distance between adjacent
points. Python functions from the math, numpy, and scipy modules
can be used. Example: --surface_equation "z =
250*numpy.sin(x*x/60000 +y*y/60000)"
--surface_filename: If this parameter specifies a file with the PDB
extension, a surface mesh is generated from the coordinates of
the PDB atoms. Example: --surface_filename mymesh.pdb
--surface_filename: If this parameter specifies a file that does not
have the PDB extension, the file is assumed to be a gray-scale
image, where black represents regions that are topologically
low, and white represents regions that are topologically high.
The --min_x, --max_x, --min_y, and --max_y parameters are used
to specify the region where the mesh should be generated. The
--step_x and --step_y parameters define the x-y distance between
adjacent points. The --max_height parameter determines the
height of the bilayer model at those locations where the image
is white; black regions are assigned a height of 0. This feature
is only available if the python PIL module has been installed on
your system. Example: --surface_filename mymesh.png
The initial lipid model
=======================
--lipid_pdb_filename: This parameter specifies a PDB file containing
an all-atom model of a planar lipid bilayer. LipidWrapper will
wrap this lipid around the user-generated mesh. Example:
--lipid_pdb_filename lipid.pdb
--lipid_headgroup_marker: A unique atom representing the headgroup of
each lipid residue must be specified. The
--lipid_headgroup_marker accepts a comma-separated lists of atom
specifications (RESNAME_ATOMNAME). If either RESNAME or ATOMNAME
is omitted, any value will be accepted. By default, LipidWrapper
identifies lipid headgroups by looking for any atom named "P"
(_P) or any atom named "O3" belonging to a cholesterol molecule
(CHL1_O3). Example: --lipid_headgroup_marker "_P,CHL1_O3"
Methods for resolving lipid clashes
===================================
--delete_clashing_lipids: It's common for lipids to sterically clash
at the interface of two adjacent surface-mesh tessellated
triangles. If this parameter is set to TRUE, any clashing lipids
are deleted. Example: --delete_clashing_lipids TRUE
--clash_cutoff: If you do choose to delete clashing lipids, this
parameter determines how close two atoms must be (in Angstroms)
to constitute a steric clash. Example: --clash_cutoff 2.0
--fill_holes: Deleting lipids often leaves holes in the membrane. If
this parameter is set to TRUE, LipidWrapper tries to fill the
hole. Example: --fill_holes TRUE
--fill_hole_exhaustiveness: Essentially, how long LipidWrapper should
try to fill the holes. Example: --fill_hole_exhaustiveness 10
--clashing_potential_margin: Lipid clashes occur at the edges of
adjacent tessellated triangles. If these triangles are very
large, it's faster to only check for clashes and holes near the
triangle edges. This variable specifies how far from the edges,
in Angstroms, that LipidWrapper should look for clashes and
holes. Example: --clashing_potential_margin 25.0
--very_distant_lipids_cutoff: LipidWrapper determines if two lipids
clash by comparing the distance between every atom in the first
lipid with every atom in the second lipid. This can be
computationally expensive. However, sometimes two lipids are so
distant from each other, that it's obvious there are no clashes,
making the pair-wise comparison unnecessary. Before performing
this expensive pair-wise comparison, LipidWrapper calculates the
distance between one atom of each lipid. If this distance is
greater than this user-specified cutoff, the program will simply
assume there are no clashes. WARNING: Remember to consider the
width of your lipid bilayer when choosing this value. Adjacent
lipids on opposite sides of the bilayer can seem distant when
considering the distance between their headgroups, for example.
Example: --very_distant_lipids_cutoff 50.0
--triangle_center_proximity_cutoff_distance: Lipid steric
clashes/holes typically occur between lipids that belong to
adjacent tessellated triangles. However, if tessellated
triangles are small enough, clashes are possible between lipids
that belong to non-adjacent triangles as well. Consequently, in
addition to checking for adjacency, LipidWrapper also checks the
distance between the triangle centers, using this user-specified
value as a cutoff. Example:
--triangle_center_proximity_cutoff_distance 50.0
--memory_optimization_factor: When the tessellated triangles are very
large and consequently contain many individual lipids, the
extensive pairwise distance comparisons required can result in
memory errors. This parameter tells lipid Wrapper to divide the
list of atoms being compared into smaller chunks. The pairwise
distance comparison is performed piecewise on each chunk-chunk
pair and so uses less memory, albeit at the expensive of speed.
Only increase the value of this parameter if you run into memory
errors. Example: --memory_optimization_factor 1
Additional options
==================
--number_of_processors: Using multiple processors can significantly
increase the speed of the LipidWrapper algorithm. Example:
--number_of_processors 8
--show_grid_points: Aside from producing PDB coordinates for lipid
atoms, additional coordinates will be appended to the bottom of
the output containing "atoms" named "X" that specify the
location of the surface mesh points. Example: --show_grid_points
TRUE
--create_triangle_tcl_file: A separate file named "triangles.tcl" will
be generated containing a tcl script that can be run in VMD to
visualize the mesh surface. Example: --create_triangle_tcl_file
TRUE
--output_directory: If an output directory is specified, all
LipidWrapper output files, as well as additional files
representing the intermediate steps required to build the final
bilayer, will be saved in that directory. Example:
--output_directory ./my_output/
--use_disk_instead_of_memory: For very large systems, storing the
growing model in memory can be problematic. If this parameter is
set to TRUE, the growing model will be stored on the hard disk
instead. However, expect longer execution times if this
parameter is set to TRUE. Example: --use_disk_instead_of_memory
TRUE
--compress_output: Depending on the user options selected,
LipidWrapper output can require a lot of disk space. If this
parameter is set to TRUE, the output will be automatically
compressed using the gzip algorithm (Lempel-Ziv coding LZ77).
The files can be uncompressed with the UNIX gunzip utility, or
similar Windows-based packages. Example: --compress_output TRUE
Example
=======
python lipidwrapper.py --surface_equation "z = 250*numpy.sin(x*x/60000
+y*y/60000) * (-numpy.sqrt(x*x+y*y)/(560 * numpy.sqrt(2)) + 1)"
--min_x 500 --max_x 1000 --min_y 500 --max_y 1000 --step_x 25
--step_y 25 --lipid_pdb_filename lipid.pdb
--lipid_headgroup_marker "_P,CHL1_O3" --delete_clashing_lipids
TRUE --clash_cutoff 1.0 --fill_holes TRUE
--fill_hole_exhaustiveness 10 > lipid_model.pdb
python ../lipidwrapper.py --surface_equation "z=25.0*x*x/10000.0 + 25.0*y*y/10000.0" --min_x -100 --max_x 100 --min_y -100 --max_y 100 --step_x 50 --step_y 50 --lipid_pdb_filename ./files/lipid_example.pdb --delete_clashing_lipids TRUE --fill_holes TRUE --clash_cutoff 1.0 --output_directory example1.quick_test_from_equation.output_dir --number_of_processors 4 --use_disk_instead_of_memory FALSE --show_grid_points TRUE --create_triangle_tcl_file TRUE --clashing_potential_margin 15.0 --memory_optimization_factor 1
python ../lipidwrapper.py --surface_equation "z = 250*numpy.sin(x*x/60000 +y*y/60000) * (-numpy.sqrt(x*x+y*y)/(560 * numpy.sqrt(2)) + 1)" --min_x -500 --max_x 500 --min_y -500 --max_y 500 --step_x 25 --step_y 25 --lipid_pdb_filename ./files/lipid_example.pdb --delete_clashing_lipids TRUE --fill_holes TRUE --clash_cutoff 1.0 --output_directory example2.from_equation.output_dir --number_of_processors 24 --use_disk_instead_of_memory TRUE --show_grid_points TRUE --create_triangle_tcl_file TRUE --clashing_potential_margin 15.0 --memory_optimization_factor 1
python ../lipidwrapper.py --surface_filename ./files/face.png --min_x -500 --max_x 500 --min_y -500 --max_y 500 --step_x 25 --step_y 25 --lipid_pdb_filename ./files/lipid_example.pdb --max_height 150 --delete_clashing_lipids TRUE --fill_holes TRUE --clash_cutoff 1.0 --output_directory example3.from_image.output_dir --number_of_processors 24 --use_disk_instead_of_memory FALSE --show_grid_points TRUE --create_triangle_tcl_file TRUE --clashing_potential_margin 15.0 --memory_optimization_factor 1
python ../lipidwrapper.py --surface_filename ./files/influenza_mesh.pdb --lipid_pdb_filename ./files/lipid_example.pdb --delete_clashing_lipids TRUE --fill_holes TRUE --clash_cutoff 1.0 --output_directory example4.from_PDB_points.output_dir --number_of_processors 24 --use_disk_instead_of_memory FALSE --show_grid_points TRUE --create_triangle_tcl_file TRUE --clashing_potential_margin 15.0 --memory_optimization_factor 1
python ../lipidwrapper.py --surface_filename ./files/concave_model.dae --lipid_pdb_filename ./files/lipid_example.pdb --delete_clashing_lipids TRUE --fill_holes TRUE --clash_cutoff 1.0 --output_directory example5.from_DAE_file.output_dir --number_of_processors 24 --use_disk_instead_of_memory FALSE --show_grid_points TRUE --create_triangle_tcl_file TRUE --clashing_potential_margin 15.0 --memory_optimization_factor 1
This diff is collapsed.
CRYST1 1.000 1.000 1.000 90.00 90.00 90.00 P 1 1
ATOM 1 SN UNK A 1 150.011 134.412 -36.701 1.00 0.00 S
ATOM 2 SN UNK A 1 114.564-250.477-120.542 1.00 0.00 S
ATOM 3 SN UNK A 1 161.847 -65.100 -24.532 1.00 0.00 S
ATOM 4 SN UNK A 1 -18.390 64.752 -23.672 1.00 0.00 S
ATOM 5 SN UNK A 1 303.449 73.456-142.919 1.00 1.00 S
ATOM 6 SN UNK A 1 14.017 256.855 -66.996 1.00 1.00 S
ATOM 7 SN UNK A 1 -53.367-151.115 -35.250 1.00 1.00 S
ATOM 8 SN UNK A 1 168.320 37.164 -7.804 1.00 1.00 S
ATOM 9 SN UNK A 1 62.095 97.849 -27.543 1.00 0.00 S
ATOM 10 SN UNK A 1 241.195 108.159 -69.839 1.00 1.00 S
ATOM 11 SN UNK A 1 81.435 198.094 -49.963 1.00 1.00 S
ATOM 12 SN UNK A 1 187.568 210.415 -83.180 1.00 1.00 S
ATOM 13 SN UNK A 1 150.770-172.395 -49.937 1.00 0.00 S
ATOM 14 SN UNK A 1 27.456-198.617 -75.976 1.00 0.00 S
ATOM 15 SN UNK A 1 -104.639 29.359 -11.098 1.00 1.00 S
ATOM 16 SN UNK A 1 -128.541 -83.174 -23.634 1.00 1.00 S
ATOM 17 SN UNK A 1 70.139 0.119 5.406 1.00 1.00 S
ATOM 18 SN UNK A 1 258.220 -0.883 -59.144 1.00 1.00 S
ATOM 19 SN UNK A 1 55.840-115.159 -18.327 1.00 1.00 S
ATOM 20 SN UNK A 1 248.798-126.329 -89.907 1.00 1.00 S
ATOM 21 SN UNK A 1 -2.296 163.084 -28.959 1.00 1.00 S
ATOM 22 SN UNK A 1 -37.271 -45.351 8.214 1.00 1.00 S
ATOM 23 SN UNK A 1 -100.708 124.272 -25.534 1.00 1.00 S
ATOM 24 SN UNK A 1 261.111 178.986-143.484 1.00 1.00 S
ATOM 25 SN UNK A 1 308.807 -40.523-166.940 1.00 1.00 S
ATOM 26 SN UNK A 1 112.950 274.637 -98.499 1.00 1.00 S
ATOM 27 SN UNK A 1 -83.569 224.598 -57.719 1.00 1.00 S
ATOM 28 SN UNK A 1 161.472 87.811 -18.397 1.00 1.00 S
ATOM 29 SN UNK A 1 104.074 115.363 -32.347 1.00 0.00 S
ATOM 30 SN UNK A 1 196.684 122.251 -49.470 1.00 0.00 S
ATOM 31 SN UNK A 1 115.152 167.446 -42.429 1.00 0.00 S
ATOM 32 SN UNK A 1 167.717 171.558 -60.981 1.00 0.00 S
ATOM 33 SN UNK A 1 138.010-221.960 -75.692 1.00 0.00 S
ATOM 34 SN UNK A 1 68.510-220.905-100.403 1.00 0.00 S
ATOM 35 SN UNK A 1 174.406-250.034-125.597 1.00 0.00 S
ATOM 36 SN UNK A 1 -149.560 10.798 -17.584 1.00 1.00 S
ATOM 37 SN UNK A 1 -160.931 -44.979 -29.105 1.00 1.00 S
ATOM 38 SN UNK A 1 164.624 -13.534 -17.027 1.00 0.00 S
ATOM 39 SN UNK A 1 159.164-119.892 -32.127 1.00 0.00 S
ATOM 40 SN UNK A 1 115.522 -31.902 -6.204 1.00 0.00 S
ATOM 41 SN UNK A 1 215.694 -36.263 -32.842 1.00 1.00 S
ATOM 42 SN UNK A 1 108.928 -90.892 -19.186 1.00 1.00 S
ATOM 43 SN UNK A 1 211.458-100.370 -46.260 1.00 0.00 S
ATOM 44 SN UNK A 1 21.289 81.052 -27.064 1.00 0.00 S
ATOM 45 SN UNK A 1 -60.264 47.537 -13.789 1.00 0.00 S
ATOM 46 SN UNK A 1 23.353 34.243 -5.921 1.00 0.00 S
ATOM 47 SN UNK A 1 -10.453 112.883 -27.698 1.00 0.00 S
ATOM 48 SN UNK A 1 -27.353 13.178 -6.049 1.00 1.00 S
ATOM 49 SN UNK A 1 -58.572 93.753 -23.704 1.00 0.00 S
ATOM 50 SN UNK A 1 279.456 91.147-101.229 1.00 1.00 S
ATOM 51 SN UNK A 1 318.406 56.077-188.426 1.00 1.00 S
ATOM 52 SN UNK A 1 287.701 36.837 -97.524 1.00 1.00 S
ATOM 53 SN UNK A 1 285.326 128.205-140.847 1.00 1.00 S
ATOM 54 SN UNK A 1 309.533 16.514-152.892 1.00 1.00 S
ATOM 55 SN UNK A 1 309.730 107.145-190.254 1.00 1.00 S
ATOM 56 SN UNK A 1 48.954 230.570 -52.983 1.00 1.00 S
ATOM 57 SN UNK A 1 6.201 213.516 -39.435 1.00 1.00 S
ATOM 58 SN UNK A 1 62.925 265.850 -82.320 1.00 1.00 S
ATOM 59 SN UNK A 1 -35.085 241.665 -60.863 1.00 1.00 S
ATOM 60 SN UNK A 1 200.129 244.902-115.184 1.00 1.00 S
ATOM 61 SN UNK A 1 235.631 227.693-147.142 1.00 1.00 S
ATOM 62 SN UNK A 1 162.392 278.551-121.491 1.00 1.00 S
ATOM 63 SN UNK A 1 -12.934-175.690 -55.555 1.00 1.00 S
ATOM 64 SN UNK A 1 -91.518-117.230 -28.808 1.00 1.00 S
ATOM 65 SN UNK A 1 1.550-136.569 -20.444 1.00 1.00 S
ATOM 66 SN UNK A 1 -45.913-100.797 -6.862 1.00 1.00 S
ATOM 67 SN UNK A 1 -58.767-190.626 -77.394 1.00 1.00 S
ATOM 68 SN UNK A 1 -107.914-162.241 -52.564 1.00 0.00 S
ATOM 69 SN UNK A 1 274.506-144.022-145.256 1.00 1.00 S
ATOM 70 SN UNK A 1 301.649 -97.166-184.858 1.00 1.00 S
ATOM 71 SN UNK A 1 -140.884 153.606 -41.385 1.00 1.00 S
ATOM 72 SN UNK A 1 112.375 70.244 -14.182 1.00 0.00 S
ATOM 73 SN UNK A 1 212.771 72.926 -29.021 1.00 1.00 S
ATOM 74 SN UNK A 1 113.792 19.878 -11.813 1.00 0.00 S
ATOM 75 SN UNK A 1 220.167 17.320 -21.511 1.00 1.00 S
ATOM 76 SN UNK A 1 73.734 149.364 -30.522 1.00 0.00 S
ATOM 77 SN UNK A 1 64.029 52.323 -19.438 1.00 0.00 S
ATOM 78 SN UNK A 1 30.060 130.174 -28.543 1.00 0.00 S
ATOM 79 SN UNK A 1 213.910 160.458 -76.189 1.00 0.00 S
ATOM 80 SN UNK A 1 257.062 54.846 -57.218 1.00 1.00 S
ATOM 81 SN UNK A 1 253.287 144.742-106.136 1.00 1.00 S
ATOM 82 SN UNK A 1 135.043 206.683 -60.634 1.00 0.00 S
ATOM 83 SN UNK A 1 40.129 182.798 -33.285 1.00 1.00 S
ATOM 84 SN UNK A 1 100.646 241.657 -64.218 1.00 0.00 S
ATOM 85 SN UNK A 1 227.773 196.605-110.027 1.00 1.00 S
ATOM 86 SN UNK A 1 151.396 245.153 -88.193 1.00 1.00 S
ATOM 87 SN UNK A 1 86.607-186.452 -63.320 1.00 0.00 S
ATOM 88 SN UNK A 1 193.087-208.022 -89.245 1.00 1.00 S
ATOM 89 SN UNK A 1 101.152-142.475 -33.846 1.00 0.00 S
ATOM 90 SN UNK A 1 204.882-154.596 -63.431 1.00 1.00 S
ATOM 91 SN UNK A 1 22.896-232.133-126.330 1.00 1.00 S
ATOM 92 SN UNK A 1 42.552-160.528 -42.051 1.00 0.00 S
ATOM 93 SN UNK A 1 -18.396-214.426 -97.747 1.00 0.00 S
ATOM 94 SN UNK A 1 239.000-178.410-115.427 1.00 1.00 S
ATOM 95 SN UNK A 1 -118.771 -27.106 -9.282 1.00 1.00 S
ATOM 96 SN UNK A 1 -149.583 59.686 -21.422 1.00 1.00 S
ATOM 97 SN UNK A 1 -71.817 -6.629 -2.845 1.00 1.00 S
ATOM 98 SN UNK A 1 -102.188 77.510 -20.133 1.00 1.00 S
ATOM 99 SN UNK A 1 -83.221 -65.128 -5.507 1.00 1.00 S
ATOM 100 SN UNK A 1 -143.575-123.921 -52.824 1.00 1.00 S
ATOM 101 SN UNK A 1 -146.642 108.554 -28.961 1.00 1.00 S
ATOM 102 SN UNK A 1 322.019 0.011-200.366 1.00 1.00 S
ATOM 103 SN UNK A 1 65.446 -59.804 5.011 1.00 0.00 S
ATOM 104 SN UNK A 1 17.386 -24.235 14.216 1.00 1.00 S
ATOM 105 SN UNK A 1 256.356 -63.619 -71.201 1.00 1.00 S
ATOM 106 SN UNK A 1 288.414 -22.467-111.004 1.00 1.00 S
ATOM 107 SN UNK A 1 8.912 -81.478 -0.544 1.00 1.00 S
ATOM 108 SN UNK A 1 282.506 -83.241-128.270 1.00 1.00 S
ATOM 109 SN UNK A 1 -50.967 143.742 -27.805 1.00 1.00 S
ATOM 110 SN UNK A 1 -43.254 196.510 -36.442 1.00 1.00 S
ATOM 111 SN UNK A 1 -93.521 176.322 -36.535 1.00 1.00 S
ATOM 112 SN UNK A 1 292.445 160.255-187.446 1.00 1.00 S
END
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment