OpenSSBD

OpenSSBD Database Engine - for storing and retrieving quantitative data of biological dynamics

Copyright (C) 2016 RIKEN/JST

Original contributors: Kenneth H.L. Ho, Yukako Tohsato, Koji Kyoda, Shuichi Onami

Synopsis

OpenSSBD is the open-source version of SSBD [Systems Science of Biological Dynamics] (http://ssbd.qbic.riken.jp/) database engine. This open-source version is mainly created for biologists and others for storing and retrieving quantitative data of biological dynamics.

Systems Science of Biological Dynamics (SSBD) database provides a rich set of resources for analyzing spatiotemporal dynamics of biologcial objects, such as single molecules, nuclei, and gene expressed cells. OpenSSBD provides the backend database engine for storing and retrieving quantitative biological data which can be collected from a variety of species, sources and methods. Quantitative numerical data are represented in a new Biological Dynamics Markup Language (BDML). The new data format allows users to exchange, store, compare and analyze data through the OpenSSBD database engine.

Reference

Koji Kyoda, Yukako Tohsato, Kenneth H. L. Ho, Shuichi Onami (2015), Biological Dynamics Markup Language (BDML): an open format for representing quantitative biological dynamics data. Bioinformatics 31(7): 1044-1052 http://bioinformatics.oxfordjournals.org/content/31/7/1044.

Screen shot

Motivation

SSBD (http://ssbd.qbic.riken.jp/) database was developed as an open database for storing and sharing quantitative biological dynamics data. With the rapid advance in microscopy, bioimage informatics, there is now a large amount of quantitative data on spatiotemporal dynamics of biological objects ranging from molecules to organisms.
SSBD aims to facilitate the reuse of these quantitative and imaging data for references and for further analysis.

OpenSSBD is released as open source software allowing system biology community and other interested parties to collaborate and to enhance the platform for sharing and reuse of quantitative data of biological dynamics.

Overview of OpenSSBD

• OpenSSBD is a client server based distributed web application.
• It is written in Python using Django web application framework and PostgreSQL database engine.
• RESTful API is written using Tastypie API framework for Django
• Browser based visualisation is mainly written in Javascript and uses Three.js Javascript 3D library and jQuery/jQuery-UI libraries.

Installation

There are two recommended installation methods:

Installation using a Docker image

1. Prerequisite Install docker

2. Get a copy of the image from from Docker Hub # docker run openssbd/public * This image includes OpenSSBD database engine together with 1 dataset "Quantitative information about nuclear division dynamics in wild-type embryo of C. elegans" * ref: Koji Kyoda, et al. (2013), WDDD: Worm Developmental Dynamics Database. Nucleic Acids Research 41(Database issue): D732-D737.

3. Examine the image in docker # docker images

4. Start the container - mapping and using port 8282 # docker run -i -t -p 8282:8282 openssbd/public:latest /bin/bash

5. Setting up within the container 1. Start up postgresql root@[container]:~/# /etc/init.d/postgresql start 2. Start up OpenSSBD root@[container]:~/# cd /usr/src/OpenSSBD root@[container]:/usr/src/OpenSSBD/# python manage.py runserver 0:8282

6. OpenSSBD can now be accessed by a web browser http://localhost:8282 * note: For Windows and MacOS users, you need to find out the IP address of the Docker-Machine using the command below. You can then access it on the web browser by using http://[ip address]:8282 # docker-machine ip default

[Installing on Ubuntu 14.04 Linux VM/machine.] (InstallUbuntu.md)

API Reference

1. Details of the API can be found on SSBD main web site http://ssbd.qbic.riken.jp/restfulapi/
2. Additional API specific for OpenSSBD

Summary of Additional OpenSSBD API

read_file API

• Description - Importing BDML files into OpenSSBD
• Usage: /SSBD/BDML/readfile/<filename>/
  • where filename is the name of the BDML file
  • limit to importing BDML version 0.15 format
  • e.g.

    # curl -X POST http://localhost:8282/SSBD/BDML/read_file/wt_N2_030131_01.bdml0.15.xml/
    {"details": "bdml 563d487f-1676-4159-a3ab-c25c2e198f6c is saved in the database", "error": "none"}

qdb_data API

• Description - Deleting dataset in OpenSSBD
• Usage: /SSBD/BDML/qdb_data/<bdml_id>/
  • it requires a DELETE http function
  • where bdml_id is the internal ID of the dataset
  • It may not cleanly delete data when there is importing error
  • e.g.

    # curl -X DELETE http://localhost:8282/SSBD/BDML/qdb_data/1/

vertices API

• Description - Retrieving coordinates from OpenSSBD for displaying on a web browser
• Usage: /SSBD/BDML/vertices/<bdml_id>/t/<time pt>/etype/<entity type>/
  • where bdml_id is the internal ID of the dataset
  • time pt is the data related to the specific time point
  • entity type is the type of entity which one wants to retrieve, point, sphere and line. Face is not supported yet.
  • e.g. retrieving BDML internal ID=1 at time point=10 and enitity type=line

    http://localhost:8282/SSBD/BDML/vertices/1/t/10/etype/line/

* It will always return in JSON format with a key _vertices_ and a list of coordinates with its component and entity ids

    { vertices : [entity_id, coordinates_id, x, y, z, t, ... ] }

Importing BDML files into OpenSSBD

• Create a directory in /tmp/bdml

  # mkdir -p /tmp/bdml

• Copy the bdml files to the /tmp/bdml directory, e.g.

  # cp wt_N2_030131_01.bdml0.15.xml /tmp/bdml

• Call read_file API, e.g.

  # curl -X POST http://localhost:9292/SSBD/BDML/read_file/wt_N2_030131_01.bdml0.15.xml/
    {"details": "bdml 563d487f-1676-4159-a3ab-c25c2e198f6c is saved in the database", "error": "none"}

• Find the bdml internal ID number using bdml API, e.g.

  http://dhcp20-193.cdb.riken.jp:8282/SSBD/api/v1/bdml/?format=xml;bdml__bdml_ID__icontains=563;

• Result:

<response>
<objects type="list">
<object>
<bdml_ID>563d487f-1676-4159-a3ab-c25c2e198f6c</bdml_ID>
<id type="integer">1</id>
<title>
BDML file for quantitative information about nuclear division dynamics of wild-type embryo
</title>
</object>
</objects>
<meta type="hash">
<next type="null"/>
<total_count type="integer">1</total_count>
<previous type="null"/>
<limit type="integer">20</limit>
<offset type="integer">0</offset>
</meta>
</response>

• Update the root table via SQL function schemaupdate4 together with the internal ID number
  • e.g.

psql -h localhost -U postgres -d "SSBD" -c "select schemaupdate4(1);"
NOTICE:  Inserted 1 into SSBD2_meta_data_model
NOTICE:  Inserted 1 into SSBD2_quant_data_model
NOTICE:  Inserted 1 into SSBD2_scaleunit_data_model
NOTICE:  Inserted 1 into SSBD2_bml_multipart_model
NOTICE:  Inserted 1 into SSBD2_root_data_model
 schemaupdate4 
---------------
             1
(1 row)

• Update the unicoords table via SQL function unicoords - it fills in the entries by calculating all the coordinates in micrometers.
  • e.g.

# psql -h localhost -U postgres -d "SSBD" -c "select unicoords(1);"
NOTICE:  Starting to insert 1 into SSBD
NOTICE:  Inserted 1 into SSBD
 unicoords 
-----------
         1
(1 row)

• Updating statistical table via function genstats
  • e.g.

# psql -h localhost -U postgres -d "SSBD" -c "select genstats(1);"
NOTICE:  Starting to insert stats 1 into SSBD
NOTICE:  Inserted stats 1 into SSBD
 genstats 
----------
        1
(1 row)

Differences between OpenSSBD and SSBD

• Although SSBD is currently running on RHEL servers, OpenSSBD is built on top of Ubuntu 14.04 Linux.
• It does not include OMERO image database. Users will need to install OMERO separately. (see https://www.openmicroscopy.org/site for more details)
• Functions are limited to
  • Importing BDML 0.15 files including data types for points, lines and spheres, but not face.
  • Importing BDML files does not support multi-part BDML files
  • Browser visualisation is limited to single time-point viewer as multiple time point viewer requires special manually tweeted optimizations
  • CSS style file is not included as it contains 3rd parties copyright material.
• read_file API is included in OpenSSBD for importing BDML files.
  • It is not available to the public on SSBD. It is a privileged function to import BDML files into SSBD.

Known issues

• Importing data is done manually through command line.
• There is only a limit basic function to delete a dataset and may need to manually remove entry from the SQL DB.
• Function to update a dataset is not provided. This is due to fact that any change to a BDML file would require creating a new unique BDML file with a unique BDML_ID. Instead there is a provision in SQL table to label a dataset status, e.g. available, error, etc.
• Although there is a provision in the root table to allow different meta information to be stored without re-importing the same dataset, data has to be updated manually.
• There is no automated function to input or update the location of the BDML files. Those data have to be input manually into the SQL tables.

Contributors guide

• Please feel free to fork, enhance/modify OpenSSBD. We look forward to hearing from you and together we hope to share new ideas and collaborate in new projects using OpenSSBD.
• If you find any bugs, or questions, please submit and open an Issue.

Acknowledgment

This work has been partly supported by National Bioscience Database Center (NBDC) of Japan Science and Technology Agency (JST).

License

Copyright (C) 2016 RIKEN/JST

GNU GENERAL PUBLIC LICENSE Version 3 (GPLv3.0)

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>