Usage

Basic Usage

To launch the alignment GUI with default settings, run:

alignment-gui

This opens the GUI window. You can then load your data by clicking the ... button in the top-right corner, selecting Open data folder…, and choosing the directory containing your data files.

Note

This mode assumes that all required data (spike sorting output, raw electrophysiology recordings, probe trajectory files, and histology volumes) are located within the same directory.

Specifying Data Directories with YAML

For finer control over data locations, you can provide a YAML configuration file that explicitly specifies the paths to required inputs.

The YAML can either be passed on the command line when the GUI is launched:

alignment-gui -y path/to/config.yaml

or chosen once the GUI is running, from the ... button in the top right corner by selecting Open session YAML…. Both are equivalent, and a different session YAML can be selected at any time without restarting the GUI.

Required and Optional Datasets

Each probe must have at least two paths to datasets defined. The picks directory containing the probe trajectory and the spike_sorting directory containing the spike sorting output.

Dataset	Description
spike_sorting	Directory containing spike sorting output (e.g., Kilosort, PyKilosort).
picks	Directory containing probe trajectory pick files.

Note

For the format of the files each of these folders is expected to contain, see Datasets.

The following paths to datasets are optional:

Dataset	Description
raw_ephys	Directory containing raw electrophysiology recordings
processed_ephys	Directory containing processed electrophysiology data. If not provided, defaults to raw_ephys path
histology	Directory containing histology volumes (typically defined in defaults)
output	Directory where alignment outputs will be saved. If not provided, defaults to spike_sorting path

Single-Probe Configuration

The simplest configuration specifies paths for a single probe.

Example YAML:

defaults:
  histology:
    path: /path/to/histology

probes:
  probe_00:
    datasets:
      spike_sorting:
        path: /path/to/probe_00/spike_sorting
      processed_ephys:
        path: /path/to/probe_00/processed_ephys
      raw_ephys:
        path: /path/to/probe_00/raw_ephys
      picks:
        path: /path/to/probe_00/picks
      output:
        path: /path/to/probe_00/alignment_outputs

Launch command:

alignment-gui -y path/to/single_probe.yaml

Multi-Probe Configuration

The GUI supports visualization of up to four probes simultaneously. This is particularly useful for multi-shank probes (e.g., Neuropixels 2.0 with 4 shanks), where data from each shank have been spike-sorted independently.

Note

Probes are visualized simultaneously, but alignment is performed independently for each probe.

Warning

When multiple probes are specified, the GUI does not split data automatically. Each probe’s data must already be separated on disk.

Warning

Each probe entry must be given its own output path. Because each entry is treated as a single-shank probe, the results are written as channel_locations.json and prev_alignments.json with no shank suffix, so two entries sharing an output path will silently overwrite each other’s results and read back each other’s previous alignments.

Example: four-probe configuration

path: /path/to/session_data

defaults:
  histology:
    path: /common/path/to/histology

probes:

  shank_0:
    datasets:
      spike_sorting:
        path: shank_0/spike_sorting
      processed_ephys:
        path: shank_0/processed_ephys
      raw_ephys:
        path: shank_0/raw_ephys
      picks:
        path: shank_0/picks
      output:
        path: shank_0/output

  shank_1:
    datasets:
      spike_sorting:
        path: shank_1/spike_sorting
      processed_ephys:
        path: shank_1/processed_ephys
      raw_ephys:
        path: shank_1/raw_ephys
      picks:
        path: shank_1/picks
      output:
        path: shank_1/output

  shank_2:
    datasets:
      spike_sorting:
        path: shank_2/spike_sorting
      processed_ephys:
        path: shank_2/processed_ephys
      raw_ephys:
        path: shank_2/raw_ephys
      picks:
        path: shank_2/picks
      output:
        path: shank_2/output

  shank_3:
    datasets:
      spike_sorting:
        path: shank_3/spike_sorting
      processed_ephys:
        path: shank_3/processed_ephys
      raw_ephys:
        path: shank_3/raw_ephys
      picks:
        path: shank_3/picks
      output:
        path: shank_3/output

Launch command:

alignment-gui -y path/to/multi_probe.yaml

Dual Configuration Mode

Dual configuration mode allows side-by-side comparison of two separate configurations within the same GUI window.

Typical use cases:

• Comparing different channel maps (e.g., dense vs. sparse)

• Evaluating spike sorting parameters

• Comparing preprocessing pipelines

Key characteristics:

• Two configurations are displayed side by side

• Alignment is performed jointly across both configurations

• Both configurations must reference the same probe identifiers

Example: dual-configuration YAML

defaults:
  histology:
    path: /path/to/histology

configurations:
  dense:
    path: /path/to/dense_session
    probes:
      probe_00:
        datasets:
          spike_sorting:
            path: alf/probe00/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00
          picks:
            path: alf/probe00/kilosort
          output:
            path: alignment_outputs

  sparse:
    path: /path/to/sparse_session
    probes:
      probe_00:
        datasets:
          spike_sorting:
            path: alf/probe00/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00
          picks:
            path: alf/probe00/kilosort
          output:
            path: alignment_outputs

Launch command:

alignment-gui -y path/to/dual_config.yaml

Note

Configuration keys (e.g., dense and sparse) may be named arbitrarily.

Combining Dual Configuration and Multi-Probe Modes

Dual configuration mode can be combined with multi-probe mode to compare multiple probes across two configurations simultaneously.

Important

Both configurations must contain the same probes, with matching probe identifiers. An error is raised if they do not.

Example: dual + multi-probe YAML

defaults:
  histology:
    path: /path/to/histology

configurations:
  dense:
    path: /path/to/dense_session
    probes:
      shank_0:
        datasets:
          spike_sorting:
            path: alf/probe00a/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00a
          picks:
            path: alf/probe00a/kilosort
          output:
            path: alignment_outputs/probe00a

      shank_1:
        datasets:
          spike_sorting:
            path: alf/probe00b/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00b
          picks:
            path: alf/probe00b/kilosort
          output:
            path: alignment_outputs/probe00b

  sparse:
    path: /path/to/sparse_session
    probes:
      shank_0:
        datasets:
          spike_sorting:
            path: alf/probe00a/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00a
          picks:
            path: alf/probe00a/kilosort
          output:
            path: alignment_outputs/probe00a

      shank_1:
        datasets:
          spike_sorting:
            path: alf/probe00b/kilosort
          raw_ephys:
            path: raw_ephys_data/probe00b
          picks:
            path: alf/probe00b/kilosort
          output:
            path: alignment_outputs/probe00b

Launch command:

alignment-gui -y path/to/dual_multi_probe.yaml

Advanced YAML Configuration

The YAML system supports defaults and hierarchical path resolution to minimize repetition when working with multiple probes or configurations.

Using Defaults

The defaults section allows you to specify common paths and settings that apply to all probes and configurations. This is particularly useful for:

• Shared resources like histology volumes that are common across multiple sessions

• Standard directory names that follow consistent naming conventions

Example:

defaults:
  histology:
    path: /common/path/to/histology
  spike_sorting:
    path: kilosort
  raw_ephys:
    path: spikeglx

How defaults work:

• Default paths are applied when a dataset path is not explicitly specified

• They can be overridden at any level (configuration, probe, or dataset)

• An empty dataset specification ({}) uses the default path

Tip

Use defaults to establish naming conventions across your project. For example, if you always save Kilosort output in a directory called kilosort, specify this in defaults rather than repeating it for each probe.

Using Base Paths

The YAML configuration supports path keys at multiple hierarchical levels to define base directories for resolving relative paths. This allows you to avoid repeating common path prefixes across multiple datasets.

Path Resolution Priority

A dataset’s path is taken from its own path field, or from the matching entry in the defaults section if the dataset does not give one. Giving an empty specification ({}) and leaving the dataset out altogether both fall back to the default.

If that path is absolute it is used as it is. If it is relative, it is resolved against the first absolute base directory found, in the following order:

1. Per-probe path — defined within an individual probe configuration

2. Per-configuration path — defined within an individual configuration

3. Top-level path — defined at the root of the YAML file

Each level is prepended in turn, joining the relative paths together, until the path is absolute. If none of them make it absolute an error is raised.

Note

The defaults section supplies dataset paths, not base directories. A default is used in place of a dataset’s own path, never as a root to resolve one against, so a dataset that gives its own relative path is resolved against the base directories above and its default is not used at all.

Note

Absolute paths (those starting with / on Unix/Linux/macOS or a drive letter on Windows) always take precedence and are used as-is, ignoring any base paths defined at higher levels.

Tip

Define base paths at the highest applicable level to minimize repetition. For example, if all probes share a common session directory, define it at the configuration level rather than repeating it for each probe.

Examples Using Base Paths

Each example below demonstrates the path resolution logic used to determine the final dataset paths.

1. Top-level base path

path: /mnt/data

probes:
  probe_00:
    datasets:
      spike_sorting:
        path: probe_00/kilosort

Resolves to:

/mnt/data/probe_00/kilosort

2. Per-configuration base path

path: /mnt/data

configurations:
  dense:
    path: dense_session
    probes:
      probe_00:
        datasets:
          spike_sorting:
            path: kilosort

Resolves to:

/mnt/data/dense_session/kilosort

3. Per-probe base path

path: /mnt/data

probes:
  probe_00:
    path: probe_00
    datasets:
      spike_sorting:
        path: kilosort

Resolves to:

/mnt/data/probe_00/kilosort

4. Dataset-level path (highest priority)

path: /mnt/data

probes:
  probe_00:
    path: probe_00
    datasets:
      spike_sorting:
        path: /custom/location/kilosort

Resolves to:

/custom/location/kilosort

5. Using defaults with empty dataset specification

path: /mnt/data

defaults:
  spike_sorting:
    path: pykilosort

probes:
  probe_00:
    path: probe_00
    datasets: {}

Resolves to:

/mnt/data/probe_00/pykilosort

Complete Example with Path Hierarchy

This comprehensive example demonstrates how different path resolution levels work together:

path: /mnt/s0/Data

defaults:
  histology:
    path: /common/histology/subject_001
  spike_sorting:
    path: pykilosort
  raw_ephys:
    path: spikeglx

configurations:
  dense:
    path: dense_session
    probes:
      probe_00:
        path: probe_00
        datasets:
          processed_ephys:
            path: pykilosort
          picks:
            path: /custom/path/to/picks  # Absolute path overrides
          output:
            path: alignment_outputs

  sparse:
    path: sparse_session
    probes:
      probe_00:
        path: probe_00
        datasets:
          spike_sorting:
            path: kilosort
          processed_ephys:
            path: raw_ephys_data
          raw_ephys: {}
          picks:
            path: kilosort
          output: {}  # Defaults to spike_sorting path

Resolved paths for this configuration:

Configuration / Probe	Dataset	Resolved Path
Dense / probe_00	spike_sorting	/mnt/s0/Data/dense_session/probe_00/pykilosort
	processed_ephys	/mnt/s0/Data/dense_session/probe_00/pykilosort
	raw_ephys	/mnt/s0/Data/dense_session/probe_00/spikeglx
	picks	/custom/path/to/picks
	histology	/common/histology/subject_001
	output	/mnt/s0/Data/dense_session/probe_00/alignment_outputs
Sparse / probe_00	spike_sorting	/mnt/s0/Data/sparse_session/probe_00/kilosort
	processed_ephys	/mnt/s0/Data/sparse_session/probe_00/raw_ephys_data
	raw_ephys	/mnt/s0/Data/sparse_session/probe_00/spikeglx
	picks	/mnt/s0/Data/sparse_session/probe_00/kilosort
	histology	/common/histology/subject_001
	output	/mnt/s0/Data/sparse_session/probe_00/kilosort