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

Arguments

Value

A processing instance, see YAELProcess

Examples

process <- as_yael_process("YAEL/test_subject")

## 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),
  atlases = list(),
  add_surfaces = FALSE,
  use_antspynet = TRUE,
  verbose = TRUE,
  ...
)

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"),
  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",

  # normalize T1 to MNI152
  normalize_template = 'mni_icbm152_nlin_asym_09b'
)



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

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",
  ...,
  usetemplateifmissing = FALSE,
  include_electrodes = TRUE
)

Arguments

Value

A 'threeBrain' instance if brain is found or usetemplateifmissing is set to true; otherwise returns NULL

Examples

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

  brain <- rave_brain("demo/DemoSubject")

  if (interactive()) {

    brain$plot()

  }

}

Description

Find external command-line tools

Usage

normalize_commandline_path(
  path,
  type = c("dcm2niix", "freesurfer", "fsl", "afni", "others"),
  unset = NA
)

cmd_dcm2niix(error_on_missing = TRUE, unset = NA)

cmd_freesurfer_home(error_on_missing = TRUE, unset = NA)

cmd_fsl_home(error_on_missing = TRUE, unset = NA)

cmd_afni_home(error_on_missing = TRUE, unset = NA)

cmd_homebrew(error_on_missing = TRUE, unset = NA)

cmd_dry_run()

rscript_path(...)

Arguments

Value

Normalized path to the command, or unset if command is missing.

Description

Convert 'RAVE' subject generated by 2.0 pipeline such that 1.0 modules can use the data. The subject must have valid electrodes. The data must be imported, with time-frequency transformed to pass the validation before converting.

Usage

rave_legacy_subject_format_conversion(subject, verbose = TRUE, ...)

Arguments

Value

Nothing

Description

A generic function that will be dispatched to using different method based on input x

Usage

rave_path(x, storage = NULL, ...)

Arguments

Description

This class is not intended for direct use. Please create new child classes and implement some key methods.

Super class

ravepipeline::RAVESerializable -> RAVEAbstarctElectrode

Public fields

Active bindings

Methods

Public methods

• RAVEAbstarctElectrode$new()

• RAVEAbstarctElectrode$set_reference()

• RAVEAbstarctElectrode$set_epoch()

• RAVEAbstarctElectrode$clear_cache()

• RAVEAbstarctElectrode$clear_memory()

• RAVEAbstarctElectrode$load_data_with_epochs()

• RAVEAbstarctElectrode$load_data()

• RAVEAbstarctElectrode$load_dimnames_with_epochs()

• RAVEAbstarctElectrode$load_data_with_blocks()

• RAVEAbstarctElectrode$load_blocks()

• RAVEAbstarctElectrode$load_dim_with_blocks()

• RAVEAbstarctElectrode$clone()

RAVEAbstarctElectrode$new()

constructor

Usage

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

Arguments

RAVEAbstarctElectrode$set_reference()

set reference for instance

Usage

RAVEAbstarctElectrode$set_reference(reference)

Arguments

RAVEAbstarctElectrode$set_epoch()

set epoch instance for the electrode

Usage

RAVEAbstarctElectrode$set_epoch(epoch, stitch_events = NULL)

Arguments

RAVEAbstarctElectrode$clear_cache()

method to clear cache on hard drive

Usage

RAVEAbstarctElectrode$clear_cache(...)

Arguments

RAVEAbstarctElectrode$clear_memory()

method to clear memory

Usage

RAVEAbstarctElectrode$clear_memory(...)

Arguments

RAVEAbstarctElectrode$load_data_with_epochs()

method to load electrode data

Usage

RAVEAbstarctElectrode$load_data_with_epochs(type)

Arguments

RAVEAbstarctElectrode$load_data()

alias of load_data_with_epochs for legacy code

Usage

RAVEAbstarctElectrode$load_data(type)

Arguments

RAVEAbstarctElectrode$load_dimnames_with_epochs()

get expected dimension names

Usage

RAVEAbstarctElectrode$load_dimnames_with_epochs(type)

Arguments

RAVEAbstarctElectrode$load_data_with_blocks()

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

Usage

RAVEAbstarctElectrode$load_data_with_blocks(blocks, type, 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.

RAVEAbstarctElectrode$load_blocks()

alias of load_data_with_blocks for legacy code

Usage

RAVEAbstarctElectrode$load_blocks(blocks, type, simplify = TRUE)

Arguments

RAVEAbstarctElectrode$load_dim_with_blocks()

get expected dimension information for block-based loader

Usage

RAVEAbstarctElectrode$load_dim_with_blocks(blocks, type)

Arguments