Additional Information

Reproducing Figures from Research Articles

This table is a guide to specific demos included with CellOrganizer that generate figures similar to those presented in publications that used CellOrganizer to analyze particular datasets. Some demos will generate the same figures as in the research article and others will build a similar output, e.g. same figure different synthetic image.

Article

Figure 1

Figure 2

Figure 3

Figure 4

Figure 5

Figure 6

Figure 7

Figure 8

Figure 9

Figure 10

Johnson et a. (2015)

N/A

demo3D27

N/A

N/A

N/A

N/A

N/A

N/A

N/A

N/A

Li et al. (2012)

N/A

demo3D00, demo3D02

N/A

demo3D04

demo3D35

N/A

N/A

N/A

N/A

N/A

Buck et al. (2012)

demo2D01

demo3D11

N/A

demo2D02, demo3D09

N/A

demo3D04

N/A

N/A

N/A

N/A

Murphy (2012)

demo2D01

demo3D11

N/A

N/A

N/A

N/A

N/A

N/A

N/A

N/A

Peng and Murphy (2011)

demo3D11

N/A

N/A

N/A

N/A

N/A

N/A

demo3D02

N/A

N/A

Shariff et al (2011)

demo3D04

demo3D04

N/A

N/A

N/A

N/A

N/A

N/A

N/A

N/A

Murphy (2010)

N/A

N/A

N/A

demo3D01

N/A

demo2D00

N/A

N/A

N/A

N/A

Shariff et al. (2010)

demo3D01, demo3D14

N/A

N/A

demo3D07, demo3D06

N/A

demo3D35

demo3D35

demo3D35

N/A

N/A

Peng et al. (2009)

N/A

demo2D04, demo3D15, demo3D20

N/A

N/A

demo3D15

N/A

N/A

N/A

N/A

N/A

OME-TIFF

The software supports saving synthetic images as valid OME.TIFF. Currently, the software can only save images with one protein pattern as OME.TIFFs. To do this, use the output flag

options.output.OMETIFF = true;

For an example, investigate and run demo3D34.

SBML Spatial Level 3

The software supports saving synthetic images as valid SBML Level 3 Spatial instances. Currently, the software can only save images with one vesicle pattern as OME.TIFFs. To do this, use the output flag

options.output.SBMLSpatial = true;

For an example, investigate and run demo3D34.

Virtual Cell

The software supports saving generated geometries as valid VCML(Virtual Cell Markup Language) files that can be imported into Virtual Cell, a platform to perform biological system modeling and simulations. To do this, use the output flag

options.output.writeVCML = true;

For simple examples, investigate and run:

  • demo3D58: Generate a single framework and vesicles from a 3D HeLa ratio model and write to VCML.

  • demo3D60: Generate a single framework and vesicles from a 3D HeLa SPHARM model and write to VCML.

  • demo3D63: Generate a single framework from a 3D HeLa SPHARM model and write to VCML with a reaction network and spatial and compartmental simulations ready to be run in Virtual Cell.

For an example application that generates 100 synthetic geometries with reaction networks (as in demo3D63), writes them to individual VCML files, and combines them into one VCML file for easy import into Virtual Cell, see generate_simulation_instances_SarmaGhosh2012.

Options

The table below describes all VCML-related options. All options are fields within the options.output.VCML structure.

Options are listed as required or optional in the case that options.output.writeVCML = true; otherwise, they have no effect.

Option

Required

Description

writeVCML

required

boolean flag specifying whether to write out VCML files for use with Virtual Cell. Default is false.

input_filename

optional

string specifying Virtual Cell VCML file with biochemistry which will be combined with generated geometry in output file. Default is empty string.

downsampling

optional

downsampling fraction for the creation of object files (1 means no downsampling, 1/5 means 1/5 the size). Default is 1.

translations

optional

N x 2 cell array of strings (first column) to be replaced by other strings (second column).

Tutorials

demo3D63

demo3D63 generates a single framework from a 3D HeLa SPHARM model and writes it to VCML with a reaction network and spatial and compartmental simulations ready to be run in Virtual Cell.

Key options:

  • options.synthesis = 'framework';: The reaction network occupies only the cytoplasm and the nucleus.

  • options.output.VCML.writeVCML = true;: Instructs CellOrganizer to create a VCML output file.

  • options.VCML.downsampling = 1/2;: Reduces the size of the 3D image holding the cell, which makes the simulation run faster and reduces the storage requirements for the simulation’s results.

  • options.VCML.translations = {'cell', 'CP'; 'nuc', 'NU'; 'nucleus', 'NU'; 'lamp2_mat_tfr_mat', 'EN'; 'CP_EC', 'PM'; 'CP_EN', 'EM'; 'CP_NU', 'NM'};: Instructs CellOrganizer to translate 'cell' into 'CP', etc. so the geometry’s compartment names match those of the input VCML file.

  • reaction_network_file = '../../../data/SarmaGhosh2012ForCOdiff1e-2.vcml';, options.VCML.input_filename = reaction_network_file;: Instructs CellOrganizer to incorporate the input VCML file’s reaction network and simulations into the output VCML file.

  • options.VCML.end_time = 4000;, etc.: Set Virtual Cell simulation parameters.

Expected outputs:

  • demo3D63/cell1/cell.vcml: The VCML file to be opened in Virtual Cell.

Using the generated VCML in Virtual Cell:

  1. In Virtual Cell, select File > Open > Local... and select this file. You should see no errors or warnings listed in the Problems tab.

  2. Click img_Spatial under Applications, then Simulations, then img_Spatial_Simulation_1, then click the green triangle button to run the simulation on the Virtual Cell server. The simulation will take several hours to complete.

T cell models

The T Cell model is a building model for 3D cells with protein patterns, and can be used to develop 4D movies. The model is based on the T cell model in Royal et al. 2016. We assume different cells have similar cell shape and can be mapped to a template. This lends the model to be useful for quantitative analysis of proteins in T cells, as well as other cells. Similar to other models in CellOrganizer, there are two parts: training and synthesis. In training, a morphing model is trained from the original images. In synthesis, images of cells are synthesized from the trained model and include the protein pattern.

We have a protocol chapter that describes how the images are generated, annotated and analysized:

The usage of the model is part of the chapter (section 3.7 & 3.8)

The training part requries T cell movies and the annotation of the synapse positions of the T cells as input. It can be further broken down into the following steps: cropping, segmentation, rigid alignment, non-rigid alignment (morphing) and model-building.

The training demo included, demo3Dtcell_train, trains a protein distribution model following the approach described in

The slowest step, which takes approximately 1 min per cell per frame, is the alignment of each cell to the standardized template. This demo uses 46 cells, so it will run for about an 1 hour on a single core.

In the synthesis part, a T cell model is required as input. Should there be a specified shape to the cells, then a cell shape model is also required. The synthesis can be further broken down into the following steps: voxel sampling, shape registration, and voxel mapping.

The synthesis demo included, demo3Dtcell_synth, sythesizes from a T cell model. The demo takes in two models, one model containing the cell and nuclear shape models, and the other containing a T cell protein shape model.

Each annotation file contains the information of chosen cell pairs for a movie (each frame is a 3D stack). An example annotation file is shown below. The annotation file should be formated as described below:

  • Each row represents a cell in a specific time point. And the adjacent rows without blank row separation represents a cell in different time points. Different cells are separated with blank row(s).

  • In column 1, the name of the image file (depending on how the images are acquired, there may be one file per time point or multiple time points in a single file).

  • In column 2, the number of the channel within that file that contains the GFP fluorescence for that time point (if each time point is in a separate file, this would typically be channel 1; if multiple time points are in the same file, this would typically be the frame number).

  • In columns 3–7, the X coordinate of the left end point, the Y coordinate of the left end point, the X coordinate of the right end point, and the Y coordinate of the right end point for the synapse in that time point.

  • In column 8, the time difference for that frame relative to time point 0.

../_images/tcell_annotation_table_figure.png

Virtual Cell

The software supports saving generated geometries as valid VCML(Virtual Cell Markup Language) files that can be imported into Virtual Cell, a platform to perform biological system modeling and simulations. To do this, use the output flag

options.output.writeVCML = true;

For simple examples, investigate and run:

  • demo3D58: Generate a single framework and vesicles from a 3D HeLa ratio model and write to VCML.

  • demo3D60: Generate a single framework and vesicles from a 3D HeLa SPHARM model and write to VCML.

  • demo3D63: Generate a single framework from a 3D HeLa SPHARM model and write to VCML with a reaction network and spatial and compartmental simulations ready to be run in Virtual Cell.

For an example application that generates 100 synthetic geometries with reaction networks (as in demo3D63), writes them to individual VCML files, and combines them into one VCML file for easy import into Virtual Cell, see generate_simulation_instances_SarmaGhosh2012.

Options

The table below describes all VCML-related options. All options are fields within the options.output.VCML structure.

Options are listed as required or optional in the case that options.output.writeVCML = true; otherwise, they have no effect.

Option

Required

Description

writeVCML

required

boolean flag specifying whether to write out VCML files for use with Virtual Cell. Default is false.

input_filename

optional

string specifying Virtual Cell VCML file with biochemistry which will be combined with generated geometry in output file. Default is empty string.

downsampling

optional

downsampling fraction for the creation of object files (1 means no downsampling, 1/5 means 1/5 the size). Default is 1.

translations

optional

N x 2 cell array of strings (first column) to be replaced by other strings (second column).

Tutorials

demo3D63

demo3D63 generates a single framework from a 3D HeLa SPHARM model and writes it to VCML with a reaction network and spatial and compartmental simulations ready to be run in Virtual Cell.

Key options:

  • options.synthesis = 'framework';: The reaction network occupies only the cytoplasm and the nucleus.

  • options.output.VCML.writeVCML = true;: Instructs CellOrganizer to create a VCML output file.

  • options.VCML.downsampling = 1/2;: Reduces the size of the 3D image holding the cell, which makes the simulation run faster and reduces the storage requirements for the simulation’s results.

  • options.VCML.translations = {'cell', 'CP'; 'nuc', 'NU'; 'nucleus', 'NU'; 'lamp2_mat_tfr_mat', 'EN'; 'CP_EC', 'PM'; 'CP_EN', 'EM'; 'CP_NU', 'NM'};: Instructs CellOrganizer to translate 'cell' into 'CP', etc. so the geometry’s compartment names match those of the input VCML file.

  • reaction_network_file = '../../../data/SarmaGhosh2012ForCOdiff1e-2.vcml';, options.VCML.input_filename = reaction_network_file;: Instructs CellOrganizer to incorporate the input VCML file’s reaction network and simulations into the output VCML file.

  • options.VCML.end_time = 4000;, etc.: Set Virtual Cell simulation parameters.

Expected outputs:

  • demo3D63/cell1/cell.vcml: The VCML file to be opened in Virtual Cell.

Using the generated VCML in Virtual Cell:

  1. In Virtual Cell, select File > Open > Local... and select this file. You should see no errors or warnings listed in the Problems tab.

  2. Click img_Spatial under Applications, then Simulations, then img_Spatial_Simulation_1, then click the green triangle button to run the simulation on the Virtual Cell server. The simulation will take several hours to complete.