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 |
Obtain channel information and data from given prefix and channel ID.
get_channel(x, channel_id)
get_channel(x, channel_id)
x |
path |
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. |
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'
get_event(x, event_type, ...)
get_event(x, event_type, ...)
x |
path |
event_type |
event type to load, common event types are
|
... |
pass to other methods |
A data frame of corresponding event type, or NULL
if event
is not found or invalid
Reads the first 10 bytes containing file type and version information.
get_file_type(path)
get_file_type(path)
path |
path to the 'Blackrock' |
A list containing file information, including file type, version information, and normalized absolute path.
Load 'NEV' information from path prefix
get_nev(x, ...)
get_nev(x, ...)
x |
path |
... |
reserved for future use |
'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
get_nsp(x)
get_nsp(x)
x |
path |
A list containing 'nev'
and imported 'nsx'
headers,
see import_nsp
for details
Load 'NSx' information from path prefix
get_nsx(x, which, ...)
get_nsx(x, which, ...)
x |
path |
which |
which 'NSx' to load, for example, |
... |
reserved for future use |
'NSx' header information if data is found, otherwise returns
NULL
. See Section "'NSx' Data" in get_specification
Get '.nev' or 'nsx' specification
get_specification(version, type = c("nev", "nsx"))
get_specification(version, type = c("nev", "nsx"))
version |
either character string or a vector of two integers; for
example, |
type |
file type; choices are |
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.
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.
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.
get_specification(version = c(2,3), type = "nev") get_specification(version = "3.0", type = "nsx")
get_specification(version = c(2,3), type = "nev") get_specification(version = "3.0", type = "nsx")
Please use import_nsp
to import 'NEV' and 'NSx' files.
import_nsp( path, prefix = NULL, exclude_events = "spike", exclude_nsx = NULL, verbose = TRUE, partition_prefix = "/part" )
import_nsp( path, prefix = NULL, exclude_events = "spike", exclude_nsx = NULL, verbose = TRUE, partition_prefix = "/part" )
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
|
exclude_nsx |
excluded 'NSx' types, integer vectors from 1 to 9; for
example, |
verbose |
logical or a progress object: when logical, |
partition_prefix |
additional prefix to the data partition; default is
|
A list of configurations, see get_specification
for
what's contained.
# 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[] }
# 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[] }
'BCI2000'
recording dataRead 'BCI2000'
recording data
read_bci2000_header(file) read_bci2000(file)
read_bci2000_header(file) read_bci2000(file)
file |
path to the recording data |
Parsed signal data
# 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)
# 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)