openworm / channelworm

Tools and curated datasets to build quantitative models of C. elegans ion channels

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.

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

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.

channelworm's Issues

Decide what Capabilities our Model(s) will have

Background

SciUnit uses Capabilities to interface between Models and Tests.

In this example, the Capability ProducesNumber describes the method(s) that Models like UniqueRandomNumberModel must implement in order to "have" the Capability.

Models that have all the Capabilities listed in a Test's required_capabilities can be run in that Test. This ensures that, when running a Suite, Tests only run on Models that make sense (i.e. that are relevant to the test).

Code

Now the question seems to be: which methods do we need Models to implement in order to be relevant to a given Test.

This code will mostly be method headers, followed by docstrings that describe what the method should do when implemented. There is a lack of method bodies because implementing a given method is left up to the Model that has the Capability.

This will be developed in tandem with writing Tests, which is tracked in a separate issue (#32).

@gsarma

Create Generates_IV_Curve Capability

This was discussed in #29, and will serve as an example for the rest of the tests to follow.

@gsarma and I will discuss this in our next meeting (Saturday).

Collect data for voltage-dependent ion channels

Collect data for these voltage-gated/calcium-activated ion channels with priority of expression in muscle cells and motor neurons:

• Voltage-gated calcium channels (VGCC): EGL-19 (Cav1: L-type), UNC-2 (Cav2: R, N, P/Q-Type), and CCA-1 (Cav3: T-Type)
• Voltage-gated potassium channels: SHK-1 (Shaker, Kv1), EXP-2 (Shab, Kv2), EGL-36 (Shaw, Kv3) and SHL-1 (Shal, Kv4)
• Calcium-activated Slo-like potassium channels: SLO-1, SLO-2

For Kv1, Kv4, and Cav1, data and related models are available, we just need to insert the parameters into the PyOW.

Develop validation test template

The template will be used to make it easier for contributors to create tests.

Implementation will be similar to the drawing below:

These are the steps building the template will require (may be modified as we move forward):

• Set up unit testing framework (SciUnit or NeuronUnit)
• Set up model imports (i.e. Grab channel models)
• Set up two example data imports (one for data tables, one for patch clamp data)
• Integrate with Travis CI

Using standards for current and voltage waveforms, and analysis

Are we going to use standards like NEO to represent and process our waveforms, or just use arrays or tuple of arrays to represent them?

Are we going to use emerging standards like ElePhanT to do the actual calculations (e.g. compute the mean of or counts spikes in a segment of membrane potential), or roll our own?

Add ion channel object and related data to the PyOpenWorm

@travs, Here is my proposed scheme:

• Every cell has 0-n ion channel with these properties:
  • membrane capacitance
  • cell surface area
  • internal ion concentration
• Every ion channel has 0-n model with these properties:
  • references
  • contributors identity
  • experiment's condition properties, like temperature, age of the organism, etc
  • channel properties: rev potential, ion type, ligand ion types, activation/inactivation type and related parameters
• Every ion channel has also genetic, etc properties independent of the model. required ones, could be inserted into the PyOW from this spreadsheet and others, could be represented by calling WormBase APIs!
• Also these data could be included:
  • ion channel's known mutants (that could be a child of the main ion channel table)
  • ion channel-related diseases (channelopathies) with refs
• Cell-channel relation
  • channel density specific to the cell type
  • specific capacitance
• There is a synapse between two cells that has properties like ion concentration, ion decay time, etc. This could be helpful (for the simulation purposes)
• SI units, that could be retrieved from here.

We can start with properties in this script for the prototype schema and then improve it using NeuroML components (e.g. cells, channels, etc)

As for the channel naming, I suggest using subfamilies (e.g. Kv1, etc).

Also, for most of these properties we need to include references, from which data extracted, that I guess we can handle it via RDF supported in the PyOW, but I'm not sure what's the best way to implement it.

In addition, we need another DB for specific data in this project (which I'll cover it via another issue)

Make digitized and simulated I/V data comparable

Problem

In order to be able to write validation tests that use patch clamp data, we need to be able to compare our simulated data with the observed data. I have a short description of the two data types below.

Simulated

We can use jNeuroML to generate .dat files from our own LEMS simulation files (.xml).

• Example (this python script creates the .dat files)
• Example (this shell script generates the .dat files using the above script, then makes plots from them)

Observed

We get back .csv files after running plots from the literature through WebPlotDigitizer.

• Example (click "data")

Implement existing SciUnit Capabilities

Over here we have some Capabilities enumerated as stubs, but not yet implemented.

@rgerkin

Decide on front end/user interface

Some brainstorming questions I have are:

1. What will the page look like?
2. How will the data be displayed?
3. Will the user be able to interact with the data? How so?

Let me know what you guys are thinking about each of these, and if there are any other questions you have about the front-end.

Insert created methods in a SciUnit file

@gsarma and I will create methods for the Tests and Capabilities of our Model.

@rgerkin agreed to help put these in a form SciUnit can understand.

Create stub for I/V Curve-producing model

We can begin creating a skeleton for an ion channel Model that will be used in SciUnit tests.

This will implement the Capabilities we have already enumerated (#41)

Needed for #27 to move forward (imports)

Design a software platform and put needed entities together

Create a software platform diagram and put together entities of the project.

Find a permanent cloud deployment service for the web app

Ideally we want as little downtime as possible.

Currently, we will deploy to OpenShift, but their basic plan has a "sleeping" period that takes a few seconds to wake from, so it will be less convenient when we want to send requests to this server if we go with that.

@joebowen mentioned resource grants that openshift offers, and that would be an awesome way to get a better service from them.

There may be other PaaS that provide similar services to OpenShift but with less/no downtime.
I'm not sure of the capabilities of any of these, but they may be worth checking into:

• PythonAnywhere
• Google App Engine
• Heroku

Get a Django web app online

This may already be fulfilled by this link, but it won't load for me :(

Adapt web app ion channel models to interface with PyOpenWorm models

The models for ion channels in the web app need to be the same as those in PyOpenWorm.

Gitter discussion

Make ChannelWorm Gitter channel

Hi Vahid! :)

Just putting an issue here in case we want to make a channel soon. I don't think I can do it since it is your own repo.

Looking forward to working with you on this!

Build a pipeline for modeling ion channels with patch-clamp data available

Develop a toolkit for digitization, fitting and optimization of HH models from patch-clamp experiments:

• Look for a patch clamp study, extract data, and digitize needed figures as a case study (using WebPlotDigitizer + Plotly)
• Fit parameters, and simulate the experiment using some GA and ODE algorithm (use/customize Neurotune+Pyelectro where needed)
• Readjust parameters if needed and optimize the model to find the best fit
• Get plots + NeuroML2 outputs
• Validate the model (using OSB model validation, and Sciunit+Neuronunit, and Travis CI)
• Document the process

Storage method of biological information for ion channels

The initial source of data for biological properties of ion channels is this spreadsheet which is obtained from WormBase.
In order to better structure and represent these biological data via ChannelWorm, we need to store (at least important ones) in a DB (preferably PyOW). but there is the problem of updating and synchronization with WormBase.
Two options are:

• Storing all the data in a DB and developing a scheduler to keep data up-to-date
• Just store important IDs and links and represent data by calling WormBase APIs

Model validation

For model validation, based on discussions from here:

"Validation framework is here: https://github.com/OpenSourceBrain/osb-model-validation. Best way to get a feel for this is to clone & install that and try one of the OSB models locally, e.g. https://github.com/OpenSourceBrain/MorrisLecarModel and run: omv all, to run all the tests. See the .test* files for the tests to perform, e.g. https://github.com/OpenSourceBrain/MorrisLecarModel/blob/master/NeuroML2/.test.jnml.w.omt and the MEP files for the Model emergent properties to compare against: https://github.com/OpenSourceBrain/MorrisLecarModel/blob/master/NeuroML2/.test.mep"

Also, it is possible to implement unit tests using sciunit + neuronunit

Sync the patch-clamp app GUI with django's patch-clamp data model

The user interface in the patch-clamp part of the web app will have a form for entering data.

This form should be automatically generated from the data models that django uses, rather than manually syncing the GUI whenever the underlying data structure is changed.

In fact, this should be done for all parts of the web app, so we can raise those issues when we have this one resolved.

Duplicate (ignore)

Augment models with metadata

Add metadata to the PyOpenWorm channelworm API and NeuroML files:

• For annotation, it is possible to add RDF based annotations to NeuroML files. ex 1, ex 2, ref
• Also we should add the modeler/contributors' name to the model/file

Difficulties in digitization of figures with no usual axes

Some figures like this:

Having unclear axes. There are three issues regarding this problem:

1. Webplotdigitizer has no capability to calibrate axes in this way (with both x and y)
2. It's not clear what is the range of values (e.g. current in this picture)
3. It's not clear what is the clamped voltage for each trace in a figure like this

What can we do when digitizing these kind of figures, to evaluate candidate models in the fitting/optimization process?

Find a method of alerting new publications about ion channels of interest

In order to being aware of new publications about patch clamp experiments, new biological studies related to ion channels in C. elegans, etc in an automatic way, we need a procedure (something like a RSS feed reader with text mining abilities!). then we can augment it by some alerting (mailing) system.

Which parameters will be used for fitting?

It looks like NeuroTune will be sufficient for our purposes of tuning the ion channel models towards their observed counterparts.

Since there may be multiple sorts of validation tests beyond IV curve comparison, we should talk about which parameters will be tuned on the ion channels.

Parameters that are intrinsic to the ion channel model itself are eluding me, since so much of their kinetics is determined by their context.

Decide on cost function/evaluation to apply when comparing I/V curves

We need some metric that returns a single value indicating how well a particular modeled I/V curve fits the expected observed I/V curve.

@VahidGh mentions:

In my implementations, I've considered the cost function for evaluating I/V cures, as sum of the squared distances between the sample and simulated points divided by the number of points and trying to minimize this.
I was thinking about storing a normalized version of this measurement and comparing with other models.
How is this different from the approach is going to be taken by the SciUnit?

What statistics should we apply in order to get this value?

Note that this is of lower priority than implementing a placeholder cost function that works

Ion Channel data model

This data model would encompass things which are not specific to a single model of an ion channel, but are relevant to the ion channel itself.

As per #7, this should include things like:

• Ion channel's subfamily name
• Genetic properties (mutants, genome, etc.)
• Channelopathies

As with #11, don't hesitate to suggest additions to this data model, as it will surely be added to/changed as we progress.

Make ChannelWorm introduction document

Use readthedocs and Sphinx to make a document for a description of the project, tasks, refs, etc.

Create stub for IV Curve test

I think we can start creating the tests that will compare simulated and actual IV curve data.

We can begin by making a skeleton for our tests that will be fleshed/implemented out later.

@gsarma @rgerkin

Related to #27

Implement prototypical acceptable range calucations in SciUnit Tests

There are not yet any Tests to perform acceptable range calculations on, but the need will surely arise with the use of any kind of complex statistical test.

This is distinct from #36 in that the results are not binary passes/fails, but a warning system to tell us when a Model's results are suspicious and should be investigated.

cc: @rgerkin @slarson @gsarma

Cell data model

Quoting @VahidGh

Every cell has 0-n ion channel with these properties:

• membrane capacitance
• cell surface area
• internal ion concentration

We have had some discussion about this in #7, but it would be good to define this problem more clearly here.

There exists a Cell data model in PyOpenWorm already, though it does not include any of the parameters Vahid listed above.

To summarize the discussion as I understand it:

1. Since they are important to modelling and simulating ion channels, we need these cell parameters stored somewhere.
2. Since the parameters are cell parameters, they should be stored along with the cell data model.
3. Since the parameters are dynamic, we will just store the initial states in the database.

Now, as Vahid mentions, these properties differ from cell to cell, so the data model should accommodate for this.
PyOpenWorm (at least on the main branch) attempts to reconstruct the organism's anatomical data one-to-one (i.e. every cell in the organism (ex: ADAL or P11) has an entry as a Cell in the db).
My question is whether the cellular data useful for ion channel modelling (ex: surface area) is specific enough to include in this type of cataloging db. Surely cell surface area differs for ADAL (or any particular cell) between organisms.

If this is the case, then our cell models will differ from those in the main PyOpenWorm branch, but this is not a problem, just something I will have to keep in mind.

If this is not clear don't hesitate to ask what the heck I'm talking about 😛

Where should we implement SciUnit Capabilities?

After discussions with @gsarma, it became apparent that there are currently two "representations" of the model, one to do with the database (PyOpenWorm), the other written NeuroML2.

When implementing a Capability like Generates_IV_Curve, where should the implemented methods go?

It would not be appropriate to implement the python methods in the NeuroML2 file, but the database does not seem like the correct place either. Should there be a third representation of the model (a .py file/class) that holds the implemented methods?

What do you guys think?
@slarson @VahidGh @rgerkin

Update documentation

• Walkthrough (mostly stubs for now) for digitization process described in this diagram
• Text description of digitization diagram
• Walkthrough for the validation and optimization stages including what we can do so far, and what gaps remain.

Install PyOpenWorm as a library rather than include it as a submodule

This can be done with

pip install git+https://github.com/openworm/PyOpenWorm.git@channelworm

Expand list of figures to include 7 I/V curves and 7 I/t plots

We have a spreadsheet that we need to populate with figures that need to be digitized. There is a folder of ion channel papers. We should go paper by paper and add figures into the spreadsheet from here.

Decide on generic API for model layer

In gitter chat @miladjafary raised the issue of having just one abstract layer to communicate with the other layers of this project, which means that our data layer will need to have some kind of API to allow access to it.

Milad, can you give some suggestions of what we need in this data API?

It will have to communicate with PyOpenWorm, certainly.

I am not sure what you mean, Milad, when you say generic API, and how this would be different from the API that exists for PyOpenWorm already. Are these the same? If not could you explain what you mean so I can get a grasp and help define the API that will unite the data layer with the abstract access layer?

Automatically grab latest version of PyOpenworm channelworm branch

Right now I have to manually commit the new version of the PyOepnWorm submodule. It would be nice to have this happen whenever PyOpenWorm is updated, but this is low priority right now.

Include branch of PyOpenWorm as submodule

The idea here is to create a branch of PyOpenWorm that has a data model for ion channel and other data that would be convenient for ChannelWorm's purposes (ex: SI unit).

The changes made to the PyOpenWorm ChannelWorm branch should be forward-compatible with PyOpenWorm. In other words, they should be merged into the master branch of PyOpenWorm further down the road, and any additions should keep this prospect in mind.

Upload code for current web app into a directory under this repo

Convert docs from rst to md

Integrate SciUnit and Nosetest frameworks

Currently

The current test example uses an assert statement (Python standard library) in order to run on Travis CI with NoseTest.

This can be improved, but ultimately the assert is wrapped around a SciUnit boolean Score, so if the score is True, the NoseTest passes.

What we want

This is fine for boolean scores, but more complex Score types (e.g. scores generated from any statistical measure) will have more complex values. Ultimately the result must be expressed as a boolean (pass/fail), which will likely be whether or not a score falls within a certain acceptable range.

@rgerkin
How can we organize our code such that these "acceptable range" calculations are exposed to Travis CI and automated testing (i.e. using NoseTest to check the assert results).

Do you think the SciUnit Tests should have the assert statements inside them, or should these statements be inside the Scores themselves? Or perhaps we could have a file of SciUnit tests/suites, and perform the acceptable range calculations on them from another file of standard python unit tests.

Thoughts?

@gsarma

Decide what Tests are required

How will we decide if our model is close enough to reality?

We will be using the SciUnit framework to write our Tests.

SciUnit background knowledge

Tests in SciUnit must override generate_prediction and compute_score, as in this simple example.

A Test is instantiated (perhaps with parameters), then run on a Model with some Observed data using the judge method (example).

What we will do

We'll come up with Tests that we think are appropriate for ChannelWorm, and decide what generate_prediction and compute_score might look like in each of those.

We can enumerate them here, and create separate issues for writing each of the Tests.

@gsarma

Estimate parameters for modeling ion channels with no patch clamp data available

Using some machine learning algorithms we should estimate parameters such as Conductance, reverse potential, and the rate of activation/inactivation in order to build HH models for ion channels with no patch clamp data available.
The steps would be as follow:

• Find data-sets and decide on the input types
• Decide on the structural properties of ion channels could be used for the feature selection
• Choose the right algorithm for this purpose
• Do the preprocessing step
• Do the training step
• Validate and improve results

Fit channel models into Muscle and Neuron (i.e. Cell) models

Since the ion channels are more useful if we know which cells they are in, the data model must take into account the distribution of ion channels.

This could be done in two reciprocal ways. For some Ion Channel model i and Cell model c:

1. A method i.appearsIn() that returns a list of Cells
2. A method c.ionChannels() that returns a list of Ion Channels

Decide on preferred outputs of the final channel model

Assuming we have successfully fitted, optimized and validated parameters for each ion channel model, what are the preferred outputs for each model to be stored and shown via the interface?

These are the options came to my mind:

• Keeping parameters along with related score of the fitting process or validation test in a DB and generating the NeuroML2 file via some API, by request.
• Depicting figures of the voltage-dependent dynamics for each channel (including the steady states of activation/inactivation and the associated time constants)
• Each figure taken from publications in comparison with the simulated one

Digitize plots from patch-clamp studies

The scenario is that a user, would need to upload a plot from a patch-clamp study, and extract digitized data for further analysis. (See this issue, and this one for more information)

The digitization process could be implemented via the WebPlotDigitizer and it's open source Python script libraries.

Extracted data should be stored in a db or .csv file for further analysis.
Also it is possible to represent the digitized plot via Plotly APIs. An auto generating link to Plotly could be great (something like Graph in Plotly in this picture )

Develop method to insert plots into PyOpenWorm

With the Experiment data model we are able to store conditions in the database.

This can be expanded to include inserting digitized plots, but methods need to be created in the existing class (linked above) to allow inserting and retrieving of columns of data.

Deploy current version of the Django+Bootstrap app

According to @miladjafary : "it's sunds that @joebowen found a way that we can put code in Repo and deployed automatic in OpenShift"

Mirror OpenShift git repo on Github

Mentioned here but deserves its own issue.

The idea is to link the two repos together so that changes in one are reflected in the other.

ChannelModel data model

There may be multiple ion channel models for a single ion channel, from different sources.

As per mine and Vahid's discussions, this should include:

• type (patch clamp, or homology estimate)
• a reference to an experiment object, with information about the patch clamp experiment this data comes from
• conductance (Quantity)
• activation parameters

EDIT:
I'm going to open this up and let users/collaborators suggest further parameters/functions for the ChannelModel class. @VahidGh @miladjafary

Check out #7 for discussion on this, and the other issues under this milestone for discussion on other data models (ex: SI units, Channel-Cell interface, etc.).

Feel free to raise an issue there if it does not exist yet!