Generating Templates

Templates refer to the extracellular action potentials (EAPs) generated by a neuron on the recording sites. Templates are generated using NEURON and LFPy packages.

The current version (1.0.4) only supports biophysical multi-compartment models from the Neocortical Microcircuit Collaboration Portal (NMC). A set of 13 cell models from layer 5 is included in the basic installation and copied in .config/mearec/cell_models/bbp. In order to add more cell models, you can simply download the zip files from the download page, move them to the cell model folder (which can be retrieved with the mearec default-config command or with the Python code: mr.get_default_cell_models_folder()), and unzip them. Note also custom models cane be used. In this notebook we show how to use models from the Allen database to build templates (and recordings).

Templates are generated in two steps:

  1. The multi-compartment model is run with (Intracellular simulations – only needs to run once)
  2. The transmembrane currents are used to generate EAPs (Extracellular simulations)

Intracellular simulations

For the intracellular simulation a NEURON simulation of sim_time (default 1 s) is performed. A constant current is applied to the soma after a delay (default 10 ms) so that the number of elicited spiked is in the target_spikes range (default [3, 50]). If the number of spikes is less or more than the target spikes boundaries, the stimulation weight is increased/decreased using the weights parameter (default [0.25, 0.75]). The user can also set the time period dt (defualt 0.03125 ms, corresponding to 32 kHz) and the cut_out times before and after the spike peak (default 2 ms before and 5 ms after).

The intracellular simulation will save the transmembrane currents for each cell model in the intracellular folder of the default output templates folder, so that currents do not need to be recomputed all the time.

Intracellular parameters summary

# intracellular simulation settings
sim_time: 1 # intracellular simulation time in s
target_spikes: [3, 50]  # min-max number of spikes in sim_time
cut_out: [2, 5]  # pre-post peak cut_out in ms
dt: 0.03125  # time step (2**-5) in ms
delay: 10  # stimulation delay in ms
weights: [0.25, 1.75]  # weights to multiply stimulus amplitude if number of spikes is above (0.25) or above (1.25) target spikes

Extracellular simulations and parameters

Once the transmembrane currents are computed, they can be used to simulate extracellular action potentials using LFPy. In brief, currents are loaded to the cell model, which is randomly placed (and optionally rotated) around the selected probe before the extracellular potentials are computed. This process is performed n times (defualt 50). Rotations are optional and can be chosen with the rot parameter among norot, physrot, 3drot.

The physrot rotation is default and it is designed for L5 models of the NMC portal. This kind of rotation applies a physiological rotation to the models: for example, pyramidal cells are rotated along the z-axis (depth) and a small rendom tilt is applied (15 degrees). Some interneurons, that do not show a preferred orientation, are rotated randomly in 3d.

The probe parameter allows the user to choose which neural probe has to be used. Probes are handled with the MEAutility package (automatically instlled), and can be (custom designed). There is a number of pre-installed probes, such as Neuronexus-32, Neuropixels, tetrodes, and various square MEAs with varying pitches and sizes. The default probe is the Neuronexus-32 (A1x32-Poly3). The MEA probes are located on the yz plane, with an adjustable x-offset (offset) set to 0 \(\mu m\) by default.

The limits for the locations of cells can be set using the xlim, ylim, and zlim. If set to null (default for ylim and zlim), the boundary is set by the maximum and minimum electrode position in the respective axis plus the overhang parameter, which is 30 \(\mu m\) by default.

The ncontacts parameter can be used to simulate the spatial extent of the electrodes. For example, if set to 10, 10 points will be randomly drawn from the area of each electrode and the resulting potential is computed as the average of the 10 electric potentials of those points.

Only templates larger than the det_thresh parameter (30 \(\mu V\) by default) will be saved.

For reproducibility, the seed can be manually set by the user (if null a random seed is used).

Extracellular parameters summary

# extracellular simulation settings
rot: physrot # random rotation to apply to cell models (norot, physrot, 3drot)
probe: Neuronexus-32 # extracellular probe (if None probes are listed)
ncontacts: 1 # number of contacts per recording site
overhang: 30 # extension in un beyond MEA boundaries for neuron locations (if lim is null)
offset: 0 # plane offset (um) for MEA
xlim: [10,80] # limits ( low high ) for neuron locations in the x-axis (depth)
ylim: null # limits ( low high ) for neuron locations in the y-axis
zlim: null # limits ( low high ) for neuron locations in the z-axis
det_thresh: 30 # detection threshold for EAPs
n: 50 # number of EAPs per cell model
seed: null # random seed for positions and rotations

Drifting templates

MEArec allows to generate recordings with drifting units over time. In order to do so, drifting templates have to be generated. Note that drifting recordings can be simulated ONLY from drifting templates.

To generate drifting, set the drifting parameter to True. Drifting is simulated as follows: first, an initial position is chosen so that the resulting EAP is above the detection threshold. Second, a final position is chosen so that i) the EAP is above threshold and ii) the drifting distance is between min_drift (defualt 20 \(\mu m\)) and max_drift defualt 100 \(\mu m\). Third, the neuron is moved along the straight line connecting the initial and final position for drift_steps points (default 50). The drift_x_lim, drift_y_lim, and drift_z_lim can be used to decide the drift directions. For example, in the default case drift_x_lim is [-10, 10], drift_y_lim is [-10, 10], and drift_z_lim is [20, 80] and the final position will be pointing upwards in the z-direction, with some small shifts in the x- abd y-axes.

Drifting parameters summary

drifting: False # if True, drifting templates are simulated
max_drift: 100  # max distance from the initial and final cell position
min_drift: 30   # min distance from the initial and final cell position
drift_steps: 50 # number of drift steps
drift_x_lim: [-10, 10] # drift limits in the x-direction
drift_y_lim: [-10, 10] # drift limits in the y-direction
drift_z_lim: [20, 80]  # drift limits in the z-direction

Running template generation using CLI

Templates can be generated using the CLI with the command: mearec gen-templates. Run mearec gen-templates --help to display the list of available arguments, that can be used to overwrite the default parameters or to point to another parameter .yaml file.

The output templates are saved in .h5 format to the default templates output folder.

Running template generation using Python

Templates can also be generated using a Python script, or a jupyter notebook.

import MEArec as mr
tempgen = mr.gen_templates(cell_models_folder, params=None, templates_tmp_folder=None, intraonly=False, parallel=True,
                           recompile=False, n_jobs=None, delete_tmp=True, verbose=False)

The cell_models_folder has to be passed as an argument. The params argument can be the path to a .yaml file or a dictionary containing the parameters (if None default parameters are used). The templates_tmp_folder points to the output temporary folder used to save generated templates. If not specified it will use the current directory. If intraonly is True, only the intracellular simulation is run. Simulations are run in parallel if parallel is True and the temporary processing folder is deleted if delete_tmp is True. If n_jobs is None, the function will use as many jobs as available cell models (if run in parallel). Finally, the recompile argument forces a recompilation of the models (use this if you added new cell models in the cell_models_folder). If verbose is True, the output shows the progress of the template simulation.

The gen_templates() function returns a gen_templates TemplateGenerator object (tempgen).

The TemplateGenerator object

The TemplateGenerator class contains several fields:

  • templates: numpy array with (n_templates, n_electrodes, n_points) - not drifting - or (n_templates, n_drift_steps, n_electrodes, n_points) for drifting ones
  • locations: (n_templates) 3D locations for the templates (for not drifting) or (n_templates, n_drift_steps) 3D locations for drifting templates.
  • rotations: (n_templates) 3D rotations applied to the cell model before computing the template (for drifting templates rotation is fixed)
  • celltypes: (n_templates) cell types of the generated templates
  • info: dictionary with parameters used

TemplateGenerator can be saved to .h5 files as follows:

import MEArec as mr
mr.save_template_generator(tempgen, filename=None)

where tempgen is a TemplateGenerator object and filename is the output file name.