Help

### Welcome to Open Source Brain!¶

We hope you'll find the information you require here, but if not, please get in touch.

### Browse the projects currently available on OSB¶

Here is a quick video showing some of the tools you can use for browsing the projects on OSB.

### Explore cells and networks in 3D¶

Here you can find a video showing how you can use the OSB Explorer to visualise cells and network models in 3D.

### Browse one of the projects¶

To get a feel for what a typical project on OSB contains, have a look through GranCellSolinasEtAl10 - Granule Cell by Solinas et al. 2010

This project contains a single compartment model of a cerebellar granule cell. This, like many other projects is based on a neuroConstruct project containing the NeuroML elements of the model. neuroConstruct can facilitate generating code for running the model in simulators like NEURON & MOOSE.

### Clone a project for your own local copy¶

If you're not familiar with Git or GitHub click here for a quick explanation and some useful links.

The project mentioned above can be cloned using the following command:

git clone git://github.com/OpenSourceBrain/GranCellSolinasEtAl10.git

If the project contains a neuroConstruct project to facilitate generating scripts for multiple simulators (it contains a neuroConstruct directory), see here.

### Is your model on ModelDB?¶

First of all, if the model is published, please submit the original scripts to ModelDB. This is the correct place for depositing models at the time of publication and should be the first port of call for anyone looking for scripts related to a publication in computational neuroscience.

Placing a model on OSB after submission to ModelDB is an indication that you wish to develop your (or other modellers’ publicly shared) models in an open source collaborative environment, to get help debugging/improving them, to convert them to simulator independent formats, and generally encourage wider reuse.

Register as a user of OSB here. Add your GitHub username and INCF user profile if you have one.

You should also add the URL of your project, software or lab. In the latter case, if the PI is in agreement, we can add the group to the list of labs taking part in the OSB initiative. Please send a mail to info@opensourcebrain.org if you are interested in that.

Create a new repository for your code on GitHub (see here if want to know more about Source Code technologies and Git/GitHub). See the introduction to creating a new repository on GitHub help.

The repository can be hosted on the OpenSourceBrain GitHub organisation, but there is no problem having it under your personal account. If you would like us to host the repository, let us know and we’ll add the repository and give your GitHub user full access to it.

### Create a new OSB project¶

Go to http://www.opensourcebrain.org when you’re logged in. There should be a green button on the top right for adding a new project.

Enter the long name of the project (this can be edited later), the short ID (this can't be changed), a description of the project and the path to the GitHub repository. If the code is not on GitHub yet, or if you host it elsewhere leave this blank. The repository URL can be added manually at a later point.

### Say hello…¶

Now is a good time to drop us a line on info@opensourcebrain.org, and let us know your plans for what you’d like to get out of OSB. We’re always happy to hear from new users.

There are 2 main options for adding documentation to an OSB project:

1) Add Wiki pages on the OSB project
2) Add README files in your GitHub (or other VCS) repository and point to these from the OSB project

### 1) Adding Wiki pages to OSB projects¶

To add a new Wiki page to your OSB project click on the "Wiki" link on the project option bar (when logged in) and start editing the wiki page.

OSB documentation is written in Markdown format syntax, together with some further Redmine and OSB specific additions (See below for further information). Note Markdown allows you to include most HTML syntax (i.e. videos...). In order to be as compatible as possible with GitHub wikis, OSB uses GitHub Flavored Markdown. You can find a cheatsheet here.

We describe briefly below some OSB/Redmine features to enhance Wiki pages on OSB (these can also be used in the text field for the main project description in Settings).

#### Reference to a Repository file.¶

You can point to any file (markdown or plain text) in your GitHub or Bitbucket repository (the repository used in your project).

github:[path]
bitbucket:[path]

This will retrieve the file content and display it in the OSB wiki page. This allows a single file in your repo (e.g. the main README) to be the master copy of the documentation for your project, and to make that accessible to someone browsing the project on OSB.

###### Example:¶

github:help/readme.md
bitbucket:help.txt

#### Reference to pubmed publication:¶

pubmed:[publicationID]

###### Example:¶

pubmed:17442244

This syntax will generate a reference link like this:
pubmed:17442244

and a bibliography section will be automatically generated at the bottom of the page. This section will summarize all the references using the following format:

Gleeson P, Steuber V and Silver RA,
neuroConstruct: a tool for modeling networks of neurons in 3D space. Neuron, 2007, 54(2): 219-35

#### Create a formula¶

You can wrte formulas in your documentation using the LaTeX syntax. You only need to enclose you formula like this:

{{latex(formula)}}

###### Example:¶

{{latex(x=\frac{-b\pm\sqrt{b2-4ac}}{2a})}} 

This will automatically generate the following image using the google chart API:

If you want to link to other Wiki page:

[[Wiki page]]

Wiki page

Issue #12

Issue #12

commit:f30e13e43

f30e13e4

Instead of adding Wiki pages on OSB, you can simply add Markdown format files to your GitHub repo (e.g. README.md) and point to these from an OSB Wiki page (or from the text field for the main project description in Settings) using:

github:README.md

For example this: https://github.com/OpenSourceBrain/ACnet2/blob/master/README.md is also used as the project decription in the OSB project page here: http://www.opensourcebrain.org/projects/acnet2.

A number of the projects on the OSB are based on neuroConstruct projects (see here). neuroConstruct is used to import model elements in NeuroML (e.g. exported from a simulator or other application), can generate code for multiple simulators, and can export NeuroML in various formats.

First, get the latest version of neuroConstruct. While there are binary installers available on the neuroConstruct download page, it’s best to use the latest version of this application from GitHub, as this will most likely be the version in which the projects on OSB were last saved.

Get the latest version of Git (see here for more about Git). Detailed instructions for installing neuroConstruct from source can be found here.

### Install your simulator(s) of choice¶

More details on the simulators supported by OSB can be found here.

### Get a local copy of one of the neuroConstruct based projects¶

Check out a local copy of one of the projects, e.g. Cerebellar Granule Cell - Maex De Schutter 1998

git clone https://github.com/OpenSourceBrain/GranuleCell.git


Run neuroConstruct as outlined in the installation instructions.

Go to File, then Open Project…, go to the folder you installed the project in and select GranuleCell/neuroConstruct/GranuleCell.ncx.
Go to tab Generate and press Generate Cell Positions and Connections.
Go to tab Export and then the tab for your chosen simulator (e.g. NEURON), press Create XXX files, then Run XXX simulation.
For more details on the interaction of neuroConstruct with these simulators see here.

### Get all of the neuroConstruct based projects on OSB¶

To clone all of the projects on OSB which contain neuroConstruct projects use the checkOSB script in the osb subfolder of the neuroConstruct home directory:

cd osb
./checkOsb.sh -u (Linux/Mac)
checkOsb.bat -u  (Windows)


This will clone ~15 projects, which will be accessible under the File - Open Source Brain Project:

### What is the motivation behind the Open Source Brain repository?¶

There are an increasing number of detailed single neuron and network models from various brain regions becoming available which encapsulate the latest data on anatomical and electrophysiological properties of the systems being investigated (e.g. on ModelDB). These complex models take a long time to develop and are normally only available in one of many incompatible, simulator specific formats.

The Open Source Brain repository (OSB) is a public repository for detailed neuronal models in standardised formats, with curated, stable releases which will evolve in line with new experimental findings, the latest modelling paradigms and simulator technology development. Anyone can contribute to any of the models on OSB, either through fixing a bug, adding new features or improving documentation for published models.

While the models can be collaboratively developed in any simulator format, the ultimate aim is to get as much of the model as possible into simulator independent formats like NeuroML and PyNN to ensure modularity, accessibility, cross simulator portability and to enable in-browser visualisation, analysis and simulation.

### Who’s behind OSB?¶

This project was started in the Silver Lab at UCL as part of a Wellcome Trust funded project to encourage collaborative development of models in computational neuroscience.

The Principal Investigator for the OSB project is Angus Silver and the core team at UCL consists of Padraig Gleeson (Project Manager), Adrian Quintan, Boris Marin, Eugenio Piasini. A special thanks to Matteo Cantarelli for his significant contributions to OSB while at UCL.

A number of international research groups and organizations are currently involved in the Open Source Brain Initiative. See here for more details.

### How is this related to other neuroinformatics initiatives?¶

We are very keen to have close links with other databases and repositories for neuroinformatics and computational neuroscience. Many of these will be enabled through common use of NeuroML, as is used by NeuroMorpho.org, and a number of other tools and resources. NeuralEnsemble hosts a number of software tools which will play a key part in simulating and analysing the models in the OSB.

We are also planning deep links to databases such as ModelDB for original model scripts and NIF/NeuroLex for definitions of model components.

See here for more details on interactions with other Neuroinformatics resources.

A number of the contributors to this initiative are involved with the various national nodes of the INCF.

### What types of models can be developed?¶

Models of information processing in the nervous system are created at many levels, from high level models of cognitive processes and consciousness to low level models of signal transduction at synapses. In the short to medium term OSB will focus on spiking neuron models, i.e. networks of individual neurons which communicate through sending events to synapses on target cells. The core set of models currently under development in the OSB are conductance based models of (often multicompartmental) neurons. This class of neuronal model is particularly suited to collaborative development, as models of channels and synapses, or whole cell models, are often reused between studies, and the models themselves are complex software entities. The focus of NeuroML v1.x was on this type of model, but with version 2.0, support has been extended to more abstract neuron models (e.g. leaky integrate and fire, adaptive threshold models).

While converting the model components to NeuroML will be a key step towards increasing model transparency and accessibility and making them available for use on multiple simulators, other cross platform technologies will be used to assist model portability. Python is a scripting language commonly used in computational neuroscience and has been adopted by a number of the target simulators for OSB models. PyNN is a Python package for simulator independent specification of neuronal network models, and will be useful for procedural specification of complex network structures. The Simulation Experiment Description Markup Language (SED-ML) will be used for specifying settings for running simulations of the models. Mappings of the model components in OSB to other structured languages in computational biology will be supported too where appropriate, such as SBML, CellML and NineML.

### My model’s only available in simulator X, not NeuroML/PyNN. Can I still share it on OSB?¶

Yes! If the model is already published, please submit to ModelDB first. On OSB we are happy to point to public repositories with the latest version of the code in any format, and have a link to the version on ModelDB. However, some of the advanced features of OSB will only be available if (parts of) the model are converted to NeuroML.

If your model is not yet published but it still public (we salute you; you are the future) we’re very happy to have it, but would ask that you make sure the versions used in publications are archived in ModelDB.

### Do I have to be registered for accessing OSB projects and tools?¶

No. You can browse the OSB projects and use most of the OSB tools. However, if you would like to create your own project you should sign up. Also, the new functionality for executing and replaying your own simulations through the OSB interface is only available for logged in users.

Since all the scripts for models on OSB reside in autonomous repositories (e.g. on GitHub), each repository can (and should...) contain its own licence information. Unfortunately this is not the case for most of the repositories on OSB (which is a more widespread problem in scientific software development). Nevertheless, the clue is in the title... a user placing a model on Open Source Brain is probably keen to have it used and reused widely. If in doubt though and you want to be sure, open an issue on the repository in question (or mail info@opensourcebrain.org) requesting licence info be added to the repository.

Don't forget the golden rule however (more important to scientists than software licences...): if you use a model, reference the original publication which describes the model. If there are significant changes in the OSB repo from the original model which you want to cite, we can generate a DOI/reference for a specific version of the model (e.g. here).

### How can I contribute?¶

We are happy to hear from anyone interested in helping out with this initiative. We are particularly keen to get modellers or software developers in computational neuroscience involved.

Note: There is a central list for projects in OSB (and related NeuroML tools) which require help from volunteers. See here.

Please sign up here to be part of OSB or contact us directly for more information. You can also sign up to the OSB Announce mailing list to get updates of progress, or the OSB Discuss mailing list for more detailed discussions on the various projects on OSB. If you find an issue or you would like to request a feature, you can create a new issue our GitHub repository.

A number of meetings have been organised/are planned to promote OSB, including:

Below is a list of some important resources in the neuroinformatics, computational neuroscience and systems biology fields and how the Open Source Brian Repository is planning to interact with them.

### ModelDB¶

ModelDB is a curated database of published models in computational neuroscience. This has been the primary source for most of the original simulator scripts on which the models in OSB are based. Where appropriate, OSB models will link back to the original published models on ModelDB.

Greater links are planned between these resources in the future to facilitate finding original model scripts (in a simulator specific format) and updated versions (in a standardized format) which have been extended/improved/used in other modeling studies.

### NeuralEnsemble¶

NeuralEnsemble is an effort to coordinate a number of projects developing software for computational neuroscience to create an interoperable set of tools for addressing complex questions about neuronal function.

Many of the tools developed as part of the NeuralEnsemble initiative will be target applications for models developed on OSB.

### NeuroLex & NIF¶

NeuroLex is the neuroscience lexicon. Many key elements in OSB models (cells, ion channels, brain regions) have unique entries in the NeuroLex lexicon, and this identifier can be used to identify the elements in OSB.

These references are currently used in many of the Theme Wiki pages (e.g. here) and will become more widely used for identifying cells, cellular elements, channels, etc. since neuroLexId is a new attribute in NeuroML v2.0 model elements (see example here).

See the NIF and NeuroLex Showcase project for more details.

### BioModels¶

The BioModels database is a repository of peer-reviewed, published, computational models. We are working with the developers of this database to allow greater linking between models in these repositories.

This work is chiefly taking place in the framework of the COMBINE Network.

### NeuroElectro¶

NeuroElectro is a structured database of information on the electrophysiological properties of neurons. This type of information will be very useful for comparing the electrical properties of model neurons with real experimental data.

An API to the NeuroElectro database will allow retrieval of this data and the SciUnit package will be used to create tests for models against these properties.

See the NeuroElectro & SciUnit Showcase project for more details.

An overview of the main target simulators for models in OSB

Note: not all simulators will be able to execute all models. See here for more information on the simulators supported by each of the models on OSB.

For more tools (e.g. for visualization, analysis of models) which can handle the NeuroML elements of the models on OSB see here.

### Brian¶

Brian is available for download here. There is a Brian Showcase project on OSB.

Greater native support for converting models in NeuroML to (and from) Brian is in development in NeuroML v2.0. See here.

Brian is also currently supported through conversion of NeuroML models to PyNN. See here.

### GENESIS 2¶

Support for running NeuroML models on GENESIS 2 is mainly enabled through generation of scripts by neuroConstruct, but see also here.

### GENESIS 3/Neurospaces¶

GENESIS 3/Neurospaces are available here.

GENESIS 3 currently supports native reading of passive models in NeuroML format (morphology + passive parameters).

Participants at the recent Workshop on Multi-Scale Modeling in Computational Neuroscience with GENESIS 3 reported some success running neuroConstruct generated GENESIS 2 scripts on GENESIS 3.

### MOOSE¶

MOOSE is available here.

Native support for NeuroML (version 1 & 2) in MOOSE is in active development, but neuroConstruct can also be used to generate MOOSE code from NeuroML models.

Follow the latest developments in MOOSE here.

Moogli is a sister project of MOOSE and is a simulator independent OpenGL based visualization tool for neural simulations.

### NEURON¶

NEURON is available here. There is a NEURON showcase project on OSB.

There is native support for reading/writing NeuroML cells in NEURON, see here.

neuroConstruct can also be used to generate NEURON code (including Parallel NEURON) from NeuroML models.

### NEST¶

NEST is currently supported through conversion of NeuroML models to PyNN. See here.

Greater native support for NEST is planned in NeuroML v2.0 (see here).

### PSICS¶

PSICS is available here.

There is some native support for NeuroML in PSICS, but neuroConstruct can also be used to generate PSICS code from NeuroML models.

### API for OSB¶

An API for getting access to information contained in OSB projects has been developed.

#### REST API¶

This is based on the REST API which was developed for Redmine, the framework on which OSB is based.

An example of the data returned by this REST API for each project on OSB can be see here: http://www.opensourcebrain.org/projects/thalamocortical.xml.

#### Python API¶

A Python module (osb) has been developed which uses this REST API and allows scripts to be developed which use the information retrieved about OSB projects.

A simple example of usage is shown below:

import osb

for project in osb.get_projects(min_curation_level="Low"):

print "Project: %s has tags: %s" % (project.name, project.tags)


and more examples can be found here.

### Why should you convert your model to NeuroML 2?¶

Converting models to the simulator independent format NeuroML 2 enables conversion of the model to many different formats, as well as enables many of the advanced features of OSB to be used with your model (e.g. 3D visualisation of cells & networks and extracting information on channel kinetics).

At the moment, there is no "magic button" to press in simulators to export your model into valid NeuroML 2. Presently the best approach is to look at some of the core examples of NeuroML 2, the OSB projects being converted to NeuroML 2, look at the XML examples there and start manual conversion of the models based on these. There are some suggestions below for work to help with this

Use jNeuroML to validate/execute/convert/view the NeuroML 2 files

jNeuroML can be used to validate NeuroML2 files:

 jnml -validate MyNeuroML2.nml


This will validate the file against the latest XSD Schema document, as well as perfom a number of other checks on the structure of the model.

Creating a LEMS simulation file to specify how long to run the simulation, timestep, what to plot/save etc. allows the model to be run with jNeuroML. See examples here and most of these OSB projects have at least one LEMS simulation file too.

To quickly visualise cells and networks in NeuroML 2 (as opposed to loading them in neuroConstruct or viewing on OSB), models can be converted to SVG format (for viewing in a web browser etc.):

 jnml MyNeuron.cell.nml -svg
jnml MyCircuit.net.nml -svg


Installing the latest development version from source as outlined here is highly recommended to get the latest features of jNeuroML.

Use pyNeuroML to export NeuroML2 morphologies from NEURON

Work in progress: pyNeuroML is a Python package which makes many of the features of jNeuroML accessible in Python scrips by bundling the jNeuroML jar file and using the functionality of that package.

In addition to jNeuroML features, pyNeuroML adds a number of Python specific features, including an updated exporter from NEURON into NeuroML2. This is currently limited to exporting just neuronal morphologies (see example here) but will be developed further to allow extraction of other features such as connectivity (and generation of templates in NeuroML2 for channels, synapses etc.).

This feature was used to extract a number of cell models from the original NEURON code in a 3D olfactory bulb model (see this script).

Use pyNeuroML to help convert channels to NeuroML 2

Another feature being worked on is a set of scripts to help conversion of ion channel models (e.g. in NEURON's NMODL format) to NeuroML 2. These scripts can be accessed after pyNeuroML is installed using:

pynml-channelanalysis NaConductance.channel.nml   # Analyse a NeuroML 2 channel
pynml-modchananalysis NaConductance               # Analyse a NEURON channel e.g. from NaConductance.mod


These scripts, while they take different approaches to generating the traces for activation/inactivation variables, produce comparable plots:

On the left are the plots produced from the NeuroML file (e.g. see here) and on the right from the NMODL version (see here).

To be clear, these scripts don't (currently) help you extract the equations from the NMODL file and put them in the correct place in the NeuroML file, they just help comparing the behaviour of the 2 channel formats to check for errors in a manual conversion.

Use neuroConstruct to help conversion to NeuroML v1/2

Many projects on OSB were originally converted from the original format (NEURON, GENESIS, etc.) to NeuroML v1.8.1 using neuroConstruct (see here for a list of these), and from there the conversion to NeuroML2 inside neuroConstruct was straightforward. More on using neuroConstruct here and details on conversion of models to NeuroML v1 here.

There is a central repository for issues listing OSB projects looking for contributors. A number of other programming tasks (e.g. further development of NeuroML based tools) are also listed, which would be of benefit to OSB projects.

See https://github.com/OpenSourceBrain/Contribute/issues for the current issues/project suggestions.

A template for new issues/project suggestions can be found here.

This is also a place for labs who have a specific, well defined model building/conversion project (or tool development task), related to the aims of Open Source Brain, to advertise the project with the understanding that they would be willing to help the developer complete the task, and that the model/code will be open to all.

### Send feedback¶

We’d love to hear your thoughts on the initiative in general, the website or any of the technologies being used. Please send us a mail at info@opensourcebrain.org. If you prefer mailing humans directly, contact Padraig Gleeson, Adrian Quintana or Boris Marin.

To get in contact with the whole OSB community see the OSB discuss and OSB announce mailing lists.

### Report a bug / Request a feature¶

To report an issue or request a feature with the OSB website, create a new issue on our GitHub repository. Note that you will have to register and be logged in to GitHub to create a new issue.