pyneuroml package

Subpackages

Submodules

pyneuroml.pynml module

Python wrapper around jnml command. Also a number of helper functions for handling/generating/running LEMS/NeuroML2 files

Thanks to Werner van Geit for an initial version of a python wrapper for jnml.

pyneuroml.pynml.cell_info(cell)

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

Parameters

cell (Cell) – cell object to investigate

Returns

string of cell information

pyneuroml.pynml.cells_info(nml_file_name)

Provide information about the cells in a NeuroML file.

Parameters

nml_file_name (str) – name of NeuroML v2 file

Returns

information on cells (str)

pyneuroml.pynml.confirm_file_exists(filename)

Check if a file exists, exit if it does not.

Parameters

filename (str) – the filename to check

pyneuroml.pynml.confirm_lems_file(filename)

Confirm that file exists and is a LEMS file before proceeding with processing.

Parameters

filename (list of strings) – Names of files to check

pyneuroml.pynml.confirm_neuroml_file(filename)

Confirm that file exists and is a NeuroML file before proceeding with processing.

Parameters

filename (str) – Names of files to check

pyneuroml.pynml.convert_to_units(nml2_quantity, unit)

Convert a NeuroML2 quantity to provided unit.

Parameters
  • nml2_quantity (str) – NeuroML2 quantity to convert

  • unit (str) – unit to convert to

Returns

converted value (float)

pyneuroml.pynml.evaluate_arguments(args)
pyneuroml.pynml.evaluate_component(comp_type, req_variables={}, parameter_values={})
pyneuroml.pynml.execute_command_in_dir(command, directory, verbose=False, prefix='Output: ', env=None)

Execute a command in specific working directory

Parameters
  • command (str) – command to run

  • directory (str) – directory to run command in

  • verbose (bool) – toggle verbose output

  • prefix (str) – string to prefix console output with

  • env (str) – environment variables to be used

pyneuroml.pynml.execute_command_in_dir_with_realtime_output(command, directory, verbose=False, prefix='Output: ', env=None)

Run a command in a given directory with real time output.

NOTE: this has only been tested on Linux.

Parameters
  • command (str) – command to run

  • directory (str) – directory to run command in

  • verbose (bool) – toggle verbose output

  • prefix (str) – string to prefix output with

  • env (str) – environment variables to be used

pyneuroml.pynml.extract_annotations(nml2_file)

Extract and print annotations from a NeuroML 2 file.

Parameters

nml2_file (str) – name of NeuroML2 file to parse

pyneuroml.pynml.extract_lems_definition_files(path=None)

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.

Parameters

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

Returns

directory path

pyneuroml.pynml.generate_lemsgraph(lems_file_name, verbose_generate=True)

Generate LEMS graph using jNeuroML

Parameters
  • lems_file_name (str) – LEMS file to parse

  • verbose_generate (bool) – whether or not jnml should be run with verbosity output

Returns bool

True of jnml ran without errors, exits without a return if jnml fails

pyneuroml.pynml.generate_nmlgraph(nml2_file_name, level=1, engine='dot')

Generate NeuroML graph.

Nml2_file_name (string)

NML file to parse

Level (string)

level of graph to generate (default: ‘1’)

Engine (string)

graph engine to use (default: ‘dot’)

pyneuroml.pynml.generate_plot(xvalues, yvalues, title, labels=None, colors=None, linestyles=None, linewidths=None, markers=None, markersizes=None, xaxis=None, yaxis=None, xlim=None, ylim=None, show_xticklabels=True, show_yticklabels=True, grid=False, logx=False, logy=False, font_size=12, bottom_left_spines_only=False, cols_in_legend_box=3, legend_position=None, show_plot_already=True, save_figure_to=None, title_above_plot=False, verbose=False)

Utility function to generate plots using the Matplotlib library.

This function can be used to generate graphs with multiple plot lines. For example, to plot two metrics you can use:

generate_plot(xvalues=[[ax1, ax2, ax3], [bx1, bx2, bx3]], yvalues=[[ay1, ay2, ay3], [by1, by2, by3]], labels=["metric 1", "metric 2"])

Please note that while plotting multiple plots, you should take care to ensure that the number of x values and y values for each metric correspond. These lists are passed directly to Matplotlib for plotting without additional sanity checks.

Please see the Matplotlib documentation for the complete list of available styles and colours: - https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.plot.html - https://matplotlib.org/stable/gallery/index.html

Parameters
  • xvalues (list of lists) – X values

  • yvalues (lists of lists) – Y values

  • title (str) – title of plot

  • labels (list of strings) – labels for each plot (default: None)

  • colors (list of strings) – colours for each plot (default: None)

  • linestyles (list strings) – list of line styles (default: None)

  • linewidths (list of floats) – list of line widths (default: None)

  • markers (list strings) – list of markers (default: None)

  • markersizes (list of floats) – list of marker sizes (default: None)

  • xaxis (str) – label of X axis (default: None)

  • yaxis (str) – label of Y axis (default: None)

  • xlim (tuple of (float, float) or individual arguments: (left=float), (right=float) See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.xlim.html) – left and right extents of x axis (default: None)

  • ylim (tuple of (float, float) or individual arguments: (top=float), (bottom=float) See https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.ylim.html) – top and bottom extents of y axis (default: None)

  • show_xticklabels (boolean) – whether labels should be shown on xtics (default: True)

  • show_yticklabels (boolean) – whether labels should be shown on ytics (default: True)

  • grid (boolean) – enable/disable grid (default: False)

  • logx (boolean) – should the x axis be in log scale (default: False)

  • logy (boolean) – should the y ayis be in log scale (default: False)

  • font_size (float) – font size (default: 12)

  • bottom_left_spines_only (boolean) – enable/disable spines on right and top (default: False) (a spine is line noting the data area boundary)

  • cols_in_legend_box (float) – number of columns to use in legend box (default: 3)

  • legend_position (str) – position of legend: (default: None) See: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.legend.html

  • show_plot_already (boolean) – if plot should be shown when created (default: True)

  • save_figure_to (str) – location to save generated figure to (default: None)

  • title_above_plot (boolean) – enable/disable title above the plot (default: False)

  • verbose (boolean) – enable/disable verbose logging (default: False)

Returns

matplotlib Axes object

pyneuroml.pynml.get_lems_model_with_units()

Get a LEMS model with NeuroML core dimensions and units.

Returns

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

pyneuroml.pynml.get_next_hex_color(my_random=None)

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.

Parameters

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

Returns

HEX colour code

pyneuroml.pynml.get_path_to_jnml_jar()

Get the path to the jNeuroML jar included with PyNeuroML.

Returns

path of jar file

pyneuroml.pynml.get_standalone_lems_model(nml_doc_fn)

Get the complete, expanded LEMS model.

This function takes a NeuroML2 file, includes all the NeuroML2 LEMS definitions in it and generates the complete, standalone LEMS model.

Parameters

nml_doc_fn (str) – name of NeuroML file to expand

Returns

complete LEMS model

pyneuroml.pynml.get_value_in_si(nml2_quantity)

Get value of a NeuroML2 quantity in SI units

Parameters

nml2_quantity (str) – NeuroML2 quantity to convert

Returns

value in SI units (float)

pyneuroml.pynml.gui_string(nogui)

Return the gui string for jnml

Parameters

nogui (bool) – toggle whether GUI should be used or not

Returns

gui string or empty string

pyneuroml.pynml.include_string(paths_to_include)

Convert a path or list of paths into an include string to be used by jnml.

Parameters

paths_to_include (str or list(str) or tuple(str)) – path or list or tuple of paths to be included

Returns

include string to be used with jnml.

pyneuroml.pynml.list_exposures(nml_doc_fn, substring='')

List exposures in a NeuroML model document file.

This wraps around lems.model.list_exposures to list the exposures in a NeuroML2 model. The only difference between the two is that the lems.model.list_exposures function is not aware of the NeuroML2 component types (since it’s for any LEMS models in general), but this one is.

Parameters
  • nml_doc_fn – NeuroML2 file to list exposures for

  • substring (str) – substring to match for in component names

Returns

dictionary of components and their exposures.

The returned dictionary is of the form:

pyneuroml.pynml.list_recording_paths_for_exposures(nml_doc_fn, substring='', target='')

List the recording path strings for exposures.

This wraps around lems.model.list_recording_paths to list the recording paths in the given NeuroML2 model. The only difference between the two is that the lems.model.list_recording_paths function is not aware of the NeuroML2 component types (since it’s for any LEMS models in general), but this one is.

Parameters
  • nml_doc_fn – NeuroML2 file to list recording paths for

  • substring (str) – substring to match component ids against

Returns

list of recording paths

pyneuroml.pynml.main(args=None)

Main

pyneuroml.pynml.nml2_to_png(nml2_file_name, max_memory='400M', verbose=True)

Generate the PNG representation of a NeuroML model using jnml

Parameters
  • nml2_file_name (str) – name of NeuroML2 file to generate PNG for

  • max_memory (str) – maximum memory allowed for use by the JVM

  • verbose (bool) – toggle whether jnml should print verbose information

pyneuroml.pynml.nml2_to_svg(nml2_file_name, max_memory='400M', verbose=True)

Generate the SVG representation of a NeuroML model using jnml

Parameters
  • nml2_file_name (str) – name of NeuroML2 file to generate SVG for

  • max_memory (str) – maximum memory allowed for use by the JVM

  • verbose (bool) – toggle whether jnml should print verbose information

pyneuroml.pynml.parse_arguments()

Parse command line arguments

pyneuroml.pynml.quick_summary(nml2_doc)

Get a quick summary of the NeuroML2 document

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

Parameters

nml2_doc (NeuroMLDocument) – NeuroMLDocument to fetch summary for

Returns

summary string

pyneuroml.pynml.read_lems_file(lems_file_name, include_includes=False, fail_on_missing_includes=False, debug=False)

Read LEMS file using PyLEMS. See WARNING below.

WARNING: this is a general function that uses PyLEMS to read any files that are valid LEMS even if they are not valid NeuroML. Therefore, this function is not aware of the standard NeuroML LEMS definitions.

To validate NeuroML LEMS files which need to be aware of the NeuroML standard LEMS definitions, please use the validate_neuroml2_lems_file function instead.

pyneuroml.pynml.read_neuroml2_file(nml2_file_name, include_includes=False, verbose=False, already_included=[], optimized=False, check_validity_pre_include=False)

Read a NeuroML2 file into a nml.NeuroMLDocument

Parameters
  • nml2_file_name (str) – file of NeuroML 2 file to read

  • include_includes (bool) – toggle whether files included in NML file should also be included/read

  • verbose (bool) – toggle verbosity

  • already_included (list) – list of files already included

  • optimized (bool) – toggle whether the HDF5 loader should optimise the document

  • check_validity_pre_include (bool) – check each file for validity before including

Returns

nml.NeuroMLDocument object containing the read NeuroML file(s)

pyneuroml.pynml.reload_saved_data(lems_file_name, base_dir='.', t_run=datetime.datetime(1900, 1, 1, 0, 0), plot=False, show_plot_already=True, simulator=None, reload_events=False, verbose=False, remove_dat_files_after_load=False)

Reload data saved from previous LEMS simulation run.

Parameters
  • lems_file_name (str) – name of LEMS file that was used to generate the data

  • base_dir (str) – directory to run in

  • t_run (datetime) – time of run

  • plot (bool) – toggle plotting

  • show_plot_already (bool) – toggle if plots should be shown

  • simulator (str) – simulator that was used to generate data

  • reload_event (bool) – toggle whether events should be loaded

  • verbose (bool) – toggle verbose output

  • remove_dat_files_after_load (bool) – toggle if data files should be deleted after they’ve been loaded

TODO: remove unused vebose argument (needs checking to see if is being used in other places)

pyneuroml.pynml.reload_standard_dat_file(file_name)

Reload a datafile as usually saved by jLEMS, etc. First column is time (in seconds), multiple other columns.

Parameters

file_name (str) – name of data file to load

Returns

tuple of (data, column names)

pyneuroml.pynml.run_jneuroml(pre_args, target_file, post_args, max_memory='400M', exec_in_dir='.', verbose=False, report_jnml_output=True, exit_on_fail=False, return_string=False)

Run jnml with provided arguments.

Parameters
  • pre_args (list of strings) – pre-file name arguments

  • target_file (str) – LEMS or NeuroML file to run jnml on

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • verbose (bool) – toggle whether jnml should print verbose information

  • report_jnml_output (bool) – toggle whether jnml output should be printed

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

  • return_string (bool) – toggle whether the output string should be returned

Returns

either a bool, or a Tuple (bool, str) depending on the value of return_string: True of jnml ran successfully, False if not; along with the output of the command

pyneuroml.pynml.run_jneuroml_with_realtime_output(pre_args, target_file, post_args, max_memory='400M', exec_in_dir='.', verbose=False, exit_on_fail=True)

Run jnml with provided arguments with realtime output.

NOTE: this has only been tested on Linux.

Parameters
  • pre_args (list of strings) – pre-file name arguments

  • target_file (str) – LEMS or NeuroML file to run jnml on

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • verbose (bool) – toggle whether jnml should print verbose information

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

pyneuroml.pynml.run_lems_with_jneuroml(lems_file_name, paths_to_include=[], max_memory='400M', skip_run=False, nogui=False, load_saved_data=False, reload_events=False, plot=False, show_plot_already=True, exec_in_dir='.', verbose=False, exit_on_fail=True, cleanup=False)

Parse/Run a LEMS file with jnml.

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters
  • lems_file_name (str) – name of LEMS file to run

  • paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed

  • nogui (bool) – toggle whether jnml GUI should be shown

  • load_saved_data (bool) – toggle whether any saved data should be loaded

  • reload_events (bool) – toggle whether events should be reloaded

  • plot (bool) – toggle whether specified plots should be plotted

  • show_plot_already (bool) – toggle whether prepared plots should be shown

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • verbose (bool) – toggle whether jnml should print verbose information

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

  • cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

pyneuroml.pynml.run_lems_with_jneuroml_brian2(lems_file_name, paths_to_include=[], max_memory='400M', skip_run=False, nogui=False, load_saved_data=False, reload_events=False, plot=False, show_plot_already=True, exec_in_dir='.', verbose=False, exit_on_fail=True, cleanup=False)

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters
  • lems_file_name (str) – name of LEMS file to run

  • paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed

  • nogui (bool) – toggle whether jnml GUI should be shown

  • load_saved_data (bool) – toggle whether any saved data should be loaded

  • reload_events (bool) – toggle whether events should be reloaded

  • plot (bool) – toggle whether specified plots should be plotted

  • show_plot_already (bool) – toggle whether prepared plots should be shown

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • verbose (bool) – toggle whether jnml should print verbose information

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

  • cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

pyneuroml.pynml.run_lems_with_jneuroml_netpyne(lems_file_name, paths_to_include=[], max_memory='400M', skip_run=False, nogui=False, num_processors=1, load_saved_data=False, reload_events=False, plot=False, show_plot_already=True, exec_in_dir='.', only_generate_scripts=False, verbose=False, exit_on_fail=True, cleanup=False)

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters
  • lems_file_name (str) – name of LEMS file to run

  • paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed

  • nogui (bool) – toggle whether jnml GUI should be shown

  • num_processors (int) – number of processors to use for running NetPyNE

  • load_saved_data (bool) – toggle whether any saved data should be loaded

  • reload_events (bool) – toggle whether events should be reloaded

  • plot (bool) – toggle whether specified plots should be plotted

  • show_plot_already (bool) – toggle whether prepared plots should be shown

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • only_generate_scripts (bool) – toggle whether only the runner script should be generated

  • verbose (bool) – toggle whether jnml should print verbose information

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

  • cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

pyneuroml.pynml.run_lems_with_jneuroml_neuron(lems_file_name, paths_to_include=[], max_memory='400M', skip_run=False, nogui=False, load_saved_data=False, reload_events=False, plot=False, show_plot_already=True, exec_in_dir='.', only_generate_scripts=False, compile_mods=True, verbose=False, exit_on_fail=True, cleanup=False, realtime_output=False)

Run LEMS file with the NEURON simulator

Tip: set skip_run=True to only parse the LEMS file but not run the simulation.

Parameters
  • lems_file_name (str) – name of LEMS file to run

  • paths_to_include (list(str)) – additional directory paths to include (for other NML/LEMS files, for example)

  • max_memory (bool) – maximum memory allowed for use by the JVM

  • skip_run (bool) – toggle whether run should be skipped, if skipped, file will only be parsed

  • nogui (bool) – toggle whether jnml GUI should be shown

  • load_saved_data (bool) – toggle whether any saved data should be loaded

  • reload_events (bool) – toggle whether events should be reloaded

  • plot (bool) – toggle whether specified plots should be plotted

  • show_plot_already (bool) – toggle whether prepared plots should be shown

  • exec_in_dir (str) – working directory to execute LEMS simulation in

  • only_generate_scripts (bool) – toggle whether only the runner script should be generated

  • compile_mods (bool) – toggle whether generated mod files should be compiled

  • verbose (bool) – toggle whether jnml should print verbose information

  • exit_on_fail (bool) – toggle whether command should exit if jnml fails

  • cleanup (bool) – toggle whether the directory should be cleaned of generated files after run completion

  • realtime_output (bool) – toggle whether realtime output should be shown

pyneuroml.pynml.split_nml2_quantity(nml2_quantity)

Split a NeuroML 2 quantity into its magnitude and units

Parameters

nml2_quantity – NeuroML2 quantity to split

Returns

a tuple (magnitude, unit)

pyneuroml.pynml.summary(nml2_doc=None, verbose=False)

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

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

  • verbose (bool) – toggle verbosity

pyneuroml.pynml.validate_neuroml1(nml1_file_name, verbose_validate=True, return_string=False)

Validate a NeuroML v1 file.

NOTE: NeuroML v1 is deprecated. Please use NeuroML v2. This functionality will be dropped in the future.

Parameters
  • nml1_file_name (str) – name of NeuroMLv1 file to validate

  • verbose_validate (bool (default: True)) – whether jnml should print verbose information while validating

  • return_string (bool) – toggle to enable or disable returning the output of the jnml validation

Returns

Either a bool, or a tuple (bool, str): True if jnml ran without errors, false if jnml fails; along with the message returned by jnml

pyneuroml.pynml.validate_neuroml2(nml2_file_name, verbose_validate=True, max_memory=None, return_string=False)

Validate a NeuroML2 file using jnml.

Params nml2_file_name

name of NeuroML 2 file to validate

Parameters
  • verbose_validate (bool (default: True)) – whether jnml should print verbose information while validating

  • max_memory (str) – maximum memory the JVM should use while running jnml

  • return_string (bool) – toggle to enable or disable returning the output of the jnml validation

Returns

Either a bool, or a tuple (bool, str): True if jnml ran without errors, false if jnml fails; along with the message returned by jnml

pyneuroml.pynml.validate_neuroml2_lems_file(nml2_lems_file_name, max_memory='400M')

Validate a NeuroML 2 LEMS file using jNeuroML.

Note that this uses jNeuroML and so is aware of the standard NeuroML LEMS definitions.

TODO: allow inclusion of other paths for user-defined LEMS definitions (does the -norun option allow the use of -I?)

Parameters
  • nml2_lems_file_name (str) – name of file to validate

  • max_memory (str) – memory to use for the Java virtual machine

Returns

True if valid, False if invalid

pyneuroml.pynml.write_lems_file(lems_model, lems_file_name, validate=False)

Write a lems_model.Model to file using pyLEMS.

Parameters
  • lems_model (lems_model.Model) – LEMS model to write to file

  • lems_file_name (str) – name of file to write to

  • validate (bool) – toggle whether written file should be validated

pyneuroml.pynml.write_neuroml2_file(nml2_doc, nml2_file_name, validate=True, verbose_validate=False)

Write a NeuroMLDocument object to a file using libNeuroML.

Parameters
  • nml2_doc (NeuroMLDocument) – NeuroMLDocument object to write to file

  • nml2_file_name (str) – name of file to write to

  • validate (bool) – toggle whether the written file should be validated

  • verbose_validate (bool) – toggle whether the validation should be verbose

Module contents