Package 'ravecore'

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

## 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(x, ...)

## S3 method for class 'character'
as_rave_project(x, strict = TRUE, parent_path = NULL, ...)

Arguments

Details

A 'RAVE' project is an aggregation of subjects with the similar research targets. For example, 'RAVE' comes with a demo subject set, and the project 'demo' contains eight subjects undergoing same experiments. Project 'YAEL' contains subject whose electrodes are localized by 'YAEL' modules. The project can be "arbitrary": this is different to a 'BIDS' "project", often served as a data-set name or identifier. A 'BIDS' project may have multiple 'RAVE' projects. For example, an audio-visual 'BIDS' data may have a 'RAVE' project 'McGurk' to study the 'McGurk' effect and another 'synchrony' to study the audio-visual synchronization.

A valid 'RAVE' project name must only contain letters and digits; underscores and dashes may be acceptable but might subject to future change. For example 'demo' is a valid project name, but 'my demo' is invalid.

RAVE supports storing the data in 'native' or 'bids'-compliant formats. The native format is compatible with the 'RAVE' 1.0 and 2.0, and requires no conversion to 'BIDS' format, while 'bids' requires the data to be stored and processed in 'BIDS'-complaint format, which is better for data sharing and migration, but might be over-kill in some cases.

If the project string contains '@', the characters after the 'at' sign will be interpreted as indication of the storage format. For instance 'demo@native' or 'demo@bids:ds0001' are interpreted differently. The previous one indicates that the project 'demo' is stored with native format, usually located at 'rave_data/data_dir' under the home directory (can be manually set to other locations). The latter one means the 'RAVE' project 'demo' is stored under 'BIDS' folder with a 'BIDS' data-set name 'ds0001'.

Value

A RAVEProject instance

See Also

RAVEProject

Examples

# ---- Native format (RAVE legacy) ------------------------
project <- as_rave_project("demo", strict = FALSE)

format(project)

project$path

project$subjects()

# Non-standard project locations (native format)
as_rave_project("demo", strict = FALSE,
                parent_path = "~/Downloads")


# ---- BIDS format ----------------------------------------
project <- as_rave_project("demo@bids:ds001", strict = FALSE)

format(project)

project$path

# BIDS format, given the parent folder; this example requires
# 'bidsr' sample data. Run `bidsr::download_bids_examples()` first.

examples <- bidsr::download_bids_examples(test = TRUE)

if(!isFALSE(examples)) {

  project <- as_rave_project(
    "audiovisual@bids", strict = FALSE,
    parent_path = file.path(examples, "ieeg_epilepsy_ecog"))

  # RAVE processed data is under BIDS derivative folder
  project$path

  # "audiovisual@bids:ieeg_epilepsy_ecog"
  format(project)
}

Description

Image registration across different modals. Normalize brain 'T1'-weighted 'MRI' to template brain and generate subject-level atlas files. See cmd_run_yael_preprocess to see how to run a built-in workflow

Usage

as_yael_process(subject, ..., engine = c("rpyANTs", "native"))

Arguments

Value

A processing instance, see YAELProcess and YAELNativeProcess

Examples

process <- as_yael_process("YAEL/test_subject")

# the same process without 'Python'
process_native <- as_yael_process("YAEL/test_subject", engine = "native")

## 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

Class definition for auxiliary channels

Super classes

ravepipeline::RAVESerializable -> RAVEAbstarctElectrode -> Auxiliary_electrode

Active bindings

Methods

Public methods

• Auxiliary_electrode$@marshal()

• Auxiliary_electrode$@unmarshal()

• Auxiliary_electrode$print()

• Auxiliary_electrode$set_reference()

• Auxiliary_electrode$new()

• Auxiliary_electrode$.load_noref_voltage()

• Auxiliary_electrode$.load_raw_voltage()

• Auxiliary_electrode$load_data_with_epochs()

• Auxiliary_electrode$load_dimnames_with_epochs()

• Auxiliary_electrode$load_data_with_blocks()

• Auxiliary_electrode$load_dim_with_blocks()

• Auxiliary_electrode$clear_cache()

• Auxiliary_electrode$clear_memory()

• Auxiliary_electrode$clone()

Auxiliary_electrode$@marshal()

Internal method

Usage

Auxiliary_electrode$@marshal(...)

Arguments

Auxiliary_electrode$@unmarshal()

Internal method

Usage

Auxiliary_electrode$@unmarshal(object)

Arguments

Auxiliary_electrode$print()

print electrode summary

Usage

Auxiliary_electrode$print()

Auxiliary_electrode$set_reference()

set reference for current electrode

Usage

Auxiliary_electrode$set_reference(reference)

Arguments

Auxiliary_electrode$new()

constructor

Usage

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

Arguments

Auxiliary_electrode$.load_noref_voltage()

load non-referenced voltage (internally used)

Usage

Auxiliary_electrode$.load_noref_voltage(reload = FALSE)

Arguments

Auxiliary_electrode$.load_raw_voltage()

load raw voltage (no process)

Usage

Auxiliary_electrode$.load_raw_voltage(reload = FALSE)

Arguments

Auxiliary_electrode$load_data_with_epochs()

method to load electrode data

Usage

Auxiliary_electrode$load_data_with_epochs(type = c("raw-voltage", "voltage"))

Arguments

Auxiliary_electrode$load_dimnames_with_epochs()

get expected dimension names

Usage

Auxiliary_electrode$load_dimnames_with_epochs(
  type = c("raw-voltage", "voltage")
)

Arguments

Auxiliary_electrode$load_data_with_blocks()

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

Usage

Auxiliary_electrode$load_data_with_blocks(
  blocks,
  type = c("raw-voltage", "voltage"),
  simplify = TRUE
)

Arguments

Returns

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.

Auxiliary_electrode$load_dim_with_blocks()

get expected dimension information for block-based loader

Usage

Auxiliary_electrode$load_dim_with_blocks(
  blocks,
  type = c("raw-voltage", "voltage")
)

Arguments

Auxiliary_electrode$clear_cache()

method to clear cache on hard drive

Usage

Auxiliary_electrode$clear_cache(...)

Arguments

Auxiliary_electrode$clear_memory()

method to clear memory

Usage

Auxiliary_electrode$clear_memory(...)

Arguments

Auxiliary_electrode$clone()

The objects of this class are cloneable with this method.

Usage

Auxiliary_electrode$clone(deep = FALSE)

Arguments

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

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

This is a legacy script and possibly contain errors. Please use cmd_run_ants_coreg for faster and stable implementation instead.

Usage

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

Arguments

Description

Please avoid calling ants_coreg directly; use cmd_run_ants_coreg for more robust behaviors

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
)

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

Check https://rave.wiki on how to set up 'conda' environment for 'RAVE' using 'ravemanager'.

Usage

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
)

Arguments

Value

A command set running the terminal command; a folder named with type will be created under the subject image input folder

Examples

## Not run: 

cmd_run_dcm2niix(
  "YAEL/pt02",
  "/path/to/DICOMDIR",
  "MRI"
)


## End(Not run)

Description

Runs 'FreeSurfer' recon-all command underneath; must have 'FreeSurfer' installed.

Usage

cmd_run_freesurfer_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_freesurfer_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 shell command set.

Examples

# Requires `FreeSurfer` and only works on MacOS or Linux
# as `FreeSurfer` does not support Windows

## Not run: 

# Create subject instance; strict=FALSE means it's OK if the subject
# is missing
subject <- as_rave_subject("YAEL/s01", strict = FALSE)

cmd_run_freesurfer_recon_all(
  subject = subject,
  mri_path = "/path/to/T1.nii.gz"
)


## End(Not run)

Description

Run 'FSL' linear registration

Usage

cmd_run_fsl_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
)

Arguments

Value

A command set running the terminal command; a 'coregistration' folder will be created under the subject imaging directory

Description

Image processing pipeline doi:10.1523/ENEURO.0328-23.2023, allowing cross-modality image registration, T1-weighted MRI normalization to template brain, creating subject-level brain atlas from inverse normalization.

Usage

yael_preprocess(
  subject,
  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_09b",
  normalize_policy = c("auto", "all"),
  normalize_images = c("T1w", "T2w", "T1wContrast", "fGATIR", "preopCT"),
  normalize_back = ifelse(length(normalize_template) >= 1, normalize_template[[1]], NA),
  normalize_affine = NULL,
  atlases = list(),
  add_surfaces = FALSE,
  use_antspynet = TRUE,
  verbose = TRUE,
  additional_images = list(),
  ...
)

cmd_run_yael_preprocess(
  subject,
  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 = "mni_icbm152_nlin_asym_09b",
  normalize_images = c("T1w", "T2w", "T1wContrast", "fGATIR", "preopCT"),
  normalize_affine = NULL,
  run_recon_all = TRUE,
  dry_run = FALSE,
  use_antspynet = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Value

Nothing, a subject imaging folder will be created under 'RAVE' raw folder. It will take a while to run the workflow.

Examples

## Not run: 

# For T1 normalization only; add ct_path to include coregistration
cmd_run_yael_preprocess(
  subject = "pt01",
  t1w_path = "/path/to/T1w.nii.gz",

  additional_images = list(
    MEG = "/path/to/meg.nii.gz"
  ),

  # normalize T1 to MNI152
  normalize_template = 'mni_icbm152_nlin_asym_09b'
)



## End(Not run)

Description

The image processing pipeline of cmd_run_yael_preprocess (doi:10.1523/ENEURO.0328-23.2023), with every step computed in 'R' by YAELNativeProcess on top of ravetools (version 0.3.3 or later) instead of ⁠ANTs⁠ through 'Python': cross-modality rigid registration, normalization of the 'T1'-weighted 'MRI' to template brains, and subject-level atlases from the inverse normalization. The functions take the same arguments, run the same steps and write the same files as yael_preprocess and cmd_run_yael_preprocess, so the results can be read by either engine.

Usage

yael_preprocess_native(
  subject,
  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_09b",
  normalize_policy = c("auto", "all"),
  normalize_images = c("T1w", "T2w", "T1wContrast", "fGATIR", "preopCT"),
  normalize_back = ifelse(length(normalize_template) >= 1, normalize_template[[1]], NA),
  normalize_affine = NULL,
  atlases = list(),
  add_surfaces = FALSE,
  use_antspynet = TRUE,
  verbose = TRUE,
  additional_images = list(),
  ...
)

cmd_run_yael_preprocess_native(
  subject,
  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 = "mni_icbm152_nlin_asym_09b",
  normalize_images = c("T1w", "T2w", "T1wContrast", "fGATIR", "preopCT"),
  normalize_affine = NULL,
  run_recon_all = TRUE,
  dry_run = FALSE,
  use_antspynet = TRUE,
  verbose = TRUE,
  ...
)

Arguments

Details

Templates are located (and downloaded when missing) by rpyANTs, whose template functions are pure 'R'; 'Python' is never started. The full template resolution is used, which takes a lot of memory. With a 1 mm 'T1' image (256 by 204 by 256 voxels), the normalization to 'mni_icbm152_nlin_asym_09a' (1 mm, with 0.5 mm tissue maps) took about 2 minutes and peaked at about 8 gigabytes of resident memory; the normalization to 'mni_icbm152_nlin_asym_09b' (0.5 mm) took about 7 minutes and peaked at 15 gigabytes of resident memory, 22 gigabytes with the memory that the operating system compressed. Hence the script built by cmd_run_yael_preprocess_native switches from 'mni_icbm152_nlin_asym_09b' to 'mni_icbm152_nlin_asym_09a' when the memory recorded in the 'RAVE' settings (max_mem, the computer memory unless set otherwise) is below 32 gigabytes, where the script of cmd_run_yael_preprocess switches below 12 gigabytes. yael_preprocess_native does not switch templates; it warns when max_mem is below 32 gigabytes and a template has more than 30 million voxels.

The algorithms differ from ⁠ANTs⁠ in a few ways, described in YAELNativeProcess: no deep_atropos, local cross-correlation instead of mutual information in the non-linear stage, greedy single-field ⁠SyN⁠, whose update-field smoothing takes the rpyANTs values (3 and 3.5) as a ⁠Gaussian⁠ standard deviation in voxels where ⁠ANTs⁠ reads them as a variance, and is increased for templates with more voxels per brain (doubled for the 0.5 mm templates) so that the deformation stays one-to-one; additional images resampled onto the native 'T1' grid (and left out when they cover less than 95 percent of the brain), and a binary template brain mask. Streamlines in ⁠VTK⁠ format are not read or written, since ieegio needs 'Python' for them.

Value

yael_preprocess_native returns nothing; the subject imaging folder is created under the 'RAVE' raw folder. It will take a while to run the workflow. cmd_run_yael_preprocess_native returns, invisibly, a list with the script, its path, the log file, the image paths, and a function execute that runs the script; the script is saved as 'scripts/cmd-yael-preprocess-native-full.R' (or '-simple.R' without ⁠FreeSurfer⁠) under the imaging folder when it runs.

See Also

YAELNativeProcess, as_yael_process, cmd_run_yael_preprocess

Examples

## Not run: 

# For T1 normalization only; add ct_path to include coregistration
cmd_run_yael_preprocess_native(
  subject = "pt01",
  t1w_path = "/path/to/T1w.nii.gz",

  additional_images = list(
    MEG = "/path/to/meg.nii.gz"
  ),

  # normalize T1 to MNI152
  normalize_template = 'mni_icbm152_nlin_asym_09a'
)


## End(Not run)

Description

These shell commands are only tested on 'MacOS' and 'Linux'. On 'Windows' machines, please use the 'WSL2' system.

Usage

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(),
  ...
)

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

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

# 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 'RAVEFileArray'
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", "Auxiliary", "Unknown")
)

Arguments

Value

Nothing

Examples

if(interactive() && has_rave_subject("demo/DemoSubject")) {

  # 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 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

Examples

# Run `install_subject("DemoSubject")` first!
if( has_rave_subject("demo/DemoSubject") ) {

convert_electrode_table_to_bids(
  "demo/DemoSubject",
  space = "ScanRAS"
)

}

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", "tsv", "h5", "fst", "json", "rds", "yaml"),
  ...
)

import_table(
  file,
  format = c("auto", "csv", "csv.zip", "tsv", "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

Morphs a ⁠YBA⁠ atlas from the ⁠MNI152⁠ symmetric template to the subject native space, calculates the anatomical labels for the electrode contacts, and optionally creates a quality-control report. This function requires the subject to be normalized to a ⁠MNI152⁠ symmetric template first; see cmd_run_yael_preprocess.

Usage

generate_atlas_YBA(
  subject,
  name = c("YBA690", "YBA696"),
  template_names = NULL,
  radius = 2,
  verbose = TRUE,
  create_report = TRUE,
  disable_viewer = TRUE
)

Arguments

Details

The workflow requires an existing non-linear normalization from the subject native ⁠T1w⁠ image to a ⁠MNI152⁠ symmetric template. Please run cmd_run_yael_preprocess with normalize_template set to one of ⁠"mni_icbm152_nlin_sym_09a"⁠, ⁠"mni_icbm152_nlin_sym_09b"⁠, or ⁠"mni_icbm152_nlin_sym_09c"⁠ if such mapping is missing.

Given the mapping, the template atlas is inverse-transformed to the native space via generate_atlases_from_template. The resulting ⁠NIfTI⁠ volume is stored under the subject 'atlases' imaging folder, with a copy (and its color lookup table) placed under the subject ⁠FreeSurfer⁠ 'mri' folder such that the atlas can be displayed by the threeBrain viewer.

When the subject has electrode contacts localized, the anatomical labels are calculated within a sphere of radius millimeters around each contact center, and are stored as 'electrode_atlas_<name>.csv' under the subject meta folder.

Value

An invisible named list of

atlas_path

path to the atlas volume created under the subject ⁠FreeSurfer⁠ 'mri' folder

label_path

path to the electrode label table, or NA if no electrode contact has been localized

colormap_path

path to the color lookup table saved along with the atlas volume

report_path

path to the report folder, or NA if create_report is false

report_file

path to the report file, or NA if create_report is false

See Also

generate_atlases_from_template, cmd_run_yael_preprocess

Examples

# Please check out https://rave.wiki to configure Python for RAVE
# or run ravemanager::configure_python()
## Not run: 

subject_id <- "YAEL/subject_code"

# ---- Step 1: normalization ------------------------------------------
# Map the native `T1w` image to a `MNI152` symmetric template. This step
# is only needed once per subject; skip it when the mapping is available
cmd_run_yael_preprocess(
  subject = subject_id,
  t1w_path = "/path/to/T1w.nii.gz",

  # `YBA` atlases are defined in the `MNI152` symmetric space
  normalize_template = "mni_icbm152_nlin_sym_09b",

  # set to `TRUE` to also run `FreeSurfer` reconstruction
  # if you haven't...
  run_recon_all = FALSE
)

# ---- Step 2: atlas, electrode labels, and report ---------------------
# Morph the atlas back to the native space, label the electrode contacts,
# and create the quality-control report
results <- generate_atlas_YBA(subject_id, name = "YBA696")

# ---- Step 3: inspect --------------------------------------------------
# Electrode labels: `results$label_path`
utils::read.csv(results$label_path)

# Quality-control report
utils::browseURL(results$report_file)


## End(Not run)

Description

Reverse-transform from template atlases via volume mapping

Usage

generate_atlases_from_template(
  subject,
  atlas_folders,
  template_name = "mni_icbm152_nlin_asym_09b",
  any_mni152 = TRUE,
  surfaces = TRUE,
  as_job = FALSE,
  extra_transform = NULL,
  extra_transform_type = c("ants", "native")
)

Arguments

Details

The workflow generates atlases from a template. To run this function, a separate normalization is required (see cmd_run_yael_preprocess). That function normalizes native subject's brain ('T1w' image) to a specified template (typically 'MNI152b' non-linear asymmetric version) via a deformation field. Once obtaining the normalization transform, generate_atlases_from_template inverse the process, creating subject-level atlases based on that template.

When surfaces is TRUE, each atlas or mask file will be binned with a threshold of 0.5. The resulting binary mask will be used to generate a mask surface using volume_to_surf function via implicit Laplacian smoothing.

The resulting surfaces and atlases typically sit at native space aligned with input 'T1w' image. For each volume, a 'GIfTI' surface will be created under right-anterior-superior ('RAS') coordinate system for further inferences. In addition, an 'STL' surface will be created under left-posterior-superior ('LPS') coordinate system. This file is mainly to be used as object file for visualizations in software such as 'BrainLab'.

Some users might have extra processing before 'YAEL' pipeline (such as 'ACPC' realignment). This function provides a set of extra arguments (extra_transform and extra_transform_type) allowing generating atlases to align with the raw 'DICOM' images. extra_transform needs to be an 'affine' matrix that maps the image from the input of the 'YAEL' pipeline to the raw 'DICOM' image. Be aware that this transform is not the point transformation matrix. When extra_transform is non-empty, an extra folder atlases_extra will be created under the subject imaging folder, with transformed files aligned to 'DICOM' stored.

Value

The function returns nothing, but will create a folder named 'atlases' under raw subject 'rave-imaging' folder.

Examples

# Please check out https://rave.wiki to configure Python for RAVE
# or run ravemanager::configure_python()
## Not run: 

generate_atlases_from_template(
  "YAEL/OCD07", "/path/to/OCD_atlases")

# If the image was ACPC realigned before being fed into the YAEL
# pipeline
generate_atlases_from_template(
  "YAEL/OCD07", "/path/to/OCD_atlases",
  extra_transform =
    "/path/to/sub-OCD7_from-T1wACPC_to-T1wNative_mode-image_xfm.mat"
)


## End(Not run)

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

This function obtains existing transforms rather than creating new transforms. Please check function cmd_run_yael_preprocess about mapping native images to the templates. This function requires additional 'Python' configuration.

Usage

get_available_morph_to_template(subject)

Arguments

Value

Template names with valid non-linear transforms.

Examples

# Please check out https://rave.wiki to configure Python for RAVE
# or run ravemanager::configure_python()
## Not run: 

get_available_morph_to_template("project_name/subject_code")


## End(Not run)

Description

Get all possible projects in 'RAVE' default directory

Usage

get_projects(refresh = TRUE)

Arguments

Value

characters of project names

Examples

get_projects()

Description

Requires optional package 'plotly'; please install the package prior to launching the viewer.

Usage

glimpse_voltage_repository_with_blocks(
  repository,
  initial_block = NULL,
  channels = NULL,
  epoch = NULL,
  start_time = 0,
  duration = 5,
  channel_gap = 1000,
  highpass_freq = NA,
  lowpass_freq = NA
)

glimpse_voltage_filearray(
  filearray,
  sample_rate,
  channels = NULL,
  epoch = NULL,
  start_time = 0,
  duration = 5,
  channel_gap = 1000,
  highpass_freq = NA,
  lowpass_freq = NA
)

Arguments

Value

An R-shiny application container environment; use print method to launch the application.

Examples

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


  repository <- ravecore::prepare_subject_voltage_with_blocks(
    subject = subject)

  if (interactive()) {
    app <- glimpse_voltage_repository_with_blocks(
      repository = repository,
      initial_block = "008",
      epoch = "auditory_onset",
      highpass_freq = 0.5
    )

    print(app)
    close(app)

  }

}

# ---- Example 2 ---------------------------------------------------

# Construct a filearray


sample_rate <- 100
filearray <- filearray::as_filearray(array(rnorm(50000),
                                           dim = c(10000, 5)))

dimnames(filearray) <- list(
  Time = seq_len(10000) / sample_rate,
  Electrode = 1:5
)

if(interactive()) {

  app <- glimpse_voltage_filearray(filearray = filearray,
                                   sample_rate = sample_rate,
                                   channel_gap = 6)

  print(app)
}

Description

Import signal data from different file formats; supports 'EDF', 'BrainVision', 'BlackRock', 'HDF5', and 'Matlab' formats under either native or 'BIDS' standard. It is recommended to use 'RAVE' user interfaces to import data.

Usage

import_from_brainvis(
  subject,
  blocks,
  electrodes,
  sample_rate,
  add = FALSE,
  data_type = "LFP",
  ...
)

import_from_edf(
  subject,
  blocks,
  electrodes,
  sample_rate,
  add = FALSE,
  data_type = "LFP",
  skip_validation = FALSE,
  ...
)

import_from_h5_mat_per_block(
  subject,
  blocks,
  electrodes,
  sample_rate,
  add = FALSE,
  data_type = "LFP",
  skip_validation = FALSE,
  ...
)

import_from_h5_mat_per_channel(
  subject,
  blocks,
  electrodes,
  sample_rate,
  add = FALSE,
  data_type = "LFP",
  skip_validation = FALSE,
  ...
)

import_from_nevnsx(
  subject,
  blocks,
  electrodes,
  sample_rate,
  add = FALSE,
  data_type = "LFP",
  skip_validation = FALSE,
  ...
)

Arguments

Recording Blocks

The term "recording block" is defined as a continuous block of signals recorded during the experiment, typically during one run of the experiment, depending on the setups and format standards:

In the context of native standard, the raw 'RAVE' data is typically stored in the '~/rave_data/raw_dir' directory ('~' stands for your home directory, or documents directory under Windows). Each subject is stored under a folder named after the subject code. For example, subject 'DemoSubject' has a raw folder path '~/rave_data/raw_dir/DemoSubject'. The block folders are stored under this subject folder (such as '008', '010', ...). Each block folder contains a 5-min recording from an experiment.

In the context of 'BIDS' standard, there is no official definition of a 'block', instead, 'BIDS' has an explicit definition of sessions, tasks, and runs. We typically consider that a combination of a session, a task, and a run consists of a recording block. For example, 'ses-01_task-01_run-01' or 'ses-01_run-01', depending on the existence of the 'BIDS' entities.

Channel Numbers

(Electrode) channel numbers refer to vectors of integers, or characters that can be interpreted as integers. For integers, this is straightforward: c(1:10, 21:30) refers to channel 1 to 20, then 21 to 30. For characters, this is converted to integer internally via an unexported function ravecore:::parse_svec.

The channel numbers must be an integer. In some data formats (such as 'EDF') or some standards ('BIDS'), the channel number is not officially explicitly defined: they use the channel labels as the identifiers. To deal with this situation, 'RAVE' treats the channel order as their numbers. In some cases, this is less ideal because the channel labels might implicitly encode the channel numbers. 'RAVE' will ignore such information for consistent behavior.

Description

Enjoy hundreds of open-access data sets from https://openneuro.org with a simple accession number.

Usage

install_openneuro(
  accession_number,
  subject_codes = NULL,
  tag = NULL,
  parent_folder = NULL
)

Arguments

Value

The data folder name on the local disk.

Examples

## Not run: 

# Download Hermes D, Miller KJ, Wandell BA, Winawer J (2015) dataset
# from https://openneuro.org/datasets/ds005953

install_openneuro('ds005953')

# Download subject sub-HUP070 used by Bernabei & Li et al.
# from https://openneuro.org/datasets/ds004100

install_openneuro('ds004100', subject_codes = "HUP070")

# access the downloaded data
bids_parent_root <- ravepipeline::raveio_getopt("bids_data_dir")

# ---- Example of visualizing electrodes on the fsaverage ----
# Load BIDS project
proj_ds004100 <- bidsr::bids_project(
  file.path(bids_parent_root, "ds004100"))

# BIDS-R Subject instance
sub_HUP070 <- bidsr::bids_subject(proj_ds004100, "HUP070")

# Find BIDS entities with electrodes as suffix
electrode <- bidsr::query_bids(sub_HUP070, list(
  data_types = "ieeg",
  suffixes = "electrodes",
  sidecars = TRUE
))

# resolve electrode table path
electrode_path <- bidsr::resolve_bids_path(
  x = proj_ds004100,
  format(electrode$parsed[[1]]))

# laod electrode coordinate
tabular <- bidsr::as_bids_tabular(electrode_path)

# Build RAVE electrode table
electrode_coordinates <- data.frame(
  Electrode = 1:nrow(tabular$content),
  x = tabular$content$x,
  y = tabular$content$y,
  z = tabular$content$z,
  Label = tabular$content$name,
  Radius = 2,
  BIDSSubject = "sub-HUP070"
)

# Load RAVE brain - fsaverage
template <- threeBrain::merge_brain(template_subject = "fsaverage")
fsaverage <- template$template_object

# This dataset uses surface RAS; see coordsys JSON
# tkrRAS: surface RAS
# scannerRAS: MRI RAS
fsaverage$set_electrodes(electrode_coordinates, coord_sys = "tkrRAS")

fsaverage$plot()




## End(Not run)

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

## Not run: 

install_subject("DemoSubject")


## End(Not run)

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

Super classes

ravepipeline::RAVESerializable -> RAVEAbstarctElectrode -> LFP_electrode

Active bindings

Methods

Public methods

• LFP_electrode$@marshal()

• LFP_electrode$@unmarshal()

• 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_with_epochs()

• LFP_electrode$load_dimnames_with_epochs()

• LFP_electrode$load_data_with_blocks()

• LFP_electrode$load_dim_with_blocks()

• LFP_electrode$clear_cache()

• LFP_electrode$clear_memory()

• LFP_electrode$clone()

LFP_electrode$@marshal()

Internal method

Usage

LFP_electrode$@marshal(...)

Arguments

LFP_electrode$@unmarshal()

Internal method

Usage

LFP_electrode$@unmarshal(object)

Arguments

LFP_electrode$print()

print electrode summary

Usage

LFP_electrode$print()

LFP_electrode$set_reference()

set reference for current electrode

Usage

LFP_electrode$set_reference(reference)

Arguments

LFP_electrode$new()

constructor

Usage

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

Arguments

LFP_electrode$.load_noref_wavelet()

load non-referenced wavelet coefficients (internally used)

Usage

LFP_electrode$.load_noref_wavelet(reload = FALSE)

Arguments

Returns

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

LFP_electrode$.load_noref_voltage()

load non-referenced voltage (internally used)

Usage

LFP_electrode$.load_noref_voltage(reload = FALSE)

Arguments

LFP_electrode$.load_wavelet()

load referenced wavelet coefficients (internally used)

Usage

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

Arguments

LFP_electrode$.load_voltage()

load referenced voltage (internally used)

Usage

LFP_electrode$.load_voltage(reload = FALSE)

Arguments

LFP_electrode$.load_raw_voltage()

load raw voltage (no process)

Usage

LFP_electrode$.load_raw_voltage(reload = FALSE)

Arguments

LFP_electrode$load_data_with_epochs()

method to load electrode data

Usage

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

Arguments

LFP_electrode$load_dimnames_with_epochs()

get expected dimension names

Usage

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

Arguments

LFP_electrode$load_data_with_blocks()

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

Usage

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

Arguments

Returns

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.

LFP_electrode$load_dim_with_blocks()

get expected dimension information for block-based loader

Usage

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

Arguments

LFP_electrode$clear_cache()

method to clear cache on hard drive

Usage

LFP_electrode$clear_cache(...)

Arguments

LFP_electrode$clear_memory()

method to clear memory

Usage

LFP_electrode$clear_memory(...)

Arguments

LFP_electrode$clone()

The objects of this class are cloneable with this method.

Usage

LFP_electrode$clone(deep = FALSE)

Arguments

Examples

# Download subject demo/DemoSubject

if(has_rave_subject("demo/DemoSubject")) {

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

# 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_with_epochs("power")
names(dimnames(power))

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


# 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

Super classes

ravepipeline::RAVESerializable -> RAVEAbstarctElectrode -> LFP_reference

Active bindings

Methods

Public methods

• LFP_reference$@marshal()

• LFP_reference$@unmarshal()

• 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_with_epochs()

• LFP_reference$load_data_with_blocks()

• LFP_reference$load_dim_with_blocks()

• LFP_reference$clear_cache()

• LFP_reference$clear_memory()

• LFP_reference$clone()

LFP_reference$@marshal()

Internal method

Usage

LFP_reference$@marshal(...)

Arguments

LFP_reference$@unmarshal()

Internal method

Usage

LFP_reference$@unmarshal(object)

Arguments

LFP_reference$print()

print reference summary

Usage

LFP_reference$print()

LFP_reference$set_reference()

set reference for current electrode

Usage

LFP_reference$set_reference(reference)

Arguments

LFP_reference$new()

constructor

Usage

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

Arguments

LFP_reference$.load_noref_wavelet()

load non-referenced wavelet coefficients (internally used)

Usage

LFP_reference$.load_noref_wavelet(reload = FALSE)

Arguments

Returns

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

LFP_reference$.load_noref_voltage()

load non-referenced voltage (internally used)

Usage

LFP_reference$.load_noref_voltage(reload = FALSE)

Arguments

LFP_reference$.load_wavelet()

load referenced wavelet coefficients (internally used)

Usage

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

Arguments

LFP_reference$.load_voltage()

load referenced voltage (internally used)

Usage

LFP_reference$.load_voltage(reload = FALSE)

Arguments

LFP_reference$load_data_with_epochs()

method to load electrode data

Usage

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

Arguments

LFP_reference$load_data_with_blocks()

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

Usage

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

Arguments

Returns

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.

LFP_reference$load_dim_with_blocks()

get expected dimension information for block-based loader

Usage

LFP_reference$load_dim_with_blocks(
  blocks,
  type = c("power", "phase", "voltage", "wavelet-coefficient", "raw-voltage")
)

Arguments

LFP_reference$clear_cache()

method to clear cache on hard drive

Usage

LFP_reference$clear_cache(...)

Arguments

LFP_reference$clear_memory()

method to clear memory

Usage

LFP_reference$clear_memory(...)

Arguments

LFP_reference$clone()

The objects of this class are cloneable with this method.

Usage

LFP_reference$clone(deep = FALSE)

Arguments

Examples

# Download subject demo/DemoSubject
if( has_rave_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_with_epochs("power")
names(dimnames(power))

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

# clear cache on hard disk
e$clear_cache()

}

Description

Load or save meta data to 'RAVE' subject

Usage

save_meta2(data, meta_type, project_name, subject_code)

load_meta2(
  meta_type = c("electrodes", "frequencies", "time_points", "epoch", "references",
    "time_excluded", "info"),
  project_name,
  subject_code,
  subject_id,
  meta_name
)

Arguments

Value

The corresponding metadata

Examples

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

  electrode_table <- subject$get_electrode_table()

  save_meta2(
    data = electrode_table,
    meta_type = "electrodes",
    project_name = subject$project_name,
    subject_code = subject$subject_code
  )

  load_meta2(meta_type = "electrodes", subject_id = subject)
}

Description

Create new electrode channel instance or a reference signal instance

Create new electrode channel instance or a reference signal instance

Usage

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

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

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. 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.

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

Electrode or reference instances that inherit RAVEAbstarctElectrode class

Examples

# Download subject demo/DemoSubject
if( has_rave_subject("demo/DemoSubject") ) {


# 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_with_epochs("power")
names(dimnames(power))

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

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

}

# Download subject demo/DemoSubject
if( has_rave_subject("demo/DemoSubject") ) {


# 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_with_epochs("power")
names(dimnames(power))

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

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

}

Get RAVESubject instance from character

Description

Get RAVESubject instance from character

Usage

new_rave_subject(project_name, subject_code, strict = TRUE)

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

has_rave_subject(subject_id)

Arguments

Value

RAVESubject instance

See Also

RAVESubject

Examples

subject <- new_rave_subject(project_name = "demo@bids:ds04001",
                            subject_code = "DemoSubject",
                            strict = FALSE)

subject

subject$project$path
subject$imaging_path

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

Display slices, or interleave with image overlays. Require installing package htmltools.

Usage

plot_volume_slices(
  x,
  overlay = NULL,
  depths = seq(-100, 100, by = 18),
  which = c("coronal", "axial", "sagittal"),
  nc = NA,
  col = c("black", "white"),
  overlay_col = col,
  overlay_alpha = NA,
  interleave = is.na(overlay_alpha),
  interleave_period = 4,
  interleave_transition = c("ease-in-out", "linear"),
  pixel_width = 0.5,
  underlay_range = NULL,
  overlay_range = NULL,
  ...
)

Arguments

Value

A 'SVG' tag object that can be embedded in shiny applications or plotted directly.

Examples

# toy-example:

shape <- c(10, 10, 10)
vox2ras <- matrix(
  c(10, 17.32, 0, -136,
    -17.32, 10, 20, -63,
    0, -20, 0, 100,
    0, 0, 0, 1),
  nrow = 4, byrow = TRUE
)

# continuous
x <- abs(array(sin(seq_len(100) / 10), shape))

underlay <- ieegio::as_ieegio_volume(x, vox2ras = vox2ras)
overlay <- ieegio::as_ieegio_volume(x > 0.2, vox2ras = vox2ras)

if(interactive()) {

  plot_volume_slices(
    underlay, overlay = overlay,
    depths = seq(0, 150, length.out = 4), pixel_width = 5,
    overlay_col = c("#00000000", "#FF000044", "#FF0000FF")
  )

}

# Require `install_subject("yael_demo_001")`
if(has_rave_subject("YAEL/yael_demo_001")) {

subject <- ravecore::as_rave_subject("YAEL/yael_demo_001",
                                     strict = FALSE)


t1 <- file.path(subject$imaging_path, "coregistration",
                "MRI_reference.nii.gz")

ct <- file.path(subject$imaging_path, "coregistration",
                "CT_RAW.nii.gz")
transform <- read.table(
  file.path(subject$imaging_path, "coregistration",
            "CT_IJK_to_MR_RAS.txt")
)

ct_image_original <- ieegio::read_volume(ct)
ct_image_aligned <- ieegio::as_ieegio_volume(
  ct_image_original[], vox2ras = as.matrix(transform)
)

if(interactive()) {
  plot_volume_slices(
    t1, overlay = ct_image_aligned,
    overlay_col = c("#00000000", "#FF000044", "#FF0000FF"),
    nc = 6
  )
}

}

Description

Calculate power baseline

Usage

power_baseline(
  x,
  baseline_windows,
  method = c("percentage", "sqrt_percentage", "decibel", "zscore", "sqrt_zscore",
    "db_zscore"),
  units = c("Trial", "Frequency", "Electrode"),
  ...
)

## S3 method for class 'rave_prepare_power'
power_baseline(
  x,
  baseline_windows,
  method = c("percentage", "sqrt_percentage", "decibel", "zscore", "sqrt_zscore",
    "db_zscore"),
  units = c("Frequency", "Trial", "Electrode"),
  electrodes,
  ...
)

## S3 method for class 'FileArray'
power_baseline(
  x,
  baseline_windows,
  method = c("percentage", "sqrt_percentage", "decibel", "zscore", "sqrt_zscore",
    "db_zscore"),
  units = c("Frequency", "Trial", "Electrode"),
  filebase = NULL,
  ...
)

## S3 method for class 'array'
power_baseline(
  x,
  baseline_windows,
  method = c("percentage", "sqrt_percentage", "decibel", "zscore", "sqrt_zscore",
    "db_zscore"),
  units = c("Trial", "Frequency", "Electrode"),
  ...
)

Arguments

Details

The arrays must be four-mode tensor and must have valid named dimnames. The dimension names must be 'Trial', 'Frequency', 'Time', 'Electrode', case sensitive.

The baseline_windows determines the baseline windows that are used to calculate time-points of baseline to be included. This can be one or more intervals and must pass the validation function validate_time_window.

The units determines the unit of the baseline. It can be one or more of 'Trial', 'Frequency', 'Electrode'. The default value is all of them, i.e., baseline for each combination of trial, frequency, and electrode. To share the baseline across trials, please remove 'Trial' from units. To calculate baseline that should be shared across electrodes (e.g. in some mini-electrodes), remove 'Electrode' from the units.

Value

Usually the same type as the input: for arrays and filearray, the outputs are also the same type with the same dimensions; for 'rave_prepare_power' repositories, the results will be stored in its 'baselined' element; see 'Examples'.

Examples

if( has_rave_subject("demo/DemoSubject") ) {

# The following code need to download additional demo data
# Please see https://rave.wiki/ for more details

repo <- prepare_subject_power_with_epochs(
  subject = "demo/DemoSubject",
  time_windows = c(-1, 3),
  electrodes = c(14, 15))

##### Direct baseline on the repository
power_baseline(x = repo, method = "decibel",
               baseline_windows = list(c(-1, 0), c(2, 3)))
power_mean <- repo$power$baselined$collapse(
  keep = c(2,1), method = "mean")
image(power_mean, x = repo$time_points, y = repo$frequency,
      xlab = "Time (s)", ylab = "Frequency (Hz)",
      main = "Mean power over trial (Baseline: -1~0 & 2~3)")
abline(v = 0, lty = 2, col = 'blue')
text(x = 0, y = 20, "Aud-Onset", col = "blue", cex = 0.6)

##### Alternatively, baseline on electrode instances
baselined <- lapply(repo$power$data_list, function(inst) {
  re <- power_baseline(inst, method = "decibel",
                       baseline_windows = list(c(-1, 0), c(2, 3)))
  collapse2(re, keep = c(2,1), method = "mean")
})
power_mean2 <- (baselined[[1]] + baselined[[2]]) / 2

# Same with precision difference
max(abs(power_mean2 - power_mean)) < 1e-6


}

Description

'RAVE' repository: basic

Usage

prepare_subject_bare(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  ...,
  auto_exclude = FALSE,
  quiet = TRUE,
  repository_id = NULL
)

prepare_subject_bare0(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  ...,
  auto_exclude = FALSE,
  quiet = TRUE,
  repository_id = NULL
)

Arguments

Value

A RAVESubjectBaseRepository instance

Examples

if ( has_rave_subject("demo/DemoSubject") ) {


repository <- prepare_subject_bare0("demo/DemoSubject",
                                    electrodes = 14:16,
                                    reference_name = "default")

print(repository)

repository$subject
repository$subject$raw_sample_rates

repository$electrode_table

repository$reference_table

electrodes <- repository$electrode_instances

# Channel 14
e <- electrodes$e_14

# referenced voltage
voltage <- e$load_data_with_blocks("008", "voltage")

ravetools::diagnose_channel(voltage, srate = 2000)


}

Description

Loads recording blocks - continuous recording chunks, typically a run of minutes.

Usage

prepare_subject_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_raw_voltage_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = "noref",
  downsample = NA,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_voltage_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = NULL,
  downsample = NA,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_time_frequency_coefficients_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_phase_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_power_with_blocks(
  subject,
  electrodes = NULL,
  blocks = NULL,
  reference_name = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

Arguments

Details

prepare_subject_with_blocks does not actually load any signal data. Its existence is simply for backward compatibility. It instantiates a super-class of the rest of methods. Therefore, please refer to the rest of the methods for loading specific data types.

If you do not need to analyze super high-frequency signals, it is recommended to set a proper downsample value to down-sample the signals while loading voltage traces. This helps optimizing the data storage and speed up computation (significantly). For example, suppose you have 200 channels sampled at 30,000 Hz, a 30-minute recording will cost around 80+ gigabyte memory only to store, let along the storage needed to compute analyses and time needed to perform those analyses. Down-sampling the channels helps a lot. If you are mostly interested in signals below 100 Hz, then down-sampling voltage traces to 400 Hz will preserve the frequency components needed, and it takes 1.2 gigabytes to hold the same recording in memory.

Due to the large-data nature of blocks of signals, the repository will prepare cache files for all the channels, allowing users to load the cached data later without needing to reload

Value

A RAVESubjectRecordingBlockRepository instance

Examples

if( has_rave_subject("demo/DemoSubject") ) {


# ---- An use-case example ------------------------------------------------
# Install subject via install_subject("DemoSubject")
subject <- as_rave_subject("demo/DemoSubject")

# list all blocks
subject$blocks

repository <- prepare_subject_voltage_with_blocks(
  subject,
  electrodes = 13:16,
  blocks = "008",
  reference = "default"
)

print(repository)

repository$blocks

# get data
container <- repository$get_container()

# block data
container$`008`
lfp_list <- container$`008`$LFP
channel_sample_rate <- lfp_list$sample_rate

# Even we only load channels 14-16, all the channels are here for
# in case we want to use the cache for future purposes
lfp_list$dimnames$Electrode

# Plot all loaded channels
channel_sel <- lfp_list$dimnames$Electrode %in% c(14, 15, 16)
channel_signals <- lfp_list$data[, channel_sel,
                                 drop = FALSE,
                                 dimnames = FALSE]

ravetools::plot_signals(t(channel_signals),
                        sample_rate = channel_sample_rate,
                        channel_names = 14:16)

# Load channel 14 and plot pwelch
channel_sel <- lfp_list$dimnames$Electrode == 14

channel_signals <- lfp_list$data[, channel_sel,
                                 drop = TRUE,
                                 dimnames = FALSE]

ravetools::diagnose_channel(channel_signals,
                            srate = channel_sample_rate,
                            name = "Channel 14",
                            nclass = 30)

# ---- Use cache ---------------------------------------------------

subject <- as_rave_subject("demo/DemoSubject")

# Lazy-load block 008
repository <- prepare_subject_voltage_with_blocks(
  subject,
  electrodes = 13:16,
  blocks = "008",
  reference = "default",
  lazy_load = TRUE  # <-- trick
)

# Immediately load data with force=FALSE to use cache if exists
repository$mount_data(force = FALSE)

# ---- More examples ---------------------------------------------


subject <- as_rave_subject("demo/DemoSubject")
repository <- prepare_subject_power_with_blocks(
  subject,
  electrodes = 14,
  blocks = "008",
  reference_name = "default"
)

block_008 <- repository$power$`008`$LFP

channel_sel <- block_008$dimnames$Electrode == 14

# Drop electrode margin
power <- block_008$data[, , channel_sel,
                        drop = TRUE, dimnames = FALSE]

# global baseline
power_baselined_t <- 10 * log10(t(power))
power_baselined_t <- power_baselined_t - rowMeans(power_baselined_t)

ravetools::plot_signals(
  power_baselined_t,
  sample_rate = block_008$sample_rate,
  channel_names = block_008$dimnames$Frequency,
  space = 1,
  start_time = 20,
  duration = 30, ylab = "Frequency",
  main = "Channel 14 - Power with Global Baseline (20-50 sec)"
)


}

Description

'RAVE' repository: with epochs

Usage

prepare_subject_with_epochs(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_raw_voltage_with_epochs(
  subject,
  electrodes = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = TRUE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_voltage_with_epochs(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_time_frequency_coefficients_with_epochs(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_power_with_epochs(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_power(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

prepare_subject_phase_with_epochs(
  subject,
  electrodes = NULL,
  reference_name = NULL,
  epoch_name = NULL,
  time_windows = NULL,
  stitch_events = NULL,
  ...,
  quiet = FALSE,
  repository_id = NULL,
  strict = TRUE
)

Arguments

Value

A RAVESubjectEpochRepository instance

Examples

if ( has_rave_subject("demo/DemoSubject") ) {


repository <- prepare_subject_with_epochs(
  "demo/DemoSubject", electrodes = 14:16,
  reference_name = "default", epoch_name = "auditory_onset",
  time_windows = c(-1, 2))

print(repository)

head(repository$epoch$table)

electrodes <- repository$electrode_instances

# Channel 14
e <- electrodes$e_14

# referenced voltage
voltage <- e$load_data_with_epochs("voltage")

# 6001 time points (2000 sample rate)
# 287 trials
# 1 channel
dim(voltage)

ravetools::plot_signals(t(voltage[, 1:10, 1]),
                        sample_rate = 2000,
                        ylab = "Trial",
                        main = "First 10 trials")

}

Description

Align 'CT' using nipy.algorithms.registration.histogram_registration.

Usage

py_nipy_coreg(
  ct_path,
  mri_path,
  clean_source = TRUE,
  inverse_target = TRUE,
  precenter_source = TRUE,
  smooth = 0,
  reg_type = c("rigid", "affine"),
  interp = c("pv", "tri"),
  similarity = c("crl1", "cc", "cr", "mi", "nmi", "slr"),
  optimizer = c("powell", "steepest", "cg", "bfgs", "simplex"),
  tol = 1e-04,
  dry_run = FALSE
)

cmd_run_nipy_coreg(
  subject,
  ct_path,
  mri_path,
  clean_source = TRUE,
  inverse_target = TRUE,
  precenter_source = TRUE,
  reg_type = c("rigid", "affine"),
  interp = c("pv", "tri"),
  similarity = c("crl1", "cc", "cr", "mi", "nmi", "slr"),
  optimizer = c("powell", "steepest", "cg", "bfgs", "simplex"),
  dry_run = FALSE,
  verbose = 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

Create 3D visualization of the brain and visualize with modern web browsers

Usage

rave_brain(
  subject,
  surfaces = "pial",
  overlays = "aparc.a2009s+aseg",
  annotations = "label/aparc.a2009s",
  streamlines = "default/*",
  ...,
  usetemplateifmissing = FALSE,
  include_electrodes = TRUE
)

Arguments