Package 'readNSx'

Title: Read 'Blackrock-Microsystems' Files ('NEV', 'NSx')
Description: Loads 'Blackrock' <https://blackrockneurotech.com> neural signal data files into the memory, provides utility tools to extract the data into common formats such as plain-text 'tsv' and 'HDF5'.
Authors: Zhengjia Wang [aut, cre]
Maintainer: Zhengjia Wang <[email protected]>
License: MPL-2.0 | file LICENSE
Version: 0.0.5
Built: 2024-09-03 21:14:20 UTC
Source: https://github.com/dipterix/readNSx

Help Index

Get channel data

Description

Obtain channel information and data from given prefix and channel ID.

Usage

get_channel(x, channel_id)

Arguments

x

path prefix specified in import_nsp, or 'nev/nsx' object
channel_id

integer channel number. Please be aware that channel number, channel ID, electrode ID refer to the same concept in 'Blackrock' 'NEV' specifications. Electrodes are not physical metals, they refer to channels for historical reasons.

Value

A list containing channel data and meta information, along with the enclosing 'NSx' information; for invalid channel ID, this function returns NULL

Get event data packets from 'NEV'

Description

Get event data packets from 'NEV'

Usage

get_event(x, event_type, ...)

Arguments

x

path prefix (see import_nsp), or 'nev/nsx' object
event_type

event type to load, common event types are

'digital_inputs'

packet identifier 0

'spike'

packet identifier 1 to 10000 as of version 3.0

'recording'

packet identifier 65529 as of version 3.0, available after version 3.0

'configuration'

packet identifier 65530 as of version 3.0, available after version 3.0

'log'

packet identifier 65531 as of version 3.0, available after version 3.0

'button_trigger'

packet identifier 65532 as of version 3.0, available after version 3.0

'tracking'

packet identifier 65533 as of version 3.0, available after version 3.0

'video_sync'

packet identifier 65534 as of version 3.0, available after version 3.0

'comment'

packet identifier 65535 as of version 3.0, available after version 2.3
...

pass to other methods

Value

A data frame of corresponding event type, or NULL if event is not found or invalid

Get 'Blackrock' file type

Description

Reads the first 10 bytes containing file type and version information.

Usage

get_file_type(path)

Arguments

path

path to the 'Blackrock' '.nev' or '.nsx' file, or a binary connection.

Value

A list containing file information, including file type, version information, and normalized absolute path.

Load 'NEV' information from path prefix

Description

Load 'NEV' information from path prefix

Usage

get_nev(x, ...)

Arguments

x

path prefix specified in import_nsp, or 'nev/nsx' object
...

reserved for future use

Value

'NEV' header information if x is valid, otherwise NULL. See Section "'NEV' Data" in get_specification

Get a collection list containing 'NEV' and 'NSx' headers

Description

Get a collection list containing 'NEV' and 'NSx' headers

Usage

get_nsp(x)

Arguments

x

path prefix specified in import_nsp, or 'nev/nsx' object

Value

A list containing 'nev' and imported 'nsx' headers, see import_nsp for details

Load 'NSx' information from path prefix

Description

Load 'NSx' information from path prefix

Usage

get_nsx(x, which, ...)

Arguments

x

path prefix specified in import_nsp, or 'nev/nsx' object
which

which 'NSx' to load, for example, which=3 loads 'ns3' headers
...

reserved for future use

Value

'NSx' header information if data is found, otherwise returns NULL. See Section "'NSx' Data" in get_specification

Get '.nev' or 'nsx' specification

Description

Get '.nev' or 'nsx' specification

Usage

get_specification(version, type = c("nev", "nsx"))

Arguments

version

either character string or a vector of two integers; for example, "2.2", "2.3", c(3, 0). Currently only these three versions are supported since I was unable to find any other versions. Please file an issue ticket if others versions are desired.
type

file type; choices are 'nev' or 'nsx'

Value

The file specification as a list. The specification usually contains three sections: basic header (fixed length), extended header (dictionary-style), and data packets (data stream). The specification is used to parse the data files.

'NEV' Data

A 'NEV' object consists of three sections:

Section 1 contains basic information such as the time-origin of all the time-stamps, the time-stamp sampling frequency, data packets sizes.

Section 2 is extended header containing the configurations of channels, digital signals, etc. For any data packets in section 3, there should be at least one table in this section describing the settings.

section 3 is a collection of event packets such as digital signal inputs ( most likely to be used at version 2.2 or by 'Ripple'), spike waveform, comments (sometimes storing epoch information), etc.

Please be aware that while most common entries can be found across different file versions, some entries are version-specific. If you are making your script general, you need to be very careful handling these differences. For more information, please search for the data specification manual from the 'Blackrock-Microsystems' website.

'NSx' Data

A 'NSx' file refers to the data files ending with 'ns1' through 'ns9'. Common types are 'ns2' (sampling at 1000 Hz), 'ns3' (sampling at 2000 Hz), and 'ns5' (sampling at 30,000 Hz).

A 'NSx' file also consists of three sections. Section 1 contains basic information such as the time-origin of all the time-stamps, sampling frequencies, and channel counts within the file. Please be careful that item time_resolution_timestamp is not the sampling frequency for signals. This item is the sampling frequency for time-stamp. To obtain the signal sample rate, divided time_resolution_timestamp by period. For example, 'ns3' usually has time-stamp resolution 30,000 and period=15, hence the signal sample rate is 30000/15=2000Hz.

Section 2 usually contains one and only one channel table of which the number of rows should coincide with number of channels from section 1. Other information such as channel labels, physical connectors, pins, units, filter settings, digital-to-analog conversion are also included. Since readNSx always attempts to convert signals in 'volts' or 'milli-volts' to 'micro-volts', the 'units' column might be different to what's actual recorded in the 'NSx' file headers.

Section 3 contains partitions of continuous recording. When imported/loaded from readNSx, the digital signals are always converted to analog signals with 'micro-volts' unit. Please use get_channel to get the channel data.

Examples

get_specification(version = c(2,3), type = "nev")

get_specification(version = "3.0", type = "nsx")

Import signal data from 'Blackrock-Microsystems' data files

Description

Please use import_nsp to import 'NEV' and 'NSx' files.

Usage

import_nsp(
  path,
  prefix = NULL,
  exclude_events = "spike",
  exclude_nsx = NULL,
  verbose = TRUE,
  partition_prefix = "/part"
)

Arguments

path

path to 'NEV' or 'NSx' files
prefix

path prefix to save data files into
exclude_events

exclude one or more 'NEV' data events, choices are 'spike', 'video_sync', 'digital_inputs', 'tracking', 'button_trigger', 'comment', 'configuration'; default is 'spike' since the spike data takes very long time to parse, and most users might still use their own offline spike-sorting algorithms.
exclude_nsx

excluded 'NSx' types, integer vectors from 1 to 9; for example, exclude_nsx=c(1,2) will prevent 'ns1' and 'ns2' from being imported
verbose

logical or a progress object: when logical, verbose indicates whether to print the progress as messages; when verbose is a progress object, this object must have inc method; examples are Progress in the shiny package, progress2 from dipsaus, or shiny_progress from shidashi
partition_prefix

additional prefix to the data partition; default is "/part"

Value

A list of configurations, see get_specification for what's contained.

Examples

# Please get your own sample data first. This package does not
# provide sample data for privacy and license concerns :)

if(interactive() && file.exists("sampledata.nev")) {

library(readNSx)

# ---- Import for the first time --------------------------------
import_nsp(
  path = "sampledata.nev",
  prefix = file.path(
    "~/BIDSRoot/MyDataSet/sub-YAB/ses-008/ieeg/",
    "sub-YAB_ses-008_task-congruency_acq-NSP1_run-01"
  ),
  exclude_events = "spike", partition_prefix = "/part"
)

# ---- Load header information --------------------------------
prefix <- "sub-YAB_ses-008_task-congruency_acq-NSP1_run-01"
nev <- get_nev(prefix)
ns3 <- get_nsx(prefix, which = 3)

# get nev from nsx, or nsx from nev
get_nev(ns3)
get_nsx(nev, which = 5)

# ---- Load channel data
result <- get_channel(prefix, channel_id = 10)
channel_signal <- result$channel_detail$part1$data
channel_signal[]

}

Read 'BCI2000' recording data

Description

Read 'BCI2000' recording data

Usage

read_bci2000_header(file)

read_bci2000(file)

Arguments

file

path to the recording data

Value

Parsed signal data

Examples

# Package comes with sample data
file <- system.file("samples", "bci2000_sample.dat", package = "readNSx")
result <- read_bci2000(file)

print(result)

# Notive: v1.0 and v1.1 are different, but all in `Source` section
# sample rate
result$parameters$Source$SamplingRate$value

# Signal data 64 channels x 500 time-points
dim(result$signals)