Update in v1.0.1 (2020 summer)

• Maintain the compatibility with HiView, which has improved significantly after the original DDOT publication
• A new script (tohiview.py) and a tutorial of uploading to HiView server has been added
• Running CliXO 0.3, CliXO 1.0 and alignOntology from DDOT is not longer supported (in order to make this package lighter and more "Pythonic"). Please visit the original repositories of these programs.
• We only tested new content with Python >=3.6, as Python 2 has been declared obsoleted.

New dependencies:

• ndex2-client

The Data-Driven Ontology Toolkit (DDOT)

The Data-Driven Ontology Toolkit (DDOT) facilitates the inference, analysis, and visualization of biological hierarchies using a data structure called an ontology.

• Open-source Python package under MIT license. Supports Python 2.7 or >=3.6.
• The HiView web application visualizes hierarchical structure and the biological evidence for that structure.

Documentation

For a quick start on DDOT's functionality, please see the tutorial and other Jupyter notebooks in the examples folder.

For further documentation, please see http://ddot.readthedocs.io/. This includes a description of the Ontology class and a list of utility functions.

Please post questions or issues to the Google Groups forum.

Installation

DDOT requires the following software

• Python v2.7 or >=3.6
• numpy
• scipy
• pandas>=0.24
• networkx=1.11. Note that networkx>=2.0 is incompatible with ddot.
• python-igraph. Recommend installing through anaconda or pip.
• ndex-dev. Recommend installing through pip.
• tulip-python. Recommend installing through pip.

The recommended method for installing these dependencies is to use the Anaconda distrubution of Python, and then install Python packages via the conda and pip repositories.

# Create and activate a virtual environment (optional, but recommended).
# Learn more about virtual environments at https://conda.io/docs/user-guide/tasks/manage-environments.html
conda create -n <environment_name>
source activate <environment_name>
 
# Install dependencies
conda install -y pandas numpy scipy networkx=1.11
conda install -y -c conda-forge python-igraph
conda install -y libiconv # Needed for igraph to run properly
pip install tulip-python
pip install ndex-dev

Install the ddot Python package

After dependencies are satisfied, download or clone this repository

git clone https://github.com/[Host_username]/ddot.git

Install ddot using pip. If you are installing within a conda virtual environment, remember to enter the environment with source activate <environment_name> before running pip.

pip install /path/to/ddot_repository

Known installation problems and tips

• Older versions of Anaconda (<= v4.5) might not install the dependencies correctly. Consider updating Anaconda to the newest version by running conda update conda (outside of a virtual environment).
• Make sure that no other local installations of Python is conflicting with Anaconda. In particular, check that the directory $HOME/.local/lib does not contain Python packages. If it does contain Python packages, check that those packages are not being imported.
• If ddot does not import successfully in a Python terminal, first check that the dependencies can be imported. In particular, check that import ndex, networkx, igraph, tulip, numpy, scipy, pandas works.
• Please raise any other installation problems as an issue on this github repo.

Docker image (v1.0)

A Docker image of DDOT is located online at Docker Hub. To learn more about Docker, see https://docs.docker.com/get-started/

Download and run image from Docker Hub

For Python 3.6,

# Download image installed with DDOT in anaconda3 (Python 3.6)
docker pull michaelkyu/ddot-anaconda3
# Run image in a container
docker run -it -p 8888:8888 michaelkyu/ddot-anaconda3

For Python 2.7,

# Download image installed with DDOT in anaconda2 (Python 2.7)
docker pull michaelkyu/ddot-anaconda2
# Run image in a container
docker run -it -p 8888:8888 michaelkyu/ddot-anaconda2

Using DDOT in Docker

After running the image, you will be inside the container's command line. Here, you can run DDOT in a basic Python terminal

(base) root@<container>:/$ python

Python 2.7.14 |Anaconda, Inc.| (default, Dec  7 2017, 17:05:42) 
[GCC 7.2.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import ddot

Alternatively, you can run DDOT in example Jupyter notebooks. To do so, start a Jupyter server in the container's command line

(base) root@<container>:/$ jupyter notebook --no-browser --allow-root --ip 0.0.0.0 --NotebookApp.token=''

Next, open up your web browser and access the notebooks at http://0.0.0.0:8888/. We recommend starting with the tutorial Tutorial.ipynb.

Citing DDOT

If you find DDOT helpful in your research, please cite

Michael Ku Yu, Jianzhu Ma, Keiichiro Ono, Fan Zheng, Samson H Fong, Aaron Gary, Jing Chen, Barry Demchak, Dexter Pratt, Trey Ideker. "DDOT: A Swiss Army Knife for Investigating Data-Driven Biological Ontologies". Cell Systems. 2019 Mar 27;8(3):267-273.