Python API

eden-simulator

EDEN bindings and helpers for Python.

runEden(example_lems_file, *, reload_events=False, verbose=False, threads=None, extra_cmdline_args=None, full_cmdline=None, executable_path=None)[source]

Run a NeuroML2/LEMS file with EDEN.

Parameters:

  • example_lems_file (str) – The filename where the <Simulation> to run is located.

  • reload_events (bool, optional) –

    Whether to return a:

    • dict with the recorded time series, mapping each recorded <LemsQuantityPath> to its sampled values over time. All samples are taken at the same points in time, represented by the additional time vector t in seconds.

    • or a pair of dict s, the first as before and the second mapping each recorded event to its times of occurrence.

  • threads (int, optional) – The number of threads to run the simulation with, or None for automatic selection.

  • verbose (bool, optional) – Add some more console output when running the simulator.

  • extra_cmdline_args (list[str], optional) – Additional command line arguments to pass to EDEN. Refer to the EDEN user’s manual, “Command line API” for more details.

  • full_cmdline (list[str], optional) – Specify the exact argv to be passed to EDEN. Refer to the EDEN user’s manual, “Command line API” for more details.

  • executable_path (str, optional) – Select a specific executable of EDEN to run the simulation with. Useful for custom installations and uses of EDEN.

Returns:

  • trajectories (dict[str, numpy.ndarray[float[n]]]) – when reload_events == False

  • (trajectories, events) (tuple(dict, dict)) – when reload_events == True; see reload_events parameter.

Notes

All values are returned in SI units, or derived thereof.

  • e.g. concentration is in mol/m³, not mol/L !

Refer to https://en.wikipedia.org/wiki/SI_derived_unit for a list of such units.

Display API

eden_simulator.display.animation

GetAutoFps(anim_axis, max_auto_fps=60)[source]

Get an appropriate update frequency for a time series.

subsample_trajectories(time_axis_sec, data=[], animation_speed=0.003, animation_frames_per_second=30)[source]

Subsample a set of time series for animated real-time display.

Parameters:

  • time_axis_sec (np.array[float]) – The timebase for the given time series, in seconds.

  • data (array) – A series by time array of values. Length of time must be same as time_axis_sec.

  • animation_speed (float) – The ratio of how fast the time series is played back, relative to time_axis_sec.

  • animation_frames_per_second (float) – The desired sampling rate for the animation. The time series are subsampled but not interpolated, thus the true frame rate may vary.

Returns:

  • samples_picked (np.array[int]) – The samples used from the provided sequence data. Useful for resampling other time series similar to data. May be less than expected if there are not enough samples to fill the grid.

  • anim_axis (np.array[float]) – Animation-time for each picked sample.

  • sampled_time_axis (np.array[float]) – Original timebase for each picked sample. Equals time_axis_sec[samples_picked].

  • sampled_data (list[list]) – Sub-sampled data. Equals data[samples_picked].

eden_simulator.display.spatial

Utilities for displaying solid neurons in euclidean space.

get_mesh_info(cell_info)[source]

Convert the ‘explain cell’ format to mappings from compartments to corresponding vertices and faces of the mesh.

Parameters:

cell_info (dict) – The information for a cell type, provided by an element of eden_simulator.experimental.explain_cell

Returns:

(mesh_vertices, mesh_faces, mesh_comp_per_face, n_comps) – The selected mesh-specific subset of cell_info.

Return type:

tuple

get_verts_faces_per_comp(mesh_vertices, mesh_faces, mesh_comp_per_face, n_comps)[source]

Convert the mesh information generated by get_mesh_info to per-vertex and per-face mappings to/from associated compartments.

Parameters:

eden_simulator.experimental.explain_cell. (As returned by get_mesh_info and ultimately)

Returns:

  • (mapped_verts, mapped_faces, verts_per_comp, faces_per_comp) (tuple)

  • mapped_verts (function) – A function receiving a 2-D numpy.array, and returning the linear combination of its columns as per verts_per_comp.

  • verts_per_comp (scipy.spmatrix) – A sparse matrix with the neuron mesh’s vertices as rows and associated compartments as columns. TODO

  • mapped_verts (function)

  • verts_per_comp (scipy.spmatrix) – Similar to the previous but mapping compartments to mesh faces. TODO

eden_simulator.display.spatial.k3d

Straightforward display of neurons with [K3D]( https://k3d-jupyter.org ).

DeduceColormap(colormap)[source]

Try to deduce a K3D colormap from the passed argument.

See also

Colormaps

k3d.helpers.map_colors()

IntToRgb(hex)[source]

K3D style packed integer array hex to … x 3 rgb array.

MinimizePlot(plot, more_objects=[])[source]

Minimise the state of a K3D plot widget.

Useful for publishing notebooks with K3D plots, when a snapshot is preferable to the fragile ipywidgets machinery and uncompressed widget_state. TODO :param plot: The plot to minimise. :type plot: k3d.Plot :param more_objects: :type more_objects: list[k3d.]

class Plot(*args: t.Any, **kwargs: t.Any)[source]

A subclass of k3d.Plot with augmented display capabilities.

To be used with extended elements such as plot_neuron, along with the usual k3d display elements.

__init__(*args, **kwargs)[source]

Public constructor

display(**kwargs)[source]

Show plot inside ipywidgets.Output().

get_snapshot(compression_level=9, voxel_chunks=[], additional_js_code='', **kwargs)[source]

Produce on the Python side a HTML document with the current plot embedded.

show_html(snapshot_type='inline', **kwargs)[source]

Show a snapshot of the plot as an ipynb displayable.

Parameters:

  • snapshot_type (str) – The snapshot_type to use in capturing.

  • kwargs (dict) – Other arguments to pass to get_snapshot().

RgbToInt(rgb)[source]

Convert … x 3 rgb array to K3D style packed ints.

decompress_cells(k3d_mesh)[source]

Revert per-cell compression to normal mode.

plot_neuron(cell_info, comp_values=(0.5, 0.5, 0.5), time_axis_sec=None, color_map=None, compress_cells=True, **kwargs)[source]

Plot a neuron mesh with K3D, optionally coloured and animated. For use with Plot. TODO

Parameters:

  • vertices (Nx3 float array)

  • faces (Mx3 int array)

  • comp_per_face (M float vector) – The compartment that each face belongs to.

  • comp_values –

    The values per compartment:

    • K x 3:

  • nah (ndarray of float K x C or T x K or T x K x C or K or C (or T x c?)) –

    The values per compartment:

    • K x 3:

  • colormap – . Cannot be used with RGB values.

  • time_axis_sec (T float array)

  • well... (need time per sec as)

  • kwargs (dict) – Additional parameters to pass through to k3d.mesh.

Returns:

mesh

Return type:

k3d.mesh

eden_simulator.display.spatial.pyvista

Display helpers for [PyVista]( https://pyvista.org ).

get_neuron_mesh(cell_info)[source]

Get a PyVista mesh, colourable per compartment.

Parameters:

cell_info (dict[str]) – A dict containing ‘mesh_vertices’, ‘mesh_faces’ and ‘mesh_comp_per_face’ describing a neuron’s 3-D mesh, as produced by by eden_simulator.experimental.explain_cell.

Returns:

mesh – A 3D mesh which can be assigned scalars per compartment.

Return type:

pyvista.UnstructuredGrid

Experimental API

Additional facilities to use EDEN’s experimental features from within Python.

NOTE: As the experimental features are still in design, parts of this API may change between versions!

GetLemsLocatorsForCell(cell_info, compartment_ids=None)[source]

Generate a list of (extended) LEMS locators to access a property all over a cell.

Parameters:

  • cell_info (dict) – The discretisation information about the cell, as returned from eden_simulator.experimental.explain_cell.

  • compartment_ids (iterable) – A specific list of compartments to access (by default all over the cell)

Returns:

l – The list of locators, to be used in extended LEMS paths capturing the cell property.

Return type:

list[str]

See also

eden_simulator.experimental.explain_cell: For obtaining cell_info. LEMS paths for cell locations : For LEMS segment locators including fractionAlong. NeuroML and spatially detailed cells: To lean more about spatially detailed cells.

explain_cell(nml_file, *, verbose=False, threads=None, extra_cmdline_args=None, executable_path=None, full_cmdline=None, **kwargs)[source]

Get more information about the structure and properties of physically-modelled cells.

Parameters:

  • nml_file (str) – The main NeuroML file (and the ones it <include>s) to consider.

  • verbose (bool, optional) – Add some more console output when running the simulator.

  • threads (int, optional) –

    The number of threads to run processing with, or None for automatic selection. (Does not have an effect in this case yet.)

    ⠀

    The following parameters are less commonly used:

  • mesh_prism_sides_count (int, optional) – A fixed number of sides for the meshes of the tubular sections comprising the neurons’ morphologies. Must be 3 or more. Defaults to 5.

  • extra_cmdline_args (list[str], optional) – Additional command line arguments to pass to EDEN. Refer to the EDEN user’s manual, “Command line API” for more details.

  • full_cmdline (list[str], optional) – Specify the exact argv to be passed to EDEN. Refer to the EDEN user’s manual, “Command line API” for more details.

  • executable_path (str, optional) – Select a specific executable of EDEN to run the simulation with. Useful for custom installations and uses of EDEN.

Returns:

  • info (dict[str, dict]) – The requested information, keyed by cell type name.

Notes

For physical (i.e. not artificial) cells:

Each keyed entry of info may have the following dict entries:

'comp_parent': ndarray[(n_comps), int]

The tree parent of each compartment. The first value, that represents the root (as modelled) of the neuron, is -1.

'comp_start_pos': ndarray[(n_comps, 3), float]

The position of the most proximal end of each compartment.

'comp_end_pos': ndarray[(n_comps, 3), float]

The position of the most distal end of each compartment.

'comp_midpoint': ndarray[(n_comps, 3), float]

The 3-D position coordinates of the midpoint of each compartment, relative to the morphology’s origin. NB: Due to curvature it may not lay exactly between comp_start_pos and ‘comp_end_pos’, or on the line joining them.

'comp_midpoint_segment': ndarray[(n_comps), int]

The NeuroML <segment> containing the midpoint of each compartment.

'comp_midpoint_fractionAlong': ndarray[(n_comps), float]

The 0-to-1, proximal-to-distal, NeuroML <segment> position where each compartment lies on its comp_midpoint_segment.

'comp_length': ndarray[(n_comps), float]

The length of the neurite cable belonging to each compartment. NB: Due to curvature and explicit discontinuities this may be more or less than the straight-line distance between comp_start_pos and comp_end_pos.

'comp_path_length_from_root': ndarray[(n_comps), float]

The distance from the neuron’s root tracing back the anatomical path, in microns. Some biophysical attributes track this distance.

'comp_area': ndarray[(n_comps), float]

The total membrane area per compartment, in μm².

'comp_volume': ndarray[(n_comps), float]

The total enclosed volume per compartment, in μm³.

'comp_capacitance': ndarray[(n_comps), float]

The total membrane capacitance per compartment, in pF.

'comp_conductance_to_parent': ndarray[(n_comps), float]

The electrical cytosolic conductance between each compartment and its tree parent, in nS. The first value for the tree root is zero (not applicable).

'segment_groups': dict[str, dict]

Details about each NeuroML segment group, keyed by name.

Each keyed entry of segment_groups may have the following dict entries:

  • 'comps': The numbered compartments included in the segment group.

  • 'cable_compartments': Same as above but in guaranteed parent-to-child order, for [“unbranched cable” groups]( intro_spatial.ipynb#The-unbranched-section-directive ).

  • 'cable_comps_fraction_along': The position along the entire cable for the corresponding cable_compartments, where 0 represents the start and 1 the end of the cell. Useful for porting NEURON models with variability over cell “sections”.

'mesh_vertices': ndarray[(n_verts, 3), float]

The vertex coordinates of the 3-D mesh representing the neuron, in microns.

'mesh_faces': ndarray[(n_faces, 3), int]

The triangles of 0-indexed vertices forming the neuron’s 3-D mesh.

'mesh_comp_per_face': ndarray[n_faces, int] (optional)

The neuron compartment that each triangle of the mesh maps to.

Useful for selectively colouring relevant regions of the neuron, and displaying the neuron in false colour.

NB: It is present when discretisation is available for the selected mesh generation method.

For physical cells, most entries have as many values as there are compartments. Spatial attributes (position coordinates, distance, and such) are given in microns following the NeuroML convention.

For thinking of the neuron as a “tree” data structure, refer to: