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:
- The multi-compartment model is run with (Intracellular simulations -- only needs to run once)
- The transmembrane currents are used to generate EAPs (Extracellular 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 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 spikesOnce 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
random 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 min_amp 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 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 rotationsMEArec allows for the generation of recordings with units drifting 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 (default 20 \mu m) and max_drift default 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- and
y-axes.
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_xlim: [-10, 10] # drift limits in the x-direction
drift_ylim: [-10, 10] # drift limits in the y-direction
drift_zlim: [20, 80] # drift limits in the z-directionTemplates 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 have 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).
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.
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.