bluecellulab.cell.morphio_wrapper

Morphology loader and HOC code generator built on top of MorphIO.

Provides soma-geometry helpers that mirror NEURON’s import3d_gui.hoc logic, plus MorphIOWrapper which loads a morphology from disk (or from an H5 container), adjusts the soma geometry, and produces the HOC commands needed to instantiate the cell in NEURON.

Adapted from neurodamus/morphio_wrapper.py.

Functions

contour2centroid(mean, points)

Convert a soma contour into a stack of cylinders.

contourcenter(xyz)

Resample a soma contour and return its centroid.

get_sides(points, major, minor)

Split a centred contour into two sides along the major axis.

is_h5_container_path(path)

make_convex(sides, rads)

Remove non-convex points from both sides of the contour.

resolve_case_insensitive_path(path)

single_point_sphere_to_circular_contour(neuron)

Convert a single-point sphere soma to an equivalent circular contour.

split_morphology_path(morphology_path)

Split a morphology path into collection directory, name, and extension.

Classes

MorphIOWrapper(input_file[, options])

Load a MorphIO morphology and generate HOC instantiation commands.

SectionName(name, id)

A simple container to uniquely identify a NEURON Section by name and ID.
class bluecellulab.cell.morphio_wrapper.MorphIOWrapper(input_file, options=0)[source]

Load a MorphIO morphology and generate HOC instantiation commands.

Given a morphology path (plain file or H5-container entry of the form container.h5/cell_name), this class:

  1. Resolves the path via split_morphology_path().

  2. Loads the morphology through morphio.Collection with Option.nrn_order to match NEURON’s section ordering.

  3. Adjusts the soma geometry to match import3d_gui.hoc: sphere → circular contour; contour → stack of cylinders.

  4. Builds the section-name list and type-ID distribution used to emit HOC commands.

The main entry point is morph_as_hoc(), which returns the list of HOC commands needed to instantiate the cell in NEURON.

classmethod mksubset(type_id, type_name)[source]

Return the HOC command that appends sections to their subset list.

Parameters:

  • type_id – Integer section-type identifier (1 = soma, 2 = axon, 3 = dend, 4 = apic).

  • type_name – HOC section-name string as returned by type2name().

Returns:

HOC command string of the form 'forsec "<type_name>" <subset>.append'.

morph_as_hoc()[source]

Generate HOC commands to instantiate the cell in NEURON.

Produces the same output as NEURON’s import3d_gui.hoc, covering:

  1. create commands for each section type and its SectionList subset (somatic, axonal, basal, apical).

  2. forall all.append to populate the global all SectionList.

  3. pt3dadd calls for soma points (in reverse order to match NEURON’s convention).

  4. connect and pt3dadd calls for every other section.

Returns:

List of HOC command strings, each executable via neuron.h(cmd) or joinable into a single block.

classmethod type2name(type_id)[source]

Return the HOC section-name string for a MorphIO type ID.

Parameters:

type_id – Integer section-type identifier (1 = soma, 2 = axon, 3 = dend, 4 = apic).

Returns:

Section-name string from the standard mapping, or "minus_<n>" for negative type IDs and "dend_<n>" for unknown positive ones.

class bluecellulab.cell.morphio_wrapper.SectionName(name, id)[source]

A simple container to uniquely identify a NEURON Section by name and ID.

name

The name of the section (e.g., “soma”, “dend”, etc.). This corresponds to the section’s logical type or label.

Type:

str

id

The index of the section among all sections with the same name. For example, in a list of dendrites, this would identify dend[0], dend[1], etc.

Type:

int

Example

For NEURON’s soma[0], the corresponding SectionName would be:

SectionName(name=”soma”, id=0)

This allows unique referencing even in models where multiple sections have the same base name.

Parameters:

  • name (str)

  • id (int)

bluecellulab.cell.morphio_wrapper.contour2centroid(mean, points)[source]

Convert a soma contour into a stack of cylinders.

Python port of contour2centroid in lib/hoc/import3d/import3d_gui.hoc. The algorithm:

  1. Fits an ellipsoid to the centred contour to find the major and minor axes via eigen-decomposition.

  2. Splits the contour into two sides along the major axis and enforces convexity.

  3. Resamples both sides to 21 evenly-spaced points along the major axis and computes cylinder diameters from the two radial profiles.

Parameters:

  • mean – (3,) centroid of the contour as returned by contourcenter().

  • points – (101, 3) resampled contour points (second element returned by contourcenter()).

Returns:

A tuple (points, diameters) where points is a (21, 3) array of cylinder centre positions along the major axis and diameters is a (21,) array of cylinder diameters.

bluecellulab.cell.morphio_wrapper.contourcenter(xyz)[source]

Resample a soma contour and return its centroid.

Python port of contourcenter in lib/hoc/import3d/import3d_sec.hoc. Resamples the contour to 101 evenly-spaced points along its perimeter using linear interpolation and returns both the centroid and the resampled points.

Parameters:

xyz – (N, 3) array of soma contour point coordinates.

Returns:

A tuple (mean, new_xyz) where mean is the (3,) centroid of the resampled contour and new_xyz is the (101, 3) array of resampled points.

bluecellulab.cell.morphio_wrapper.get_sides(points, major, minor)[source]

Split a centred contour into two sides along the major axis.

Rotates the point array so the maximum major-axis coordinate is last, then splits at the minimum into a left and right side (each in ascending major-axis order). Corresponds to line 1191 of lib/hoc/import3d/import3d_gui.hoc.

Parameters:

  • points – (N, 2) array of contour points centred at the origin.

  • major – Unit vector of the major (longest) axis of the ellipsoid fitted to the soma contour.

  • minor – Unit vector of the minor axis (constrained to the XY plane).

Returns:

A tuple (sides, rads) where each is a length-2 list containing the major-axis coordinates and the minor-axis (radial) coordinates of the two sides respectively.

bluecellulab.cell.morphio_wrapper.make_convex(sides, rads)[source]

Remove non-convex points from both sides of the contour.

Enforces monotonicity on each side so that the resulting outline is convex. Points that break convexity are discarded together with their corresponding radial values.

Parameters:

  • sides – Length-2 list of major-axis coordinate arrays for the two contour sides, as returned by get_sides().

  • rads – Length-2 list of minor-axis (radial) coordinate arrays, parallel to sides.

Returns:

(sides, rads) with non-convex points removed.

bluecellulab.cell.morphio_wrapper.single_point_sphere_to_circular_contour(neuron)[source]

Convert a single-point sphere soma to an equivalent circular contour.

NEURON’s import3d_gui.hoc converts single-point sphere somas to circular contours so that contour2centroid() can process them uniformly. This function applies the same transformation.

Parameters:

neuron – Mutable MorphIO morphology with a single-point sphere soma. Modified in place.

bluecellulab.cell.morphio_wrapper.split_morphology_path(morphology_path)[source]

Split a morphology path into collection directory, name, and extension.

Handles two cases:

  • Regular file on disk (path exists): uses os.path.dirname for the collection directory and os.path.splitext for the name and extension.

  • H5 container entry (path does not exist on disk): walks up via os.path.dirname until an existing filesystem entry (the container) is found, then derives the cell name and extension relative to it.

Parameters:

morphology_path – Path to a morphology file, or to a cell entry inside an H5 container (e.g. /data/merged.h5/cell_name.h5).

Returns:

A tuple (collection_dir, morph_name, morph_ext) where collection_dir is the directory or container path, morph_name is the bare name without extension, and morph_ext is the file extension (e.g. ".h5").

Raises:

BluecellulabError – If no existing filesystem entry is found while walking up the path.