.. _gen-templates: 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 :code:`.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 :code:`mearec default-config` command or with the Python code: :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 :code:`sim_time` (default 1 s) is performed. A constant current is applied to the soma after a :code:`delay` (default 10 ms) so that the number of elicited spiked is in the :code:`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 :code:`weights` parameter (default [0.25, 0.75]). The user can also set the time period :code:`dt` (defualt 0.03125 ms, corresponding to 32 kHz) and the :code:`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 :code:`intracellular` folder of the default output templates folder, so that currents do not need to be recomputed all the time. Intracellular parameters summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # 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 :code:`n` times (defualt 50). Rotations are optional and can be chosen with the :code:`rot` parameter among :code:`norot, physrot, 3drot`. The :code:`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 :code:`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 (:code:`offset`) set to 0 :math:`\mu m` by default. The limits for the locations of cells can be set using the :code:`xlim`, :code:`ylim`, and :code:`zlim`. If set to :code:`null` (default for :code:`ylim` and :code:`zlim`), the boundary is set by the maximum and minimum electrode position in the respective axis plus the :code:`overhang` parameter, which is 30 :math:`\mu m` by default. The :code:`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 :code:`min_amp` parameter (30 :math:`\mu V` by default) will be saved. For reproducibility, the :code:`seed` can be manually set by the user (if :code:`null` a random seed is used). Extracellular parameters summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash # 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 .. _drift-templates: Drifting templates ------------------ MEArec 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 :code:`drifting` parameter to :code:`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 :code:`min_drift` (default 20 :math:`\mu m`) and :code:`max_drift` default 100 :math:`\mu m`. Third, the neuron is moved along the straight line connecting the initial and final position for :code:`drift_steps` points (default 50). The :code:`drift_x_lim`, :code:`drift_y_lim`, and :code:`drift_z_lim` can be used to decide the drift directions. For example, in the default case :code:`drift_x_lim` is [-10, 10], :code:`drift_y_lim` is [-10, 10], and :code:`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 parameters summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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-direction Running template generation using Python ---------------------------------------- Templates can also be generated using a Python script, or a jupyter notebook. .. code-block:: python 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 :code:`cell_models_folder` has to be passed as an argument. The :code:`params` argument can be the path to a .yaml file or a dictionary containing the parameters (if None default parameters are used). The :code:`templates_tmp_folder` points to the output temporary folder used to save generated templates. If not specified it will use the current directory. If :code:`intraonly` is True, only the intracellular simulation is run. Simulations are run in parallel if :code:`parallel` is True and the temporary processing folder is deleted if :code:`delete_tmp` is True. If :code:`n_jobs` is None, the function will use as many jobs as available cell models (if run in parallel). Finally, the :code:`recompile` argument forces a recompilation of the models (use this if you have added new cell models in the :code:`cell_models_folder`). If :code:`verbose` is True, the output shows the progress of the template simulation. The :code:`gen_templates()` function returns a gen_templates :code:`TemplateGenerator` object (:code:`tempgen`). Running template generation using CLI (not recommended) ------------------------------------------------------- Templates can be generated using the CLI with the command: :code:`mearec gen-templates`. Run :code:`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 object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The :code:`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 :code:`TemplateGenerator` can be saved to .h5 files as follows: .. code-block:: python import MEArec as mr mr.save_template_generator(tempgen, filename=None) where :code:`tempgen` is a :code:`TemplateGenerator` object and :code:`filename` is the output file name.