################################################################ ############ Lattice Microbes HeLa Model README ################ ######################### for Linux ############################ ################################################################ ####################### April 6, 2020 ########################## ################################################################ This README explains how to build and install the HeLa cell model published in: Zhaleh Ghaemi, Joseph R. Peterson, Martin Gruebele, and Zaida Luthey-Schulten. An in-silico human cell model reveals the influence of spatial organization on rna splicing. PLOS Computational Biology, 16(3):1–23, 03 2020 https://doi.org/10.1371/journal.pcbi.1007717 README Author: Benjamin R. Gilbert In order to build and simulate the HeLa Cell model, it is necessary to perform the following steps: 1) Build and install the Lattice Microbes Simulation Sofware (if this has not been done previously). Complete the steps in PRE-INSTALLATION 2) Apply a HeLa Cell Software Patch, specifically designed for the HeLa model, to the Lattice Microbes source code, and rebuild and reinstall the patched Lattice Microbes Software. Complete the steps in INSTALLATION 3) Visualize the Hela Cell Model in 3D with VMD plugin ######################## ### PRE-INSTALLATION ### ######################## ### Install base Lattice Microbes v2.3 ### Before installing the HeLa model, the user should install the base Lattice Microbes v2.3 from source and verify that it is working properly. Download the Lattice Microbes source code from http://faculty.scs.illinois.edu/schulten/lm/. Read the User's Guide http://faculty.scs.illinois.edu/schulten/lm/download/lm23/UsersGuide.pdf and the Installation Guide for Linux http://faculty.scs.illinois.edu/schulten/software_manuals/LM_2.3_INSTALL_annotations.pdf for guidance on building and installing Lattice Microbes. ### Test the base Lattice Microbes Installation v2.3 ### 1) Call the lm binary with the help option. lm --help The output should look like the following. Lattice Microbes 2.3a build by "user" on "user"-Linux-Machine at 2020-04-02 23:17:36 in 64-bit mode with options CUDA. Copyright (C) 2008-2016 Luthey-Schulten Group, University of Illinois at Urbana-Champaign. Usage: lm (-h|--help) Usage: lm (-v|--version) Usage: lm [OPTIONS] (-l|--list-devices) Usage: lm [OPTIONS] Usage: lm [OPTIONS] (-s|--script) script_filename [(-sa|--script-args) script_arguments+] Usage: lm [OPTIONS] [SIM_OPTIONS] (-f|--file) simulation_filename OPTIONS -c num_cpus --cpu=num_cpus The number of CPUs on which to execute (default all). -V --verbose=level Specified verbosity level. High numbers generate more noise. (default 6) -cr num --cpus-per-replicate=num The number of CPUs (possibly fractional) to assign per replicate, e.g. "2", "1/4" (default 1). -g cuda_devices --gpu=cuda_devices A list of cuda devices on which to execute, e.g. "0-3", "0,2" (default 0). -gr num --gpus-per-replicate=num The number of cuda devices (possibly fractional) to assign per replicate, e.g. "2", "1/4" (default 1). -nc --no-capabilities Don't print the capabilities of the CUDA devices. -nr --no-reserve-core Don't reserve a CPU core for the output thread. SIM_OPTIONS -r replicates --replicates=replicates A list of replicates to run, e.g. "0-9", "0,11,21" (default 0). -sp --spatially-resolved The simulations should use the spatially resolved reaction model (default). -ws --well-stirred The simulations should use the well-stirred reaction model. -sl solver --solver=solver The specific solver class to use for the simulations. -ck --checkpoint=interval Enable checkpointing with the given interval as hh:mm:ss (default 00:00:00 -- disabled). 2020-04-05 14:00:57) Info: Program execution finished. 2) Run some of the example files found within /lm-"version number"/src/python/Examples. Ex. python example-bimol.py -o cmebimol.lm ################################## ### INSTALLATION of HeLa Model ### ################################## Installing the HeLa model will include installing a custom Python package; therefore, if already using some form of Python virtual environments for Lattice Microbes, it is suggested that a copy of the existing Python virtual environment used for Lattice Microbes is created and that the copy is used when installing and running the HeLa model. When using the "conda" tool in the Anaconda Python distribution, this is done using the "--clone" option. ### Installation Steps ### 1) Download the HeLa git repository from https://github.com/EukaryoticCellBuilder/HeLa_Builder 2) Make a directory to store the HeLa model code. mkdir /home/"user"/HeLa_model mv HeLa-Builder_master.zip /home/"user"/HeLa_model/. 3) Extract the HeLa git repository within the HeLa model directory. cd /home/"user"/HeLa_model unzip HeLa-Builder_master.zip 4) If working with Lattice Microbes v2.3 or lower, then a patch needs to be applied to the Lattice Microbes source code and following the patch, Lattice Microbes needs to be rebuilt and reinstalled. In either case, it is strongly suggested to use the HeLa model with a new install of Lattice Microbes. 4.0) Download the Lattice Microbes source code and place it within a new source directory. Create a new source directory. mkdir /home/"user"/LM_v"version number"_HeLa Download the Lattice Microbes source code from http://faculty.scs.illinois.edu/schulten/lm/ and place it in the new source directory. mv lm-"version number"-src.tar.gz /home/"user"/LM_v"version number"_HeLa Extract the archive within the new source directory. cd /home/"user"/LM_v"version number"_HeLa tar -xzvf lm-"version number"-src.tar.gz Within new source directory there will be a subdirectory named lm-"version number". 4.1-patch) Copy the patch file to /home/"user"/LM_v_"version number"_HeLa/lm-"version number" cp /home/"user"/HeLa_model/HeLa_Builder-master/pylm-builder.patch /home/"user"/LM_v_"version number"_HeLa/lm-"version number"/. 4.2-patch) Apply the patch to the source code, this will modify a number of the files found in the subdirectories of /home/"user"/LM_v_"version number"_HeLa/lm-"version number"/src cd /home/"user"/LM_v_"version number"_HeLa/lm-"version number" git apply --reject pylm-builder.patch 4.3-patch) Read the User's Guide http://faculty.scs.illinois.edu/schulten/lm/download/lm23/UsersGuide.pdf and the Installation Guide for Linux http://faculty.scs.illinois.edu/schulten/software_manuals/LM_2.3_INSTALL_annotations.pdf for guidance on building and installing Lattice Microbes. Build and install Lattice Microbes using the patched source code found in the directory /home/"user"/LM_v_"version number"_HeLa/lm-"version number" and the instructions for versions 2.3 and lower. If Lattice Microbes has been previously installed, take care to select a different install directory for the files built from the patched source code. Additionally, to enable visualization of Lattice Microbes results using VMD v1.9.4a, see the relevant section of the Installation Guide for Linux. 4.1-no-patch) Build and install Lattice Microbes using the Lattice Microbes source code and the instructions for versions higher than 2.3. 5) Verify that the correct Python virtual environment is activated, then add the new installation of the patched Lattice Microbes to the user's Python path. 6) Install the custom package for the HeLa model. If using a Python virtual environment, this will install the package within the Python virtual environment. cd /home/"user/HeLa_model/HeLa_Builder-master python setup.py install ############################### ### EXECUTION of HeLa Model ### ############################### 1) Run the HeLa model to generate an input file containing the geometry of the HeLa cell. cd /home/"user/HeLa_model/HeLa_Builder-master python HeLa/hela.py #This will create an input file named "HeLa-full_*.lm" in the working directory, where "*" is a wildcard.# 2) Visualization of the HeLa model produced in Lattice Microbes can be performed with VMD v1.9.4a. The Lattice Microbes plugin for VMD is installed at a location within your VMD installation by enabling a Lattice Microbes build option prior the build and installation of Lattice Microbes. If Lattice Microbes has already been built and installed without also installing the VMD plugin, simply rebuild and reinstall Lattice Microbes without changing any options other than those related to the VMD plugin. The Installation Guide for Linux contains more detailed information about enabling VMD. ### Steps to load the .lm file into VMD ### 1) Open VMD 2) Open the Tk Console window by going to Extensions>Tk Console and enter the following commands in the Tk Console. set env(LM_CREATE_OBSTACLE_ATOMS) 1 set env(LM_CREATE_SITE_ATOMS) 1 3) Load the .lm file by going to File>New Molecule and browsing for the file. 4) Enter the following command in the Tk Console. graphics top delete all ### Guide for visualization of the HeLa model ### 1) Open the Graphical Representations window by going to Graphics>Graphical Representations. 2) Under the Draw Style pane in the Graphical Representations window change the Drawing Method to LatticeCubes. 3) Species and cell regions can be selected under the Selections pane in the Graphical Represntations window. Begin by clicking the Reset button. Species can be selected by double-clicking the name Keyword and then double-clicking your selection from the list of species appearing in the Value field. Name List: S = Spliceosome SpremRNA = Spliceosome-premRNA complex gene = gene mRNA = mRNA premRNA = premRNA site = site (selects all lattice sites) Cell regions can be selected by double-clicking the type Keyword and then double-clicking your selection from list of numbers appearing in the Value field. Type List: 0 = Extracellular Space 1 = Cell Wall 2 = Cytoplasm 3 = Nucleus 4 = Cajal 5 = Speckle 6 = Nuclear Envelope 7 = Nuclear Pore Complex 8 = Mitochondria 9 = Golgi Apparatus 10 = Endoplasmic Reticulum The user can also type their selections directly into the Selected Atoms field and join multiply selections using Boolean operators. Ex. Display both genes and Golgi Apparatus name gene or type 9 3-optional) Run Lattice Microbes using the generated HeLa geometry. To run the Lattice Microbes simulation from the terminal use lm --help to see simulation options/format, an example is provided below. lm -r 1 -sp -sl "lm::rdme::MpdRdmeSolver" -f "HeLa-full_*.lm"