Package 'raveio'

Description

ants_coreg aligns 'CT' to 'MR' images; ants_mri_to_template aligns native 'MR' images to group templates

Usage

ants_coreg(
  ct_path,
  mri_path,
  coreg_path = NULL,
  reg_type = c("DenseRigid", "Rigid", "SyN", "Affine", "TRSAA", "SyNCC", "SyNOnly"),
  aff_metric = c("mattes", "meansquares", "GC"),
  syn_metric = c("mattes", "meansquares", "demons", "CC"),
  verbose = TRUE,
  ...
)

cmd_run_ants_coreg(
  subject,
  ct_path,
  mri_path,
  reg_type = c("DenseRigid", "Rigid", "SyN", "Affine", "TRSAA", "SyNCC", "SyNOnly"),
  aff_metric = c("mattes", "meansquares", "GC"),
  syn_metric = c("mattes", "meansquares", "demons", "CC"),
  verbose = TRUE,
  dry_run = FALSE
)

ants_mri_to_template(
  subject,
  template_subject = getOption("threeBrain.template_subject", "N27"),
  preview = FALSE,
  verbose = TRUE,
  ...
)

cmd_run_ants_mri_to_template(
  subject,
  template_subject = getOption("threeBrain.template_subject", "N27"),
  verbose = TRUE,
  dry_run = FALSE
)

ants_morph_electrode(subject, preview = FALSE, dry_run = FALSE)

Arguments

Value

Aligned 'CT' will be generated at the coreg_path path:

'ct_in_t1.nii.gz'

aligned 'CT' image; the image is also re-sampled into 'MRI' space

'transform.yaml'

transform settings and outputs

'CT_IJK_to_MR_RAS.txt'

transform matrix from volume 'IJK' space in the original 'CT' to the 'RAS' anatomical coordinate in 'MR' scanner; 'affine' transforms only

'CT_RAS_to_MR_RAS.txt'

transform matrix from scanner 'RAS' space in the original 'CT' to 'RAS' in 'MR' scanner space; 'affine' transforms only

Description

This function is soft-deprecated. Use yael_preprocess instead.

Usage

ants_preprocessing(
  work_path,
  image_path,
  resample = FALSE,
  verbose = TRUE,
  template_subject = raveio_getopt("threeBrain_template_subject")
)

Arguments

Value

Nothing. All images are saved to work_path

Description

Archive and share a subject

Usage

archive_subject(
  subject,
  path,
  includes = c("orignal_signals", "processed_data", "rave_imaging", "pipelines", "notes",
    "user_generated"),
  config = list(),
  work_path = NULL,
  zip_flags = NULL
)

Arguments

Examples

# This example requires you to install demo subject

## Not run: 


# Basic usage
path <- archive_subject('demo/DemoSubject')

# clean up
unlink(path)

# Advanced usage: include all the original signals
# and processed data, no cache data, re-name to
# demo/DemoSubjectLite
path <- archive_subject(
  'demo/DemoSubject',
  includes = c("orignal_signals", "processed_data"),
  config = list(
    rename = list(
      project_name = "demo",
      subject_code = "DemoSubjectLite"
    ),
    orignal_signals = list(
      # include all raw signals
      include_all = TRUE
    ),
    processed_data = list(
      include_cache = FALSE
    )
  )
)

# Clean up temporary zip file
unlink(path)


## End(Not run)

Convert character to RAVEProject instance

Description

Convert character to RAVEProject instance

Usage

as_rave_project(project, ...)

Arguments

Value

A RAVEProject instance

See Also

RAVEProject

Get RAVESubject instance from character

Description

Get RAVESubject instance from character

Usage

as_rave_subject(subject_id, strict = TRUE, reload = TRUE)

Arguments

Value

RAVESubject instance

See Also

RAVESubject

Description

Convert numeric number into print-friendly format

Usage

as_rave_unit(x, unit, label = "")

Arguments

Value

Still numeric, but print-friendly class

Examples

sp <- as_rave_unit(1024, 'GB', 'Hard-disk space is ')
print(sp, digits = 0)

sp - 12

as.character(sp)

as.numeric(sp)

# Vectorize
sp <- as_rave_unit(c(500,200), 'MB/s', c('Writing: ', 'Reading: '))
print(sp, digits = 0, collapse = '\n')

Description

Image registration across different modals. Normalize brain 'T1'-weighted 'MRI' to template brain and generate subject-level atlas files.

Usage

as_yael_process(subject)

Arguments

Value

A processing instance, see YAELProcess

Examples

library(raveio)
process <- as_yael_process("testtest2")

# This example requires extra demo data & settings.
## Not run: 

# Import and set original T1w MRI and CT
process$set_input_image("/path/to/T1w_MRI.nii", type = "T1w")
process$set_input_image("/path/to/CT.nii.gz", type = "CT")

# Co-register CT to MRI
process$register_to_T1w(image_type = "CT")

# Morph T1w MRI to 0.5 mm^3 MNI152 template
process$map_to_template(
  template_name = "mni_icbm152_nlin_asym_09b",
  native_type = "T1w"
)


## End(Not run)

Description

Back up and rename the file or directory

Usage

backup_file(path, remove = FALSE, quiet = FALSE)

Arguments

Value

FALSE if nothing to back up, or the back-up path if path exists

Examples

path <- tempfile()
file.create(path)

path2 <- backup_file(path, remove = TRUE)

file.exists(c(path, path2))
unlink(path2)

Description

Currently only supports minimum file specification version 2.3. Please contact the package maintainer or 'RAVE' team if older specifications are needed

Value

absolute file path

absolute file paths

nothing

a data frame

a list of spike 'waveform' (without normalization)

a normalized numeric vector (analog signals with 'uV' as the unit)

Public fields

Active bindings

Methods

Public methods

• BlackrockFile$print()

• BlackrockFile$new()

• BlackrockFile$nev_path()

• BlackrockFile$nsx_paths()

• BlackrockFile$refresh_data()

• BlackrockFile$get_epoch()

• BlackrockFile$get_waveform()

• BlackrockFile$get_electrode()

• BlackrockFile$clone()

Method print()

print user-friendly messages

Usage

BlackrockFile$print()

Method new()

constructor

Usage

BlackrockFile$new(path, block, nev_data = TRUE)

Arguments

Method nev_path()

get 'NEV' file path

Usage

BlackrockFile$nev_path()

Method nsx_paths()

get 'NSx' file paths

Usage

BlackrockFile$nsx_paths(which = NULL)

Arguments

Method refresh_data()

refresh and load 'NSx' data

Usage

BlackrockFile$refresh_data(force = FALSE, verbose = TRUE, nev_data = FALSE)

Arguments

Method get_epoch()

get epoch table from the 'NEV' comment data packet

Usage

BlackrockFile$get_epoch()

Method get_waveform()

get 'waveform' of the spike data

Usage

BlackrockFile$get_waveform()

Method get_electrode()

get electrode data

Usage

BlackrockFile$get_electrode(electrode, nstype = NULL)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

BlackrockFile$clone(deep = FALSE)

Arguments

Description

Manipulate cached data on the file systems

Usage

cache_root(check = FALSE)

clear_cached_files(subject_code, quiet = FALSE)

Arguments

Details

'RAVE' intensively uses cache files. If running on personal computers, the disk space might be filled up very quickly. These cache files are safe to remove if there is no 'RAVE' instance running. Function clear_cached_files is designed to remove these cache files. To run this function, please make sure that all 'RAVE' instances are shutdown.

Value

cache_root returns the root path that stores the 'RAVE' cache data; clear_cached_files returns nothing

Examples

cache_root()

Description

Avoid repeating yourself

Usage

cache_to_filearray(
  fun,
  filebase,
  globals,
  dimension,
  type = "auto",
  partition_size = 1L,
  verbose = FALSE,
  ...
)

Arguments

Examples

c <- 2
b <- list(d = matrix(1:9,3))
filebase <- tempfile()

f <- function() {
  message("New calculation")
  re <- c + b$d
  dimnames(re) <- list(A=1:3, B = 11:13)

  # `extra` attribute will be saved
  attr(re, "extra") <- "extra meta data"
  re
}

# first time running
arr <- cache_to_filearray( f, filebase = filebase )

# cached, no re-run
arr <- cache_to_filearray( f, filebase = filebase )

# file array object
arr

# read into memory
arr[]

# read extra data
arr$get_header("extra")

# get digest results
arr$get_header("raveio::filearray_cache")

## Clean up this example
unlink(filebase, recursive = TRUE)

Description

Print colored messages

Usage

catgl(..., .envir = parent.frame(), level = "DEBUG", .pal, .capture = FALSE)

Arguments

Details

The level has order that sorted from low to high: "DEBUG", "DEFAULT", "INFO", "WARNING", "ERROR", "FATAL". Each different level will display different colors and icons before the message. You can suppress messages with certain levels by setting 'raveio' options via raveio_setopt('verbose_level', <level>). Messages with levels lower than the threshold will be muffled. See examples.

Value

The message as characters

Examples

# ------------------ Basic Styles ---------------------

# Temporarily change verbose level for example
raveio_setopt('verbose_level', 'DEBUG', FALSE)

# debug
catgl('Debug message', level = 'DEBUG')

# default
catgl('Default message', level = 'DEFAULT')

# info
catgl('Info message', level = 'INFO')

# warning
catgl('Warning message', level = 'WARNING')

# error
catgl('Error message', level = 'ERROR')

try({
  # fatal, will call stop and raise error
  catgl('Error message', level = 'FATAL')
}, silent = TRUE)

# ------------------ Muffle messages ---------------------

# Temporarily change verbose level to 'WARNING'
raveio_setopt('verbose_level', 'WARNING', FALSE)

# default, muffled
catgl('Default message')

# message printed for level >= Warning
catgl('Default message', level = 'WARNING')
catgl('Default message', level = 'ERROR')

Description

These shell commands are for importing 'DICOM' images to 'Nifti' format, reconstructing cortical surfaces, and align' the CT' to 'MRI'. The commands are only tested on 'MacOS' and 'Linux'. On 'Windows' machines, please use the 'WSL2' system.

Usage

cmd_run_3dAllineate(
  subject,
  mri_path,
  ct_path,
  overwrite = FALSE,
  command_path = NULL,
  dry_run = FALSE,
  verbose = dry_run
)

cmd_execute(
  script,
  script_path,
  command = "bash",
  dry_run = FALSE,
  backup = TRUE,
  args = NULL,
  ...
)

cmd_run_r(
  expr,
  quoted = FALSE,
  verbose = TRUE,
  dry_run = FALSE,
  log_file = tempfile(),
  script_path = tempfile(),
  ...
)

cmd_run_dcm2niix(
  subject,
  src_path,
  type = c("MRI", "CT"),
  merge = c("Auto", "No", "Yes"),
  float = c("Yes", "No"),
  crop = c("No", "Yes", "Ignore"),
  overwrite = FALSE,
  command_path = NULL,
  dry_run = FALSE,
  verbose = dry_run
)

cmd_run_flirt(
  subject,
  mri_path,
  ct_path,
  dof = 6,
  cost = c("mutualinfo", "leastsq", "normcorr", "corratio", "normmi", "labeldiff", "bbr"),
  search = 90,
  searchcost = c("mutualinfo", "leastsq", "normcorr", "corratio", "normmi", "labeldiff",
    "bbr"),
  overwrite = FALSE,
  command_path = NULL,
  dry_run = FALSE,
  verbose = dry_run
)

cmd_run_recon_all(
  subject,
  mri_path,
  args = c("-all", "-autorecon1", "-autorecon2", "-autorecon3", "-autorecon2-cp",
    "-autorecon2-wm", "-autorecon2-pial"),
  work_path = NULL,
  overwrite = FALSE,
  command_path = NULL,
  dry_run = FALSE,
  verbose = dry_run
)

cmd_run_recon_all_clinical(
  subject,
  mri_path,
  work_path = NULL,
  overwrite = FALSE,
  command_path = NULL,
  dry_run = FALSE,
  verbose = dry_run,
  ...
)

Arguments

Value

A list of data containing the script details:

script

script details

script_path

where the script should/will be saved

dry_run

whether dry-run mode is turned on

log_file

path to the log file

execute

a function to execute the script

Description

Aligns 'T1w' with other image types; normalizes 'T1w' 'MRI' to 'MNI152' templates via symmetric non-linear morphs. Create brain custom atlases from templates.

Usage

cmd_run_yael_preprocess(
  subject_code,
  t1w_path = NULL,
  ct_path = NULL,
  t2w_path = NULL,
  fgatir_path = NULL,
  preopct_path = NULL,
  flair_path = NULL,
  t1w_contrast_path = NULL,
  register_reversed = FALSE,
  normalize_template = c("mni_icbm152_nlin_asym_09a", "mni_icbm152_nlin_asym_09c"),
  run_recon_all = TRUE,
  dry_run = FALSE,
  verbose = TRUE
)

yael_preprocess(
  subject_code,
  t1w_path = NULL,
  ct_path = NULL,
  t2w_path = NULL,
  fgatir_path = NULL,
  preopct_path = NULL,
  flair_path = NULL,
  t1w_contrast_path = NULL,
  register_policy = c("auto", "all"),
  register_reversed = FALSE,
  normalize_template = "mni_icbm152_nlin_asym_09a",
  normalize_policy = c("auto", "all"),
  normalize_back = ifelse(length(normalize_template) >= 1, normalize_template[[1]], NA),
  atlases = list(),
  add_surfaces = FALSE,
  verbose = TRUE
)

Arguments

Value

Nothing, a subject imaging folder will be created under 'RAVE' raw folder

Examples

## Not run: 


# For T1 preprocessing only
yael_preprocess(
  subject_code = "patient01",
  t1w_path = "/path/to/T1.nii or T1.nii.gz",

  # normalize T1 to all 2009 MNI152-Asym brains (a,b,c)
  normalize_template = c(
    "mni_icbm152_nlin_asym_09a",
    "mni_icbm152_nlin_asym_09b",
    "mni_icbm152_nlin_asym_09c"
  ),

  # only normalize if not exists
  normalize_policy = "auto",

  # use MNI152b to create native processing folder
  normalize_back = "mni_icbm152_nlin_asym_09b",

  # Atlases generated from different templates have different
  # coordinates, hence both folder path and template names must be
  # provided
  atlases = list(
    mni_icbm152_nlin_asym_09b = "/path/to/atlas/folder1",
    mni_icbm152_nlin_asym_09c = "/path/to/atlas/folder2"
  )

)

# For T1 and postop CT coregistration only
yael_preprocess(
  subject_code = "patient01",
  t1w_path = "/path/to/T1.nii or T1.nii.gz",
  ct_path = "/path/to/CT.nii or CT.nii.gz",

  # No normalization
  normalize_template = NULL,
  normalize_back = NA

)

# For both T1 and postop CT coregistration and T1 normalization
yael_preprocess(
  subject_code = "patient01",
  t1w_path = "/path/to/T1.nii or T1.nii.gz",
  ct_path = "/path/to/CT.nii or CT.nii.gz",

  normalize_template = c(
    "mni_icbm152_nlin_asym_09a",
    "mni_icbm152_nlin_asym_09b",
    "mni_icbm152_nlin_asym_09c"
  ),

  normalize_policy = "auto",

  normalize_back = "mni_icbm152_nlin_asym_09b",

  atlases = list(
    mni_icbm152_nlin_asym_09b = "/path/to/atlas/folder1",
    mni_icbm152_nlin_asym_09c = "/path/to/atlas/folder2"
  )

)



## End(Not run)

Description

Collapse power array with given analysis cubes

Usage

collapse_power(x, analysis_index_cubes)

## S3 method for class 'array'
collapse_power(x, analysis_index_cubes)

## S3 method for class 'FileArray'
collapse_power(x, analysis_index_cubes)

Arguments

Value

a list of collapsed (mean) results

freq_trial_elec

collapsed over time-points

freq_time_elec

collapsed over trials

time_trial_elec

collapsed over frequencies

freq_time

collapsed over trials and electrodes

freq_elec

collapsed over trials and time-points

freq_trial

collapsed over time-points and electrodes

time_trial

collapsed over frequencies and electrodes

time_elec

collapsed over frequencies and trials

trial_elec

collapsed over frequencies and time-points

freq

power per frequency, averaged over other modes

time

power per time-point, averaged over other modes

trial

power per trial, averaged over other modes

Examples

if(!is_on_cran()) {

# Generate a 4-mode tensor array
x <- filearray::filearray_create(
  tempfile(), dimension = c(16, 100, 20, 5),
  partition_size = 1
)
x[] <- rnorm(160000)
dnames <- list(
  Frequency = 1:16,
  Time = seq(0, 1, length.out = 100),
  Trial = 1:20,
  Electrode = 1:5
)
dimnames(x) <- dnames

# Collapse array
results <- collapse_power(x, list(
  overall = list(),
  A = list(Trial = 1:5, Frequency = 1:6),
  B = list(Trial = 6:10, Time = 1:50)
))

# Plot power over frequency and time
groupB_result <- results$B


image(t(groupB_result$freq_time),
      x = dnames$Time[groupB_result$cube_index$Time],
      y = dnames$Frequency[groupB_result$cube_index$Frequency],
      xlab = "Time (s)",
      ylab = "Frequency (Hz)",
      xlim = range(dnames$Time))

x$delete(force = TRUE)


}

Description

Collapse high-dimensional tensor array

Usage

collapse2(x, keep, method = c("mean", "sum"), ...)

## S3 method for class 'FileArray'
collapse2(x, keep, method = c("mean", "sum"), ...)

## S3 method for class 'Tensor'
collapse2(x, keep, method = c("mean", "sum"), ...)

## S3 method for class 'array'
collapse2(x, keep, method = c("mean", "sum"), ...)

Arguments

Value

A collapsed array (or a vector or matrix), depending on keep

See Also

collapse

Examples

x <- array(1:16, rep(2, 4))

collapse2(x, c(3, 2))

# Alternative method, but slower when `x` is a large array
apply(x, c(3, 2), mean)

# filearray
y <- filearray::as_filearray(x)

collapse2(y, c(3, 2))

collapse2(y, c(3, 2), "sum")

# clean up
y$delete(force = TRUE)

Description

In some cases, for example, deep-brain stimulation ('DBS'), it is often needed to analyze averaged electrode channels from segmented 'DBS' leads, or create bipolar contrast between electrode channels, or to generate non-equally weighted channel averages for 'Laplacian' reference. compose_channel allows users to generate a phantom channel that does not physically exist, but is treated as a normal electrode channel in 'RAVE'.

Usage

compose_channel(
  subject,
  number,
  from,
  weights = rep(1/length(from), length(from)),
  normalize = FALSE,
  force = FALSE,
  label = sprintf("Composed-%s", number),
  signal_type = c("auto", "LFP", "Spike", "EKG", "Audio", "Photodiode", "Unknown")
)

Arguments

Value

Nothing

Examples

library(raveio)


# Make sure demo subject exists in this example, just want to make
# sure the example does not error out
if(
  interactive() && "demo" %in% get_projects() &&
  "DemoSubject" %in% as_rave_project('demo')$subjects() &&
  local({
    subject <- as_rave_subject("demo/DemoSubject")
    !100 %in% subject$electrodes
  })
) {

  # the actual example code:
  # new channel 100 = 2 x channel 14 - (channe 15 + 16)
  compose_channel(
    subject = "demo/DemoSubject",
    number = 100,
    from = c(14, 15, 16),
    weights = c(2, -1, -1),
    normalize = FALSE
  )

}

Description

Convert 'BlackRock' 'NEV/NSx' files

Usage

convert_blackrock(
  file,
  block = NULL,
  subject = NULL,
  to = NULL,
  epoch = c("comment", "digital_inputs", "recording", "configuration", "log",
    "button_trigger", "tracking", "video_sync"),
  format = c("mat", "hdf5"),
  header_only = FALSE,
  ...
)

Arguments

Value

The results will be stored in directory specified by to. Please read the output message carefully.

Description

Convert electrode table

Usage

convert_electrode_table_to_bids(
  subject,
  space = c("ScanRAS", "MNI305", "fsnative")
)

Arguments

Value

A list of table in data frame and a list of meta information

Description

'HDF5', 'csv' are common file formats that can be easily read into 'Matlab' or 'Python'

Usage

convert_fst_to_hdf5(fst_path, hdf5_path, exclude_names = NULL)

convert_fst_to_csv(fst_path, csv_path, exclude_names = NULL)

Arguments

Value

convert_fst_to_hdf5 will return a list of data saved to 'HDF5'; convert_fst_to_csv returns the normalized 'csv' path.

Description

Force creating directory with checks

Usage

dir_create2(x, showWarnings = FALSE, recursive = TRUE, check = TRUE, ...)

Arguments

Value

Normalized path

Examples

path <- file.path(tempfile(), 'a', 'b', 'c')

# The following are equivalent
dir.create(path, showWarnings = FALSE, recursive = TRUE)

dir_create2(path)

'iEEG/ECoG' Tensor class inherit from Tensor

Description

Four-mode tensor (array) especially designed for 'iEEG/ECoG' data. The Dimension names are: Trial, Frequency, Time, and Electrode.

Value

a data frame with the dimension names as index columns and value_name as value column

an ECoGTensor instance

Super class

raveio::Tensor -> ECoGTensor

Methods

Public methods

• ECoGTensor$flatten()

• ECoGTensor$new()

Method flatten()

converts tensor (array) to a table (data frame)

Usage

ECoGTensor$flatten(include_index = TRUE, value_name = "value")

Arguments

Method new()

constructor

Usage

ECoGTensor$new(
  data,
  dim,
  dimnames,
  varnames,
  hybrid = FALSE,
  swap_file = temp_tensor_file(),
  temporary = TRUE,
  multi_files = FALSE,
  use_index = TRUE,
  ...
)

Arguments

Author(s)

Zhengjia Wang

Description

Stores and load data in various of data format. See 'Details' for limitations.

Usage

export_table(
  x,
  file,
  format = c("auto", "csv", "csv.zip", "h5", "fst", "json", "rds", "yaml"),
  ...
)

import_table(
  file,
  format = c("auto", "csv", "csv.zip", "h5", "fst", "json", "rds", "yaml"),
  ...
)

Arguments

Details

The format 'rds', 'h5', 'fst', 'json', and 'yaml' try to preserve the first-level column attributes. Factors will be preserved in these formats. Such property does not exist in 'csv', 'csv.zip' formats.

Open-data formats are 'h5', 'csv', 'csv.zip', 'json', 'yaml'. These formats require the table elements to be native types (numeric, character, factor, etc.).

'rds', 'h5', and 'fst' can store large data sets. 'fst' is the best choice is performance and file size are the major concerns. 'rds' preserves all the properties of the table.

Value

The normalized path for export_table, and a data.table for import_table

Examples

x <- data.table::data.table(
  a = rnorm(10),
  b = letters[1:10],
  c = 1:10,
  d = factor(LETTERS[1:10])
)

f <- tempfile(fileext = ".csv.zip")

export_table(x = x, file = f)

y <- import_table(file = f)

str(x)
str(y)

# clean up
unlink(f)

Description

Try to find path under root directory even if the original path is missing; see examples.

Usage

find_path(path, root_dir, all = FALSE)

Arguments

Details

When file is missing, find_path concatenates the root directory and path combined to find the file. For example, if path is "a/b/c/d", the function first seek for existence of "a/b/c/d". If failed, then "b/c/d", and then "~/c/d" until reaching root directory. If all=TRUE, then all files/directories found along the search path will be returned

Value

The absolute path of file if exists, or NULL if missing/failed.

Examples

root <- tempdir()

# ------ Case 1: basic use case -------

# Create a path in root
dir_create2(file.path(root, 'a'))

# find path even it's missing. The search path will be
# root/ins/cd/a - missing
# root/cd/a     - missing
# root/a        - exists!
find_path('ins/cd/a', root)

# ------ Case 2: priority -------
# Create two paths in root
dir_create2(file.path(root, 'cc/a'))
dir_create2(file.path(root, 'a'))

# If two paths exist, return the first path found
# root/ins/cd/a - missing
# root/cd/a     - exists - returned
# root/a        - exists, but ignored
find_path('ins/cc/a', root)

# ------ Case 3: find all -------
# Create two paths in root
dir_create2(file.path(root, 'cc/a'))
dir_create2(file.path(root, 'a'))

# If two paths exist, return the first path found
# root/ins/cd/a - missing
# root/cd/a     - exists - returned
# root/a        - exists - returned
find_path('ins/cc/a', root, all = TRUE)

Description

To properly run this function, please install ravetools package.

Usage

generate_reference(subject, electrodes)

Arguments

Details

The goal of generating common average signals is to capture the common movement from all the channels and remove them out from electrode signals.

The common average signals will be stored at subject reference directories. Two exact same copies will be stored: one in 'HDF5' format such that the data can be read universally by other programming languages; one in filearray format that can be read in R with super fast speed.

Value

A reference instance returned by new_reference with signal type determined automatically.

Description

Get all possible projects in 'RAVE' directory

Usage

get_projects(refresh = TRUE)

Arguments

Value

characters of project names

Description

Get value or return default if invalid

Usage

get_val2(x, key = NA, default = NULL, na = FALSE, min_len = 1L, ...)

Arguments

Value

values of the keys or default is invalid

Examples

x <- list(a=1, b = NA, c = character(0))

# ------------------------ Basic usage ------------------------

# no key, returns x if x is valid
get_val2(x)

get_val2(x, 'a', default = 'invalid')



# get 'b', NA is not filtered out
get_val2(x, 'b', default = 'invalid')

# get 'b', NA is considered invalid
get_val2(x, 'b', default = 'invalid', na = TRUE)



# get 'c', length 0 is allowed
get_val2(x, 'c', default = 'invalid', min_len = 0)

# length 0 is forbidden
get_val2(x, 'c', default = 'invalid', min_len = 1)

Description

Returns all names contained in 'HDF5' file

Usage

h5_names(file)

Arguments

Value

characters, data set names

Description

Check whether a 'HDF5' file can be opened for read/write

Usage

h5_valid(file, mode = c("r", "w"), close_all = FALSE)

Arguments

Value

logical whether the file can be opened.

Examples

x <- array(1:27, c(3,3,3))
f <- tempfile()

# No data written to the file, hence invalid
h5_valid(f, 'r')

save_h5(x, f, 'dset')
h5_valid(f, 'w')

# Open the file and hold a connection
ptr <- hdf5r::H5File$new(filename = f, mode = 'w')

# Can read, but cannot write
h5_valid(f, 'r')  # TRUE
h5_valid(f, 'w')  # FALSE

# However, this can be reset via `close_all=TRUE`
h5_valid(f, 'r', close_all = TRUE)
h5_valid(f, 'w')  # TRUE

# Now the connection is no longer valid
ptr

Description

Import electrode table into subject meta folder

Usage

import_electrode_table(path, subject, use_fs = NA, dry_run = FALSE, ...)

Arguments

Value

Nothing, the electrode information will be written directly to the subject's meta directory

Description

Install 'RAVE' modules

Usage

install_modules(modules, dependencies = FALSE)

Arguments

Value

nothing

Description

Install a subject from the internet, a zip file or a directory

Usage

install_subject(
  path = ".",
  ask = interactive(),
  overwrite = FALSE,
  backup = TRUE,
  use_cache = TRUE,
  dry_run = FALSE,
  force_project = NA,
  force_subject = NA,
  ...
)

Arguments

Examples

# Please run 2nd example of function archive_subject

## Not run: 

install_subject(path)


## End(Not run)

Description

Use this function only for examples and test. The goal is to comply with the 'CRAN' policy. Do not use it in normal functions to cheat. Violating 'CRAN' policy will introduce instability to your code. Make sure reading Section 'Details' before using this function.

Usage

is_on_cran(if_interactive = FALSE, verbose = FALSE)

Arguments

Details

According to 'CRAN' policy, package examples and test functions may only use maximum 2 'CPU' cores. Examples running too long should be suppressed. Normally package developers will use interactive() to avoid running examples or parallel code on 'CRAN'. However, when checked locally, these examples will be skipped too. Coding bug in those examples will not be reported.

The objective is to allow 'RAVE' package developers to write and test examples locally or on integrated development environment (such as 'Github'), while suppressing them on 'CRAN'. In such way, bugs in the examples will be revealed and fixed promptly.

Do not use this function inside of the package functions to cheat or slip illegal code under the eyes of 'CRAN' folks. This will increase their work load and introduce instability to your code. If I find it out, I will report your package to 'CRAN'. Only use this function to make your package more robust. If you are developing 'RAVE' module, this function is explicitly banned. I'll implement a check for this, sooner or later.

Value

A logical whether current environment should be considered as on 'CRAN'.

Description

Check if data is close to “valid"

Usage

is_valid_ish(
  x,
  min_len = 1,
  max_len = Inf,
  mode = NA,
  na = TRUE,
  blank = FALSE,
  all = FALSE
)

Arguments

Value

logicals whether input x is valid

Examples

# length checks
is_valid_ish(NULL)                     # FALSE
is_valid_ish(integer(0))               # FALSE
is_valid_ish(integer(0), min_len = 0)  # TRUE
is_valid_ish(1:10, max_len = 9)        # FALSE

# mode check
is_valid_ish(1:10)                     # TRUE
is_valid_ish(1:10, mode = 'numeric')   # TRUE
is_valid_ish(1:10, mode = 'character') # FALSE

# NA or blank checks
is_valid_ish(NA)                     # FALSE
is_valid_ish(c(1,2,NA), all = FALSE) # FALSE
is_valid_ish(c(1,2,NA), all = TRUE)  # TRUE as not all elements are NA

is_valid_ish(c('1',''), all = FALSE)  # TRUE
is_valid_ish(1:3, all = FALSE)        # TRUE as 1:3 are not characters

Description

Check If Input Has Blank String

Usage

is.blank(x)

Arguments

Value

x == ""

Description

Check If Input Has Zero Length

Usage

is.zerolenth(x)

Arguments

Value

whether x has zero length

Description

Join Multiple Tensors into One Tensor

Usage

join_tensors(tensors, temporary = TRUE)

Arguments

Details

Merges multiple tensors. Each tensor must share the same dimension with the last one dimension as 1, for example, 100x100x1. Join 3 tensors like this will result in a 100x100x3 tensor. This function is handy when each sub-tensors are generated separately. However, it does no validation test. Use with cautions.

Value

A new Tensor instance with the last dimension

Author(s)

Zhengjia Wang

Examples

tensor1 <- Tensor$new(data = 1:9, c(3,3,1), dimnames = list(
A = 1:3, B = 1:3, C = 1
), varnames = c('A', 'B', 'C'))
tensor2 <- Tensor$new(data = 10:18, c(3,3,1), dimnames = list(
  A = 1:3, B = 1:3, C = 2
), varnames = c('A', 'B', 'C'))
merged <- join_tensors(list(tensor1, tensor2))
merged$get_data()

Run lapply in parallel

Description

Uses lapply_async2, but allows better parallel scheduling via with_future_parallel. On 'Unix', the function will fork processes. On 'Windows', the function uses strategies specified by on_failure

Usage

lapply_async(
  x,
  FUN,
  FUN.args = list(),
  callback = NULL,
  ncores = NULL,
  on_failure = "multisession",
  ...
)

Arguments

Examples

if(!is_on_cran()) {
library(raveio)

# ---- Basic example ----------------------------
lapply_async(1:16, function(x) {
  # function that takes long to fun
  Sys.sleep(1)
  x
})

# With callback
lapply_async(1:16, function(x){
  Sys.sleep(1)
  x + 1
}, callback = function(x) {
  sprintf("Calculating|%s", x)
})

# With ncores
pids <- lapply_async(1:16, function(x){
  Sys.sleep(0.5)
  Sys.getpid()
}, ncores = 2)

# Unique number of PIDs (cores)
unique(unlist(pids))

# ---- With scheduler ----------------------------
# Scheduler pre-initialize parallel workers and temporary
# switches parallel context. The workers ramp-up
# time can be saved by reusing the workers.
#
with_future_parallel({

  # lapply_async block 1
  pids <- lapply_async(1:16, function(x){
    Sys.sleep(1)
    Sys.getpid()
  }, callback = function(x) {
    sprintf("lapply_async without ncores|%s", x)
  })
  print(unique(unlist(pids)))

  # lapply_async block 2
  pids <- lapply_async(1:16, function(x){
    Sys.sleep(1)
    Sys.getpid()
  }, callback = function(x) {
    sprintf("lapply_async with ncores|%s", x)
  }, ncores = 4)
  print(unique(unlist(pids)))

})


}

Description

provides hybrid data structure for 'fst' file

Value

none

none

none

vector, dimensions

subset of data

Methods

Public methods

• LazyFST$open()

• LazyFST$close()

• LazyFST$save()

• LazyFST$new()

• LazyFST$get_dims()

• LazyFST$subset()

Method open()

to be compatible with LazyH5

Usage

LazyFST$open(...)

Arguments

Method close()

close the connection

Usage

LazyFST$close(..., .remove_file = FALSE)

Arguments

Method save()

to be compatible with LazyH5

Usage

LazyFST$save(...)

Arguments

Method new()

constructor

Usage

LazyFST$new(file_path, transpose = FALSE, dims = NULL, ...)

Arguments

Method get_dims()

get data dimension

Usage

LazyFST$get_dims(...)

Arguments

Method subset()

subset data

Usage

LazyFST$subset(i = NULL, j = NULL, ..., drop = TRUE)

Arguments

Author(s)

Zhengjia Wang

Examples

if(!is_on_cran()){

# Data to save, total 8 MB
x <- matrix(rnorm(1000000), ncol = 100)

# Save to local disk
f <- tempfile()
fst::write_fst(as.data.frame(x), path = f)

# Load via LazyFST
dat <- LazyFST$new(file_path = f, dims = c(10000, 100))

# dat < 1 MB

# Check whether the data is identical
range(dat[] - x)

# The reading of column is very fast
system.time(dat[,100])

# Reading rows might be slow
system.time(dat[1,])

}

Description

provides hybrid data structure for 'HDF5' file

Value

none

self instance

self instance

subset of data

dimension of the array

data type, currently only character, integer, raw, double, and complex are available, all other types will yield "unknown"

Public fields

Methods

Public methods

• LazyH5$finalize()

• LazyH5$print()

• LazyH5$new()

• LazyH5$save()

• LazyH5$open()

• LazyH5$close()

• LazyH5$subset()

• LazyH5$get_dims()

• LazyH5$get_type()

Method finalize()

garbage collection method

Usage

LazyH5$finalize()

Method print()

overrides print method

Usage

LazyH5$print()

Method new()

constructor

Usage

LazyH5$new(file_path, data_name, read_only = FALSE, quiet = FALSE)

Arguments

Method save()

save data to a 'HDF5' file

Usage

LazyH5$save(
  x,
  chunk = "auto",
  level = 7,
  replace = TRUE,
  new_file = FALSE,
  force = TRUE,
  ctype = NULL,
  size = NULL,
  ...
)

Arguments

Method open()

open connection

Usage

LazyH5$open(new_dataset = FALSE, robj, ...)

Arguments

Method close()

close connection

Usage

LazyH5$close(all = TRUE)

Arguments

Method subset()

subset data

Usage

LazyH5$subset(..., drop = FALSE, stream = FALSE, envir = parent.frame())

Arguments

Method get_dims()

get data dimension

Usage

LazyH5$get_dims(stay_open = TRUE)

Arguments

Method get_type()

get data type

Usage

LazyH5$get_type(stay_open = TRUE)

Arguments

Author(s)

Zhengjia Wang

Examples

# Data to save
x <- array(rnorm(1000), c(10,10,10))

# Save to local disk
f <- tempfile()
save_h5(x, file = f, name = 'x', chunk = c(10,10,10), level = 0)

# Load via LazyFST
dat <- LazyH5$new(file_path = f, data_name = 'x', read_only = TRUE)

dat

# Check whether the data is identical
range(dat - x)

# Read a slice of the data
system.time(dat[,10,])

Description

Please use a safer new_electrode function to create instances. This documentation is to describe the member methods of the electrode class LFP_electrode

Value

if the reference number if NULL or 'noref', then returns 0, otherwise returns a FileArray-class

If simplify is enabled, and only one block is loaded, then the result will be a vector (type="voltage") or a matrix (others), otherwise the result will be a named list where the names are the blocks.

Super class

raveio::RAVEAbstarctElectrode -> LFP_electrode

Active bindings

Methods

Public methods

• LFP_electrode$print()

• LFP_electrode$set_reference()

• LFP_electrode$new()

• LFP_electrode$.load_noref_wavelet()

• LFP_electrode$.load_noref_voltage()

• LFP_electrode$.load_wavelet()

• LFP_electrode$.load_voltage()

• LFP_electrode$.load_raw_voltage()

• LFP_electrode$load_data()

• LFP_electrode$load_blocks()

• LFP_electrode$clear_cache()

• LFP_electrode$clear_memory()

• LFP_electrode$clone()

Method print()

print electrode summary

Usage

LFP_electrode$print()

Method set_reference()

set reference for current electrode

Usage

LFP_electrode$set_reference(reference)

Arguments

Method new()

constructor

Usage

LFP_electrode$new(subject, number, quiet = FALSE)

Arguments

Method .load_noref_wavelet()

load non-referenced wavelet coefficients (internally used)

Usage

LFP_electrode$.load_noref_wavelet(reload = FALSE)

Arguments

Method .load_noref_voltage()

load non-referenced voltage (internally used)

Usage

LFP_electrode$.load_noref_voltage(reload = FALSE)

Arguments

Method .load_wavelet()

load referenced wavelet coefficients (internally used)

Usage

LFP_electrode$.load_wavelet(
  type = c("power", "phase", "wavelet-coefficient"),
  reload = FALSE
)

Arguments

Method .load_voltage()

load referenced voltage (internally used)

Usage

LFP_electrode$.load_voltage(reload = FALSE)

Arguments

Method .load_raw_voltage()

load raw voltage (no process)

Usage

LFP_electrode$.load_raw_voltage(reload = FALSE)

Arguments

Method load_data()

method to load electrode data

Usage

LFP_electrode$load_data(
  type = c("power", "phase", "voltage", "wavelet-coefficient", "raw-voltage")
)

Arguments

Method load_blocks()

load electrode block-wise data (with no reference), useful when epoch is absent

Usage

LFP_electrode$load_blocks(
  blocks,
  type = c("power", "phase", "voltage", "wavelet-coefficient", "raw-voltage"),
  simplify = TRUE
)

Arguments

Method clear_cache()

method to clear cache on hard drive

Usage

LFP_electrode$clear_cache(...)

Arguments

Method clear_memory()

method to clear memory

Usage

LFP_electrode$clear_memory(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

LFP_electrode$clone(deep = FALSE)

Arguments

Examples

# Download subject demo/DemoSubject

subject <- as_rave_subject("demo/DemoSubject", strict = FALSE)

if(dir.exists(subject$path)) {

# Electrode 14 in demo/DemoSubject
e <- new_electrode(subject = subject, number = 14, signal_type = "LFP")

# Load CAR reference "ref_13-16,24"
ref <- new_reference(subject = subject, number = "ref_13-16,24",
                     signal_type = "LFP")
e$set_reference(ref)

# Set epoch
e$set_epoch(epoch = 'auditory_onset')

# Set loading window
e$trial_intervals <- list(c(-1, 2))

# Preview
print(e)

# Now epoch power
power <- e$load_data("power")
names(dimnames(power))

# Subset power
subset(power, Time ~ Time < 0, Electrode ~ Electrode == 14)

# Draw baseline
tempfile <- tempfile()
bl <- power_baseline(power, baseline_windows = c(-1, 0),
                     method = "decibel", filebase = tempfile)
collapsed_power <- collapse2(bl, keep = c(2,1))
# Visualize
dname <- dimnames(bl)
image(collapsed_power, x = dname$Time, y = dname$Frequency,
      xlab = "Time (s)", ylab = "Frequency (Hz)",
      main = "Mean power over trial (Baseline: -1~0 seconds)",
      sub = glue('Electrode {e$number} (Reference: {ref$number})'))
abline(v = 0, lty = 2, col = 'blue')
text(x = 0, y = 20, "Audio onset", col = "blue", cex = 0.6)

# clear cache on hard disk
e$clear_cache()
ref$clear_cache()

}

Description

Please use a safer new_reference function to create instances. This documentation is to describe the member methods of the electrode class LFP_reference

Value

if the reference number if NULL or 'noref', then returns 0, otherwise returns a FileArray-class

If simplify is enabled, and only one block is loaded, then the result will be a vector (type="voltage") or a matrix (others), otherwise the result will be a named list where the names are the blocks.

Super class

raveio::RAVEAbstarctElectrode -> LFP_reference

Active bindings

Methods

Public methods

• LFP_reference$print()

• LFP_reference$set_reference()

• LFP_reference$new()

• LFP_reference$.load_noref_wavelet()

• LFP_reference$.load_noref_voltage()

• LFP_reference$.load_wavelet()

• LFP_reference$.load_voltage()

• LFP_reference$load_data()

• LFP_reference$load_blocks()

• LFP_reference$clear_cache()

• LFP_reference$clear_memory()

• LFP_reference$clone()

Method print()

print reference summary

Usage

LFP_reference$print()

Method set_reference()

set reference for current electrode

Usage

LFP_reference$set_reference(reference)

Arguments

Method new()

constructor

Usage

LFP_reference$new(subject, number, quiet = FALSE)

Arguments

Method .load_noref_wavelet()

load non-referenced wavelet coefficients (internally used)

Usage

LFP_reference$.load_noref_wavelet(reload = FALSE)

Arguments

Method .load_noref_voltage()

load non-referenced voltage (internally used)

Usage

LFP_reference$.load_noref_voltage(reload = FALSE)

Arguments

Method .load_wavelet()

load referenced wavelet coefficients (internally used)

Usage

LFP_reference$.load_wavelet(
  type = c("power", "phase", "wavelet-coefficient"),
  reload = FALSE
)

Arguments

Method .load_voltage()

load referenced voltage (internally used)

Usage

LFP_reference$.load_voltage(reload = FALSE)

Arguments

Method load_data()

method to load electrode data

Usage

LFP_reference$load_data(
  type = c("power", "phase", "voltage", "wavelet-coefficient")
)

Arguments

Method load_blocks()

load electrode block-wise data (with reference), useful when epoch is absent

Usage

LFP_reference$load_blocks(
  blocks,
  type = c("power", "phase", "voltage", "wavelet-coefficient"),
  simplify = TRUE
)

Arguments

Method clear_cache()

method to clear cache on hard drive

Usage

LFP_reference$clear_cache(...)

Arguments

Method clear_memory()

method to clear memory

Usage

LFP_reference$clear_memory(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

LFP_reference$clone(deep = FALSE)

Arguments

Examples

## Not run: 

# Download subject demo/DemoSubject


subject <- as_rave_subject("demo/DemoSubject")

# Electrode 14 as reference electrode (Bipolar referencing)
e <- new_reference(subject = subject, number = "ref_14",
                   signal_type = "LFP")

# Reference "ref_13-16,24" (CAR or white-matter reference)
ref <- new_reference(subject = subject, number = "ref_13-16,24",
                     signal_type = "LFP")
ref

# Set epoch
e$set_epoch(epoch = 'auditory_onset')

# Set loading window
e$trial_intervals <- list(c(-1, 2))

# Preview
print(e)

# Now epoch power
power <- e$load_data("power")
names(dimnames(power))

# Subset power
subset(power, Time ~ Time < 0, Electrode ~ Electrode == 14)

# clear cache on hard disk
e$clear_cache()


## End(Not run)

Description

Analyze file structures and import all json and tsv files. File specification can be found at https://bids-specification.readthedocs.io/en/stable/, chapter "Modality specific files", section "Intracranial Electroencephalography" (doi:10.1038/s41597-019-0105-7). Please note that this function has very limited support on BIDS format.

Usage

load_bids_ieeg_header(bids_root, project_name, subject_code, folder = "ieeg")

Arguments

Value

A list containing the information below:

Examples

# Download https://github.com/bids-standard/bids-examples/
# extract to directory ~/rave_data/bids_dir/

bids_root <- '~/rave_data/bids_dir/'
project_name <- 'ieeg_visual'

if(dir.exists(bids_root) &&
   dir.exists(file.path(bids_root, project_name, 'sub-01'))){

  header <- load_bids_ieeg_header(bids_root, project_name, '01')

  print(header)

  # sessions
  names(header$sessions)

  # electrodes
  head(header$sessions$`01`$spaces$unknown_space$table)

  # visual task channel settings
  head(header$sessions$`01`$tasks$`01-visual-01`$channels)

  # event table
  head(header$sessions$`01`$tasks$`01-visual-01`$channels)
}

Description

Function try to load 'fst' arrays, if not found, read 'HDF5' arrays

Usage

load_fst_or_h5(
  fst_path,
  h5_path,
  h5_name,
  fst_need_transpose = FALSE,
  fst_need_drop = FALSE,
  ram = FALSE
)

Arguments

Details

RAVE stores data with redundancy. One electrode data is usually saved with two copies in different formats: 'HDF5' and 'fst', where 'HDF5' is cross-platform and supported by multiple languages such as Matlab, Python, etc, while 'fst' format is supported by R only, with super high read/write speed. load_fst_or_h5 checks whether the presence of 'fst' file, if failed, then it reads data from persistent 'HDF5' file.

Value

If 'fst' cache file exists, returns LazyFST object, otherwise returns LazyH5 instance

Lazy Load 'HDF5' File via hdf5r-package

Description

Wrapper for class LazyH5, which load data with "lazy" mode - only read part of dataset when needed.

Usage

load_h5(file, name, read_only = TRUE, ram = FALSE, quiet = FALSE)

Arguments

Value

If ram is true, then return data as arrays, otherwise return a LazyH5 instance.

See Also

save_h5

Examples

file <- tempfile()
x <- array(1:120, dim = c(4,5,6))

# save x to file with name /group/dataset/1
save_h5(x, file, '/group/dataset/1', quiet = TRUE)

# read data
y <- load_h5(file, '/group/dataset/1', ram = TRUE)
class(y)   # array

z <- load_h5(file, '/group/dataset/1', ram = FALSE)
class(z)   # LazyH5

dim(z)

Description

Load 'RAVE' subject meta data

Usage

load_meta2(meta_type, project_name, subject_code, subject_id, meta_name)

Arguments

Value

A data frame of the specified meta type or NULL is no meta data is found.

A port to read_yaml

Description

For more examples, see save_yaml.

Usage

load_yaml(file, ..., map = NULL)

Arguments

Value

A fastmap2. If map is provided then return map, otherwise return newly created one

See Also

fastmap2, save_yaml, read_yaml, write_yaml

Description

Convert 'FreeSurfer' 'mgh' to 'Nifti'

Usage

mgh_to_nii(from, to)

Arguments

Value

Nothing; the file will be created to path specified by to

Description

Add new 'RAVE' (2.0) module to current project

Usage

module_add(
  module_id,
  module_label,
  path = ".",
  type = c("default", "bare", "scheduler"),
  ...,
  pipeline_name = module_id,
  overwrite = FALSE
)

Arguments

Value

Nothing.

Description

Create, view, or reserve the module registry

Usage

module_registry(
  title,
  repo,
  modules,
  authors,
  url = sprintf("https://github.com/%s", repo)
)

module_registry2(repo, description)

get_modules_registries(update = NA)

get_module_description(path)

add_module_registry(title, repo, modules, authors, url, dry_run = FALSE)

Arguments

Details

A 'RAVE' registry contains the following data entries: repository title, name, 'URL', authors, and a list of module IDs. 'RAVE' requires that each module must use a unique module ID. It will cause an issue if two modules share the same ID. Therefore 'RAVE' maintains a public registry list such that the module maintainers can register their own module ID and prevent other people from using it.

To register your own module ID, please use add_module_registry to validate and send an email to the 'RAVE' development team.

Value

a registry object, or a list of registries

Examples

if(interactive()) {

library(raveio)

# get current registries
get_modules_registries(FALSE)

# create your own registry
module_registry(
  repo = "rave-ieeg/rave-pipelines",
  title = "A Collection of 'RAVE' Builtin Pipelines",
  authors = list(
    list("Zhengjia", "Wang", role = c("cre", "aut"),
         email = "[email protected]")
  ),
  modules = "brain_viewer"
)

# If your repository is on Github and RAVE-CONFIG file exists
module_registry2("rave-ieeg/rave-pipelines")

# send a request to add your registry

reg <- module_registry2("rave-ieeg/rave-pipelines")
add_module_registry(reg)

}

Description

Create a variable that automatically validates

Usage

new_constraints(type, assertions = NULL)

new_constrained_variable(name, initial_value, constraints = NULL, ...)

new_constrained_binding(name, expr, quoted = FALSE, constraints = NULL, ...)

Arguments

Examples

# ---- Basic usage ----------------------------------------
analysis_range <- new_constrained_variable("Analysis range")

# Using checkmates::assert_numeric
analysis_range$use_constraints(
  constraints = "numeric",
  any.missing = FALSE,
  len = 2,
  sorted = TRUE,
  null.ok = FALSE
)

analysis_range$initialized # FALSE
print(analysis_range)

# set value
analysis_range$set_value(c(1, 2))

# get value
analysis_range$value   # or $get_value()

# ---- Fancy constraints ------------------------------------
# construct an analysis range between -1~1 or 4~10
time_window <- validate_time_window(c(-1, 1, 4, 10))
analysis_range <- new_constrained_variable("Analysis range")
analysis_range$use_constraints(
  constraints = new_constraints(
    type = "numeric",
    assertions = list(
      # validator 1
      "numeric" = list(
        any.missing = FALSE,
        len = 2,
        sorted = TRUE,
        null.ok = FALSE
      ),

      # validator 2
      "range" = quote({
        check <- FALSE
        if(length(.x) == 2) {
          check <- sapply(time_window, function(w) {
            if(
              .x[[1]] >= w[[1]] &&
              .x[[2]] <= w[[2]]
            ) { return (TRUE) }
            return( FALSE )
          })
        }
        if(any(check)) { return(TRUE) }

        valid_ranges <- paste(
          sapply(time_window, function(w) {
            paste(sprintf("%.2f", w), collapse = ",")
          }),
          collapse = "] or ["
        )
        return(sprintf("Invalid range: must be [%s]", valid_ranges))
      })
    )
  )
)

# validate and print out error messages
# remove `on_error` argument to stop on errors
analysis_range$validate(on_error = "message")

# Try with values (-2,1) instead of c(0,1)
analysis_range$value <- c(0, 1)

print(analysis_range)
analysis_range[]

# Change the context
time_window <- validate_time_window(c(0, 0.5))

# re-validate will error out
analysis_range$validate(on_error = "message")

Description

Create new electrode channel instance or a reference signal instance

Usage

new_electrode(subject, number, signal_type, ...)

new_reference(subject, number, signal_type, ...)

Arguments

Details

In new_electrode, number should be a positive valid integer indicating the electrode number. In new_reference, number can be one of the followings:

'noref', or NULL

no reference is needed

'ref_X'

where 'X' is a single number, then the reference is another existing electrode; this could occur in bipolar-reference cases

'ref_XXX'

'XXX' is a combination of multiple electrodes that can be parsed by parse_svec. This could occur in common average reference, or white matter reference. One example is 'ref_13-16,24', meaning the reference signal is an average of electrode 13, 14, 15, 16, and 24.

Value

Electrode or reference instances that inherit RAVEAbstarctElectrode class

Examples

## Not run: 

# Download subject demo/DemoSubject (~500 MB)

# Electrode 14 in demo/DemoSubject
subject <- as_rave_subject("demo/DemoSubject")
e <- new_electrode(subject = subject, number = 14, signal_type = "LFP")

# Load CAR reference "ref_13-16,24"
ref <- new_reference(subject = subject, number = "ref_13-16,24",
                     signal_type = "LFP")
e$set_reference(ref)


# Set epoch
e$set_epoch(epoch = 'auditory_onset')

# Set loading window
e$trial_intervals <- list(c(-1, 2))

# Preview
print(e)

# Now epoch power
power <- e$load_data("power")
names(dimnames(power))

# Subset power
subset(power, Time ~ Time < 0, Electrode ~ Electrode == 14)

# Draw baseline
tempfile <- tempfile()
bl <- power_baseline(power, baseline_windows = c(-1, 0),
                     method = "decibel", filebase = tempfile)
collapsed_power <- collapse2(bl, keep = c(2,1))
# Visualize
dname <- dimnames(bl)
image(collapsed_power, x = dname$Time, y = dname$Frequency,
      xlab = "Time (s)", ylab = "Frequency (Hz)",
      main = "Mean power over trial (Baseline: -1~0 seconds)",
      sub = glue('Electrode {e$number} (Reference: {ref$number})'))
abline(v = 0, lty = 2, col = 'blue')
text(x = 0, y = 20, "Audio onset", col = "blue", cex = 0.6)

# clear cache on hard disk
e$clear_cache()
ref$clear_cache()


## End(Not run)

Description

Create a collection of constraint variables

Usage

new_variable_collection(name = "", explicit = TRUE, r6_def = NULL)

Arguments

Value

A RAVEVariableCollectionWrapper instance

Examples

collection <- new_variable_collection()

# Add unconstrained variables
collection$add_variable(id = "title", "Voltage traces")

# Add a variable with placeholder
collection$add_variable(id = "time_points")

# Add variable with constraints
collection$add_variable(
  id = "analysis_range",
  var = new_constrained_variable(
    name = "Analysis range",
    initial_value = c(0, 1),
    constraints = "numeric",
    any.missing = FALSE,
    len = 2,
    sorted = TRUE,
    null.ok = FALSE
  )
)

collection$use_constraints(quote({
  # `x` is the list of values
  time_range <- range(.x$time_points, na.rm = TRUE)
  if(
    .x$analysis_range[[1]] >= time_range[[1]] &&
    .x$analysis_range[[2]] <= time_range[[2]]
  ) {
    # valid
    re <- TRUE
  } else {

    # error message
    re <- sprintf(
      "Invalid analysis range, must be within [%.2f, %.2f]",
      time_range[[1]], time_range[[2]]
    )
  }

  re
}))


collection$set_value("time_points", seq(-1, 10, by = 0.5))

# validation will pass
collection$validate()

# Get variable values
collection$as_list()
collection[]

# get one variable
collection$get_value("analysis_range")

# get unregistered variable
collection$get_value("unregistered_variable")

# get partial variables with single `[`
collection["title", "analysis_range"]
collection[c("title", "analysis_range")]

collection$set_value("analysis_range", c(-2, 5))

## Not run: 
collection$validate()

# error out when explicit, please either
# set explicit=TRUE or register the variable via $add_variable
collection$set_value("unregistered_variable", 1)


## End(Not run)

# turn off explicit variable option
collection$explicit <- FALSE
collection$set_value("unregistered_variable", 1)
collection$get_value("unregistered_variable")

Description

Supports 'Rigid', 'affine', or 'non-linear' transformation

Usage

niftyreg_coreg(
  ct_path,
  mri_path,
  coreg_path = NULL,
  reg_type = c("rigid", "affine", "nonlinear"),
  interp = c("trilinear", "cubic", "nearest"),
  verbose = TRUE,
  ...
)

cmd_run_niftyreg_coreg(
  subject,
  ct_path,
  mri_path,
  reg_type = c("rigid", "affine", "nonlinear"),
  interp = c("trilinear", "cubic", "nearest"),
  verbose = TRUE,
  dry_run = FALSE,
  ...
)

Arguments

Value

Nothing is returned from the function. However, several files will be generated at the 'CT' path:

'ct_in_t1.nii'

aligned 'CT' image; the image is also re-sampled into 'MRI' space

'CT_IJK_to_MR_RAS.txt'

transform matrix from volume 'IJK' space in the original 'CT' to the 'RAS' anatomical coordinate in 'MR' scanner

'CT_RAS_to_MR_RAS.txt'

transform matrix from scanner 'RAS' space in the original 'CT' to 'RAS' in 'MR' scanner space

Description

Set pipeline inputs, execute, and read pipeline outputs

Usage

pipeline(
  pipeline_name,
  settings_file = "settings.yaml",
  paths = pipeline_root(),
  temporary = FALSE
)

pipeline_from_path(path, settings_file = "settings.yaml")

Arguments

Value

A PipelineTools instance

Examples

if(!is_on_cran()) {

library(raveio)

# ------------ Set up a bare minimal example pipeline ---------------
pipeline_path <- pipeline_create_template(
  root_path = tempdir(), pipeline_name = "raveio_demo",
  overwrite = TRUE, activate = FALSE, template_type = "rmd-bare")

save_yaml(list(
  n = 100, pch = 16, col = "steelblue"
), file = file.path(pipeline_path, "settings.yaml"))

pipeline_build(pipeline_path)

rmarkdown::render(input = file.path(pipeline_path, "main.Rmd"),
                  output_dir = pipeline_path,
                  knit_root_dir = pipeline_path,
                  intermediates_dir = pipeline_path, quiet = TRUE)

utils::browseURL(file.path(pipeline_path, "main.html"))

# --------------------- Example starts ------------------------

pipeline <- pipeline("raveio_demo", paths = tempdir())

pipeline$run("plot_data")

# Run again and you will see some targets are skipped
pipeline$set_settings(pch = 2)
pipeline$run("plot_data")

head(pipeline$read("input_data"))

# or use
pipeline[c("n", "pch", "col")]
pipeline[-c("input_data")]

pipeline$target_table

pipeline$result_table

pipeline$progress("details")

# --------------------- Clean up ------------------------
unlink(pipeline_path, recursive = TRUE)

}