.. _user: Tutorial ======================================== Introduction ---------------------------------------- Successful vaccines work by inducing the development of memory B-cells that produce high-affinity antibody to antigens possessed by the microbe or virus against which the vaccine is directed. The key to the development of high-affinity antibodies is affinity maturation. In this process, somatic mutations are introduced into the genes that encode the antibody heavy and light chains. B-cells that bear mutated receptors with improved affinity for the eliciting ligand are thereby given a selective growth advantage and become the memory cells that provide protection against subsequent challenges. These events take place in the Darwinian microcosm of the germinal centers in the secondary lymphoid tissues. Germinal centers self-organize from more homogeneous primary follicles via signals exchanged by T-cells, B-cells, follicular dendritic cells, and several kinds of stromal cells, and these stochastic encounters that occur dynamically in a heterogeneous 3D spatial structure are believed to be major determinants of the vaccine response. We have developed a software application, Daphne, to study the spatial signaling and reorganization that drives the germinal center reaction. This 3D, multi-cellular, simulation system is built on the generic processes of Newtonian mechanics, and generalized chemical kinetics, as well as a small number of cell biology-specific constructs. The Daphne system simulates in continuous time and continuous space, and uses mass-action kinetic ordinary differential equations realized in a moment expansion for cytoplasmic biochemistry and plasma membrane biochemistry, reaction-diffusion partial differential equations for extracellular soluble factors, Markov models for discrete cellular transition such as cell division, differentiation and death, and stochastic processes for cellular chemokine sensing and locomotion. The user has complete control over the chemistry and cell biology in any given simulation. He or she may run simulations as provided, alter reaction rates or force parameters, or start from scratch and build. Customizable cell rendering capability allows the user to visualize cells by phenotype. Database and reporting files allow the user to re-play simulations and run post-simulation analyses. Various tools allow the user to probe the inner dynamics of cells during simulation and playback. In this article we provide an overview of the simulation software, demonstrate how to select pre-defined entities (genes, molecules, reactions, reaction complexes, and cells), how to create a custom cell, and how to set up and run a simulation protocol. Installation ---------------------------------------- * The Daphne software requires a 64-bit Windows system. Mac and Linux users can only run via emulation software. * Instructions and software for installing the Daphne simulation system are available at the following website. http://www.bu.edu/computationalimmunology/daphne-installer/ * Click on the installer link and save the zip file to your local file system. * Unzip the DaphneInstaller file and run the setup.exe file. * Save the files to the default installation directory (C:\Program Files\Boston University\DaphneInstall\) or select a custom location. * After installation, a Daphne shortcut will be added to your desktop. * Open Daphne using the icon on your desktop. * Daphne will launch with the predefined chemotaxis protocol (‘simple_chemotaxis.json’). Overview of the Graphical User Interface (GUI) ---------------------------------------- The GUI is comprised of six functional units (Figure 1). The simulation protocol, 3D graphics, and protocol stores windows can be undocked (and re-docked). * *Protocol Builder* * *3D Graphics Window* * *Protocol Stores* * *Main Menu* * *Toolbar* * *Status Bar* .. figure:: ./img/Picture1.png :width: 600px :align: center Overview of the Graphical User Interface for the Daphne simulation system Load the blank protocol ---------------------------------------- * In the main menu, select *File* and *Load Protocol*. * In the file dialog window, select blank_protocol.json and *Open*. * In the main menu, select *File* and *Save Protocol As*. In the file dialog window, enter a name for the protocol and select *Save*. Get subcellular components from the User Store ---------------------------------------- * In the* Main Menu*, select *Stores* and *Molecules*. * The left panel of the stores dialog window displays the source store for molecules and the right panel displays the destination store (Figure 2). Initially, the left panel of the stores dialog window displays molecules in the User Store and the right panel displays molecules in the *Protocol Store*. * In the left panel select the following molecules from the *User Store*: CXCR4| and sApop. * *Molecules* can be selected individually by clicking on the molecule or multiple molecules can be selected using Ctrl Right Click. * After selecting the desired molecules, push the blue arrow in the middle of the dialog window (Figure 2) to transfer the molecules to the right panel (*Protocol Store*) and close the dialog window. .. figure:: ./img/Picture2.png :width: 600px :align: center Transfer molecules between stores. Initially, the left panel of the stores dialog window displays molecules in the User Store and the right panel displays molecules in the Protocol Store. The user can use the selectors to change the direction of transfer. Grayed molecule names indicate molecules that are identical in both stores. * In the main menu, select *Stores* and Genes. In a similar manner as with molecules, select and transfer the gene, gApop, to the *Protocol Store*: * In the main menu, select *Stores* and Reactions. In a similar manner as with molecules, select and transfer the following reactions to the *Protocol Store*:: gApop -> sApop + gApop sApop -> * In the main menu, select *Stores* and Reaction Complexes. The term Reaction Complex is the name designated for an entity in Daphne that specifies a group of reactions. Typically, reactions in the Reaction Complex represent a set of inter-related reactions that, as a whole, represent a certain process inside the cell or in the extracellular medium. * In a similar manner as with molecules and reactions, select and transfer the following reaction complexes to the *Protocol Store* (Figure 3):: CXCR5 receptor production and recycling CXCR4 receptor production and recycling GC B cell chemotaxis: ECM reactions GC B cell chemotaxis: cytosol reactions Goldbeter-Koshland switch reactions Goldbeter-Koshland molecule homeostasis .. figure:: ./img/Picture3.png :width: 600px :align: center Transfer reaction complexes between stores. The term Reaction Complex is the name designated for an entity in Daphne that specifies a group of reactions. Typically, the group of reactions in the Reaction Complex represent a set of inter-related reactions that, as a whole, represent a certain process inside the cell or in the extracellular medium. The reactions display shows the reactions that comprise the selected reaction complex Review the subcellular components in the Protocol Store ---------------------------------------- * Select the Subcellular Components Store tab (Figure 4). .. figure:: ./img/Picture4.png :width: 600px :align: center Protocol Store subcellular components. In clockwise order, starting at the top left, unexpanded view of the Subcellular Components Store, Genes, Molecules, Reactions, and Reaction Complexes. There are more genes and molecules than were transferred. This is because molecules and genes that are reactants in reactions are added to the Protocol Store when reactions or reaction complexes are added. Similarly, there are more reactions than were added, because the reactions that comprise a reaction complex are added to the Protocol Store when a reaction complex is added. * Select the *Genes*, *Molecules*, *Reactions*, *Reaction Complexes*, expanders to review the entities in the *Protocol Store*. There are more genes and molecules than were transferred in steps 4.3 and 4.5. This is because molecules and genes that are reactants are added to the *Protocol Store* when reactions or reaction complexes are added. Similarly, there are more reactions than were added in step 4.8, because the reactions that comprise a reaction complex are added to the *Protocol Store* when a reaction complex is added. Create a custom cell – add molecules and genes ---------------------------------------- * Predefined cells can be added to the *Protocol Store* in a similar manner as with molecules, genes, reactions, and reaction complexes, but for this demonstration we will create a new user-defined cell. Select the *Cells Store* tab and push the *New* button. In addition to a cell name and radius, there are three broad areas for defining cells: *Movement*, *Chemistry*, and *Transitions* (Figure 5a). * (Optional) Override the default cell name (*Default Cell*) in the cell name text box. * Expand the *Chemistry* section and then expand the *Molecules* and *Genes* section. The list of membrane molecules will show, by default, and will be empty to start. * Add a molecule to the membrane by clicking the *Add* button. By default, the first available membrane-bound molecule from the *Subcellular Components Store* will be added (CXCL12:CXCR4|). Keep the default concentration of zero. * Select the *Cytosol* tab to add molecules to the cytosol. * Click the *Add* button. By default, the first available bulk molecule from the *Molecules* Library will be added (A) (Figure 5b-c). Use the molecule selector to change the molecule type to sApop (Figure 5) and keep the default concentration of zero. * Select the *Nucleus* tab, click the *Add* button, and add *gApop* the nucleus. * Close the *Molecules* and *Genes* section. .. figure:: ./img/Picture5.png :width: 600px :align: center .(a) Cells Store tab with the Cell Library for the Protocol. Besides the cell name and radius, there are three broad areas for defining cells: Movement, Chemistry, and Transitions. Cell Chemistry (b-c) Adding a molecule to the cytosol and changing the molecule type. Create a custom cell – add reactions Cytosol ---------------------------------------- * Expand the *Reactions* section. By default, the list of membrane reactions (reactions that only have membrane-bound molecules as reactants) is shown. * We will not add any reactions to the membrane, so select the *Cytosol* tab and click on Add a reaction. * *Reactions* from the *Subcellular Components Store* that can be added to the cytosol are shown in the *Available Reactions* list. Note that reactions that involve only bulk molecules or combination of bulk molecules and membrane-bound molecules are eligible to be added to the cytosol. Also note that gene transcription reactions for synthesizing molecules can also be added to the cytosol, since there is currently no distinction between the cytosol and nucleus. * Select the reaction `gApop -> *sApop* + gApop` for producing the pseudo-molecule, *sApop*, and the *sApop* degradation reaction, *sApop* ->, and press the Add button. (Multiple reactions can be selected using Ctrl Right Click.) The selected reactions now appear in the list of cytosol reactions. * Close the *Reactions* expander. Create a custom cell – add reaction complexes ---------------------------------------- * Expand the Reaction Complexes section. By default, the list of membrane reaction complexes (reaction complexes whose reactions only have membrane-bound molecules as reactants) is shown. * We will not add any reaction complexes to the membrane, so select the *Cytosol* tab and click on the *Add* reaction complex expander. * Reaction Complexes from the *Subcellular Components Store* that can be added to the cytosol are shown in the Available Reaction Complexes list. Note that reaction complexes whose reactions involve only bulk molecules or combination of bulk molecules and membrane-bound molecules or gene transcription reactions are eligible to be added to the cytosol. * Select the following reaction complexes:: CXCR5 receptor production and recycling CXCR4 receptor production and recycling GC B cell chemotaxis: cytosol reactions Goldbeter-Koshland switch reactions Goldbeter-Koshland molecule homeostasis * Close the Reaction Complexes and *Chemistry* expanders. Create a custom cell – add cell differentiation ---------------------------------------- * Expand the Transitions and Differentiation sections to specify cell differentiation. * Click on the New Differentiation Scheme button. * By default, the differentiation scheme starts with two states, with the default names: State0 and State1 (Figure 6a). The user can edit these state names and add states in the *Epigenetic Map* table. * In the *Epigenetic Map* table, change State0 to activated and State1 to pre-centroblast. * Right-click in the table, select *Add* a State, and change the default state name to centroblast. * Repeat three more times to add the following states: centrocyte, rescued, and apoptotic. (Figure 6b). .. figure:: ./img/Picture6.png :width: 600px :align: center Adding a differentiation scheme. (a) A new differentiation scheme with two default states. (b) A user-defined differentiation scheme with six states * The *Epigenetic Map* table specifies the state-dependent activation level of genes. Genes that are not listed in the table have the same (default) activation level that is independent of the state. * Use the *Add* a gene pulldown menu (Figure 7a) in the *Epigenetic Map* section to select gE1. By default, the gene is inactivate (has value 0) for all the states. In the gE1 column, click in the row corresponding to the activated state and change the value from 0 to 6.4x10-3. With this modification, the gE1 gene will produce cytoplasmic E1 molecules while in the activated state with rate π=ακχ (copies/min-µm3), where α is the activation level, κ is the transcription reaction rate, and χ is the gene copy number. Similarly, change the value in the rescued state from 0 to 3x10-3. * Add the gW, gE2, and gA genes to the *Epigenetic Map* and change the activation levels for these genes from 0 to 1 in the pre-centroblast row. * Add the gCXCR4 gene to the *Epigenetic Map* and change the activation level from 0 to 1 in the centroblast row. * Add the gCXCR5 and gDif1 genes to the *Epigenetic Map* and change their activation levels from 0 to 1 in the centrocyte row. * Finally, add the gApop gene and change its activation level from 0 to 1 in the apoptotic row (Figure 7b). .. figure:: ./img/Picture7.png :width: 600px :align: center Epigenetic map. (a) The Add a gene pulldown menu and (b) user-specified gene activation levels * The *Transition Regulators* table (Figure 8a) specifies the possible transitions from one state to another. Transitions occur in a probabilistic manner that can be driven by a molecular concentration or by a probability distribution. It is possible to specify multiple destination states from a given starting state (see 9.5.3). * Specify the condition for transitioning from the centroblast state to the centrocyte state. Double click in the table cell corresponding to the centroblast row and centrocyte column. The interface for specifying a molecular-driven transition is shown, by default (Figure 8b). For molecule-driven transitions, the probability of transition in a time step dt is prob = (Background) + (Linear coefficient) * (mean concentration) * dt. Select the W molecule from the drop-down list and change the Linear coefficient to 3x10-3 (the Background value remains at zero) (Figure 8b). .. figure:: ./img/Picture8.png :width: 600px :align: center .(a) An empty Transition Regulators table for specifying transitions between differentiation states. (b) the (default) interface for a molecular-driven transition, where the W molecule has been selected, yet. In this case, the probability of transition in time step dt is:: prob = (Background) + (Linear coefficient) * (mean concentration of W) * dt. * Specify the condition for transitioning from the activated state to the pre-centroblast state. Double click in the table cell corresponding to the activated row and pre-centroblast column. The interface for specifying a molecular-driven transition is shown, by default (Figure 8b). Click on the Molecular button to change the transition type to a Distribution type (Figure 9a). Click on the *Constant* dropdown menu and select a Weibull distribution (Figure 9b). Change the scale to 1577 minutes and the shape to 10. These parameter choices give a mean transition time of 25 hours (Figure 9c). .. figure:: ./img/Picture9.png :width: 600px :align: center .(a) The initial interface for a distribution-driven transition. The default is a Constant (Dirac delta) distribution. (b) The dropdown menu for choosing a probability distribution. (c) An example of a Weibull * Specify the conditions for transitioning from the pre-centroblast state to the centroblast state. In the same manner as above, double click in the table cell corresponding to the pre-centroblast row and centroblast column and select a *Constant* (Dirac delta) distribution with const. Value = 10 minutes, which specifies that the pre-centroblast to centrocyte transition will always occur 10 minutes from the time the cell transitions into the pre-centroblast state. Similarly, select a *Constant* distribution with const. Value = 10 minutes for the rescued to centroblast transition. * Specify two possible transitions out of the centrocyte state. First, in the table cell corresponding to the centrocyte row and rescued column, select a *Gamma* distribution with shape = 50 and rate = 0.139. Second, in the table cell corresponding to the centrocyte row and apoptotic column, select a *Gamma* distribution with shape = 50 and rate = 0.154. The final *Transition Regulators* table will appear as in Figure 10. .. figure:: ./img/Picture10.png :width: 600px :align: center The table specifying the transitions among different differentiation states. Create a custom cell – add cell division ---------------------------------------- * Expand the *Transitions* and *Division* sections to specify cell division (cell cycle). * Click on the *New Division Scheme* button. * By default, the differentiation scheme starts with two states, with default names *G1-S-G2-M* and cytokinetic. * The methods for adding and modifying states and gene activations in the cell cycle *Epigenetic Map* table are the as with cell differentiation (Section 9.3), with two exceptions. The cytokinetic state is always the last state and cannot be edited by the user. The user can specify how the cell transitions into the cytokinetic state, but once this state is reached the cell divides immediately and automatically returns to the first state of the division scheme (cell cycle). * Using the same methods as in 9.3, above, change the name of the first state from *G1-S-G2-M* to *G0*and add subsequent states *G1*,*S*, and *G2-M* (Figure 11a). * Using the same methods as in 9.4, above, add the gW, gE2, and gA genes to the cell cycle *Epigenetic Map* and change the activations in the S phase row to 1 (Figure 11a). .. figure:: ./img/Picture11.png :width: 600px :align: center The table specifying the epigenetic map for the cell cycle. * The methods for the cell cycle state transitions in the *Transition Regulators* table are the same as with cell differentiation (Section 9.5). * Specify the condition for transitioning from the *G0* state to the *G1* state as dependent on the concentration of the *Wp* molecule with *Background* and *Linear*coefficients 0 and 0.1, respectively. * Specify the conditions for G1->S transition and the S->G2-M transition as dependent *Gamma* distributions with rate = 0.514 and 0.19, respectively, and shape = 50 for both. Create a custom cell – add cell death ---------------------------------------- * Cell death is specified through a single probabilistic transition, either molecule- or distribution-driven. * Expand the *Transitions* and *Death* sections to specify cell death. * Click on the *New Death Driver* button. * Select the *sApop* molecule and specify a *Linear Coefficient* of 1 (Figure 12a). * In this way, cell death will only occur once the cell differentiates into the apoptotic state, since the *sApop* molecule is only produced in the apoptotic state (9.4.5), and cell death will occur in a probabilistic manner dependent on the concentration of *sApop* according to the formula in 9.5.1. Create a custom cell – movement ---------------------------------------- * Expand the *Movement*section and select the A\* molecule as the chemotactic driver molecule (Figure 12b). With this specification, the cell will experience a chemotactic force proportional to the gradient of the A\* molecule in the cytosol. * Gradients in the distribution of the A\* molecule in the cytosol are produce by gradients in the distribution of the bound chemokine receptors (*CXCL12:CXCR4*| and *CXCL13:CXCR5|)* through the reactions `A + CXCL12:CXCR4| -> A\* + CXCL12:CXCR4|` and `A + CXCL13:CXCR5| -> A\* + CXCL13:CXCR5|`. * The cell will also experience stochastic (Brownian-type) movement due to the (default) non-zero const. Value specified for the stochastic motion force parameter (Figure 12b). .. figure:: ./img/Picture12.png :width: 600px :align: center . (a) An example of cell death driven by the molecular concentration of sApop. (b) The interface for specifying cell parameters related to movement. In this case, the chemotactic force is proportional to the gradient of the A* molecule in the cytosol. New simulation protocol – extracellular medium ---------------------------------------- * In the simulation *Protocol Builder* (Figure 1), select the *Extracellular Medium* (ECM) tab. * In the *Extracellular Medium Extents* section (Figure 13a), change the size of the simulation space from 200 to 260 µm in each dimension. * In the *Molecular Concentrations* section, expand the *Reaction Complexes* section, open the *Add* reaction complex section, select the GC B cell chemotaxis: ECM reactions reaction complex, and press the *Add* button (Figure 13b). * In the *Molecular Concentrations* section, click on the *CXCL13* molecular concentration in the list box and expand the *Details* section. * Change the initial distribution from *Homogeneous* to *Gaussian*. .. figure:: ./img/Picture13.png :width: 600px :align: center Interface for specifying a Gaussian initial distribution for molecules in the extracellular medium. * Change the coordinates for the center of the distribution from (100, 100, 100) to (130, 130, 130) (Figure 14). * Increase the standard deviation (std. dev.) values from 50 to 130 µm (Figure 14). * Change the peak concentration from 1 to 500 molec/µm3 (Figure 14). * Turn off the grid and blob visualization of the *Gaussian* distribution center and standard deviations by clicking on the white and red eyeballs (Figure 14). * In the Molecule Properties section, change the value of the diffusion coefficient (Diff Coeff) from 4500 to 0 (Figure 14). .. figure:: ./img/Picture14.png :width: 600px :align: center Interface for specifying a Gaussian initial distribution for molecules in the extracellular medium * In the *Molecular Concentrations* section, click on the *CXCL12* molecular concentration in the list box and expand the *Details*section. * Change the initial distribution from *Homogeneous*to Gaussian. * Change the coordinates for the center of the distribution from (100, 100, 100) to (222, 222, 222). * Increase the standard deviation (std. dev.) values from 50 to 100 µm. * Change the peak concentration from 1 to 500 molec/µm3. * Turn off the grid and blob visualization of the *Gaussian* distribution center and standard deviations by clicking on the white and red eyeballs. * In the Molecule Properties section, change the value of the diffusion coefficient (Diff Coeff) from 4500 to 0. New simulation protocol – add the custom cell to the simulation protocol ---------------------------------------- * In the simulation *Protocol Builder* (Figure 1), select the *Cells* tab and push the *Add* button. * By default, a cell population of the next available cell type from the Cells Store will be added. In this case, there is only one cell type in the Cells Library - the custom cell created in steps 6-12, above, so a new cell population of the custom cell type will be added to the simulation protocol. * Select the 3D View tab and press *Apply* in the ribbon to view and update the 3D graphics. * By default, the initial coordinates of the cell are randomly selected from uniform distributions on the simulation extents in each dimension. This can be seen by expanding the Cell Placement Method section (Figure 15). .. figure:: ./img/Picture15.png :width: 600px :align: center .(a) An example of the Population Details interface in the Cells tab of the protocol after adding a new cell population to the simulation protocol. The initial coordinates of the cells in a newly added cell population are randomly selected from uniform distributions in each spatial dimension. The user can also select a Normal distribution for randomly assigning cell coordinates or assign specific coordinates by editing or pasting into the Actual Cell Locations table. (b) The 3D Graphics window displaying the cell location in the simulation coordinate New simulation protocol – simulation settings ---------------------------------------- * In the simulation *Protocol Builder*, select the *Sim Setup* tab (Figure 16). .. figure:: ./img/Picture16a.png :width: 600px :align: center . (a) The interface for specifying simulation settings. (b) The interface for selecting reporting options. In the example here, cell coordinates and all transition states will be written to file at a frequency specified by the sampling interval. Data are written to text files and can be analyzed using post-simulation options in Daphne or with third party software (e.g., Excel, Matlab). * (Optional) Change the protocol *Experiment* name and *Description* to something of your choosing. * Change the total time (total simulation time) from 100 to 11,520 minutes (8 days). * Change the rendering interval from 1 to 30 minutes. The rendering interval determines how often the 3D graphics window is updated during the simulation. * Change the sampling interval from 1 to 15 minutes. The sampling interval determines how often data is saved to the report files. New simulation protocol – customize report files ---------------------------------------- * In the simulation *Protocol Builder*, select the *Reports* tab. * (Optional) Specify a file name root. All report files names will begin with the file name root. If no file name root is specified, a default is created (more detail?) * In the Cell Spatial State section and check the box for reporting cell positions (Figure 17). .. figure:: ./img/Picture16b.png :width: 600px :align: center The interfaces for selecting reporting on molecular concentrations associated with cells. Selections apply to each cell in the selected cell population. Users can select one of two modes for reporting on molecular concentrations: the concentration, only, or the concentration and the gradient. (a) The interface for selecting reporting options for ECM probe and cell membrane molecules. The ECM probe molecule settings allow the user to record the ECM environment at the position of the cell. The value of the selected ECM molecular concentration at the position of each cell will be recorded, if checked. (b) The interface for selecting reporting options for molecular concentrations in the cytosol. * In the Cell Transition State section, check the boxes for reporting on *Death*, *Division*, *Generation*, *Differentiation*, and *Exiting* states (Figure 16b).. * Expand the *Molecules* by *Cell*section. * In the *ECM* probe at cell location section, check the boxes for reporting the concentration and gradient of *CXCL13 *and *CXCL12* at the cell position. * In the *Molecules* in membrane section, check the box for reporting the means and gradients of the *CXCL13:CXCR5|* and *CXCL12:CXCR4|* membrane-bound molecules. * In the *Molecules* in cytosol section, check the box for reporting the mean and gradient of the A\* molecule. Check the boxes for reporting the mean of the *W*, *Wp*, *E1*, and *sApop* molecules. Start and pause the simulation ---------------------------------------- (Add steps for saving the state, change rendering option, probing cells) Post-simulation analyses ---------------------------------------- (Add steps for simulation playback, cell tracks, plotting cell population dynamics, and plotting cell lineage)