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.
Creating Your Own Project
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.
Sign up to OSB¶
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 email@example.com if you are interested in that.
Share your code¶
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.
Add some documentation¶
There is information here on adding documentation to your OSB project.
Now is a good time to drop us a line on firstname.lastname@example.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.
Write Your Project Documentation
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).
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.
Reference to pubmed publication:¶
This syntax will generate a reference link like this:
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:
This will automatically generate the following image using the google chart API:
Link to Wiki page¶
If you want to link to other Wiki page:
Link to an Issue¶
If you want to link to an issue in your project:
Link to a Commit¶
If you want to link to a commit in your repository:
2) Add README files in your GitHub¶
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:
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.
Using neuroConstruct Based Projects
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.
Install the latest version of neuroConstruct¶
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.
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?¶
The Principal Investigator for the OSB project is Angus Silver and the core team at UCL consists of Padraig Gleeson (Project Manager) and Matt Earnshaw. Special thanks to Matteo Cantarelli, Adrian Quintan, Boris Marin and Eugenio Piasini for their 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.
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 email@example.com) 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.
Find out about all the ways to follow the project or get in contact here.
A number of meetings have been organised/are planned to promote OSB, including:
- Open collaboration in computational neuroscience: a workshop at CNS 2015
- OSB 2015 in Sardinia in May 2015
- A workshop on Open collaboration in computational neuroscience at Neuroinformatics 2014 in Leiden in August 2014 featuring OSB
- OSB 2014 in Sardinia in May 2014
- Hackathon 2013 in London in Nov 2013
- Sardinia 2013 the OSB kickoff meeting in May 2013
Interaction With Other Neuroinformatics Resources
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 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 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.
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 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.
GENESIS 2 is available for download here.
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 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.
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 is available for download here.
PSICS is available here.
API for OSB¶
An API for getting access to information contained in OSB projects has been developed.
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.
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.
Converting To NeuroML2
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
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.).
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:
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.
Contribute To OSB
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.
Running Simulations on OSB
It is possible to run simulations on OSB directly from your browser
Neuron on OSB, jNeuroML on OSB, and NetPyNE on OSB simulation options run on the OSB platform's own server. Limitations on the size and duration of simulations apply.
Neuron on NSG and NetPyNE on NSG run on the Neuroscience Gateway Portal. NetPyNE on NSG simulations can be run on up to 64 processors.
Connect to Dropbox¶
Simulation results in HDF5 format can be automatically sent to a Dropbox App folder.
To enable this, click the "Link Dropbox…" button in the Run Experiment dialog.
You will be asked to give Geppetto access to its own folder within Dropbox. Copy and paste the code into the dialog on OSB.
After completing this configuration, the "Upload results to Dropbox on completion" option will be checked by default in the run dialog, and results files should appear automatically in your Apps/Geppetto folder.
Creating new tutorials¶
We encourage users to turn their OSB projects into new tutorials...
Please get in contact at any stage of preparing your tutorial.
How To Contact Us
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 firstname.lastname@example.org. If you prefer mailing humans directly, contact Padraig Gleeson.
Report a bug / Request a feature¶
Follow us on Twitter at @OSBTeam¶
You can follow us on Twitter at @OSBTeam to find out what's new with OSB.