API Reference

class spikewrap.Session(subject_path, session_name, file_format, run_names='all', output_path=None, probe=None)

Bases: object

Represents an electrophysiological recording session, consisting of a single or multiple runs. Exposes functions for preproecssing and sorting data from the session.

Parameters:

• subject_path (Path | str) – The path to the subject’s directory. This should contain the session_name directory.

• session_name (str) – The name of this session. Must match the session folder name in the subject_path.

• file_format (Literal['spikeglx', 'openephys']) – Acquisition software used for recording, either "spikeglx" or "openephys". Determines how a session’s runs are discovered.

• run_names (Union[Literal['all'], list[str]]) – Specifies which runs within the session to include. If "all" (default), includes all runs detected within the session. Otherwise, a list of str, a list of specific run names. Each name must correspond to a run folder within the session. Order passed will be the concentration order.

• output_path (Path | None) – The path where preprocessed data will be saved (in NeuroBlueprint style).

• probe (Probe | None) – A ProbeInterface probe object to set on the recordings. If None, auto-detection of probe is attempted.

Notes

The responsibility of this class is to manage the processing of runs contained within the session. Raw data are held in self._raw_runs, a list of SeparateRawRun. The sync channel (if available) is held on the raw run in a recording object (other channels unused) and possibly mutated. load_raw_runs() will refresh the run sync channels.

self._pp_runs is filled by self.preprocess(). Copies of _raw_runs are concatenated and / or split-by-shank before preprocessing, which fills self._pp_runs. The sync channel is attached in-memory (no longer on a recording).

self._sorting_runs contains the sorting based on self._pp_runs. Again, copies of preprocessing runs are concatenated and / or split by shank before sorting.

Properties of this class should never be modified from outside the class.

preprocess(configs, concat_runs=False, per_shank=False)

Preprocess recordings for all runs for this session.

This step is lazy, under the hood running the preprocessing steps from configs on SpikeInterface recording objects. Preprocessing of data is performed on the fly when required (e.g. plotting, saving or sorting).

Parameters:

• configs (dict | str | Path) –

  • If a str is provided, expects the name of a stored configuration file. See show_available_configs() and save_config_dict() for details.

  • If a Path is provided, expects the path to a valid spikewrap config YAML file.

  • A spikewrap configs dictionary, either including the "preprocessing" level or the "preprocessing" level itself. See documentation for details.

• concat_runs (bool) – If True, all runs will be concatenated together before preprocessing. Use session.get_raw_run_names() to check the order of concatenation.

• per_shank (bool) – If True, perform preprocessing on each shank separately.

• overwrite_in_memory – If False (default), the

Return type:

None

save_preprocessed(overwrite=False, chunk_duration_s=2, n_jobs=1, slurm=False)

Save preprocessed data for all runs in the current session.

This method iterates over each run in the session and invokes the save_preprocessed method to persist the preprocessed data. It supports options to overwrite existing data, specify chunk sizes for data saving, utilize parallel processing, and integrate with SLURM for job scheduling.

Parameters:

• overwrite (bool) – If True, existing preprocessed run data will be overwritten. Otherwise, an error will be raised.

• chunk_duration_s (float) – Size of chunks which are separately to preprocessed and written.

• n_jobs (int) – Number of parallel jobs to run for saving preprocessed data. Sets SpikeInterface’s set_global_job_kwargs.

• slurm (dict | bool) – Configuration for submitting the save jobs to a SLURM workload manager. If False (default), jobs will be run locally. If True, job will be run in SLURM with default arguments. If a dict is provided, it should contain SLURM arguments. See tutorials in the documentation for details.

Return type:

None

plot_preprocessed(run_idx='all', mode='map', time_range=(0.0, 1.0), show_channel_ids=True, show=False, figsize=(10, 6))

Plot preprocessed run data.

One plot will be generated for each run. For preprocessing per-shank, each shank will appear in a subplot. Under the hood, calls SpikeInterface’s plot_traces() function.

Parameters:

• run_idx –

  • If "all", plots preprocessed data for all runs in the session.

  • If an integer, plots preprocessed data for the run at the specified index in self._pp_runs.

• mode – Determines the plotting style, a heatmap-style or line plot.

• time_range – Time range (start, end), in seconds, to plot. e.g. (0.0, 1.0)

• show_channel_ids – If True, displays the channel identifiers on the plots.

• show – If True, displays the plots immediately. If False, the plots are generated and returned without being displayed.

• figsize – Specifies the size of the figure in inches as (width, height).

Returns:

dict of {str – A dictionary mapping each run’s name to its corresponding matplotlib.Figure object.

Return type:

matplotlib.Figure}

sort(configs, run_sorter_method='local', per_shank=False, concat_runs=False, overwrite=True, slurm=False)

Sort the preprocessed recordings (self.get_preprocessed_run_names()) and save the output to disk.

Parameters:

• configs (str | dict) –

  • If a str is provided, expects the name of a stored configuration file. See show_available_configs() and save_config_dict() for details.

  • If a Path is provided, expects the path to a valid spikewrap config YAML file.

  • A spikewrap configs dictionary, either including the "sorting" level or the "sorting" level itself. Only 1 sorter at a time currently supported.

• run_sorter_method (str) –

  • if “local”, use the current python environment to run sorting (e.g. for kilosort4)

  • if a path (either string or Path), must be the path to a matlab repository used to run the sorter (e.g. kilosort 2.5 repository).

  • if “docker” or “singularity”, docker or singularity will be used to run the sorting. singularity images are stored in a folder at the level of “rawdata” and “derivatives”.

• per_shank (bool) – If True, preprocessed recordings will be split by shank. If preprocessed recordings were already split by shank for preprocessing, this should be False.

• concat_runs (bool) – If True, preprocessed runs will be concatenated togerher before sorting. If runs were already concatenated before preprocessing, this should be False.

• overwrite (bool) – If True, existing outputs will be overwritten. Otherwise, an error will be raised if existing outputs are found.

• slurm (bool) – Configuration for submitting the save jobs to a SLURM workload manager. If False (default), jobs will be run locally. If True, job will be run in SLURM with default arguments. If a dict is provided, it should contain SLURM arguments. See tutorials in the documentation for details.

wait_for_slurm()

Run a while loop with pause until all slurm jobs are complete.

get_raw_run_names()

Return a list of run names for the raw data.

Their order is the order in which any concatenation will be performed.

Return type:

list[str]

get_preprocessed_run_names()

Return a list of names of the preprocessed data. If data was concatenated, the run name will be “concat_run”.

If not concatenated, their order is the order concatenation will take place prior to sorting (if concat_run=True).

Return type:

list[str]

parent_input_path()

Name of the parent path for this sessions raw data (i.e. the path of the subject folder).

Return type:

Path

get_output_path()

The path where processed data will be output for this session.

Return type:

Path

load_raw_data(overwrite=False)

Load raw data, to allow editing of the sync channel. Note this will overwrite any previous editing of the sync channel.

Return type:

None

get_sync_channel(run_idx)

Return the sync channel in a numpy array. Currently only Neuropixels (sync channel is 385th channel) supported.

Parameters:

run_idx (int) – Index of the run to get the sync channel from, as ordered by self.get_raw_run_names().

plot_sync_channel(run_idx, show=True)

Plot the sync channel for the run.

Parameters:

• run_idx (int) – Index of the run to get the sync channel from, as ordered by self.get_raw_run_names().

• show (bool) – If True, plt.show() is called.

Return type:

list[Line2D]

silence_sync_channel(run_idx, periods_to_silence)

Set periods on the sync channel to zero.

Parameters:

• run_idx (int) – Index of the run to get the sync channel from, as ordered by self.get_raw_run_names().

• periods_to_silence (list[tuple]) – A list of 2-tuples, where each entry in the tuples are the (start, stop) sample to silence. For example, [(0, 10), (50, 500)] will set the samples 0 - 10 and 50 - 500 to zero.

Return type:

None

save_sync_channel(overwrite=False, slurm=False)

Save all loaded runs sync channel to disk.

Return type:

None

raw_runs_loaded()

spikewrap.get_example_data_path(file_format='spikeglx')

Get the path to the example data directory. This contains a very small example spikeglx dataset in NeuroBlueprint format.

Returns:

Path to the root folder of the example dataset.

Return type:

Path

spikewrap.show_configs(name)

Print the configuration options.

Return type:

None

spikewrap.get_configs_path()

Get the path to the User home directory folder in which all spikewrap config yamls are stored.

Returns:

The path to the spikewrap configs directory.

Return type:

Path

spikewrap.show_supported_preprocessing_steps()

Print the (currently supported) SpikeInterface preprocessing steps.

Return type:

None

spikewrap.show_available_configs()

Print the file names of all YAML config files in the user config path.

Return type:

None

spikewrap.load_config_dict(filepath)

Load a configuration dictionary from a YAML file.

Parameters:

filepath (Path) – The full path to the YAML file, including the file name and extension.

Returns:

The configs dict loaded from the YAML file.

Return type:

dict

spikewrap.save_config_dict(config_dict, name, folder=None)

Save a configuration dictionary to a YAML file.

Parameters:

• config_dict (dict) – The configs dictionary to save.

• name (str) – The name of the YAML file (with or without the .yaml extension).

• folder (Path | None) – If None (default), the config is saved in the spikewrap-managed user configs folder. Otherwise, save in folder.

spikewrap.default_slurm_options(partition='cpu')

Get a set of default SLURM job submission options based on the selected partition.

All arguments correspond to sbatch arguments except for:

wait

Whether to block the execution of the calling process until the job completes.

env_name

The name of the Conda environment to run the job in. Defaults to the active Conda environment of the calling process, or “spikewrap” if none is detected. To modify this, update the returned dictionary directly.

Parameters:

partition (Literal['cpu', 'gpu']) – The SLURM partition to use.

Returns:

Dictionary of SLURM job settings, including:

nodes - The number of nodes to allocate for the job. mem_gb - The amount of memory (in gigabytes) to allocate per node for the job. timeout_min - The maximum runtime in minutes before the job is terminated. cpus_per_task - The number of CPUs allocated per task. tasks_per_node - The number of tasks to run on each node. slurm_partition - The SLURM partition (queue) to submit the job to. slurm_gres - The generic resources (e.g., GPUs) to allocate for the job, specified in the format required by SLURM. exclude - A list of nodes to exclude from the job allocation. wait - if True, freeze execution until slurm job is finished. env_name - The name of the environment (e.g., conda or virtualenv) to activate before running the job.

Return type:

options

spikewrap.run_in_slurm(slurm_opts, func_to_run, log_base_path, suffix_name=None)

Run a function in a slurm job.

Parameters:

• slurm_opts (None | dict) – A dictionary of options that control execution of the slurm job. See spikewrap.default_slurm_options() for details.

• func_to_run (Callable) – The function to run inside the slurm job.

• log_base_path (Path) – The path where a folder slurm logs will be output

• suffix_name (str | None) – If given (default None), a suffix for the output folder e.g. _sort