---
title: "detect_all_events function: cgmguru and iglu-compatible event preprocessing"
output:
  rmarkdown::html_vignette:
    toc: true
    toc_depth: 2
vignette: >
  %\VignetteIndexEntry{detect_all_events function: cgmguru and iglu-compatible event preprocessing}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 7,
  fig.height = 4,
  message = FALSE,
  warning = FALSE
)

library(cgmguru)

# Availability flags used in chunk eval options
iglu_available <- requireNamespace("iglu", quietly = TRUE)
iglu_api_ok <- iglu_available
```

## Relationship to iglu

`cgmguru::detect_all_events()` is an independent C++/Rcpp implementation of
event calculation and CGM summary output. Its preprocessing is designed to be
compatible with the event grid semantics used by `iglu`: subject-specific
reading intervals, a midnight-aligned full-day grid, interpolation up to
`inter_gap`, removal of larger gap-masked rows, and segment-wise event
classification.

When `reading_minutes` is omitted or `NULL`, cgmguru calculates it
automatically per subject from the median positive timestamp spacing in the
input data.

The `iglu` package is used here as a formal reference, source of public example
datasets, and comparison target. cgmguru does not call `iglu` at runtime for its
core algorithms.

## Datasets

We use two CGM example datasets shipped with `iglu`:

- `example_data_5_subject`: 5 subjects
- `example_data_hall`: 19 subjects

```{r data-load, eval=iglu_available}
data(example_data_5_subject, package = "iglu")
data(example_data_hall, package = "iglu")

# Base-R summaries (no external dependencies)
summary_5 <- data.frame(
  rows = nrow(example_data_5_subject),
  subjects = length(unique(example_data_5_subject$id)),
  time_min = min(example_data_5_subject$time),
  time_max = max(example_data_5_subject$time),
  gl_min = min(example_data_5_subject$gl, na.rm = TRUE),
  gl_max = max(example_data_5_subject$gl, na.rm = TRUE)
)

summary_5
```

```{r data-load-missing, eval=!iglu_available}
cat("Note: The 'iglu' package is not available; vignette examples are skipped.\n")
```

## iglu: episode_calculation

`iglu::episode_calculation()` identifies hypo/hyperglycemia episodes.

```{r iglu-episodes-5, eval=iglu_available}
iglu_episodes_5 <- iglu::episode_calculation(
  data = example_data_5_subject
)
print(iglu_episodes_5)
```

```{r iglu-episodes-hall, eval=iglu_api_ok}
iglu_episodes_hall <- iglu::episode_calculation(
  data = example_data_hall
)
print(iglu_episodes_hall)
```

## cgmguru: detect_all_events

```{r cgmguru-all-5, eval=iglu_available}
all_events_5 <- detect_all_events(example_data_5_subject)
print(all_events_5)
```

```{r cgmguru-all-hall, eval=iglu_available}
all_events_hall <- detect_all_events(example_data_hall)
print(all_events_hall)
```

## Speed comparison

We compare performance using `microbenchmark` on both datasets. Each benchmark contrasts `iglu::episode_calculation()` with `cgmguru::detect_all_events()`.

```{r speed-microbenchmark, cache=FALSE, eval=iglu_available}
library(microbenchmark)
library(iglu)

# example_data_5_subject
bench_5 <- microbenchmark(
  episode_calculation = iglu::episode_calculation(example_data_5_subject),
  detect_all_events   = cgmguru::detect_all_events(example_data_5_subject),
  times = 10,
  unit = "ms"
)
print(bench_5)

# example_data_hall (all subjects)
bench_hall <- microbenchmark(
  episode_calculation = iglu::episode_calculation(example_data_hall),
  detect_all_events   = cgmguru::detect_all_events(example_data_hall),
  times = 10,
  unit = "ms"
)
print(bench_hall)
```

```{r iglu-api-mismatch, eval=iglu_available && !iglu_api_ok}
cat("Note: Installed 'iglu' version has a different 'episode_calculation' API; iglu examples are skipped.\n")
```

## References

- Broll S, Urbanek J, Buchanan D, Chun E, Muschelli J, Punjabi N, and Gaynanova I. Interpreting blood glucose data with R package iglu. *PLoS One*. 2021;16(4):e0248560. doi:10.1371/journal.pone.0248560.
- Chun E, Fernandes JN, and Gaynanova I. An Update on the iglu Software Package for Interpreting Continuous Glucose Monitoring Data. *Diabetes Technology & Therapeutics*. 2024;26(12):939-950. doi:10.1089/dia.2024.0154.
- iglu package site and citation guidance: <https://irinagain.github.io/iglu/> and <https://irinagain.github.io/iglu/authors.html>.