• Stars
    star
    2,659
  • Rank 17,192 (Top 0.4 %)
  • Language
    Python
  • License
    MIT License
  • Created almost 12 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Repository for the main Dockerfile with the OpenWorm software stack and project-wide issues

OpenWorm

Docker Image CI

About OpenWorm

OpenWorm aims to build the first comprehensive computational model of Caenorhabditis elegans (C. elegans), a microscopic roundworm. With only a thousand cells, it solves basic problems such as feeding, mate-finding and predator avoidance. Despite being extremely well-studied in biology, a deep, principled understanding of the biology of this organism remains elusive.

We are using a bottom-up approach, aimed at observing the worm behaviour emerge from a simulation of data derived from scientific experiments carried out over the past decade. To do so, we are incorporating the data available from the scientific community into software models. We are also forging new collaborations with universities and research institutes to collect data that fill in the gaps.

You can earn a badge with us simply by trying out this package! Click on the image below to get started. OpenWorm Docker Badge

Quickstart

We have put together a Docker container that pulls together the major components of our simulation and runs it on your machine. When you get it all running it does the following:

  1. Run our nervous system model, known as c302, on your computer.
  2. In parallel, run our 3D worm body model, known as Sibernetic, on your computer, using the output of the nervous system model.
  3. Produce graphs from the nervous system and body model that demonstrate its behavior on your computer for you to inspect.
  4. Produce a movie showing the output of the body model.

Example Output

Worm Crawling

NOTE: Running the simulation for the full amount of time would produce content like the above. However, in order to run in a reasonable amount of time, the default run time for the simulation is limited. As such, you will see only a partial output, equivalent to about 5% of run time, compared to the examples above. To extend the run time, use the -d argument as described below.

Installation

Pre-requisites:

  1. You should have at least 60 GB of free space on your machine and at least 2GB of RAM
  2. You should be able to clone git repositories on your machine. Install git, or this GUI may be useful.

To Install:

  1. Install Docker on your system.
  2. If your system does not have enough free space, you can use an external hard disk. On MacOS X, the location for image storage can be specified in the Advanced Tab in Preferences. See this thread in addition for Linux instructions.

Running

  1. Ensure the Docker daemon is running in the background (on MacOS/Windows there should be an icon with the Docker whale logo showing in the menu bar/system tray).
  2. Open a terminal and run: git clone http://github.com/openworm/openworm; cd openworm
  3. Optional: Run ./build.sh (or build.cmd on Windows). If you skip this step, it will download the latest released Docker image from the OpenWorm Docker hub.
  4. Run ./run.sh (or run.cmd on Windows).
  5. About 5-10 minutes of output will display on the screen as the steps run.
  6. The simulation will end. Run stop.sh (stop.cmd on Windows) on your system to clean up the running container.
  7. Inspect the output in the output directory on your local machine.

Advanced

Arguments

  • -d [num] : Use to modify the duration of the simulation in milliseconds. Default is 15. Use 5000 to run for time to make the full movie above (i.e. 5 seconds).

Other things to try

  • Open a terminal and run ./run-shell-only.sh (or run-shell-only.cmd on Windows). This will let you log into the container before it has run master_openworm.py. From here you can inspect the internals of the various checked out code bases and installed systems and modify things. Afterwards you'll still need to run ./stop.sh to clean up.
  • If you wish to modify what gets installed, you should modify Dockerfile. If you want to modify what runs, you should modify master_openworm.py. Either way you will need to run build.sh in order to rebuild the image locally. Afterwards you can run normally.

FAQ

What is the Docker container?

The Docker container is a self-contained environment in which you can run OpenWorm simulations. It's fully set up to get you started by following the steps above. At the moment, it runs simulations and produces visualizations for you, but these visualizations must be viewed outside of the Docker container. While you do not need to know much about Docker to use OpenWorm, if you are planning on working extensively with the platform, you may benefit from understanding some basics. Docker Curriculum is an excellent tutorial for beginners that is straightforward to work through (Sections 1 - 2.5 are plenty sufficient).

Is it possible to modify the simulation without having to run build.sh?

Yes, but it is marginally more complex. The easiest way is to modify anything in the Docker container once you are inside of it - it will work just like a bash shell. If you want to modify any code in the container, you'll need to use an editor that runs in the terminal, like nano. Once you've modified something in the container, you don't need to re-build. However, if you run stop.sh once you exit, those changes will be gone.

How do I access more data than what is already output?

The simulation by default outputs only a few figures and movies to your home system (that is, outside of the Docker container). If you want to access the entire output of the simulation, you will need to copy it from the Docker container.

For example, say you want to extract the worm motion data. This is contained in the file worm_motion_log.txt, which is found in the /home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt. The directory [SPECIFIC_TIMESTAMPED_DIRECTORY] will have a name like C2_FW_2018_02-12_18-36-32, and its name can be found by checking the output directory. This is actually the main output directory for the simulation, and contains all output, including cell modelling and worm movement.

Once the simulation ends and you exit the container with exit, but before you run stop.sh, run the following command from the openworm-docker-master folder:

docker cp openworm:/home/ow/sibernetic/simulations/[SPECIFIC_TIMESTAMPED_DIRECTORY]/worm_motion_log.txt ./worm_motion_log.txt

This will copy the file from the Docker container, whose default name is openworm. It is crucial that you do not run stop.sh before trying to get your data out (see below)

What is the difference between exit and stop.sh?

When you are in the Docker Container openworm, and are done interacting with it, you type exit to return to your system's shell. This stops execution of anything in the container, and that container's status is now Exited. If you try to re-start the process using run-shell-only.sh, you will get an error saying that the container already exists. You can choose, at this point, to run stop.sh. Doing so will remove the container and any files associated with it, allowing you to run a new simulation. However, if you don't want to remove that container, you will instead want to re-enter it.

How do I enter a container I just exited?

If you run stop.sh you'll delete your data and reset the container for a new run. If, however, you don't want to do that, you can re-enter the Docker container like this:

docker start openworm                 # Restarts the container
docker exec -it openworm /bin/bash    # Runs bash inside the container

This tells Docker to start the container, to execute commands (exec) with an interactive, tty (-it) bash (bash) shell in the container openworm.

You'll be able to interact with the container as before.

Documentation

to find out more about OpenWorm, please see the documentation at http://docs.openworm.org or join us on Slack.

This repository also contains project-wide tracking via high-level issues and milestones.

More Repositories

1

sibernetic

This is a C++/OpenCL implementation of the PCISPH algorithm supplemented with a set of biomechanics related features applied to C. elegans locomotion
C
354
star
2

org.geppetto

Geppetto is an open-source platform to build web-based applications to visualize and simulate neuroscience data and models.
Python
209
star
3

owmeta

Unified, simple data access python library for data & facts about C. elegans anatomy
Python
152
star
4

CElegansNeuroML

NeuroML based C elegans model, contained in a neuroConstruct project, as well as c302
Jupyter Notebook
134
star
5

c302

The c302 framework
Python
68
star
6

wormbrowser

The Worm Browser -- a 3D browser of the cellular anatomy of the c. elegans
JavaScript
49
star
7

open-worm-analysis-toolbox

A testing pipeline that allows us to run a behavioural phenotyping of our virtual worm running the same test statistics the Schafer Lab used on their worm data.
Python
48
star
8

muscle_model

Model of C elegans body wall muscle based on Boyle & Cohen 2008
Jupyter Notebook
47
star
9

openworm_docs

Documentation for OpenWorm, i.e. docs.openworm.org
Python
44
star
10

hodgkin_huxley_tutorial

A repository containing code for a number of tutorials on the Hodgkin Huxley model, including an interactive Jupyter notebook
Python
36
star
11

bionet

Artificial biological neural network
C++
31
star
12

CyberElegans

Neuromechanical model of C. Elegans
C++
31
star
13

org.geppetto.frontend

Geppetto Java frontend bundle
Java
29
star
14

robots

C. elegans robots
C
24
star
15

openworm.github.io

OpenWorm main website
HTML
24
star
16

org.geppetto.core

Geppetto core bundle
Java
23
star
17

openwormbrowser-ios

OpenWorm Browser for iOS, based on the open-3d-viewer, which was based on Google Body Browser
Objective-C
22
star
18

Blender2NeuroML

Conversion script to bring neuron models created in Blender into NeuroML format
Python
17
star
19

pygeppetto

Python Library to create, load, edit and save a Geppetto Model
Python
14
star
20

ChannelWorm

Tools and curated datasets to build quantitative models of C. elegans ion channels
JavaScript
12
star
21

tracker-commons

Compilation of information and code bases related to open-source trackers for C. elegans
Scala
11
star
22

ChannelWorm2

Tools and curated datasets to build quantitative models of C. elegans ion channels
Jupyter Notebook
10
star
23

org.geppetto.model.neuroml

NeuroML Model Bundle for Geppetto
Java
9
star
24

org.geppetto.simulation

Generic simulation bundle for Geppetto
Java
9
star
25

org.geppetto.solver.sph

PCI SPH Solver bundle for Geppetto
Java
9
star
26

skeletonExtraction

Transforms Sibernetic output into a COLLADA animation
C++
7
star
27

WormWorx

C. elegans simulator
C
6
star
28

behavioral_syntax

behavioral syntax analysis based on the paper of Andre Brown
Jupyter Notebook
5
star
29

movement_cloud

Movement Analysis on the cloud
Python
5
star
30

SegWorm

SegWorm is Matlab code from Dr. Eviatar Yemini built as part of the WormBehavior database (http://wormbehavior.mrc-lmb.cam.ac.uk/)
MATLAB
5
star
31

org.geppetto.frontend.jupyter

Geppetto Jupyter Notebook Extension
Python
5
star
32

sibernetic_NEURON

Interface between Sibernetic and NEURON simulator
Python
5
star
33

org.geppetto.sibernetic

PCI SPH Model Bundle for Geppetto
Java
5
star
34

org.geppetto.recording

Python project allowing to create a recording for Geppetto
Python
5
star
35

neuronal-analysis

Tools to produce, analyse and compare both simulated and recorded neuronal datasets
Jupyter Notebook
4
star
36

OpenData

Repo for Google Summer of Code Open Data Project 2019
Jupyter Notebook
4
star
37

org.geppetto.docs

Repository to host Geppetto documentation
Python
4
star
38

org.geppetto.simulator.sph

SPH Simulator bundle for Geppetto
Java
4
star
39

sibernetic_config_gen

Generates starting scene configuration for the Sibernetic simulation engine
Python
4
star
40

geppetto-client

The web client of a Geppetto application
JavaScript
4
star
41

org.geppetto.simulator.jlems

jLEMS based simulator for Geppetto
Java
3
star
42

YAROM

Yet Another RDF-Object Mapper
Python
3
star
43

OpenWormData

TeX
3
star
44

org.geppetto.model.swc

SWC Model Interpreter for Geppetto
Java
3
star
45

org.geppetto.model

Java
3
star
46

HeuristicWorm

C++
3
star
47

org.geppetto.maven

Maven repository for Geppetto
3
star
48

org.geppetto.simulator.external

Geppetto bundle to add support for external neuronal simulators (NEURON, etc.)
Python
3
star
49

owmeta-core

Core library for owmeta
Python
3
star
50

org.geppetto.model.nwb

Java
3
star
51

geppetto-application

Sample Geppetto application
JavaScript
3
star
52

WormsenseLab_ASH

Electrophysiological recordings of neuron ASH from Wormsense Lab
Jupyter Notebook
3
star
53

NeuroPAL

Some tests on using the NeuroPAL datasets
Jupyter Notebook
3
star
54

org.geppetto.samples

Sample simulations for Geppetto
JavaScript
3
star
55

pharyngeal_muscle_model

C. elegans pharyngeal muscle cell (pm3) model, capable of generating Ca2+ slow action potential (NEURON, NMODL).
C
3
star
56

tests

OpenWorm tests across various repos
Jupyter Notebook
3
star
57

org.wormsim.frontend

WormSim frontend bundle
JavaScript
3
star
58

owmeta-movement

DataSources and utilities for movement data in OpenWorm
Python
2
star
59

org.geppetto.persistence

Persistance bundle for Geppetto
Java
2
star
60

org.geppetto.templatebundle

Java
2
star
61

org.geppetto.datasources

Java
2
star
62

JohnsonMailler_MuscleModel

C. elegans muscle model from Johnson & Mailler 2015
HTML
2
star
63

org.geppetto.simulator.libroadrunner

libRoadRunner simulator bundle for Geppetto
Java
2
star
64

owmeta-modeldb

Python
2
star
65

openworm-scholar

A service providing enhanced notifications of published research in Open Worm
Python
2
star
66

org.geppetto.bower

Geppetto repository for packaged bower components
JavaScript
2
star
67

org.geppetto.testbackend

Java
2
star
68

owmeta-bundles

Bundles for owmeta
2
star
69

org.wormsim.bower

Wormsim repository for packaged bower UI components
2
star
70

owmeta-pytest-plugin

Pytest plugin for testing with owmeta-core
Python
2
star
71

worm-math-book

An online book focusing on the mathematical concepts and models of the OpenWorm project.
Jupyter Notebook
2
star
72

owmeta-sciunit

owmeta types for SciUnit and NeuronUnit
Python
2
star
73

org.geppetto.frontend.nodejs

Geppetto Node.js backend
JavaScript
2
star
74

jenkins

Groovy
1
star
75

multi-dev-sibernetic

Multi devices sibernetic engine
C++
1
star
76

.github

The OpenWorm organisation template repository.
Python
1
star
77

bt-gsoc-2019

End to end process of the Framework including a BitTorrent Client, Access Control and Data Integrity checks.
Python
1
star
78

Newsletter

A repository containing a newsletter with regular OpenWorm updates
1
star
79

owmeta-core-data

owmeta repository for the owmeta-core schema
1
star