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
- 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
- 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:
- 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:
- 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:
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:
- 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:
- 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, include_spike_traces: bool = True)[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
include_spike_traces (bool, default=True) – If True, will include the spike traces (which can be large for many units)
- 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)