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 and selecting 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.

Launch the GUI using:

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

Required and Optional Datasets

Each YAML file must define paths for the following datasets:

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

The following 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.

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 number of probes with matching probe identifiers.

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

When a relative path is specified for a dataset, the system searches for a base directory in the following order:

1. Dataset-level path — explicitly defined within the dataset’s path field

2. Default path — defined in the defaults section

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

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

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

During the search for the base directory it will join together relative paths to build the final absolute path.

If a dataset uses an empty specification ({}), the default path is appended to the resolved base path.

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
    backend: phylib
  raw_ephys:
    path: spikeglx
    backend: 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