pyneuroml.utils package#

The utils package contains various utility functions to aid users working with PyNeuroML. Many of these methods are meant for internal use in the package and so may change in the future: the API here is not considered stable.

Copyright 2024 NeuroML Contributors

pyneuroml.utils.extract_lems_definition_files(path: str | None | TemporaryDirectory = None) str#

Extract the NeuroML2 LEMS definition files to a directory and return its path.

This function can be used by other LEMS related functions that need to include the NeuroML2 LEMS definitions.

If a path is provided, the folder is created relative to the current working directory.

If no path is provided, for repeated usage for example, the files are extracted to a temporary directory using Python’s tempfile.mkdtemp function.

Note: in both cases, it is the user’s responsibility to remove the created directory when it is no longer required, for example using. the shutil.rmtree() Python function.


path (str or None) – path of directory relative to current working directory to extract to, or None


directory path

pyneuroml.utils.extract_position_info(nml_model: NeuroMLDocument, verbose: bool = False) tuple#

Extract position information from a NeuroML model

Returns a tuple of dictionaries:

  • cell_id_vs_cell: dict(cell id, cell object)

  • pop_id_vs_cell: dict(pop id, cell object)

  • positions: dict(pop id, dict(cell id, position in x, y, z))

  • pop_id_vs_color: dict(pop id, colour property)

  • pop_id_vs_radii: dict(pop id, radius property)

  • nml_model (NeuroMLDocument) – NeuroML2 model to extract position information from

  • verbose (bool) – toggle function verbosity


[cell id vs cell dict, pop id vs cell dict, positions dict, pop id vs colour dict, pop id vs radii dict]

Return type:

tuple of dicts

pyneuroml.utils.get_colour_hex(fract: float, min_colour: Tuple[int, int, int] = (255, 255, 0), max_colour: Tuple[int, int, int] = (255, 0, 0)) str#

Get colour hex at fraction between min_colour and max_colour.

  • fract (float between (0, 1)) – fraction between min_colour and max_colour

  • min_colour (tuple) – lower colour tuple (R, G, B)

  • max_colour (tuple) – upper colour tuple (R, G, B)


colour in hex representation

Return type:


pyneuroml.utils.get_files_generated_after(timestamp: float = 1716386730.7327344, directory: str = '.', ignore_suffixes: List[str] = ['xml', 'nml'], include_suffixes: List[str] = []) List[str]#

Get files modified after provided time stamp in directory, excluding provided suffixes.

Currently ignores directories.

Added in version 1.0.9.

  • timestamp (float) – time stamp to compare to

  • directory (str) – directory to list files of

  • ignore_suffixes (str) – file suffixes to ignore (none if empty)

  • include_suffixes (str) – file suffixes to include (all if empty)


list of file names

Return type:


pyneuroml.utils.get_ion_color(ion: str) str#

Get colours for ions in hex format.

Hard codes for na, k, ca, h. All others get a grey.


ion (str) – name of ion


colour in hex

Return type:


pyneuroml.utils.get_model_file_list(rootfile: str, filelist: List[str], rootdir: str = '.', lems_def_dir: str | None = None) str | None#

Get the list of files to archive.

This method will take the rootfile, and recursively resolve all the files it uses.

  • rootfile (str) – main NeuroML/LEMS/SED-ML file to resolve

  • filelist (list of strings) – list of file paths to append to

  • rootdir (str) – directory holding the root file

  • lems_def_dir (str) – path to directory holding lems definition files


value of lems_def_dir so that the temporary directory can be cleaned up. strings are immuatable in Python so the variable cannot be modified in the function.


ValueError – if a file that does not have “.xml” or “.nml” as extension is encountered

pyneuroml.utils.get_pyneuroml_tempdir(rootdir: str = '.', prefix: str = 'pyneuroml')#

Generate a pyneuroml directory name that can be used for various purposes.

Default format: {rootdir}/{prefix}_{timestamp}_{6 random characters}

  • rootdir (str) – root directory where to create the new directory

  • prefix (str) – prefix for directory name


generated directory name

Return type:


pyneuroml.utils.get_state_color(s: str) str#

Get colours for state variables.

Hard codes for m, k, r, h, l, n, a, b, c, q, e, f, p, s, u.


state (str) – name of state


colour in hex format

Return type:


pyneuroml.utils.rotate_cell(cell: Cell, x: float = 0, y: float = 0, z: float = 0, order: str = 'xyz', relative_to_soma: bool = False, inplace: bool = False) Cell#

Return a new cell object rotated in the provided order along the provided angles (in radians) relative to the soma position.

  • cell (neuroml.Cell) – cell object to rotate

  • x (float) – angle to rotate around x axis, in radians

  • y (float) – angle to rotate around y axis, in radians

  • z (float) – angle to rotate around z axis, in radians

  • order (str) – rotation order in terms of x, y, and z

  • relative_to_soma (bool) – whether rotation is relative to soma

  • inplace (bool) – toggle whether the cell object should be modified inplace or a copy created (creates and returns a copy by default)


new neuroml.Cell object

Return type:


Derived from LFPy’s implementation: LFPy/LFPy

pyneuroml.utils.translate_cell_to_coords(cell: Cell, inplace: bool = False, dest: List[float] = [0, 0, 0]) Cell#

Translate cell so that its soma moves to given coordinates

Added in version 1.2.13.

  • cell (neuroml.Cell) – cell object to translate

  • inplace (bool) – toggle whether the cell object should be modified inplace or a copy created (creates and returns a copy by default)

  • dest (list[x,y,z]) – destination coordinates (x,y,z) for cell’s root


new neuroml.Cell object

Return type:

neuroml.Cell module#

Utilities for getting information from NeuroML models

File: pyneuroml/utils/

Copyright 2024 NeuroML contributors Cell) str#

Provide information on a NeuroML Cell instance:

  • morphological information:

    • Segment information:

      • parent segments

      • segment location, extents, diameter

      • segment length

      • segment surface area

      • segment volume

    • Segment group information:

      • included segments

  • biophysical properties:

    • channel densities

    • specific capacitances


cell (Cell) – cell object to investigate


string of cell information str) str#

Provide information about the cells in a NeuroML file.


nml_file_name (str) – name of NeuroML v2 file


information on cells (str) NeuroMLDocument) str#

Get a quick summary of the NeuroML2 document

NOTE: You should prefer nml2_doc.summary(show_includes=False)


nml2_doc (NeuroMLDocument) – NeuroMLDocument to fetch summary for


summary string NeuroMLDocument | None = None, verbose: bool = False) None#

Wrapper around nml_doc.summary() to generate the pynml-summary command line tool.

  • nml2_doc (NeuroMLDocument) – NeuroMLDocument object or name of NeuroML v2 file to get summary for.

  • verbose (bool) – toggle verbosity

pyneuroml.utils.plot module#

Common utils to help with plotting

File: pyneuroml/utils/

Copyright 2023 NeuroML contributors

class pyneuroml.utils.plot.LineDataUnits(*args, **kwargs)#

Bases: Line2D

New Line class for making lines with specific widthS


set(*, agg_filter=<UNSET>, alpha=<UNSET>, animated=<UNSET>, antialiased=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, color=<UNSET>, dash_capstyle=<UNSET>, dash_joinstyle=<UNSET>, dashes=<UNSET>, data=<UNSET>, drawstyle=<UNSET>, fillstyle=<UNSET>, gapcolor=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, linestyle=<UNSET>, linewidth=<UNSET>, marker=<UNSET>, markeredgecolor=<UNSET>, markeredgewidth=<UNSET>, markerfacecolor=<UNSET>, markerfacecoloralt=<UNSET>, markersize=<UNSET>, markevery=<UNSET>, mouseover=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, pickradius=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, solid_capstyle=<UNSET>, solid_joinstyle=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xdata=<UNSET>, ydata=<UNSET>, zorder=<UNSET>)#

Set multiple properties at once.

Supported properties are


agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image alpha: scalar or None animated: bool antialiased or aa: bool clip_box: ~matplotlib.transforms.BboxBase or None clip_on: bool clip_path: Patch or (Path, Transform) or None color or c: :mpltype:`color` dash_capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} dash_joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} dashes: sequence of floats (on/off ink in points) or (None, None) data: (2, N) array or two 1D arrays drawstyle or ds: {‘default’, ‘steps’, ‘steps-pre’, ‘steps-mid’, ‘steps-post’}, default: ‘default’ figure: ~matplotlib.figure.Figure fillstyle: {‘full’, ‘left’, ‘right’, ‘bottom’, ‘top’, ‘none’} gapcolor: :mpltype:`color` or None gid: str in_layout: bool label: object linestyle or ls: {‘-’, ‘–’, ‘-.’, ‘:’, ‘’, (offset, on-off-seq), …} linewidth or lw: float marker: marker style string, ~.path.Path or ~.markers.MarkerStyle markeredgecolor or mec: :mpltype:`color` markeredgewidth or mew: float markerfacecolor or mfc: :mpltype:`color` markerfacecoloralt or mfcalt: :mpltype:`color` markersize or ms: float markevery: None or int or (int, int) or slice or list[int] or float or (float, float) or list[bool] mouseover: bool path_effects: list of .AbstractPathEffect picker: float or callable[[Artist, Event], tuple[bool, dict]] pickradius: float rasterized: bool sketch_params: (scale: float, length: float, randomness: float) snap: bool or None solid_capstyle: .CapStyle or {‘butt’, ‘projecting’, ‘round’} solid_joinstyle: .JoinStyle or {‘miter’, ‘round’, ‘bevel’} transform: ~matplotlib.transforms.Transform url: str visible: bool xdata: 1D array ydata: 1D array zorder: float

pyneuroml.utils.plot.add_box_to_matplotlib_2D_plot(ax, xy, height, width, color)#

Add a box to a matplotlib plot, at xy of height, width and color.

  • ax (matplotlob.axes.Axis) – matplotlib.axes.Axes object

  • xy (List[float]) – bottom left corner of box

  • height (float) – height of box

  • width (float) – width of box

  • color (str) – color of box for edge, face, fill



pyneuroml.utils.plot.add_line_to_matplotlib_2D_plot(ax, xv, yv, width, color, axis_min_max)#

Add a line to a matplotlib plot

  • ax (matplotlib.axes.Axes) – matplotlib.axes.Axes object

  • xv ([float, float]) – x values

  • yv ([float, float]) – y values

  • width (float) – width of line

  • color (str) – color of line

  • axis_min_max ([float, float]) – min, max value of axis

pyneuroml.utils.plot.add_scalebar_to_matplotlib_plot(axis_min_max, ax)#

Add a scalebar to matplotlib plots.

The scalebar is of magnitude 50 by default, but if the difference between max and min vals is less than 100, it’s reduced to 5, and if the difference is less than 10, it’s reduced to 1.

  • axis_min_max ([float, float]) – minimum, maximum value in plot

  • ax (matplotlib.axes.Axes) – axis to plot scalebar at



pyneuroml.utils.plot.add_text_to_matplotlib_2D_plot(ax: Axes, xv: List[float], yv: List[float], color: str, text: str, horizontal: str = 'center', vertical: str = 'bottom', clip_on: bool = True)#

Add text to a matplotlib plot between two points

Wrapper around matplotlib.axes.Axes.text.

Rotates the text label to ensure it is at the same angle as the line.

  • ax (Axes) – matplotlib axis object

  • xv (list[x1, x2]) – start and end coordinates in one axis

  • yv (list[y1, y2]) – start and end coordinates in second axix

  • color (str) – color of text

  • text (str) – text to write

  • clip_on (bool) – toggle clip_on (if False, text will also be shown outside plot)

pyneuroml.utils.plot.autoscale_matplotlib_plot(verbose: bool = False, square: bool = True) None#

Autoscale the current matplotlib plot

  • verbose (bool) – toggle verbosity

  • square (bool) – toggle squaring of plot



pyneuroml.utils.plot.get_cell_bound_box(cell: Cell)#

Get a boundary box for a cell


cell (neuroml.Cell) – cell to get boundary box for


tuple (min view, max view)

pyneuroml.utils.plot.get_new_matplotlib_morph_plot(title: str = '', plane2d: str = 'xy') Tuple[Figure, Axes]#

Get a new 2D matplotlib plot for morphology related plots.

  • title (str) – title of plot

  • plane2d – plane to use


new [matplotlib.figure.Figure, matplotlib.axes.Axes]

Return type:

[matplotlib.figure.Figure, matplotlib.axes.Axes]

pyneuroml.utils.plot.get_next_hex_color(my_random: Random | None = None) str#

Get a new randomly generated HEX colour code.

You may pass a random.Random instance that you may be used. Otherwise the default Python random generator will be used.


my_random (random.Random) – a random.Random object


HEX colour code

pyneuroml.utils.plot.load_minimal_morphplottable__model(nml_model: NeuroMLDocument, nml_file_path: str = '')#

Take a model that has been loaded without recursively including all bits, and load only information that is needed to plot it.

  • nml_model (neuroml.NeuroMLDocument) – partially loaded model

  • nml_file_path (str) – path of file corresponding to the model

pyneuroml.utils.misc module#

Miscellaneous utils

File: pyneuroml/utils/

Copyright 2024 NeuroML contributors

pyneuroml.utils.misc.get_path_to_jnml_jar() str#

Get the path to the jNeuroML jar included with PyNeuroML.


path of jar file

pyneuroml.utils.cli module#

Utilities use in writing console scripts.

File: pyneuroml/utils/

Copyright 2023 NeuroML contributors

pyneuroml.utils.units module#

Methods related to units.

File: pyneuroml/utils/

Copyright 2024 NeuroML contributors

pyneuroml.utils.units.convert_to_units(nml2_quantity: str, unit: str) float#

Convert a NeuroML2 quantity to provided unit.

  • nml2_quantity (str) – NeuroML2 quantity to convert

  • unit (str) – unit to convert to


converted value (float)

pyneuroml.utils.units.get_lems_model_with_units() Model#

Get a LEMS model with NeuroML core dimensions and units.


a lems.model.model.Model that includes NeuroML dimensions and units.

pyneuroml.utils.units.get_value_in_si(nml2_quantity: str) float | None#

Get value of a NeuroML2 quantity in SI units


nml2_quantity (str) – NeuroML2 quantity to convert


value in SI units (float)

pyneuroml.utils.units.split_nml2_quantity(nml2_quantity: str) Tuple[float, str]#

Split a NeuroML 2 quantity into its magnitude and units


nml2_quantity – NeuroML2 quantity to split


a tuple (magnitude, unit)

pyneuroml.utils.xml module#

Utility methods related to xml processing

File: pyneuroml/utils/

Copyright 2024 NeuroML contributors