API reference

Module MEArec.generators

class MEArec.generators.TemplateGenerator(cell_models_folder=None, templates_folder=None, temp_dict=None, info=None, tempgen=None, params=None, intraonly=False, parallel=True, recompile=False, n_jobs=None, joblib_backend='loky', delete_tmp=True, verbose=False)[source]

Bases: object

Class for generation of templates called by the gen_templates function. The list of parameters is in default_params/templates_params.yaml.

Parameters:
  • cell_models_folder (str) – Path to folder containing Blue Brain Project cell models

  • templates_folder (str) – Path to output template folder (if not in params)

  • temp_dict (dict) –

    Dictionary to instantiate TemplateGenerator with existing data. It contains the following fields:
    • templates : float (n_templates, n_electrodes, n_timepoints)

    • locations : float (n_templates, 3)

    • rotations : float (n_templates, 3)

    • celltypes : str (n_templates)

  • info (dict) –

    Info dictionary to instantiate TemplateGenerator with existing data. It contains the following fields:
    • params : dict with template generation parameters

    • electrodes : dict with probe info (from MEAutility.return_mea_info(‘probe-name’))

  • tempgen (TemplateGenerator) – If a TemplateGenerator is passed, the cell types, locations, and rotations of the templates will be set using the provided templates

  • params (dict) – Dictionary with parameters to simulate templates. Default values can be retrieved with mr.get_default_template_params()

  • intraonly (bool) – If True, only intracellular simulations are performed

  • parallel (bool) – If True, cell models are run in parallel

  • recompile (bool) – If True, cell models are recompiled (suggested if new models are added)

  • n_jobs (int) – If None, all cpus are used

  • delete_tmp (bool) – If True, temporary files are removed

  • verbose (bool) – If True, output is verbose

generate_templates()[source]

Generate templates.

class MEArec.generators.SpikeTrainGenerator(params=None, spiketrains=None, seed=None, verbose=False)[source]

Bases: object

Class for generation of spike trains called by the gen_recordings function. The list of parameters is in default_params/recordings_params.yaml (spiketrains field).

Parameters:
  • params (dict) – Dictionary with parameters to simulate spiketrains. Default values can be retrieved with mr.get_default_recordings_params()[‘spiketrains’]

  • spiketrains (list of neo.SpikeTrain) – List of neo.SpikeTrain objects to instantiate a SpikeTrainGenerator with existing data

  • verbose (bool) – If True, output is verbose

add_synchrony(idxs, rate=0.05, time_jitt=array(1.) * ms, verbose=False)[source]

Adds synchronous spikes between pairs of spike trains at a certain rate.

Parameters:
  • idxs (list or array) – Spike train indexes to add synchrony to

  • rate (float) – Rate of added synchrony spike to spike train idxs[1] for each spike of idxs[0]

  • time_jitt (quantity) – Maximum time jittering between added spikes

  • verbose (bool) – If True output is verbose

Returns:

  • sync_rate (float) – New synchrony rate

  • fr1 (quantity) – Firing rate spike train 1

  • fr2 (quantity) – Firing rate spike train 2

generate_spikes()[source]

Generate spike trains based on default_params of the SpikeTrainGenerator class. self.spiketrains contains the newly generated spike trains

set_spiketrain(idx, spiketrain)[source]

Sets spike train idx to new spiketrain.

Parameters:
  • idx (int) – Index of spike train to set

  • spiketrain (neo.SpikeTrain) – New spike train

class MEArec.generators.RecordingGenerator(spgen=None, tempgen=None, params=None, rec_dict=None, info=None)[source]

Bases: object

Class for generation of recordings called by the gen_recordings function. The list of parameters is in default_params/recordings_params.yaml.

Parameters:
  • spgen (SpikeTrainGenerator) – SpikeTrainGenerator object containing spike trains

  • tempgen (TemplateGenerator) – TemplateGenerator object containing templates

  • params (dict) – Dictionary with parameters to simulate recordings. Default values can be retrieved with mr.get_default_recording_params()

  • rec_dict (dict) –

    Dictionary to instantiate RecordingGenerator with existing data. It contains the following fields:
    • recordings : float (n_electrodes, n_samples)

    • spiketrains : list of neo.SpikeTrains (n_spiketrains)

    • templates : float (n_spiketrains, 3)

    • template_locations : float (n_spiketrains, 3)

    • template_rotations : float (n_spiketrains, 3)

    • template_celltypes : str (n_spiketrains)

    • channel_positions : float (n_electrodes, 3)

    • timestamps : float (n_samples)

    • voltage_peaks : float (n_spiketrains, n_electrodes)

    • spike_traces : float (n_spiketrains, n_samples)

  • info (dict) – Info dictionary to instantiate RecordingGenerator with existing data. Same fields as ‘params’

annotate_overlapping_spikes(parallel=True)[source]

Annnotate spike trains with overlapping information.

parallelbool

If True, spike trains are annotated in parallel

extract_templates(cut_out=[0.5, 2], recompute=False)[source]

Extract templates from spike trains.

Parameters:
  • cut_out (float or list) – Ms before and after peak to cut out. If float the cut is symmetric.

  • recompute (bool) – If True, templates are recomputed from extracted waveforms

extract_waveforms(cut_out=[0.5, 2])[source]

Extract waveforms from spike trains and recordings.

Parameters:

cut_out (float or list) – Ms before and after peak to cut out. If float the cut is symmetric.

generate_recordings(tmp_mode=None, tmp_folder=None, n_jobs=0, template_ids=None, drift_dicts=None, verbose=None)[source]

Generates recordings

Parameters:
  • tmp_mode (None, 'memmap') – Use temporary file h5 memmap or None None is no temporary file and then use memory.

  • tmp_folder (str or Path) – In case of tmp files, you can specify the folder. If None, then it is automatic using tempfile.mkdtemp()

  • n_jobs (int) – if >1 then use joblib to execute chunk in parallel else in loop

  • template_ids (list or None) – If None, templates are selected randomly based on selection rules. If a list of indices is provided, the indices are used to select templates (template selection is bypassed)

  • drift_dicts (list or None) – List of drift dictionaries to construct multiple drift vectors. (see MEArec.get_default_drift_dict())

  • verbose (bool or int) – Determines the level of verbose. If 1 or True, low-level, if 2 high level, if False, not verbose

Module MEArec.generation_tools

MEArec.generation_tools.gen_templates(cell_models_folder, params=None, templates_tmp_folder=None, tempgen=None, intraonly=False, parallel=True, n_jobs=None, joblib_backend='loky', recompile=False, delete_tmp=True, verbose=True)[source]
Parameters:
  • cell_models_folder (str) – path to folder containing cell models

  • params (str or dict) – Path to parameters yaml file or parameters dictionary

  • templates_tmp_folder (str) – Path to temporary folder where templates are temporarily saved

  • tempgen (TemplateGenerator) – If a TemplateGenerator is passed, the cell types, locations, and rotations of the templates will be set using the provided templates

  • intraonly (bool) – if True, only intracellular simulation is run

  • parallel (bool) – if True, multi-threading is used

  • n_jobs (int) – Number of jobs to run in parallel (If None all cpus are used)

  • joblib_backend (str) – The joblib backend to use when n_jobs > 1 (default ‘loky’)

  • recompile (bool) – If True, cell models are recompiled

  • delete_tmp – if True, the temporary files are deleted

  • verbose (bool, or int) – If True, the output is verbose (1). If verbose is 2, every step produces an output

Returns:

Generated template generator object

Return type:

TemplateGenerator

MEArec.generation_tools.gen_spiketrains(params=None, spiketrains=None, seed=None, verbose=False)[source]

Generates spike trains.

Parameters:
  • params (str or dict) – Path to parameters yaml file or parameters dictionary

  • spiketrains (list) – List of neo.SpikeTrains (alternative to params definition)

  • verbose (bool) – If True, the output is verbose

Returns:

Generated spike train generator object

Return type:

SpikeTrainGenerator

MEArec.generation_tools.gen_recordings(params=None, templates=None, tempgen=None, spgen=None, verbose=True, tmp_mode='memmap', template_ids=None, tmp_folder=None, n_jobs=0, drift_dicts=None)[source]

Generates recordings.

Parameters:
  • templates (str) – Path to generated templates

  • params (dict or str) – Dictionary containing recording parameters OR path to yaml file containing parameters

  • tempgen (TemplateGenerator) – Template generator object

  • spgen (SpikeTrainGenerator) – Spike train generator object. If None spike trains are created from params[‘spiketrains’]

  • verbose (bool or int) – Determines the level of verbose. If 1 or True, low-level, if 2 high level, if False, not verbose

  • tmp_mode (None, 'h5' 'memmap') – Use temporary file h5 memmap or None None is no temporary file

  • template_ids (list or None) – If None, templates are selected randomly based on selection rules. If a list of indices is provided, the indices are used to select templates (template selection is bypassed)

  • tmp_folder (str or Path) – In case of tmp files, you can specify the folder. If None, then it is automatic using tempfile.mkdtemp()

Returns:

Generated recording generator object

Return type:

RecordingGenerator

Module MEArec.tools

MEArec.tools.load_templates(templates, return_h5_objects=True, verbose=False, check_suffix=True)[source]

Load generated eap templates.

Parameters:
  • templates (str or Path object) – templates file

  • return_h5_objects (bool) – If True output objects are h5 objects

  • verbose (bool) – If True output is verbose

  • check_suffix (bool) – If True, hdf5 suffix is checked

Returns:

tempgen – TemplateGenerator object

Return type:

TemplateGenerator

MEArec.tools.load_recordings(recordings, return_h5_objects=True, load=None, load_waveforms=True, check_suffix=True, verbose=False)[source]

Load generated recordings.

Parameters:
  • recordings (str or Path object) – Recordings file

  • return_h5_objects (bool) – If True output objects are h5 objects

  • load (list) –

    List of fields to be loaded ((‘recordings’, ‘channel_positions’, ‘voltage_peaks’, ‘spiketrains’,

    ’timestamps’, ‘spike_traces’, ‘templates’))

  • load_waveforms (bool) – If True waveforms are loaded to spiketrains

  • verbose (bool) – If True output is verbose

  • check_suffix (bool) – If True, hdf5 suffix is checked

Returns:

recgen – RecordingGenerator object

Return type:

RecordingGenerator

MEArec.tools.save_template_generator(tempgen, filename=None, verbose=True)[source]

Save templates to disk.

Parameters:
  • tempgen (TemplateGenerator) – TemplateGenerator object to be saved

  • filename (str) – Path to .h5 file

  • verbose (bool) – If True output is verbose

MEArec.tools.save_recording_generator(recgen, filename=None, verbose=False)[source]

Save recordings to disk.

Parameters:
  • recgen (RecordingGenerator) – RecordingGenerator object to be saved

  • filename (str) – Path to .h5 file

  • verbose (bool) – If True output is verbose

MEArec.tools.get_default_config(print_version=False)[source]

Returns default_info and mearec_home path.

Returns:

  • default_info (dict) – Default_info from config file

  • mearec_path (str) – Mearec home path

MEArec.tools.get_default_cell_models_folder()[source]

Returns default cell models folder.

Returns:

cell_models_folder – Path to default cell models folder

Return type:

str

MEArec.tools.get_default_templates_params()[source]

Returns default templates parameters.

Returns:

templates_params – Dictionary with default teplates parameters

Return type:

dict

MEArec.tools.get_default_recordings_params()[source]

Returns default recordings parameters.

Returns:

recordings_params – Dictionary with default recording parameters

Return type:

dict

MEArec.tools.plot_rasters(spiketrains, cell_type=False, ax=None, overlap=False, color=None, fs=10, marker='|', mew=2, markersize=5)[source]

Plot raster for spike trains.

Parameters:
  • spiketrains (list) – List of neo spike trains

  • cell_type (bool) – If True and ‘bintype’ in spike train annotation spike trains are plotted based on their type

  • ax (axes) – Plot on the given axes

  • overlap (bool) – Plot spike colors based on overlap

  • labels (bool) – Plot spike colors based on labels

  • color (matplotlib color (single or list)) – Color or color list

  • fs (int) – Font size

  • marker (matplotlib arg) – Marker type

  • mew (matplotlib arg) – Width of marker

  • markersize (int) – Marker size

Returns:

ax – Matplotlib axis

Return type:

axis

MEArec.tools.plot_templates(gen, template_ids=None, single_jitter=True, ax=None, single_axes=False, max_templates=None, drifting=False, cmap=None, ncols=6, **kwargs)[source]

Plot templates.

Parameters:
  • gen (TemplateGenerator or RecordingGenerator) – Generator object containing templates

  • template_ids (int or list) – The template(s) to plot

  • single_axes (bool) – If True all templates are plotted on the same axis

  • ax (axis) – Matplotlib axis

  • single_jitter (bool) – If True and jittered templates are present, a single jittered template is plotted

  • max_templates (int) – Maximum number of templates to be plotted

  • drifting (bool) – If True and templates are drifting, drifting templates are displayed

  • cmap (matplotlib colormap) – Colormap to be used

  • ncols (int) – Number of columns for subplots

Returns:

ax – Matplotlib axes

Return type:

ax

MEArec.tools.plot_recordings(recgen, ax=None, start_time=None, end_time=None, overlay_templates=False, n_templates=None, max_channels_per_template=16, cmap=None, templates_lw=1, **kwargs)[source]

Plot recordings.

Parameters:
  • recgen (RecordingGenerator) – Recording generator object to plot

  • ax (axis) – Matplotlib axis

  • start_time (float) – Start time to plot recordings in s

  • end_time (float) – End time to plot recordings in s

  • overlay_templates (bool) – If True, templates are overlaid on the recordings

  • n_templates (int) – Number of templates to overlay (if overlay_templates is True)

  • max_channels_per_template (int) – Number of maximum channels in which the template is overlaid

  • cmap (matplotlib colormap) – Colormap to be used

Returns:

ax – Matplotlib axis

Return type:

axis

MEArec.tools.plot_waveforms(recgen, spiketrain_id=None, ax=None, color=None, cmap=None, electrode=None, max_waveforms=None, ncols=6, cut_out=2)[source]

Plot waveforms of a spike train.

Parameters:
  • recgen (RecordingGenerator) – Recording generator object to plot spike train waveform from

  • spiketrain_id (int or list) – Indexes of spike trains

  • ax (axis) – Matplotlib axis

  • color (matplotlib color) – Color of the waveforms

  • cmap (matplotlib colormap) – Colormap to be used

  • electrode (int or 'max') – Electrode id or ‘max’

  • ncols (int) – Number of columns for subplots

  • cut_out (float or list) – Cut outs in ms for waveforms (if not computed). If float the cut out is symmetrical.

Returns:

ax – Matplotlib axis

Return type:

axis

MEArec.tools.plot_amplitudes(recgen, spiketrain_id=None, electrode=None, ax=None, color=None, cmap=None, single_axes=True, marker='*', ms=5, ncols=6)[source]

Plot waveform amplitudes over time.

Parameters:
  • recgen (RecordingGenerator) – Recording generator object to plot spike train waveform from

  • spiketrain_id (int or list) – Indexes of spike trains

  • electrode (int or 'max') – Electrode id or ‘max’

  • ax (axis) – Matplotlib axis

  • color (matplotlib color) – Color of the waveform amplitudes

  • cmap (matplotlib colormap) – Colormap to be used

  • single_axes (bool) – If True all templates are plotted on the same axis

  • marker (str) – Matplotlib marker (default ‘*’)

  • ms (int) – Markersize (default 5)

  • ncols (int) – Number of columns for subplots

Returns:

ax – Matplotlib axis

Return type:

axis

MEArec.tools.plot_pca_map(recgen, n_pc=2, max_elec=None, cmap='rainbow', cut_out=2, n_units=None, ax=None, whiten=False, pc_comp=None)[source]

Plots a PCA map of the waveforms.

Parameters:
  • recgen (RecordingGenerator) – Recording generator object to plot PCA scores of

  • ax (axis) – Matplotlib axis

  • n_pc (int) – Number of principal components (default 2)

  • max_elec (int) – Max number of electrodes to plot

  • cmap (matplotlib colormap) – Colormap to be used

  • cut_out (float or list) – Cut outs in ms for waveforms (if not computed). If float the cut out is symmetrical. n_units

  • whiten (bool) – If True, PCA scores are whitened

  • pc_comp (np.array) – PC component matrix to be used.

Returns:

  • ax (axis) – Matplotlib axis

  • pca_scores (list) – List of np.arrays with pca scores for the different units

  • pca_component (np.array) – PCA components matrix (n_pc, n_waveform_timepoints)

Module MEArec.drift_tools

MEArec.drift_tools.generate_drift_dict_from_params(drift_fs, duration, template_locations, external_drift_vector_um=None, external_drift_times=None, t_start_drift=None, t_end_drift=None, drift_mode_probe='rigid', drift_mode_speed='slow', non_rigid_gradient_mode='linear', non_rigid_linear_direction=1, non_rigid_linear_min_factor=0.5, non_rigid_step_depth_boundary=None, non_rigid_step_factors=None, preferred_dir=[0, 0, 1], slow_drift_velocity=5, slow_drift_waveform='triangluar', slow_drift_amplitude=None, fast_drift_period=10.0, fast_drift_max_jump=20.0, fast_drift_min_jump=5.0, external_drift_factors=None)[source]

Generate for each units a drift position vector. The output vector handle of indexes for drift steps along time.

Parameters:
  • drift_fs (float) – Sampling frequency in Hz

  • duration (float) – Duration drift vector in s

  • template_locations (np.array 3d) – Shape: (num_cells, drift_steps, 3) Template locations for every drift steps

  • external_drift_vector_um (1d array or None) – External drift signal to apply. It needs to be consistent with drift_fs and duration (or external_drift_times)

  • external_drift_times (1d array or None) – External drift times to use for external_drift_signal_um.

  • t_start_drift (float) – When the drift start in second

  • drift_mode_probe ('rigid' or 'non-rigid') – Global drift or per cell.

  • drift_mode_speed (str 'slow', 'fast', 'slow+fast') – Drift mode speed

  • non_rigid_gradient_mode ('linear' | 'step') – Mode to generate non rigid gradient over units on velocity. If ‘linear’, drift factors (0.5-1) are assigned to each cells linearly with depth (deeper cells have more drift).

  • non_rigid_linear_direction (int) – Direction of linear gradient. Only used if ‘drift_mode_probe’ is ‘non-rigid’ and ‘non_rigid_gradient_mode’ is ‘linear’ If positive, deeper cells drift more than surface cells. If negative, deeper cells drift more than surface cells. Zero is not allowed, by default 1

  • non_rigid_linear_min_factor (float (default 0.5)) – When non_rigid_gradient_mode=’linear’ this control the minimum factor. The max is always 1.

  • non_rigid_step_depth_boundary (float or None) – Depth boundary in the preferred_dir dimension to apply the drift step, by default is half of the template locations extensions. Only used if ‘drift_mode_probe’ is ‘non-rigid’ and ‘non_rigid_gradient_mode’ is ‘step’

  • non_rigid_step_factors (None or tuple/list of two elements) – Factors to apply to cells above (non_rigid_step_factors[0]) and below (non_rigid_step_factors[1]) step depth boundary. Default is (1, 0). Only used if ‘drift_mode_probe’ is ‘non-rigid’ and ‘non_rigid_gradient_mode’ is ‘step’

  • preferred_dir (list of int) – Use for gradient when non rigid mode.

  • slow_drift_velocity (float) – Slow drift velocity in um/min.

  • slow_drift_waveform ('trianglar' or 'sine') – Waveform shape for slow drift

  • fast_drift_period (float) – Period between fast drift events

  • fast_drift_max_jump (float) – Maximum ‘jump’ in um for fast drifts

  • fast_drift_min_jump (float) – Minimum ‘jump’ in um for fast drifts

  • external_drift_factors (None) – If templates are selected externally (and template_ids) is used in the generate_recordings() function, this vector specifies the factor (0-1) for each cell.

Returns:

drift_list

Each dict contains info for a drift signal:
  • ”drift_times” (1d array): times for different drift vectors. (Only for external times)

  • ”drift_fs” (float): sampling frequency

  • ”drift_vector_um” (1d array): drift signals in um

  • ”drift_vector_idxs” (1d array): drift signals in template idxs (with respect to middle step)

  • ”drift_factor” (1d array): array with gradient for each unit for the drift signal

    vector. For rigid motion, all values are 1.

Return type:

list of dicts

Module MEArec.simulate_cells

Test implementation using cell models of the Blue Brain Project with LFPy. The example assumes that cell models available from https://bbpnmc.epfl.ch/nmc-portal/downloads are unzipped in the folder ‘cell_models’

The function compile_all_mechanisms must be run once before any cell simulation

MEArec.simulate_cells.calculate_extracellular_potential(cell, mea, ncontacts=10, position=None, rotation=None)[source]

Calculates extracellular signal in uV on MEA object.

Parameters:
  • cell (LFPy Cell) – The simulated cell

  • mea (MEA, str, or dict) – Mea object from MEAutility, string with probe name, or dict with probe info

Returns:

v_ext – Extracellular potential computed on the electrodes (n_elec, n_timestamps)

Return type:

np.array

MEArec.simulate_cells.return_bbp_cell(cell_folder, end_T, dt, start_T, verbose=0)[source]

Function to load cell models

Parameters:
  • cell_folder (string) – Path to folder with the BBP cell model

  • end_T (float) – Simulation length [ms]

  • dt (float) – Time step of simulation [ms]

  • start_T (float) – Simulation start time (recording starts at 0 ms)

Returns:

cell – LFPy cell object

Return type:

object

MEArec.simulate_cells.return_bbp_cell_morphology(cell_name, cell_folder, pt3d=False)[source]

Function to load cell models

Parameters:
  • cell_name (string) – Name of the cell type.

  • cell_folder (string) – Folder containing cell models.

  • pt3d (bool) – If True detailed 3d morphology is used

Returns:

cell – LFPy cell object

Return type:

object

MEArec.simulate_cells.run_cell_model(cell_model_folder, verbose=False, sim_folder=None, save=True, custom_return_cell_function=None, **kwargs)[source]

Run simulation and adjust input strength to have a certain number of spikes (target_spikes[0] < num_spikes <= target_spikes[1] where target_spikes=[10,30] by default)

Parameters:
  • cell_model_folder (string) – Path to folder where cell model is saved.

  • verbose (int) – If 1, output is verbose

  • save (bool) – If True, currents and membrane potentials are saved in ‘sim_folder’. If False the function returns the simulated cell, the soma potentials of the spikes, and the transmembrane currents of the spikes

  • sim_folder (string) – Data directory for transmembrane currents and membrane potential of the neuron.

  • custom_return_cell_function (function) – Python function to to return an LFPy cell from the cell_model_folder

  • **kwargs (keyword arguments) – Kwargs must include: ‘sim_time’, ‘dt’, ‘delay’, ‘weights’, ‘target_spikes’, ‘cut_out’, ‘seed’

Returns:

  • cell (object) – LFPy cell object (if save is False)

  • v (np.array) – Array (N_spikes x t) with soma membrane potential (if save is False)

  • i (np.array) – Array (N_spikes x N_compartments x t) with transmembrane currents (if save is False)