Axon models

OSS-DBSv2 supports pathway-based analyses in which extracellular fields are sampled along trajectories and then coupled to axon models. This extends the workflow beyond field simulation toward estimates of neural pathway activation.

Workflow overview

A typical pathway-based workflow consists of:

  1. generating or importing pathway trajectories

  2. evaluating the extracellular solution along those pathways

  3. mapping the sampled signal to a neuron model

  4. computing activation-related outputs

This part of the software is more specialized than the basic volume conductor workflow, but it becomes essential when the scientific question focuses on which pathways are activated rather than only how far the field spreads.

Implemented model families

The codebase includes morphology handling for models such as MRG2002 and McNeal1976, together with a neuron-simulation abstraction for running pathway activation analyses.

When to use this part of the toolbox

  • use it when tract-based activation is a central study outcome

  • skip it for a first validation run focused only on electric fields or basic VTA-like analyses

  • treat it as a separate workflow layer that builds on a correct and stable volume conductor setup

API reference

Axon models

class ossdbs.axon_processing.axon_models.AxonModels(stim_dir: str, hemis_idx: int, description_file: str)[source]

Bases: object

Model to represent axons for simulation in OSS-DBS.

property axon_model

Name of the axon model.

property combined_h5_file

Name of final HDF5 file.

convert_fibers_to_axons()[source]

Seed axons iterating over all pathways.

property stim_dir

Stimulation directory, where all files are to be found.

class ossdbs.axon_processing.axon_models.AxonMorphology(downsampled=False)[source]

Bases: ABC

Axon morphology class.

property axon_length

Length of axon.

property downsampled

Full or downsampled model.

property fiber_diam

Fiber diameter.

abstract get_local_compartment_coords(axon_morphology)[source]

Get 1-D coordinates of internodal compartments relative to the node at 0.0.

Return type:

numpy.ndarray

property n_Ranvier

Number of nodes of Ranvier compartments.

property n_comp

Number of compartments.

property n_segments

Number of segments.

abstract property node_step

Node step.

abstract update_axon_morphology(axon_diam, axon_length=None, n_Ranvier=None)[source]

Axon morphology for specific model.

class ossdbs.axon_processing.axon_models.AxonMorphologyMRG2002(downsampled=False)[source]

Bases: AxonMorphology

Axon morphology for MRG2002 model.

get_local_compartment_coords() → ndarray[source]

Get 1-D coordinates of internodal compartments relative to the node at 0.0.

Parameters:

axon_morphology (dict) – geometric description of a single axon

Return type:

Nx1 numpy.ndarray

get_n_comp(downsampled)[source]

Get number of compartments depending on sampling.

get_n_segments(downsampled)[source]

Get number of segments depending on sampling.

property inter_nodes

Number of internodal compartments.

property n_Ranvier

Number of nodes of Ranvier compartments.

property n_comp

Number of compartments.

property n_para1

Number of all 1st paranodal compartments.

property n_para2

Number of all 2nd paranodal compartments.

property node_step

Node step.

property para1_length

Length of the 1st paranodal compartments.

property para1_nodes

Number of first paranodal compartments.

property para2_length

Length of the 2nd paranodal compartments.

property para2_nodes

Number of 2nd paranodal compartments.

property ranvier_length

Length of Ranvier compartment.

property ranvier_nodes

Number of node of Ranvier compartments.

update_axon_morphology(fiber_diam: float, axon_length: float | None = None, n_Ranvier: int | None = None) → dict[source]

Get geometric description of a single axon.

Parameters:

  • fiber_diam (float) – diameter in micrometers for all fibers in the pathway

  • axon_length (float, optional) – axon lengths in mm for all fibers in the pathway

  • n_Ranvier (int, optional) – number of nodes of Ranvier per axon.

Return type:

dict

Notes

Either axon_length or n_Ranvier needs to be specified.

class ossdbs.axon_processing.axon_models.AxonMorphologyMcNeal1976(downsampled=False)[source]

Bases: AxonMorphology

Axon morphology class for the McNeal1976 model.

property downsampled

Full or downsampled model.

get_local_compartment_coords()[source]

Get 1-D coordinates of internodal compartments relative to the node at 0.0.

Return type:

Nx1 numpy.ndarray

property n_comp

Only nodes and one internodal per segment.

property node_step

Node step.

update_axon_morphology(fiber_diam: float, axon_length: float | None = None, n_Ranvier: int | None = None) → dict[source]

Get geometric description of a single axon.

Parameters:

  • fiber_diam (float) – diameter in micrometers for all fibers in the pathway

  • axon_length (float, optional) – axon lengths in mm for all fibers in the pathway

  • n_Ranvier (int, optional) – number of nodes of Ranvier per axon.

Return type:

dict

Notes

Either axon_length or n_Ranvier needs to be specified.

Neuron simulator

class ossdbs.axon_processing.neuron_model.MRG2002(pathways_dict: dict, output_path: str, scaling_vector: list | None = None)[source]

Bases: NeuronSimulator

MRG2002 NEURON model.

modify_hoc_file(nRanvier, stepsPerMs, axon_morphology)[source]

Update parameters in the hoc file.

paste_to_hoc(parameters_dict: dict) → None[source]

Update the hoc file with parameters.

property resources_path

Link to template NEURON files.

upsample_voltage(v_time_sol, axonDiam, axon_morphology)[source]

Upsample potential distribution for downsampled neurons by interpolating.

Parameters:

  • v_time_sol (numpy.ndarray) – LxM potential distribution (in V) in space (on the neuron) and time (DBS signal)

  • axonDiam (float) – Diameter of axon

  • axon_morphology (AxonMorphology) – Model of axon morphology

Returns:

v_time_sol_full

Return type:

NxM numpy.ndarray

Notes

TODO estimate ratios directly from the morphology TODO refactor code

class ossdbs.axon_processing.neuron_model.McNeal1976(pathways_dict: dict, output_path: str, scaling_vector: list | None = None)[source]

Bases: NeuronSimulator

McNeal1976 NEURON model.

modify_hoc_file(nRanvier, stepsPerMs, axon_morphology)[source]

Update parameters in the hoc file.

paste_to_hoc(parameters_dict)[source]

Update the hoc file with parameters.

property resources_path

Link to template NEURON files.

class ossdbs.axon_processing.neuron_model.NeuronSimulator(pathways_dict: dict, output_path: str, scaling_vector: list | None = None)[source]

Bases: ABC

Interface to NEURON simulator.

property axon_model

Name of axon model.

check_pathway_activation(pathway_dataset, pathway_idx, pathway_name=None, scaling_index=None)[source]
Parallelized probing of action potentials at all stimulated neurons

(axons) described by supplied pathway datagroups.

Parameters:

  • pathway_dataset (h5 group) – contains datasets that describe geometries for all neuron (axons)

  • pre_status (numpy.ndarray) – vector of initial neuron (axon) statuses (0: available for probing, -1: intersected with electrode, -2: inside CSF)

  • pathway_name (str, optional) – Name of pathway

  • pathway_idx (int) – Index of pathway

  • scaling_index (int, optional) – Index of scaling (needed for superposition)

Note

Creates ‘Axon_states_*’ .mat and .csv files for visualization in Lead-DBS and Paraview, respectively. Also stores summary statistics in ‘Pathway_status_*.json’

compile_neuron_files()[source]

Compile a NEURON file.

property connectome_name

Name of connectome.

copy_neuron_files()[source]

Copy files from template folder to local folder.

property downsampled: bool

Return if model is downsampled.

get_N_orig_neurons(idx: int)[source]

Get the number of original neurons.

get_N_seeded_neurons(idx: int)[source]

Get the number of seeded neurons.

get_axon_diam(idx: int)[source]

Return the axon/fiber diameters.

get_n_Ranvier(idx: int)[source]

Get the number of nodes of Ranvier.

get_v_ext(v_time_sol)[source]

Convert potential computed by OSS-DBS to extracellular potential.

Parameters:

v_time_sol (numpy.ndarray) – NxM potential distribution (in V) in space (on the neuron) and time (DBS signal)

Returns:

v_ext – NxM extracellular potential distribution (mV) in space (on the neuron) and time (DBS signal)

Return type:

numpy.ndarray

Notes

Scaling is taken into account!

property hoc_file

Name of hoc file.

load_solution(time_domain_h5_file: str)[source]

Load solution from h5 file.

Parameters:

time_domain_h5_file (str) – Name of file holding time-domain solution

Returns:

td_solution – Time-domain solution

Return type:

h5 dataset

load_unit_solutions(time_domain_h5_files: list)[source]

Load solutions from h5 file for each contact-ground.

Parameters:

time_domain_h5_files (list) – names of files holding time-domain solution

Returns:

td_unit_solutions – unit time-domain solutions for each contact

Return type:

list

abstract modify_hoc_file(nRanvier, stepsPerMs, axon_morphology)[source]

Update parameters in the hoc file.

property neuron_executable: str

Name of the NEURON executable.

property output_path

Output path to save results.

abstract paste_to_hoc(parameters_dict: dict)[source]

Paste Python parameters into HOC file.

property pathways_dict

Information about pathways.

process_pathways(td_solution, scaling: float = 1.0, scaling_index: int | None = None)[source]

Go through all pathways and compute the activation.

Parameters:

  • td_solution (h5 dataset) – time-domain solution

  • scaling (float) – scaling factor for the whole solution

  • scaling_index (int) – index of the scaling factor or scaling vector

property resources_path

Path were NEURON templates are stored.

run_NEURON(v_ext: ndarray, extra_initialization: bool = False) → bool[source]

Load a NEURON model and run simulation.

Parameters:

  • v_ext (np.ndarray) – NxM extracellular potential distribution in mV (N: neuron, M: time)

  • extra_initialization (bool) – Delete and create nodes (needed for MRG2002 model)

property signal_dict

Information about stimulation signal.

superimpose_unit_solutions(td_unit_solutions, scaling_vector: list)[source]

Scale and superimpose solutions obtained for each contact-ground. This should be done across all datagroups and datasets.

Parameters:

  • td_unit_solutions (list) – unit time-domain solutions for each contact

  • scaling_vector (list) – current scaling across contacts

Returns:

td_solution – Superimposed and scaled time-domain solution

Return type:

h5 dataset