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 FilesBoston UniversityDaphneInstall) 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 1: 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 2: 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 3: 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 4: 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 5: .(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 6: 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 7: 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).

• 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 9: .(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 10: 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 11: 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 12: . (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 13: 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 14: 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 15: .(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 16: . (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 17: 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)