---
title: "Grouped Hyper Data Frame"
author: Tingting Zhan
date: today
format: 
  html:
    page-layout: full
    html-math-method: katex
    link-external-icon: true
    link-external-newwindow: true
number-sections: true
toc: true
toc-location: left
toc-depth: 4
toc-title: ''
editor: source
bibliography: groupedHyperframe.bib
knitr:
  opts_chunk: 
    collapse: true
    comment: "#" 
vignette: >
  %\VignetteIndexEntry{intro}
  %\VignetteEngine{quarto::html}
  %\VignetteEncoding{UTF-8}
---


The complete vignette of R package **`groupedHyperframe`** (v`r packageVersion('groupedHyperframe')`) 

> <https://rpubs.com/tingtingzhan/groupedHyperframe>

documents

-   the creation of *grouped hyper data frame*;
-   the creation of a grouped hyper data frame with one-and-only-one point-pattern hypercolumn;
-   the batch process on eligible marks for the one-and-only-one point-pattern hypercolumn in a (grouped) hyper data frame;
-   the computation of various summary statistics from one or more function-value-table hypercolumn(s) of a (grouped) hyper data frame;
-   the aggregation of summary statistics, over a (nested) grouping structure, in a grouped hyper data frame.

The complete vignette exceeds the file size limit allowed on [CRAN](https://cran.r-project.org/package=groupedHyperframe).  



# Prerequisite

## Environment

Package **`groupedHyperframe`** (v`r packageVersion('groupedHyperframe')`) requires R version 4.5.0 (released 2025-04-11) or higher ([macOS](https://cran.r-project.org/bin/macosx/), [Windows](https://cran.r-project.org/bin/windows/base/), [Linux](https://cran.r-project.org/bin/linux/)).

An Integrated Development Environment (IDE), e.g., [RStudio](https://posit.co/download/rstudio-desktop/) [@RStudio] or [Positron](https://positron.posit.co/download.html), is not required, but highly recommended.


```{r}
#| code-fold: true
#| code-summary: "Environment on author's computer"
#| label: author-env
Sys.info()[c('sysname', 'release', 'machine')]
R.version
```

## Enhancement & Dependency

Package **`groupedHyperframe`** (v`r packageVersion('groupedHyperframe')`) `Enhances` the **`spatstat.*`** family of packages [@spatstat15; @spatstat05], especially **`spatstat.geom`** and **`spatstat.explore`**. Details are provided in the [complete vignette](https://rpubs.com/tingtingzhan/groupedHyperframe), Section 4.1.


The dependencies of package **`groupedHyperframe`** are detailed in the [complete vignette](https://rpubs.com/tingtingzhan/groupedHyperframe), Section 4.1. 


Package **`groupedHyperframe`** requires the *development versions* of the **`spatstat.*`** family of packages. Installation instructions are provided in the [complete vignette](https://rpubs.com/tingtingzhan/groupedHyperframe), Section 4.1. 


## Installation

Package **`groupedHyperframe`** (v`r packageVersion('groupedHyperframe')`) can be installed using the following command.

```{r}
#| eval: false
utils::install.packages('groupedHyperframe')
```

# Getting Started

Examples in the [complete vignette](https://rpubs.com/tingtingzhan/groupedHyperframe) require that the `search` path has

```{r}
#| message: false
#| label: search
library(groupedHyperframe)
library(survival)
```

```{r}
#| echo: false
#| label: CRAN_cores
options(cores = 2L)
```

# Peer-Reviewed Publications

Package **`groupedHyperframe`** (v`r packageVersion('groupedHyperframe')`) plays a pivotal role in these peer reviewed publications from the authors.

## @Zhan25

```{r}
#| echo: false
Zhan25 = bibentry(
  bibtype = 'article',
  title = 'Quantile Index predictors using R package `hyper.gam`',
  author = c('Tingting Zhan', 'Misung Yi', 'Inna Chervoneva' ),
  journal = 'Bioinformatics',
  volume = {41}, number = {8}, pages = 'btaf430',
  year = '2025', month = '07',
  issn = '1367-4811',
  doi = '10.1093/bioinformatics/btaf430'
)
```


> `r Zhan25 |> format(style = 'text') |> gsub(pattern = '\n', replacement = ' ', x = _)`

<details>

<summary>[BibTeX](https://ctan.org/pkg/bibtex) and/or [BibLaTeX](https://ctan.org/pkg/biblatex) entries for [LaTeX](https://www.latex-project.org) users</summary>

```{r}
#| echo: false
#| comment: ''
c(
  Zhan25,
  citation(package = 'groupedHyperframe')
) |> toBibtex()
```

</details>

as well as @Yi25; @Yi23a; @Yi23b, was featured with a hyper data frame *`Ki67q`* with a numeric-hypercolumn *`logKi67.quantile`*. Functions in the R code-chunk below are explained in the [complete vignette](https://rpubs.com/tingtingzhan/groupedHyperframe).

```{r}
#| code-fold: true
#| code-summary: 'R code in @Zhan25'
Ki67q = groupedHyperframe::Ki67 |>
  within.data.frame(expr = {
    x = y = NULL # remove x- and y-coords for non-spacial application
  }) |>
  as.groupedHyperframe(group = ~ patientID/tissueID) |> 
  quantile(probs = seq.int(from = .01, to = .99, by = .01)) |> 
  aggregate(by = ~ patientID)
```

```{r}
#| message: false
#| code-fold: true
#| code-summary: 'A `hyperframe` object *`Ki67q`*: aggregated quantiles'
Ki67q |>
  head()
```

Readers are encouraged to learn more about this application from package **`hyper.gam`** [@hypergam, [CRAN](https://CRAN.R-project.org/package=hyper.gam), [Github](https://github.com/tingtingzhan/hyper.gam)] [vignette](https://rpubs.com/tingtingzhan/hyper_gam), section *Quantile Index*.



# Acknowledgement

This work is supported by National Institutes of Health, U.S. Department of Health and Human Services grants

-   R01CA222847 ([I. Chervoneva](https://orcid.org/0000-0002-9104-4505), [T. Zhan](https://orcid.org/0000-0001-9971-4844), and [H. Rui](https://orcid.org/0000-0002-8778-261X))
-   R01CA253977 (H. Rui and I. Chervoneva).




# References {.appendix}

::: {#refs}
:::