Title:	Compute Neural Fragility for Ictal iEEG Time Series
Version:	2.0.1
Description:	Provides tools to compute the neural fragility matrix from intracranial electrocorticographic (iEEG) recordings, enabling the analysis of brain dynamics during seizures. The package implements the method described by Li et al. (2017) <doi:10.23919/ACC.2017.7963378> and includes functions for data preprocessing ('Epoch'), fragility computation ('calcAdjFrag'), and visualization.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.2
Depends:	R (≥ 4.1.0), Epoch
LazyData:	true
Imports:	stats, methods, ggplot2 (≥ 3.4.0), viridis, ggtext, glue, rlang, foreach, progress, ramify, reshape2
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0), doSNOW, gsignal
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://github.com/Jiefei-Wang/EZFragility
NeedsCompilation:	no
Packaged:	2025-09-07 18:57:44 UTC; wangj
Author:	Jiefei Wang [aut, cre], Patrick Karas [aut], Anne-Cecile Lesage [aut], Ioannis Malagaris [aut], Oliver Zhou [aut], Liliana Camarillo Rodriguez [aut], Sean O'Leary [aut], Yuanyi Zhang [aut]
Maintainer:	Jiefei Wang <szwjf08@gmail.com>
Repository:	CRAN
Date/Publication:	2025-09-07 23:30:21 UTC

Getters and Setters for S4 object

Description

Getters and Setters for S4 object

Usage

## S4 method for signature 'FragStat'
x$name

## S4 replacement method for signature 'FragStat'
x$name <- value

## S4 method for signature 'Fragility'
x$name

## S4 replacement method for signature 'Fragility'
x$name <- value

Arguments

Value

S4 object itself or slot value

Subset a Fragility object

Description

Subset a Fragility object

Usage

## S4 method for signature 'Fragility'
x[i, j, ..., drop = FALSE]

Arguments

Value

A new Fragility object with the subsetted data

Calculate adjacency matrices and fragility matrix from iEEG recording

Description

The function calculates the neural fragility column from an adjacency matrix in each time window

Usage

calcAdjFrag(
  epoch,
  window,
  step,
  lambda = NULL,
  nSearch = 100L,
  progress = FALSE,
  parallel = FALSE
)

Arguments

Details

1/ For each time window i, a discrete stable Linear time system (adjacency matrix) is computed named A_i such that A_i x(t) = x(t+1). The 'lambda' option is the regularization parameter for the ridge regression. lambda=NULL(default) will find a lambda value that ensures the stability of the estimated A_i.

2/For each stable estimated A_i, the minimum norm perturbation \Gamma_{ik} (k index of the electrodes) for column perturbation is computed. Each column is normalized \frac{max(\Gamma_{i})-\Gamma_{ik}}{max(\Gamma_i)}

Value

A Fragility object

Source

Recreation of the method described in Li A, Huynh C, Fitzgerald Z, Cajigas I, Brusko D, Jagid J, et al. Neural fragility as an EEG marker of the seizure onset zone. Nat Neurosci. 2021 Oct;24(10):1465–74 (pubmed). We have found solutions to fill up missing details in the paper method description

Examples

## A dummy example with 5 electrodes and 20 time points
data <- matrix(rnorm(100), nrow = 5)
## create an Epoch object
epoch <- Epoch(data, startTime = 0, samplingRate = 1)
windowNum <- 10
step <- 5
lambda <- 0.1
calcAdjFrag(
    epoch = epoch, window = windowNum,
    step = step, lambda = lambda, progress = TRUE
)

## A more realistic example with parallel computing

if (requireNamespace("doSNOW")) {
    ## Register a SNOW backend with 4 workers
    library(parallel)
    library(doSNOW)
    cl <- makeCluster(4, type = "SOCK")
    registerDoSNOW(cl)

    data("pt01EcoG")
    window <- 250
    step <- 125
    title <- "PT01 seizure 1"
    calcAdjFrag(
        epoch = pt01EcoG, window = window,
        step = step, parallel = TRUE, progress = TRUE
    )

    ## stop the parallel backend
    stopCluster(cl)
}

Check and keep valid index only

Description

Check and keep valid index only

Usage

checkIndex(indices, names)

Arguments

Find Seizure Onset Zone

Description

The function estimates the seizure onset zone (SOZ). For each row, it calculates the maximum, minimum, or mean of row. The rows with the highest values are considered as the SOZ.

Usage

estimateSOZ(
  x,
  method = c("mean", "median", "max", "min"),
  proportion = 0.1,
  ...
)

Arguments

Value

A vector of electrode names, or indices if the electrode names are NULL

Compute quantiles, mean and standard deviation for two electrodes groups

Description

Compute quantiles, mean and standard deviation for two electrodes groups

Usage

fragStat(frag, groupIndex = NULL, groupName = "SOZ", ranked = FALSE)

Arguments

Value

list of 5 items with quantile matrix, mean and sdv from both electrodes groups

Examples

data("pt01Frag")
data("pt01EcoG")    
## sozNames is the name of the electrodes we assume are in the SOZ
sozNames <- metaData(pt01EcoG)$sozNames
pt01fragstat <- fragStat(frag = pt01Frag, groupIndex = sozNames)

Compute the normalized fragility row for adjacency matrix A

Description

The matrix A is used for the regression: A * x(t) = x(t+1)

Usage

fragilityRow(A, nSearch = 100, normalize = TRUE)

Arguments

Get the number of rows or columns of a Fragility object

Description

Get the number of rows or columns of a Fragility object

Usage

## S4 method for signature 'Fragility'
nrow(x)

## S4 method for signature 'Fragility'
ncol(x)

Arguments

Value

• nrow(x): The number of rows (electrodes) in the fragility matrix.

• ncol(x): The number of columns (time points) in the fragility matrix.

• dim(x): A vector of length 2 containing the number of rows and columns in the fragility matrix.

Visualization functions (raw signal, fragility matrix)

Description

plotFragHeatmap: plot fragility heatmaps with electrodes marked as soz colored

plotFragQuantile: Plot Fragility time quantiles for two electrodes groups

plotFragQuantile: Plot Fragility time distribution for two electrodes groups

Usage

plotFragHeatmap(
  frag,
  groupIndex = NULL,
  maxLabels = 50,
  ranked = FALSE,
  x.lab.size = 4,
  y.lab.size = 10
)

plotFragQuantile(frag, groupIndex = NULL, groupName = "SOZ")

plotFragDistribution(
  frag,
  groupIndex = NULL,
  groupName = "SOZ",
  bandType = c("SEM", "SD"),
  rollingWindow = 1,
  ranked = FALSE
)

Arguments

Value

A ggplot object

Examples

data("pt01EcoG")

## sozNames is the name of the electrodes we assume are in the SOZ
sozNames <- metaData(pt01EcoG)$sozNames

## precomputed fragility object
data("pt01Frag")

## plot the fragility heatmap
plotFragHeatmap(frag = pt01Frag, groupIndex = sozNames)

## plot the fragility quantiles
plotFragQuantile(frag = pt01Frag, groupIndex = sozNames)

## plot the fragility distribution
plotFragDistribution(frag = pt01Frag, groupIndex = sozNames)

## plot with smoothing
plotFragDistribution(frag = pt01Frag, groupIndex = sozNames, rollingWindow = 2)

Pt01 seizure 1 around seizure onset

Description

This data corresponds to the first seizure of patient from the Fragility Data Set. EcoG recording gathered in collaboration with the National Institute of Health. The data contains only the good channels. It has been notch filtered and common average referenced in RAVE. The time range for full data is (-10:10s). Due to the size limit of the package, The full data has been epoched -1:2s around the seizure onset. The acquisition frequency is 1000 Hz

Usage

## EEG data
data(pt01EcoG)

Format

pt01EcoG: A Matrix with 84 rows (electrodes) and 3000 columns (time points)

pt01Frag: A fragility object results of applying the main function calcAdjFrag to pt01EcoG with window = 250 and step = 125

Source

Fragility Multi-Center Retrospective Study (OpenNeuro)

fit a generalized linear model to compute adjacency matrix A

Description

A x(t) = x(t+1)

Usage

ridge(xt, xtp1, lambda)

Arguments

Value

adjacency matrix A

computes R2

Description

computes R2

Usage

ridgeR2(xt, xtp1, A)

Arguments

Ridge Regression for Electrode Readings

Description

Ridge regression to compute matrix adjancency matrix A such as A xt = xtpt1 the lambda parmeter is found by dichotomy such that A is stable (all eigenvalues have a norm less than one)

Usage

ridgeSearch(xt, xtp1, lambda = NULL)

Arguments

Value

adjacency matrix Afin with lambda as attribute

Print the FragStat object

Description

Print the FragStat object

Usage

## S4 method for signature 'FragStat'
show(object)

Arguments

Value

the object itself

Print the Fragility object

Description

Print the Fragility object

Usage

## S4 method for signature 'Fragility'
show(object)

Arguments

Value

the object itself