olfactorybulb.slicebuilder

This is the main class where NEURON cells are imported into Blender, where they are positioned and oriented within bulbar layers. Transformed cell coordinates are saved for later instatiation by NEURON during simulations. Synapse locations are identified and saved into synapse set files.

class olfactorybulb.slicebuilder.blender.SliceBuilderBlender(odors=['Apple'], slice_object_name='DorsalColumnSlice', max_mcs=10, max_tcs=None, max_gcs=300, mc_particles_object_name='2 ML Particles', tc_particles_object_name='1 OPL Particles', gc_particles_object_name='4 GRL Particles', glom_particles_object_name='0 GL Particles', glom_layer_object_name='0 GL', outer_opl_object_name='1 OPL-Outer', inner_opl_object_name='1 OPL-Inner')

Bases: object

__init__(odors=['Apple'], slice_object_name='DorsalColumnSlice', max_mcs=10, max_tcs=None, max_gcs=300, mc_particles_object_name='2 ML Particles', tc_particles_object_name='1 OPL Particles', gc_particles_object_name='4 GRL Particles', glom_particles_object_name='0 GL Particles', glom_layer_object_name='0 GL', outer_opl_object_name='1 OPL-Outer', inner_opl_object_name='1 OPL-Inner')

Prepares the slice builder

Parameters

• odors – A list of odors whose glomeruli to include (e.g. [‘Apple’, ‘Mint’]), use ‘all’ for all gloms.

• slice_object_name – The name of the Blender mesh that defines the shape of the virtual slice

• max_mcs – The maximum number of MCs to include in the model

• max_tcs – Maximum number of TCs. Use None to use mouse MC-TC ratio.

• max_gcs – Maximum number of GCs. Use None to use mouse MC-GC ratio.

• mc_particles_object_name – The name of the Blender object that defines MC soma locations

• tc_particles_object_name – The name of the Blender object that defines TC soma locations

• gc_particles_object_name – The name of the Blender object that defines GC soma locations

• glom_particles_object_name – The name of the Blender object that defines glomerulus locations

• glom_layer_object_name – The name of the Blender object that defines the geometry of glomerular layer

• outer_opl_object_name – The name of the Blender object that defines the outer boundary of the OPL layer

• inner_opl_object_name – The name of the Blender object that defines the inner boundary of the OPL layer

add_gc(gc_pt)

Instantiates, places, and orients a granule cell in the granule cell layer

Parameters

gc_pt – XYZ array of GC soma location

add_mc(mc_pt)

Instantiates in NEURON, places, and orients a mitral cell within the mitral cell layer and confines its lateral dendrites to the curvature of the surrounding internal part of the outer plexiform layer.

Parameters

mc_pt – A dict whose ‘loc’ key contains a numpy array of xyz coordinates of the cell soma

add_synapse_sets()

Creates synapse sets between MCs-GCs and TCs-GCs

add_tc(tc_pt)

Similar to add_mc(pt). Instantiates, places, and orients a tufted cell model and confines its lateral dendrites to the outer portion of the outer plexiform layer.

Parameters

tc_pt – A dict with ‘loc’ that contains a numpy array of xyz coordinates of the TC soma

build(seed=0)

Positions MC/TC/GC models within the OB layers, identifies synapse locations, and saves the model for later simulation in NEURON

Parameters

seed – The random seed to use (to assist reproducibility)

clear_slice_files()

Deletes previously saved virtual slice .json files from the slice directory (e.g. olfactorybulb/slices/DorsalColumnSlice/.json)

static closest_point_on_object(global_pt, mesh_obj)

Gets the closest point and distance of a mesh object from a specified point

Parameters

• global_pt – The point from which to measure distance

• mesh_obj – A mesh object

Returns

A tuple with an xyz numpy array of the closest point and distance to it

confine_dends(group_name, start_layer_name, end_layer_name, max_angle, height_start, height_end)

Confines the lateral dendrits of cells in a group to follow the curvature between two layers

Height_start and height_end specify fractions that define the corridor between the layers to which the dendrites should be confined. E.g. To confine the dendrites in the halfway between the two layers, closer to the start layer, set height_start and height_end to 0 and 0.5. Set them to 0.5 and 1.0 to confine to the halfway that is closer to the end region. 1.0 corresponds to the local distance between the two layers.

The two layers should be ‘locally’ parallel. E.g. two planes, or two concentric spheres. In OB model case, the OB layers are complex shapes, but concentric-like.

Parameters

• group_name – The name of the group of cells to confine

• start_layer_name – The name of the first confinement layer

• end_layer_name – The name of the second confinement layer

• max_angle – The maximum angle that a dendritic branch can rotate to be confined between layers

• height_start – Fraction between 0-1

• height_end – Fraction between 0-1

create_groups()

Creates empty BlenderNEURON cell groups for MCs, TCs, and GCs.

create_synapse_set(group_from, group_to)

Defines a synapse set between two BlenderNEURON groups of cells

Parameters

• group_from – One of ‘MCs’, ‘TCs’, ‘GCs’

• group_to – One of ‘MCs’, ‘TCs’, ‘GCs’

static dist_to(targets_array, loc)

Returns an array of distances to the specified list of points from a given point

Parameters

• targets_array – The array of xzy target coordinates

• loc – The target coordinate

Returns

An array of distances

dist_to_gloms(loc)

Returns an array of distances to glomeruli from a given location

Parameters

loc – XYZ coordinate

Returns

Distances to glomeruli

extend_apic(apic_start, apic_end, apic_glom_loc)

TODO: This is probably unused, leftover from an earlier version.

Parameters

• apic_start –

• apic_end –

• apic_glom_loc –

Returns

find_closest_glom(cell_loc)

Finds the closest glomerulus to the specified coordinates

Parameters

cell_loc – A numpy array of xyz coordinates

Returns

A tuple with the location of the closest glomerulus and distance to it

find_matching_glom(cell_loc, cell_model_info)

Finds a glomerulus that is approximately the same distance from the soma as the length of the cells apical dendrite

Parameters

• cell_loc – A numpy xyz array with coordinates

• cell_model_info – Cell model metadata dict with ‘apical_dendrite_reach’ key that contains the apical dendrite length

Returns

The xyz location and the id of the matching glomerulus

static get_apic_lengths(base_models)

Gets the apical dendrite lengths of the specified base models

Parameters

base_models – List with metadata of base cell models

Returns

A numpy array of apical dendrite lengths

get_cell_base_model_info()

Gets metadata info about each of the base (untransformed) MC, TC, and GC cell models

get_cell_locations()

Identifies the locations of glomeruli, mcs, tcs, and gcs that are contained by the virtual slice.

get_key_mctc_section_objects(base_model_dict, base_class, instance_name)

Gets the blender objects of soma, apical dendrite start (base), and apical dendrite end (tuft) sections

Parameters

• base_model_dict – A dicttionary of base cell model metadata info

• base_class – The name of a base cell class

• instance_name – The name of blender object of cell soma section

Returns

Blender objects of soma, apical dendrite start, and apical dendrite end

get_locs_within_slice(particle_obj_name, slice_obj_name, allowed_particles=None, limit=None)

Gets a list of particle locations that are contained by a slice object

Parameters

• particle_obj_name – A blender particle object

• slice_obj_name – A blender mesh object that represents the virtual slice

• allowed_particles – A list of particle ids that are allowed to be included. If None, not restricted.

• limit – A list of dicts with ids and locs of matching points

Returns

get_longest_apic_model(base_model_dict)

Returns the metadata of the base cell model that has that longest apical dendrite

Parameters

base_model_dict – The dict of base cell model metadatas

Returns

A metadata object

get_opl_distance_info(cell_loc, pts)

Computes distances to and the closest point of an outer plexiform layer to a given point

Parameters

• cell_loc – The xyz location of a point

• pts – The list of xyz coordinates of the OPL layer mesh

Returns

A tuple with closest location on the layer, the distance to that point, and a list of distances to all OPL points

get_opl_locs(opl_name, slice_obj_name)

Gets the coordinates of inner or outer boundaries of the OPL layer that are contained by the virtual slice

get_random_model(base_models, longer_idxs)

Given a list of indices stored in longer_idxs, selects a random element of base_models

Parameters

• base_models – A list of base cell models

• longer_idxs – A list of indices from which to pick a random index

Returns

A random cell model

globalize_slice()

Converts all points of the slice object to global coordinates (relative to scene origin)

import_instance(instance_name, group_name)

Imports and shows a cell instantiated in NEURON into Blender using a BlenderNEURON group

Parameters

• instance_name – The name of the cell model to import (as named by NEURON)

• group_name – The name of the group to associate the cell with

static is_inside(target_pt_global, mesh_obj, tolerance=1)

Determines if a target point is inside a mesh

Parameters

• target_pt_global – Target xyz point, in global coordinates

• mesh_obj – Target mesh object

• tolerance – A tolerance in degrees to account for rounding error in detecting points inside. <=1 is generally sufficient.

Returns

True or False

link_cell_to_glom(instance_name, matching_glom_id)

Adds a cell instance to a list of cells that belong to the specified glomerulus

Parameters

• instance_name – The name of the cell as returned by NEURON

• matching_glom_id – The id of the glomerulus, with which to associate the cell

property neuron

Returns the client class that communicates with NEURON via methods defined in olfactorybulb.slicebuilder.nrn

property node

Returns the BlenderNEURON node that runs within Blender

parent(obj, parent)

Make one blender object a parent of another

Parameters

• obj – The child object

• parent – The child’s parent object

position_orient_align_mctc(soma, apic_start, apic_end, loc, closest_glom_loc, apic_glom_loc)

TODO: this appears to have the same/similar function as self.position_orient_cell. This may be redundant code.

Parameters

• soma –

• apic_start –

• apic_end –

• loc –

• closest_glom_loc –

• apic_glom_loc –

Returns

position_orient_cell(soma, apic_end, soma_loc, closest_glom_loc)

Position cell at a location, rotate it around its apical dendrite axis, and rotate it around the soma so it’s apical dendrite ‘points’ towards the closest glomerulus location.

Parameters

• soma – Blender object that holds the soma section

• apic_end – Blender object that holds the apical dendrite (furthest apical section on/near apical axis)

• soma_loc – The desired cell soma location

• closest_glom_loc – The location of the closest glomerulus

save_transform(group_name, instance_name)

Saves trnsformed cells in a cell group to a NEURON compatible file

Parameters

• group_name – The name of the BlenderNEURON cell group to save

• instance_name – The name of the file to save. Can be the name of the cell soma segment.

property slice_dir

Returns the path to the directory where virtual slice cell and synapse files will be saved

unparent(obj)

Removes the parent of a Blender object, and keeps the object in the same location

Parameters

obj – The blender object to unparent

Returns

The parent of the target object

olfactorybulb.slicebuilder.blender.auto_start(scene)

A Blender startup script that starts the SliceBuilder on Blender startup

class olfactorybulb.slicebuilder.nrn.SliceBuilderNRN

Bases: object

Establishes an interface for Blender to load cells into NEURON

__init__()

Starts NEURON, creates a BlenderNEURON node, and adds methods to the node that Blender can call.

create_cell(type, class_name)

Creates an instance of a base cell model in NEURON.

Parameters

• type – One of ‘MC’, ‘TC’, or ‘GC’

• class_name – One of the cell classes in prev_ob_models.Birgiolas2020.isolated_cells

Returns

The name that NEURON gives to the cell soma segment e.g. ‘MC5[0].soma’

get_base_model_info()

Returns metadata information from the model database about each base cell model.

A base cell model is a NEURON model of a cell with a representative morphology centered at the origin and rotated so the apical dendrites are aligned with the Z axis.

The based models are positioned within layers, and oriented appropriately. MC and TC lateral dendrites are also modified so they follow the curvature of the external plexiform layer.

Returns

A tuple of mc, tc, and gc dictionaries of metadata

get_model_info(cell_type='MC')

Returns the list of metadata of base cell models of a given cell type.

See olfactorybulb.database.CellModel for metadata field names.

Parameters

cell_type – One of ‘MC’, ‘TC’, or ‘GC’

Returns

A dictionary of base cell model class names and their metadata

get_odor_gloms(odors)

Gets the list of glomerular ids that are activated by the specified list of odors

Parameters

odors – A list of odor names, or ‘all’

Returns

List of glomerulus ids, or None when ‘all’ odors were specified

olfactorybulb.slicebuilder.utils.print_apic_reach()

Prints the distance between the selected apical dendrite and the cell soma. This assumes only one cell is in the scene and the cell is in ‘Section’ interaction level.

Returns

Nothing, prints to console