pyNeuroML

pyNeuroML#

Suggested NeuroML tool

pyNeuroML is the suggested software tool for working with NeuroML. It builds on jNeuroML, libNeuroML, and pyLEMS.

Citation

Please cite Vella et al. ([VCC+14]) if you use pyNeuroML.

pyNeuroML is a Python package that allows you to work with NeuroML models using the Python programming language. It includes all the API functions provided by libNeuroML and pyLEMS, and also wraps all the functions that jNeuroML provides, which can therefore be used from within Python itself.

With pyNeuroML you can:

  • Create NeuroML models and simulations

  • Validate NeuroML v1.8.1 and v2.x files

  • Simulate NeuroML 2 models

  • Export NeuroML 2 and LEMS files to many formats such as Neuron, Brian, Matlab, etc.

  • Import other languages into LEMS (e.g. SBML)

  • Visualise NeuroML models and simulations

jNeuroML and pyNeuroML

Fig. 63 Relationship between jLEMS, jNeuroML, the NeuroML 2 LEMS definitions, libNeuroML, pyLEMS and pyNeuroML.#

Quick start#

Install Python and the Java Runtime Environment#

Python is generally pre-installed on all computers nowadays. However, if you do not have Python installed on your system, please follow the official installation instructions to install Python on your computer. A number of Free/Open source Integrated Development Environments (IDEs) are also available that make working with Python (even) easier. An example list is here.

Since pyNeuroML wraps around jNeuroML which is written in Java, you will need a Java Runtime Environment (JRE) installed on your system. On most Linux systems Free/Open source OpenJDK runtime environment is already pre-installed. You can also install Oracle’s proprietary Java platform from their download page if you prefer. Please refer to your operating system’s documentation to install a JRE.

Install pyNeuroML with pip#

Tip: Use a virtual environment

While using Python packages, it is suggested to use a virtual environment to isolate the software you install from each other. Learn more about using virtual environments in Python here.

The easiest way to install the latest version of pyNeuroML is using the default Python package manager, pip:

pip install pyneuroml

By default, this will only install the minimal set of packages required to use pyNeuroML. To use pyNeuroML with specific supporting tools, please install them as required:

  • simulation backends

    • pip install pyneuroml[neuron]: NEURON

    • pip install pyneuroml[brian]: Brian2

    • pip install pyneuroml[netpyne]: NetPyNE

    • pip install pyneuroml[tellurium]: Tellurium

  • COMBINE formats (SEDML/SBML):

    • pip install pyneuroml[combine]

  • analysis and visualization

    • pip install pyneuroml[analysis]

  • visualization

    • VisPy:

      • pip install pyneuroml[vispy]: Qt6 (default):

      • pip install pyneuroml[vispy-qt5] : Qt5

      • pip install pyneuroml[vispy-common]: to manually use another supported backend:

    • pip install pyneuroml[povray]: Povray

    • pip install pyneuroml[plotly]: PlotLy

  • model fitting

    • pip install pyneuroml[tune]

  • HDF5 support

    • pip install pyneuroml[hdf5]

  • Neuroscience Gateway (NSG) support

    • pip install pyneuroml[nsg]

  • RDF annotations

    • pip install pyneuroml[annotations]

A number of “meta” packages are also available:

  • pip install pyneuroml[all]: install everything

  • pip install pyneuroml[dev]: install for development

  • pip install pyneuroml[doc]: install for building documentation

Installing optional dependencies#

The optional “extras” provided by pyNeuroML may require some additional software to be installed that is not Python based, and so cannot be automatically installed using pip:

NEURON#

For compiling NEURON mod files, you also need a C compiler and the make utility installed on your computer. Additionally, to run parallel simulations the MPI libraries are also needed. Please see the NEURON installation documentation for more information on installing NEURON on your computer.

Povray#

Requires the installation of the Povray tool.

Vispy#

Requires installation of a back end. The default is Qt6, but one can also use Qt5, or a different back end. Vispy also makes use of GPUs via OpenGL. So a recent GPU is recommended for larger scale models.

For more information on individual simulation backends and extras, please refer to their respective documentations.

Installation on Fedora Linux#

On Fedora Linux systems, the NeuroFedora community provides pyNeuroML as a package in their extras repository and can be installed using the following commands:

sudo dnf copr enable @neurofedora/neurofedora-extra
sudo dnf install python3-pyneuroml

Optional packages can also be installed using the default package manager:

sudo dnf install python3-brian2 python3-neuron neuron-devel python3-netpyne

MPI builds of these tools are also available in the NeuroFedora repositories. Please see the project documentation on installing and using them.

Documentation#

pyNeuroML provides a set of command line utilities along with an API to use from within Python scripts:

TODO!

Check that all of these have usage documentation that is viewable using the -h flag. Issue filed: NeuroML/pyNeuroML#87

  • pynml

  • pynml-channelanalysis

  • pynml-modchananalysis

  • pynml-plotspikes

  • pynml-povray

  • pynml-sonata

  • pynml-summary

  • pynml-tune

These utilities are self-documented. So, to learn how these utilities are to be used, run them with the -h flag. For example:

pynml -h
usage: pynml [-h|--help] [<shared options>] <one of the mutually-exclusive options>

pyNeuroML v0.5.9: Python utilities for NeuroML2
    libNeuroML v0.2.54
    jNeuroML v0.10.2

optional arguments:
  -h, --help            show this help message and exit

Shared options:
  These options can be added to any of the mutually-exclusive options

  -verbose              Verbose output
  -java_max_memory MAX  Java memory for jNeuroML, e.g. 400M, 2G (used in
                        -Xmx argument to java)
  -nogui                Suppress GUI,
                        i.e. show no plots, just save results
  <LEMS/NeuroML 2 file>
                        LEMS/NeuroML 2 file to process

...

API documentation#

Detailed API documentation for pyNeuroML can be found here.

The pyNeuroML API is also self documented. You can use Python’s in-built documentation viewer pydoc to view the documentation for any of the package’s modules and their functions:

pydoc pyneuroml
Help on package pyneuroml:

NAME
    pyneuroml

PACKAGE CONTENTS
    analysis (package)
    lems (package)
    neuron (package)
    plot (package)
    povray (package)
    pynml
    swc (package)
    tune (package)

DATA
    JNEUROML_VERSION = '0.10.2'

VERSION
    0.5.9

FILE
    /usr/lib/python3.9/site-packages/pyneuroml/__init__.py

pydoc pyneuroml.analysis

Help on package pyneuroml.analysis in pyneuroml:

NAME
    pyneuroml.analysis

PACKAGE CONTENTS
    ChannelDensityPlot
    ChannelHelper
    NML2ChannelAnalysis

FUNCTIONS
    analyse_spiketime_vs_dt(nml2_file, target, duration, simulator, cell_v_path, dts, verbose=False, spike_threshold_mV=0, show_plot_already=True, save_figure_to=None, num_of_last_spikes=None)

    generate_current_vs_frequency_curve(nml2_file, cell_id, start_amp_nA=-0.1, end_amp_nA=0.1, step_nA=0.01, custom_amps_nA=[], analysis_duration=1000, analysis_delay=0, pre_zero_pulse=0, post_zero_pulse=0, dt=0.05, temperature='32degC', spike_threshold_mV=0.0, plot_voltage_traces=False, plot_if=True, plot_iv=False, xlim_if=None, ylim_if=None, xlim_iv=None, ylim_iv=None, label_xaxis=True, label_yaxis=True, show_volts_label=True, grid=True, font_size=12, if_iv_color='k', linewidth=1, bottom_left_spines_only=False, show_plot_already=True, save_voltage_traces_to=None, save_if_figure_to=None, save_iv_figure_to=None, save_if_data_to=None, save_iv_data_to=None, simulator='jNeuroML', num_processors=1, include_included=True, title_above_plot=False, return_axes=False, verbose=False)

FILE
    /usr/lib/python3.9/site-packages/pyneuroml/analysis/__init__.py

Most IDEs are able to show you this information as you use them in your Python scripts.

Getting help#

For any questions regarding pyNeuroML, please open an issue on the GitHub issue tracker here. Any bugs and feature requests can also be filed there.

You can also use any of the communication channels of the NeuroML community.

Development#

pyNeuroML is developed on GitHub at NeuroML/pyNeuroML under the LPGL-3.0 license. The repository contains the complete source code along with instructions on building/installing pyNeuroML. Please follow the instructions there to build pyNeuroML from source.