XitoSBML: Spatial SBML Plugin for ImageJ

XitoSBML is an ImageJ plugin which creates a Spatial SBML model from segmented images. XitoSBML is not just a converter, but also a spatial model editor so that users can add molecules(species), reactions, and advection/diffusion coefficients to the converted Spatial SBML model.

How to Install

1. Launch ImageJ (Fiji)
2. Click [Help] -> [Update...]
3. Click [Manage update sites] button on [ImageJ Updater] dialog
4. On [Manage update sites dialog], scroll down the list of update sites, turn on [XitoSBML] checkbox and press [Close] button
5. Click [Apply changes] button on [ImageJ Updater] dialog
6. ImageJ (Fiji) will download and install XitoSBML and its dependent libraries
7. Restart ImageJ (Fiji); then you will find [XitoSBML] plugin under [Plugins] menu

Here is a screencast of the above installation procedure (screencast is also available as an MP4 file).

How to Use

Convert segmented (binary) images to Spatial SBML (which contains simulation space only)

XitoSBML requires segmented images to create spatial model. Please prepare segmented images of original microscopic images beforehand. The segmented images will be obtained by using pre-built Segmentaion function in ImageJ.

1. Launch ImageJ (Fiji)
2. Load original images (not mandatory) and their segmented images
3. Click [Plugins] -> [XitoSBML] -> [run Spatial Image SBML Plugin]
4. On [DomainType Namer] dialog, assign an opened segmented image to each organelle (ex. nucleus, cytosol)
5. XitoSBML will ask whether you want to add SBML objects (Species, Reactions, and Parameters) to the converted Spatial SBML model. If you just want to convert your segmented image files to Spatial SBML, then just click [No]
6. Specify a filename of converted SBML model
7. XitoSBML will display the converted Spatial SBML document and Domain Hierarchy of your model to let you confirm the converted result
8. Exported SBML and the merged segmented image will be stored (where you specified in step 6)

Here is a screencast of the above procedure (screencast is also available as an MP4 file).

Example files

This repository also contains example 2D and 3D images and converted Spatial SBML models under examples directory. Here is a description on example files.

2D images and model

directory	filename	input or output	description
examples/2D	Rat_Hippocampal_Neuron-Nuc.tiff	input	2D segmented image of nucleus
examples/2D	Rat_Hippocampal_Neuron-Cyt.tiff	input	2D segmented image of cytosol
examples/2D	example2D.xml	output	2D spatial SBML model generated by XitoSBML
examples/2D	example2D.tiff	output	2D merged segmented image generated by XitoSBML
examples/2D	Rat_Hippocampal_Neuron-Hoechst.tiff	--	Original 2D fluroscent microscopic image of nucleus
examples/2D	Rat_Hippocampal_Neuron-NicotinicAcetylcholineAlpha7.tiff	--	Original 2D fluroscent microscopic image of cytosol

3D images and model

directory	filename	input or output	description
examples/3D	nuc-zstack.tiff	input	3D (Z-stack) segmented image of nucleus
examples/3D	cyt-zstack.tiff	input	3D (Z-stack) segmented image of cytosol
examples/3D	zstack.xml	output	3D spatial SBML model generated by XitoSBML
examples/3D	zstack.tiff	output	3D (Z-stack) merged segmented image generated by XitoSBML

Convert segmented (binary) images to Spatial SBML (as a mathematical model)

Next example will show how to create a Spatial SBML model, add SBML objects to the model, and make it as a mathematical model. The following figure represents the diagram of this example model. Note that species A and B diffuse inside the nucleus and cytosol with the given diffusion coefficients (Dnuc and Dcyt), respectively.

1. Launch ImageJ (Fiji)
2. Load original images (not mandatory) and their segmented images
3. Click [Plugins] -> [XitoSBML] -> [run Spatial Image SBML Plugin]
4. On [DomainType Namer] dialog, assign an opened segmented image to each organelle (ex. nucleus, cytosol)
5. XitoSBML will ask whether you want to add SBML objects (Species, Reactions, and Parameters) to the converted Spatial SBML model. This time, we want to add SBML objects so click [Yes]
6. In [Species] tab, add species A and B. Note that we will add species A to Nucleus and B to Cytosol
7. In [Diffusion] tab, add Diffusion coefficient for species A (Dnuc) and B (Dcyt)
8. In [Reaction] tab, add a reaction (A -> B) and its kinetic law. Please do not forget to assign reactants and products for the reaction
9. Specify a filename of converted SBML model
10. XitoSBML will display the converted Spatial SBML document and Domain Hierarchy of your model to let you confirm the converted result
11. Exported SBML and the merged segmented image will be stored (where you specified in step 9)

Here is a screencast of the above procedure (screencast is also available as an MP4 file).

You can find example 2D and 3D images and converted Spatial SBML model under examples directory.

The mathematical (spatial) model created by this example can be executed by several spatial simulators which support Spatial SBML. For example, you can use our SpatialSimulator for executing the converted model. We have provided a Docker image for SpatialSimulator so that you can easily install and run SpatialSimulator on your environment.

git clone https://github.com/funasoul/docker-spatialsim.git
cd ./docker-spatialsim/
# Copy example2D.xml to this directory
./docker-spatialsim.sh -t 0.2 -d 0.0001 -o 50 example2D.xml

SpatialSimulator will generate numbers and images of the simulation result.

Species A	Species B

How to Compile

To whom might be interested, here is an instruction on how to compile XitoSBML from source code.

Dependencies

XitoSBML requires the following third-party applications/libraries.

• JSBML
• Fiji Is Just ImageJ
• ImageJ 3D Viewer version 1.5 or higher
• Maven

Build XitoSBML

% git clone https://github.com/spatialsimulator/XitoSBML.git
% mvn install -Dimagej.app.directory=/path/to/ImageJ

For example, if you want to build XitoSBML on Fiji.app(MacOSX), the mvn command will be executed as follows:

% mvn install -Dimagej.app.directory=/Applications/Fiji.app/

Documentation

Javadocs of XitoSBML API are included under apidocs directory in the repository, and are available on our web site.

Here are the high-level key classes of XitoSBML, which will be a good starting point to read through the code.

Class	Plugin item on ImageJ
jp.ac.keio.bio.fun.xitosbml.xitosbml.MainImgSpatial.java	run Spatial Image SBML Plugin
jp.ac.keio.bio.fun.xitosbml.xitosbml.MainModelEdit.java	run Model Editor
jp.ac.keio.bio.fun.xitosbml.xitosbml.MainModelValidator.java	run Model Validation

Licensing

XitoSBML is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.