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.
- Parameters:
path (str or None) – path of directory relative to current working directory to extract to, or None
- Returns:
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)
A few notes about this utility function:
it expects cells to be “flattened” and complete, i.e., they should contain their own morphologies and not refer to other “standalone” morphology elements. You can use the
neuroml.utils.fix_external_morphs_biophys_in_cell()
function in the libNeuroML package to flatten cell models.if the NeuroMLDocument contains cells, it will only process those and ignore any standalone Morphology elements. Only if the document has no cells will it attempt to process morphologies by placing them in dummy cells and networks.
- Parameters:
nml_model (NeuroMLDocument) – NeuroML2 model to extract position information from
verbose (bool) – toggle function verbosity
- Returns:
[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.
- Parameters:
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)
- Returns:
colour in hex representation
- Return type:
str
- pyneuroml.utils.get_files_generated_after(timestamp: float = 1734539190.6789024, 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.
- Parameters:
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)
- Returns:
list of file names
- Return type:
list(str)
- 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.
- Parameters:
ion (str) – name of ion
- Returns:
colour in hex
- Return type:
str
- 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.
- Parameters:
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
- Returns:
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.
- Raises:
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}
- Parameters:
rootdir (str) – root directory where to create the new directory
prefix (str) – prefix for directory name
- Returns:
generated directory name
- Return type:
str
- 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.
- Parameters:
state (str) – name of state
- Returns:
colour in hex format
- Return type:
str
- pyneuroml.utils.make_cell_upright(cell: Cell = None, inplace: bool = False) Cell #
Use cell’s PCA to make it upright
Added in version 1.2.13.
- Parameters:
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)
- Returns:
new neuroml.Cell object
- Return type:
neuroml.Cell
- 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.
- Parameters:
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)
- Returns:
new neuroml.Cell object
- Return type:
neuroml.Cell
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.
- Parameters:
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
- Returns:
new neuroml.Cell object
- Return type:
neuroml.Cell
pyneuroml.utils.info module#
Utilities for getting information from NeuroML models
File: pyneuroml/utils/info.py
Copyright 2024 NeuroML contributors
- pyneuroml.utils.info.cell_info(cell: 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
- Parameters:
cell (Cell) – cell object to investigate
- Returns:
string of cell information
- pyneuroml.utils.info.cells_info(nml_file_name: str) str #
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.utils.info.quick_summary(nml2_doc: NeuroMLDocument) str #
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.utils.info.summary(nml2_doc: NeuroMLDocument | None = None, verbose: bool = False) None #
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.utils.plot module#
Common utils to help with plotting
File: pyneuroml/utils/plot.py
Copyright 2023 NeuroML contributors
- class pyneuroml.utils.plot.LineDataUnits(*args, **kwargs)#
Bases:
Line2D
New Line class for making lines with specific widthS
- Reference:
https://stackoverflow.com/questions/19394505/expand-the-line-with-specified-width-in-data-unit
- 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
- Properties:
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 or ~matplotlib.figure.SubFigure 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.
- Parameters:
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
- Returns:
None
- pyneuroml.utils.plot.add_line_to_matplotlib_2D_plot(ax, xv, yv, width, color, axis_min_max)#
Add a line to a matplotlib plot
- Parameters:
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.
- Parameters:
axis_min_max ([float, float]) – minimum, maximum value in plot
ax (matplotlib.axes.Axes) – axis to plot scalebar at
- Returns:
None
- 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.
- Parameters:
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
- Parameters:
verbose (bool) – toggle verbosity
square (bool) – toggle squaring of plot
- Returns:
None
- pyneuroml.utils.plot.get_cell_bound_box(cell: Cell)#
Get a boundary box for a cell
- Parameters:
cell (neuroml.Cell) – cell to get boundary box for
- Returns:
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.
- Parameters:
title (str) – title of plot
plane2d – plane to use
- Returns:
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.
- Parameters:
my_random (random.Random) – a random.Random object
- Returns:
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.
- Parameters:
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/misc.py
Copyright 2024 NeuroML contributors
- pyneuroml.utils.misc.get_path_to_jnml_jar() str #
Get the path to the jNeuroML jar included with PyNeuroML.
- Returns:
path of jar file
pyneuroml.utils.cli module#
Utilities use in writing console scripts.
File: pyneuroml/utils/cli.py
Copyright 2023 NeuroML contributors
pyneuroml.utils.units module#
Methods related to units.
File: pyneuroml/utils/units.py
Copyright 2024 NeuroML contributors
- pyneuroml.utils.units.convert_to_units(nml2_quantity: str, unit: str) float #
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.utils.units.get_lems_model_with_units() Model #
Get a LEMS model with NeuroML core dimensions and units.
- Returns:
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
- Parameters:
nml2_quantity (str) – NeuroML2 quantity to convert
- Returns:
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
- Parameters:
nml2_quantity – NeuroML2 quantity to split
- Returns:
a tuple (magnitude, unit)
pyneuroml.utils.xml module#
Utility methods related to xml processing
File: pyneuroml/utils/xml.py
Copyright 2024 NeuroML contributors