Skip to content

Latest commit

 

History

History
142 lines (113 loc) · 8.69 KB

README.md

File metadata and controls

142 lines (113 loc) · 8.69 KB
Raw

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.

XitoSBML

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). install-xitosbml

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).

example1

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.

diagram of example2

  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).

example2

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
example2 species A example2 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.

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.