| Title: | Read 'Blackrock-Microsystems' Files ('NEV', 'NSx') |
| Version: | 0.0.5 |
| 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'. |
| License: | MPL-2.0 | file LICENSE |
| Language: | en-US |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Imports: | data.table, fastmap, hdf5r, jsonlite, R6 |
| LinkingTo: | cpp11 |
| Suggests: | bit64, tools, testthat (≥ 3.0.0), knitr, rmarkdown, spelling |
| SystemRequirements: | HDF5 (>= 1.8.13), little-endian platform |
| NeedsCompilation: | yes |
| Copyright: | For the readNSx package: Zhengjia Wang. |
| URL: | http://dipterix.org/readNSx/ |
| BugReports: | https://github.com/dipterix/readNSx/issues |
| Config/testthat/edition: | 3 |
| VignetteBuilder: | knitr |
| Packaged: | 2024-09-03 21:08:16 UTC; dipterix |
| Author: | Zhengjia Wang [aut, cre] |
| Maintainer: | Zhengjia Wang <dipterix.wang@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2024-09-03 21:30:02 UTC |
Get channel data
Description
Obtain channel information and data from given prefix and channel ID.
Usage
get_channel(x, channel_id)
Arguments
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. |
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 |
event_type |
event type to load, common event types are
|
... |
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' |
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 |
... |
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 |
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 |
which |
which 'NSx' to load, for example, |
... |
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, |
type |
file type; choices are |
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
|
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
|
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)