SpikeGLX User Manual

Topics:

Appendix:

Overview

Additional Guides

PXIe

System requirements for PXI.

OneBox

Quadbase Probes

Help

SpikeGLX Ecosystem

SpikeGLX, the acquisition app, is just one component of our Neuropixels data processing system:

Data Review

Online Integration

SpikeGLX setup tips here.

Offline Postprocessing

Refer to our download page, where we describe a host of associated tools, including:

And more.

Help

Also on our download page, you’ll find many videos and help documents on installing, getting started, running and troubleshooting. There’s also a link to the Neuropixels Discord server which hosts a community of ~3000 users.

Installing SpikeGLX

To install SpikeGLX on a new system, just copy a virgin SpikeGLX folder to your C-drive and double click SpikeGLX.exe to begin.

Do not put the SpikeGLX folder within the Windows Program Files folder or any other location that requires administrator permissions.

The contents of a virgin (see below) SpikeGLX folder:

SpikeGLX/
    _Calibration/
    _Help/
    _ImroX/
    _Waves/
    generic/
    iconengines/
    imageformats/
    networkinformation/
    platforms/
    styles/
    tls/
    translations/
    D3Dcompiler_47.dll
    FpgaManager.dll
    FTD3XX.dll
    libgcc_s_seh-1.dll
    libstdc++-6.dll
    libwinpthread-1.dll
    msvcp(version).dll
    msvcp(version)-atomic-wait.dll
    NeuropixAPI_version_info.dll
    opengl32sw.dll
    qt.conf
    Qt6Core.dll
    Qt6Gui.dll
    Qt6Network.dll
    Qt6OpenGL.dll
    Qt6OpenGLWidgets.dll
    Qt6Svg.dll
    Qt6Widgets.dll
    SpikeGLX_STD.exe
    SpikeGLX_STD_NISIM.exe
    vcruntime(version).dll
    vcruntime(version_1).dll

Virgin: The SpikeGLX folder does not contain a _Configs subfolder.

_Configs Folder

There are no hidden Registry settings or other components placed into your system folders. Your personal preferences and settings will be stored in SpikeGLX/_Configs.

If you give the software to someone else (please do), delete the _Configs folder because several settings in there are machine-dependent.

The _Configs folder is automatically created (as needed) when SpikeGLX is launched.

Tip: As you work with SpikeGLX you’ll create several of your own custom files to remember preferred settings {channel mappings, imec readout tables, …}. Resist the urge to store these in the SpikeGLX folder. If you want to upgrade, and, we will add cool features over time, the clutter will make it much harder to figure out what you have to replace.

Calibration Data

Each imec probe has a folder, labeled by probe serial number, containing its associated calibration data files. For example, NP 1.0 probes need gain and ADC files, while NP 2.0 probes need only gain files. Other probe types may differ. In all cases, place each probe’s whole calibration folder into the SpikeGLX _Calibration subfolder.

SpikeGLX reads an EEPROM chip on the probe to obtain its serial and model number. The serial number is used to look up the matching calibration folder name.

Some older NP 2.0 headstages do not have EEPROM chips. For those headstages a dialog will pop up when you click Detect so that you can manually enter those headstage serial numbers (find them on the tags/stickers on the headstage). This allows manual association of the headstages with their calibration folders. If you run again with the identical collection of parts the dialog will fill in your previous serial numbers as a convenience.

When you click Detect the imec box may display a yellow warning icon and the text Cal Issue. This means either that, on the IM Setup tab you have selected the run-time calibration policy Skip all calibration, or, for at least one of the probes, the calibration folder could not be found. In other words, this run will be performed without applying calibration files to one or more of the probes.

By the way, the _Calibration subfolder also contains supplementary SpikeGLX data:

Do keep (transplant) the _Calibration subfolder when you upgrade SpikeGLX!

Remote Command Servers

SpikeGLX contains two TCP/IP command servers:

Upon first launch SpikeGLX configures both servers with a local-host (loopback) address. The severs are initially disabled for security. To enable scriptability use the server settings dialogs under the Options menu. Click My Address to set an appropriate interface (IP address). We recommend keeping the default port and timeout values.

Note: If your SpikeGLX address was assigned by a DNS service, it might change if other machines are added or removed on the network. Just click My Address again to read the updated value.

Data Directory

On first startup, the software will automatically create a directory called C:/SGL_DATA as a default output file storage location. Of course, the C:/ drive is the worst possible choice, but it’s the only drive we know you have. Please use menu item Options/Choose Data Directory to select an appropriate folder on your data drive.

You can store your data files anywhere you want. The menu item is a convenient way to “set it and forget it” for those who keep everything in one place. Alternatively, each time you configure a run you can revisit this choice on the Save tab of the Configure Acquisition dialog.

Multidrive Run Splitting

If you do very long recordings or use many probes you can distribute the data streams across multiple drives like this:

  1. Select Options/Choose Data Directory.
  2. Check the Multidrive box.
  3. Add additional paths to the directory table.

The result is as follows:

The mod operation is just the remainder when dividing j by N. For example, 7 mod 3 = 1.

Optimal Computer Settings

Real-time data acquisition (DAQ) is a demanding process. SpikeGLX monitors its performance and when it’s not working well, there are two principal symptoms. (1) You’ll get POP errors, which means an internal data buffer is overflowing because the computer isn’t keeping up with the data acquisition rate. Use the Metrics Window (Ctrl+M) and the Help file there to learn more about that. (2) SpikeGLX will command the run to stop if performance lag is too severe.

The following sections recommend computer usage/settings that either (A) Minimize non-essential activity (B) Allow the computer to operate at higher power levels, or, (C) Keep the system components from falling asleep on the job. You don’t necessarily need to do everything listed here; it depends upon how well your system is keeping up with your experiment demands. The most impactful things are listed first, so try them in this order.

Run Fewer Apps

Don’t make SpikeGLX compete with other processes for CPU and system resources. Run what you must for your experiment, but no more than that.

Your computer may contain a dozen background tasks that run at inopportune times. For example, Windows Update, or NI Updater. After a disruptive event use the System Event Viewer: Right-click Start button, select Event Viewer. Look at the logged time that the run stopped and search the Windows Logs, particularly the Application and System logs for events immediately prior to the disturbance. See if you can disable the offending task.

Note that when the computer boots up it can take several minutes to fully configure the OS and start all of its supporting software components. It’s a good idea to wait 5 minutes after a reboot before starting a DAQ run.

If Windows 10

The Windows 10 Task Scheduler runs “Microsoft Compatibility Appraiser” every day at around 3am or 4am in the morning. This task checks whether you should be notified to update your system from Windows 10 to 11. The scan drives CPU usage to 100% for several seconds and can disrupt a DAQ run, causing POP errors. If this is happening to you, Double-click the Disable_MS_Compat_Appraiser.bat script in your SpikeGLX download.

Screen Saver and Power Settings

  1. Find the Screen Saver control panel: Type “screen saver” into the Search Box on the Taskbar.
  1. Locate your Power Plan settings: There may be a power settings link in the Screen Saver control panel, or type “power settings” into the Search Box.

For data acquisition:

  1. Edit the high performance plan for even better performance, in either of two ways:

    1. As of version 20250525 The SpikeGLX download folder contains a script named DAQ_power_settings.bat. Double-click to run it. It makes the needed changes listed below, even in versions of the OS that hide advanced settings.

    2. Set advanced settings manually: Look for Advanced Settings or change plan settings or similar:

      • Put the computer to sleep: Never.
      • Hard disk/Turn off hard disk after: Never.
      • Sleep/Sleep after: Never.
      • Sleep/Allow wake timers: Disable.
      • USB settings/USB selective suspend setting: Disable.
      • Intel(R) Graphics Settings/Intel(R) Graphics Power Plan: Maximum Performance.
      • PCI Express/Link State Power Management: Off.
      • Processor power management/Minimum processor state: 5%.
      • Processor power management/System cooling policy: Active.
      • Processor power management/Maximum processor state: 100%.

Tip: For some settings, ‘Never’ might not appear as a choice. Try typing either ‘never’ or ‘0’ directly into the box.

Power Mode Controls

First, a reminder to acquire data plugged into AC power. Many computers have a utility to control performance. Perhaps a Power Mode slider in the System Tray, or a custom control panel to switch performance modes. Familiarize yourself with the controls provided by the computer’s vendor and be sure to set the highest performance option for DAQ runs.

On many computers Airplane Mode not only manages network connectivity, but also throttles power settings. So disable Airplane Mode for DAQ runs.

Graphics Settings

Note that many desktop CPUs don’t have an iGPU, so if you only have a dGPU there is no need to set the graphics device at all: it will always use the dGPU by default.

Tell Windows to use the appropriate graphics device for SpikeGLX:

  1. Type “Graphics settings” into the search box of the Windows Taskbar.
  2. Select Add desktop app.
  3. Navigate to and select SpikeGLX.exe.
  4. SpikeGLX now appears in the list; click on it.
  5. Select eitherPower Saving (intel graphics) or High Performance (your card).
  6. Restart SpikeGLX.

Read this for a detailed discussion of which graphics device is the best choice.

Here’s the summary…

A separate high performance card (dGPU, e.g. GeForce) is superior in rendering performance to a CPU’s built-in Intel graphics (iGPU), but it has a huge disadvantage. If the display is actually plugged into the Intel graphics device, the card has to push all those pixels over to the iGPU to display anything and that is a massive latency hit that competes with DAQ. Therefore, if the iGPU is already “good enough” then Intel is the better choice for SpikeGLX.

OK, what is good enough? Intel graphics performance can be captured by “execution units.” We want at least 64 execution units. Intel also specs graphics in terms of Xe cores, each of which is 16 execution units, so we want at least 4 Xe cores. These engines are generally good enough:

These are generally not good enough:

The best way to get the specs for your CPU’s built-in graphics is to do a Web search for your full processor model name, like “Intel Ultra 9 275HX” and then click the link for the Intel spec sheet.

Graphics Problems

If your Graph windows or Shank viewers appear black, or if they flash or flicker, there are solutions on the SpikeGLX FAQ page.

Vigilant Mode

Check this box on the IM Setup tab to keep the computer more alert during DAQ runs.

Network Adapter Settings

The settings listed here will minimize the impact of network traffic on data acquisition tasks by keeping the network components active, thus reducing latency.

  1. Open the Device Manager: Right-click Windows Start Button and select Device Manager.
  2. Click open Network adapters and find your Ethernet device.
  3. Double-click it to get the Properties dialog.
  4. On Power Management tab, uncheck Allow the computer to turn off this device to save power.
  5. On Advanced tab, make these choices (the ones you have):

Data Stream

The following technical background will help you understand and configure your system, and help explain data storage formats. A key concept is the data stream which has several parts:

Stream Components

On the input side, stream-specific hardware acquires data at its own characteristic sample rate and feeds that into a long stream buffer (FIFO queue). This happens in a reader thread.

The enqueued data are then available to other output threads:

Notes:

Each stream gets its own metadata and binary data files.

The file saving Trigger unit is shared between streams so that data files are better time synchronized.

Likewise, the GraphFetcher is shared to facilitate synchronous data viewing.

More cores allow better load balancing among these activities.

Supported Streams

SpikeGLX supports multiple concurrent data streams that you can enable independently each time you run:

Imec probes currently read out 384 channels of neural data and have 8 bits of status data (stored as a 16-bit SY word). Bit #0 of the status word signals that custom user FPGA code running on the Enclustra has detected an interesting neural event (NOT YET IMPLEMENTED). Status bit #6 is the sync waveform, the other bits are error flags. Each probe is its own stream.

Quad-probes (part number NP2020) have four separate shanks. 384 channels are read out from each shank, and the stream records 4 SY status words.

Imec OneBoxes are compact and inexpensive alternatives to PXI chassis. Each OneBox connects via USB. A box has two ports for neural headstages. The probes you plug into a OneBox are treated as additional imecj data streams, as if those probes were plugged into PXI modules. OneBoxes can also read up to 12 analog channels and those channels can be thresholded, making 12 pseudo digital channels. These nonneural inputs are referred to as OneBox streams, with labels obx0, obx1, and so on.

An Nidq device (M, X or S-series, digital, a.k.a. 62xx, 63xx, 61xx, 65xx) can be used to record auxiliary, usually non-neural, experiment signals. These devices offer several analog and digital channels. You can actually use two such devices if needed.

The Whisper system is a 32X multiplexer add-on that plugs into an NI device, giving you 256 input channels. Whisper requires S-series devices (61xx).

Stream Length

To allow fetching of peri-event context data the streams are sized to hold the smaller of {8 seconds of data, 40% of your available RAM}. We always generate a warning message with the length, like this: “History length limited to 8 seconds.” Making it a warning gives it a highlight color in the logs so you’ll take notice of it.

Channel Naming and Ordering

Imec Channels

Each imec stream acquires up to three distinct types of channels:

1. AP = 16-bit action potential channels
2. LF = 16-bit local field potential channels (some probes)
3. SY = 16-bit status/sync words (sync is bit #6)

Most probes read out 384 AP and a single SY channel. Some probes read out a separate LF band with the same channel count as the AP band. Quad-probes read out 1536 AP channels (384 from each of four shanks) and have four SY words (one per shank).

Throughout the software the channels are maintained in acquisition order. That is, each acquired sample (or timepoint) contains all 384 AP channels, followed by the 384 LF channels (if present), followed by the SY channel(s).

The channels all have names with two (zero-based) indices, like this:

AP0;0 .. AP383;383 | LF0;384 .. LF383;767 | SY0;768

For example, LF1;385 tells you: - This is an LF channel - It’s the second channel in the LF group - It’s the 386th channel overall

The second “overall” index (after the semicolon) is the index you should use for all GUI functions that select channels. For example:

imec Data Files Are Split

In memory, the LF channels are upsampled to 30kHz for symmetry with the AP channels. However, for better disk efficiency the AP and LF data are written out separately and the LF data have their natural sampling rate of 2.5kHz.

If you elected to save all channels YourFile.imec0.ap.bin would contain:

AP0;0 .. AP383;383 | SY0;768

and YourFile.imec0.lf.bin would contain:

LF0;384 .. LF383;767 | SY0;768

Note that the sync channel is duplicated into both files for alignment in your offline analyses. Note, too, that each binary file has a partner meta file.

OneBox Channels

Each OneBox stream acquires up to three distinct types of channels:

1. XA = 16-bit analog channels
2. XD = 16-bit digital words (packed lines)
3. SY = 16-bit status/sync word (sync is bit #6)

You can specify up to 12 analog channels to read out.

If you click the XD checkbox, all 12 channels are thresholded at 10% of the current voltage range maximum, and read out as the low-12 bits of a single 16-bit word.

Throughout the software the channels are maintained in acquisition order. That is, each acquired sample (or timepoint) contains the XA channels (if present), followed by the XD channel (if present), followed by the SY channel.

The channels all have names with two (zero-based) indices, like this:

XA0;0 .. XA11;11 | XD0;12 | SY0;13

For example, XD0;12 tells you: - This is the XD channel - It’s the 0th channel in the XD group - It’s the twelfth channel overall

The second “overall” index (after the semicolon) is the index you should use for all GUI functions that select channels. For example:

NIDQ Channels

There are four categories of channels {MN, MA, XA, XD} and these are acquired and stored in that order, though they may be acquired from either one or two NI devices (named say, ‘dev1 and ’dev2’).

1. MN = dev1 multiplexed neural signed 16-bit channels
2. (likewise from dev2)
3. MA = dev1 multiplexed aux analog signed 16-bit channels
4. (likewise from dev2)
5. XA = dev1 non-muxed aux analog signed 16-bit channels
6. (likewise from dev2)
7. XD = dev1 non-muxed aux digital unsigned 16-bit words (packed lines)
8. (likewise from dev2)

Notes:

  1. Within a multiplexed subgroup, like MN or MA, all the channels connected to a given multiplexer are grouped together. The names of the channels acquired from neural muxer #2 are “MN2C0”…“MN2C31”. Zero-based labeling is used throughout.

  2. If a second device is used, each MN, MA, … category within the central stream is seamlessly expanded as if there were a single higher capacity device.

  3. Channel names, e.g., “MA1C2;34” indicate both which channel this is within its own category (here, the 3rd channel in group MA1) and, which it is across all the channels in this stream (here, the 35th channel in the stream). The latter index (34) is how you should refer to this channel in save-strings, in trigger setups and for audio out selection.

  4. Up to 32 digital lines can be acquired from your main device (say, dev1) and from a secondary device (say, dev2). The number of bytes needed to hold dev1’s lines depends on the highest numbered line. If the highest named line is #31, then 32 bits are required, hence 4 bytes. If #14 is the highest, then 16 bits, hence 2 bytes are used to store the data for that device. Dev1 may need {0,1,2,3 or 4} bytes to hold its XD lines. Dev2 is evaluated the same way, but independently. In the stream, all the bytes for dev1 are together, followed by all those for dev2. These bytes are set into 16-bit words. Note that the metadata item nSavedChans tallies: analog 16-bit channels + digital 16-bit words.

  5. Trigger line numbering depends on bytes. Say XD1=“0:4,22” and XD2=“9.” Suppose you want to use line #9 on dev2 as a TTL trigger input. You should specify bit #33, here’s why: There are 6 bits used on dev1, but the highest is #22, so three bytes are needed. Therefore, the offset to the first bit (bit #0) on dev2 is 24. Add 9 to that to get 33.

  6. The streams, hence, graphs and data files, always hold an integral number of 16-bit fields. The bytes of digital data are likewise grouped into 16-bit words. There are anywhere from 0..4 bytes (B1) of dev1 lines followed by 0..4 bytes (B2) for dev2. The count of 16-bit words is int(1 + B1 + B2)/2). That means, divide by 2 and truncate (round down) to an integer.

  7. The Graphs window depicts digital data words as groups of 16-lines. The lowest line number in a group is at the bottom. In files the data words have the lowest numbered lines in the lowest order bits.

Shank Map

A shank map is a table describing where each neural channel is on your physical probe. This information is used for spatial channel averaging, and for activity visualization. Both imec and nidq streams can be used to record from probes, so can have associated shank maps.

A rudimentary tool is provided to create, edit and save nidq shank maps (and shank map (.smp) files). However, the shank map is automatically derived from the imro table for imec probes; imec shank maps are internal, they are not edited or saved directly.

If you do not supply a nidq map, a default layout is used for MN channels. The default is a probe with 1 shank, 2 columns and a row count equal to MN/2 (neural channel count / [2 columns]).

To make and use a custom nidq map you must save it in a file. The file format looks like this:

1,2,480     // header: nShanks,nColsPerShank,nRowsPerShank
0 0 0 1     // entry: iShank <space> iCol <space> iRow <space> iUsed
0 1 0 1
0 0 1 1
0 1 1 1
...         // one entry per spiking acquisition channel

This universal layout scheme has a few simple rules:

You can mark a site used=0 if you know it is broken or disconnected. For imec probes, we automatically set used=0 for reference sites and those you have turned off (bad channels) in the IM Setup tab.

Most importantly a shank map is a mapping from an acquisition channel to a probe location. So…while there can be more potential sites (nShanks x nCols x nRows) than channels…

Channel Map

The Graphs window arranges the channels in the standard acquisition order (AP, LF, SY), (XA, XD, SY) and (MN, MA, XA, XD) or in a user order that you can specify using a channel Map. Each stream gets its own channel map file.

A rudimentary tool is provided to create, edit and save channel maps (and channel map (.cmp) files).

If you do not supply a map, the default user order depends upon the stream. The imec default order follows the imro table, ordered first by shank, then going upward from tip to base. The nidq default is acquisition channel ordered.

To make and use a custom map you must save it in a file. The file format looks like this:

6,2,32,0,1   // header (type counts): MN,MA,C,XA,XD
MN0C0;0 256  // entry: channel-name;acq-index  <space>  sort-index
MN0C1;1 1
MN0C2;2 2
MN0C3;3 3
...
XD0;256 0    // this example makes the digital graph first

You can save and reuse channel map files in another run by loading that file from the Channel Map dialog. However, this only makes sense if the loaded map describes the same types and counts of channels as you’ve configured in the current run, hence, the header values, which are counts of channel types. The C value is the number of channels per muxer.

Editing the sort order simply consists of reordering the right-most column of sort-index values which must be in the range [0..N-1], where N is the total channel count. For digital data we don’t count individual lines. Rather we count 16-line blocks of channels.

You can edit these files in any text editor if you prefer. You can change channel name strings too (shh).

You can also change the channel map from the Graphs window by right-clicking on the graphs area and selecting Edit Channel Order....

Channel maps order the visual Graphs window. They do not alter the order of run data saved in .bin/.meta files, which are instead, always in acquired-channel-order.

File Format

For ALL types of data stream {imec, obx, nidq}, output data files are always paired; a .bin and a matching .meta file. The internal structure of these files is similar for any stream type…

Bin Files

The .bin file is the binary data. There is no header. The data are packed timepoints. Within each timepoint the 16-bit channels are packed and ordered exactly as described above in the section Channel Naming and Ordering. Note that a timepoint is always a whole number of 16-bit words. There is one 16-bit word per saved analog channel. At the rear of the timepoint are any saved digital lines, bundled together as the bits of 16-bit words as described in the notes above.

Meta Files

The .meta data are text files in “.ini” file format. That is, every line has the pattern tag=value. All of the meta data entries are described in the document Metadata_Help.html.

Each metadata file is written three times:

  1. When created.
  2. When firstSample is determined.
  3. When {fileSHA1, fileTimeSecs, fileSizeBytes} are determined.

fileTimeSecs = (fileSizeBytes/2/nSavedChans) / xxSampRate, xx={im,ob,ni}.

File Parsing Tools

The SpikeGLX Downloads Page has simple tools (MATLAB and python) demonstrating how to parse the binary and metadata files.

Save Channel Subset

Each hardware configuration tab determines which channels are acquired from that hardware and held in the central data stream. All acquired channels are shown in the Graphs window. However, you don’t have to save all of the channels to your disk files.

You can enter a print-page-range style string for the subset of channels that you want to save. This string is composed of index numbers in the range [0..N-1], where N is the total channel count. To save all channels you can use the shorthand string all, or *.

Notes:

  1. You can also change this list from the Graphs window by right-clicking on the graphs area and selecting Edit Saved Channels....

  2. In the Imro Editor Edit tab you can graphically select which channels to save with the Boxes => file chans button..

  3. Remember that digital lines are grouped into 16-bit words which are essentially pseudo-channels in your subset string. If you don’t save a given word of digital line data, several lines will be affected.

Imec Example

Suppose you are running an NP 1.0 probe.

Online, the probe stream consists of (769) 16-bit words: the (384) neural AP channels followed by (384) neural LF channels, and a 16-bit SY word that contains sync and flag bits. In the SpikeGLX interface you generally refer to these data words by their logical index numbers, which are 0-768 in this case. The AP-channels have logical index range [0:383], the LF have range [384:767] and the SY channel is 768.

Saving All

Note that NP1.0-like probes save AP-band and LF-band data in separate data files tagged as xxx.ap.yyy and xxx.lf.yyy, while NP2.0 probes, which are full-band, save a single file using the xxx.ap.yyy name type.

If we were saving all channels, then each timepoint of our ap.bin file would have 385 words = 384 neural + SY. The ap.meta would contain these entries about file format:

acqApLfSy=384,384,1         // count of channel types being acquired
nSavedChans=385             // total channel count saved to this file
snsApLfSy=384,0,1           // count of channel types saved in this file
snsSaveChanSubset=0:383,768 // saved-channel-i maps to acquired-channel-j

The lf.bin likewise has 385 words per timepoint, and the lf.meta entries are:

acqApLfSy=384,384,1         // same as AP: count of channel types acquired
nSavedChans=385             // complement: count saved to this file
snsApLfSy=384,0,1           // complement: LF + SY, but not AP
snsSaveChanSubset=384:768   // saved-channel-i maps to acquired-channel-j

Note that the common SY channel is stored in both files.

Saving Subset

Suppose on the IM Setup tab we enter 100:383,484:768 which means we are not saving AP 0-99, nor LF 384-483, so omitting the first 100 channels of each band. Then each .bin file will have 285 words per timepoint. These are the ap.meta entries:

acqApLfSy=384,384,1           // same: acquiring same channels
nSavedChans=285               // diff: now only 285 saved to file
snsApLfSy=284,0,1             // diff: count of channel types saved in this file
snsSaveChanSubset=100:383,768 // diff: note lowest channel is 100

The lf.bin in this example also have 285 words per timepoint and these lf.meta:

acqApLfSy=384,384,1           // same: acquiring same channels
nSavedChans=285               // diff: now only 285 saved to file
snsApLfSy=0,284,1             // diff: complement of AP set
snsSaveChanSubset=484:768     // diff: note lowest channel is 484

These mapping data are crucial to understanding the significance of the saved words.

Note that you can save any arbitrary subset of the 768 neural NP1.0 channels. You don’t have to make LF mirror the AP, but it makes a simpler example.

NI Example

Suppose you configured your NI device to acquire analog (XA) channels 3:6 and digital lines 0,1.

Online, your NI stream consists of (5) 16-bit words: the (4) analog channels followed by a 16-bit word that contains lines 0,1 as bit-# 0,1 of that word. In the SpikeGLX interface you generally refer to these data words by their logical index numbers, which are 0-4 in this case. Let’s say you were recording sync in NI channel-5. Then on the Sync tab, for example, you would configure sync input as analog channel 2 (the third word in the stream).

Saving All

If we were saving all channels, then each timepoint of our .bin file would have 5 words. The metadata would contain these entries about file format:

acqMnMaXaDw=0,0,4,1   // count of channel types being acquired
nSavedChans=5         // total channel count saved to file
niXAChans1=3:6        // original XA channel hardware identities
niXDBytes1=1          // digital lines fit in 1 byte (but extended to 16-bits)
niXDChans1=0:1        // original digital line hardware identities
snsMnMaXaDw=0,0,4,1   // count of channel types saved in file
snsSaveChanSubset=all // saved-channel-i maps to acquired-channel-j (1:1)

Saving Subset

Suppose on the NI Setup tab we enter 2:4 as the Save channel subset. These are logical indices. That means we will not save the first two analog channels 3,4. Rather, we will save analog 5,6 and the digital word, so we will save (3) of the (5) acquired channels. Now, each timepoint of the .bin file will have 3 words, and the new metadata look like this:

acqMnMaXaDw=0,0,4,1   // same: acquiring same channels
nSavedChans=3         // diff: now only 3 saved to file
niXAChans1=3:6        // same: original XA channel hardware identities
niXDBytes1=1          // same: digital lines fit in 1 byte (but extended to 16-bits)
niXDChans1=0:1        // same: original digital line hardware identities
snsMnMaXaDw=0,0,2,1   // diff: count of channel types saved in file
snsSaveChanSubset=2:4 // diff: file-index 0,1,2 maps to acquired 2,3,4

Synchronization

Each stream has its own asynchronous hardware clock, hence, its own start time and sample rate. The time at which an event occurs, for example a spike or a TTL trigger, can be accurately mapped from one stream to another if we can accurately measure the stream timing parameters. SpikeGLX has several tools for that purpose:

Procedure to Calibrate Sample Rates

  1. A pulse generator is configured to produce a square wave with period of {1,2,or,3} s and 50% duty cycle. You can provide your own source, or SpikeGLX can program one of the acquisition devices to generate the waveform.

  2. You connect the output of the generator to one input channel of each stream and name these channels in the Sync tab in the Configuration dialog.

  3. In the Sync tab you check the box to do a calibration run. This will automatically acquire and analyze data appropriate to measuring the sample rates of each enabled stream. These rates are stored in a database (by device SN) for use in subsequent runs. The database is in the _Calibration subfolder. Be sure to transplant this folder to the new SpikeGLX folder when you upgrade the software.

The calibration procedure measures the rates of clocks relative to the square wave generator clock. You should use the same generator for real runs that you use for the calibration.

Full detail on the procedure is found in the help for the Configuration dialog’s Sync tab.

Running Without a Generator

You really should run the sample rate calibration procedure at least once to have a reasonable idea of the actual sample rates of your specific hardware. In our experience, the actual rate of an imec stream may be 30,000.60 Hz, whereas the advertised rate is 30 kHz. That’s a difference of 2160 samples or 72 msec of cumulative error per hour that is correctible by doing this calibration.

The other required datum is the stream start time. SpikeGLX records the wall time that each stream’s hardware is commanded to begin acquiring data. However, that doesn’t account for the time it takes the command to be transmitted to the device, to be decoded, to be responded to, and for the first data to actually arrive at the device. This estimate of the start time is only good to about 10 ms.

It is an option to do your data taking runs without a connected square wave generator, and you might choose that if you only have one stream, or if the sync hardware is malfunctioning for any reason. Under these conditions runs will start off with time synchronization errors of 5 to 10 ms (owing to T-zero error) and that error will slowly drift depending upon how accurate the rate calibration is and whether the stream has clock drift that isn’t captured by a simple rate constant. Thankfully, you can do much better than that…

Running With a Squarewave Generator

In this mode of operation, you’ve previously done a calibration run to get good estimators of the rates, and you are dedicating a channel in each stream to the common generator (pulser) during regular data runs. Two things happen under these conditions:

  1. When the run is starting up SpikeGLX uses the pulser to adjust the estimated stream start times so they agree to within a millisecond.

  2. During the run, the time coordinate of any event can be referenced to the nearest pulser edge, which is no more than one sync period away, and that allows times to be mapped with sub-millisecond accuracy.

Updating the Calibration

Menu item: Tools/Sample Rates From Run lets you open any existing run that was acquired with a connected generator and recalibrate the rates for those streams. You can then elect to update the stated sample rates within this run’s metadata, and/or update the global settings for use in the next run.

Gates and Triggers

File writing is governed by an event hierarchy:

Run -> Gate -> Trigger -> File

The following process works the same whether controlled manually via the SpikeGLX GUI, or scripted using the remote MATLAB or C++ interface (API).

  1. You configure experiment parameters, including:

  1. You start the run with the Run button in the Configure dialog:

  2. Initially, the gate is low (closed, disabled) and no files can be written. When the selected gate criterion is met the gate goes high (opens, enables), the gate index g is set to zero and the trigger criteria are then evaluated.

  3. Triggers are like mini programs that determine when to capture data to files. There are several options you can read about here. Triggers act only while the gate is high and are terminated if the gate goes low. Gates always override triggers. Each time the gate goes high the gate-index (g) is incremented and the t-index is reset to zero. The trigger program is run again within the new gate window.

  4. When the selected trigger condition is met, a new file is created. On creation of the first file with a given g index, a new run folder is created in the data directory to hold all the data for that gate. That is, we create folder data-path/run-name_gN. Thus, the first file written for the first trigger would be data-path/run-name_g0/run-name_g0_t0.nidq.bin. When the trigger goes low the file is finalized/closed. If the selected trigger is a repeating type and if the gate is still high then the next trigger will begin file data-path/run-name_g0/run-name_g0_t1.nidq.bin, and so on within gate zero. (For other data streams, the same naming rule applies, with nidq replaced by imec0.ap, imec0.lf or obx0.obx).

  5. If the gate is closed and then reopened, triggering resets and the next folder/file will be named data-path/run-name_g1/run-name_g1_t0.nidq.bin, and so on.

  6. The run itself can be stopped manually via the GUI, or by remote command.

Note that there is an option on the Save Tab called Folder per probe. If this is set, there is still a run folder for each g-index run-name_gN. However, inside that there is also a subfolder for each probe that contains all the t-indices for that g-index and that probe. A probe subfolder is named like run-name_gN/run-name_gN_imecM.

Console Window

The Console window contains the application’s menu bar. The large text field (“Log”) is a running history of informative messages: errors, warnings, current status, names of completed files, and so on. Of special note is the status bar at the bottom edge of the window. During a run this shows the current gate/trigger indices and the current file writing efficiency, which is a key readout of system stability.

You are encouraged to keep this window parked where you can easily see these very useful experiment readouts.

File Menu

Options Menu

Tools Menu

Window Menu

Status Bar

System performance and stability readout. For extended system tracking open the Run Metrics Window from the Windows menu.

Acquisition Performance

The imec hardware buffers a small amount data per probe. A fast running loop in SpikeGLX requests packets of probe data and marshals them into the central stream. Every few seconds we read how full the hardware buffer is. If it is more than 5% full we make a report in the console log like this:

IMEC FIFO queue imec5 fill% 6.2

If the queue grows a little it’s not a problem unless the percentage exceeds 95%, at which point the run is automatically stopped.

Disk Performance

During file writing the status bar displays a message like this:

FileQFill%=(ni:0.1,ob:0.0,im:0.0) MB/s=14.5 (14.2 req)

The streams each have an in-memory queue of data waiting to be spooled to disk. The FileQFill% is how full each binary file queue is. The queues may fill a little if you run other apps or copy data to/from the disk during a run. That’s not a problem as long as the percentage falls again before hitting 95%, at which point the run is automatically stopped.

In addition, we show the overall current write speed and the minimum speed required to keep up. The current write speed may fluctuate a little but that’s not a problem as long as the average is close to the required value.

Run Metrics Window

Choose menu item Window/Run Metrics to open a window that consolidates the most vital health statistics from the Console log, and adds a few more:

Click the Help button in the window to get a detailed description of the metrics.

Configure Acquisition Dialog

In brief: Configure and start a new run.

Notes on the dialog as a whole:

Hardware -> Memory -> Visualization -> Files

   Devices tab: Select which streams/hardware to acquire.
        IM tab: Configure imec neural probe streams.
       Obx tab: Configure imec OneBox ADC streams, and DAC output.
        NI tab: Configure NI ADC streams.
      Sync tab: Cross-connect streams for precision alignment.
     Gates tab: Together with...
  Triggers tab: Define trials and how to write files.
      Save tab: Specify where to put files and how to name them.

Detailed help for each tab is available here:

Graphs Window

Click Run in the Configure Acquisition dialog and the Graphs Window opens automatically. A second Graphs Window can also be opened with menu command Window::More Traces. Each windows shows up to two streams.

Here you can:

There’s a new Help button in the lower-right corner.

Offline File Viewer

Choose File::Open File Viewer and then select a *.bin file to open. You can open and view data files from any stream, and you can link the files from a run so scrolling is synchronized between multiple viewers.

In a viewer window, choose Help::File Viewer Help for more details.

Anatomy: Pinpoint, Trajectory Explorer

Pinpoint Needs HelloSGLX

This is the communications chain among: {manipulators, Pinpoint, HelloSGLX, SGLX}:

[MAN] <-> [PIN] <-> [HEL] <-> [SGL]

Pinpoint software needs the HelloSGLX application as a relay. Get the latest release tag and place the ‘HelloSGLX-win’ folder on the same machine as Pinpoint. You will need to paste the path to the HelloSGLX exe into Pinpoint. Very easy.

In contrast, Trajectory Explorer is a MATLAB application and uses our MATLAB SDK to talk directly with SpikeGLX. The communication for that looks like this:

[MAN] <-> [TE] <-> [SGL].

General Setup

The setup for either Pinpoint or Trajectory Explorer is very similar:

  1. Go to that application’s Github page to learn how to install that app and its atlas data, and how to connect supported manipulators.

  2. Launch SpikeGLX and select Options/Command Server Settings.... Check the box to enable the SpikeGLX command server. If putting the anatomy application and SpikeGLX on the same machine, set the IP Address to 127.0.0.1. If SpikeGLX will be on a separate machine, click the My Address button to read out the SpikeGLX machine’s IP address. Remember the IP address and port, as you will need to enter these values into the setup dialog for your anatomy application.

  3. Start a SpikeGLX run first. The anatomy programs send data to the SpikeGLX online Graph Windows and Shank Viewers. These views are only available while running. The Shank Viewer has a box of color-coded region names. Below that, a checkbox lets you apply color to the shank. Another checkbox lets you color the Graph traces.

  4. The anatomy programs only send a new message to SpikeGLX when first connecting, or if the probe moves. So if you stop a SpikeGLX run and start another, you won’t see any anatomy data until one of these events triggers a message to be sent.

  5. The latest overlay of anatomical data is now stored in your run’s metadata as item ~anatomy_shankj. See the Metadata guide.

Checksum Tools

SHA1 Checksum

Each .meta file stores the SHA1 checksum for the binary file in the field fileSHA1=. Use menu item Tools/Verify SHA1 to recalculate the current value for any (.bin,.meta) pair and determine if either file may have been corrupted. The SHA1 checksum, per se, does not provide any pathway to recovery.

PAR2 Redundancy Tool

Of course, you can create a perfect backup of a file by simply copying it whole, and that’s the recommended thing to do provided you can afford the storage space.

Alternatively, Parity ARchive 2 is a Usenet format for detecting and correcting binary file corruption using only a fraction of the original file’s size. (That fraction is called the redundancy percentage.) The downside is that the smaller the fraction you use for the backup set, the lower the likelihood of being able to fully recover the original file.

To invoke the tool use menu item Tools/PAR2 Redundancy Tool to create a backup set for a given data file. Subsequently, using the same tool, you can use the backup set to verify the file and to attempt recovery in case of corruption.

fin