Session YAML

This page lists every key of the session YAML, the file that tells the GUI where each dataset of a session is. Open it from the data source button (... → Open session YAML…) or with alignment-gui -y <file> (see Command line).

Structure

path: /base/folder              # optional

defaults:                       # optional
  <dataset>:
    path: <path>

probes:                         # either probes ...
  <probe name>:
    path: <path>                # optional
    datasets:
      <dataset>:
        path: <path>

configurations:                 # ... or configurations, not both
  <configuration name>:
    path: <path>                # optional
    probes:
      <probe name>:
        ...                     # as under probes above

Keys

Top level

path: Base folder that relative paths are resolved against. Optional.
defaults: A path for each dataset, used for every probe that does not give its own. Optional.
probes: The probes of the session, by name. The names are used for the shank tabs. Use either probes or configurations.
configurations: Up to two configurations, by name, shown side by side and aligned together. Each holds its own probes. Every configuration must contain the same probe names. A file with probes and no configurations is treated as a single configuration.

Configuration

path: Base folder for the probes of this configuration. Optional.
probes: The probes of this configuration, by name, as under the top-level probes.

Probe

path: Base folder for the datasets of this probe. Optional.
datasets: A path for each dataset, by dataset name. A dataset given as {}, or left out, uses its path from defaults.

Dataset

path: Folder holding the dataset, absolute or relative. ~ is expanded to the home folder. For features it is the path to a file rather than a folder.

Datasets

Every probe must give output, the folder the results are written to, and at least one of spike_sorting and processed_ephys. A probe without spike_sorting must also give raw_ephys, the folder with the .ap.meta file, which is then the only source of the probe geometry. A dataset that is only read, and is not given, is looked for where it is usually saved: the trajectory beside the spike sorting, and the RMS and power spectra beside the raw data or the spike sorting. The raw data is never looked for.

Dataset	Contents	If not given
`output`	Where the results are written	Required
`spike_sorting`	Spike sorting output	Required if `processed_ephys` is not given; otherwise the plots that need spike sorting are empty
`processed_ephys`	RMS and power spectra	Read from `raw_ephys`, or from `spike_sorting` if there is no `raw_ephys`; required if neither is given
`picks`	Traced probe trajectory	Read from `spike_sorting`; required if there is no `spike_sorting`
`raw_ephys`	Raw SpikeGLX recordings and metadata	No raw data snippets are shown; required if `spike_sorting` is not given
`histology`	Histology volumes	Only the Allen atlas slices are shown
`features`	Per-channel features file	No channel predictions

The files expected in each dataset are listed in Input datasets and Output files.

Path resolution

A dataset’s path is its own path, or the one from defaults if it gives none. An absolute path is used as it is. A relative path has the base folders prepended in this order until it is absolute:

the probe’s path
the configuration’s path
the top-level path

If it is still relative after all three, loading fails with an error. How this works, with worked examples, is explained in How session YAML paths are resolved.

Errors

Loading the file fails when:

the file does not exist, is empty, or does not hold a mapping
a probe does not give output, gives neither spike_sorting nor processed_ephys, or has no picks and no spike_sorting to read them from
a probe without spike_sorting does not give raw_ephys
there are more than two configurations
the configurations do not all contain the same probes
a relative path cannot be made absolute

Example

path: /mnt/data/subject01/2025-01-15

defaults:
  histology:
    path: /mnt/data/subject01/histology

probes:
  probe00:
    datasets:
      spike_sorting:
        path: probe00/kilosort
      processed_ephys:
        path: probe00/kilosort
      raw_ephys:
        path: probe00/spikeglx
      picks:
        path: probe00/picks
      output:
        path: probe00/alignment