Type:	Package
Title:	Grouped Hyper Data Frame: An Extension of Hyper Data Frame
Version:	0.2.4
Description:	An S3 class 'groupedHyperframe' that inherits from hyper data frame. Batch processes on point-pattern hyper column. Aggregation of function-value-table hyper column(s) and numeric hyper column(s) over a nested grouping structure.
RoxygenNote:	7.3.2
LazyData:	true
LazyDataCompression:	xz
Encoding:	UTF-8
License:	GPL-2
Depends:	R (≥ 4.5)
Language:	en-US
Imports:	cli, parallel, matrixStats, pracma, spatstat.explore, spatstat.geom, SpatialPack
Suggests:	knitr, quarto, rmarkdown, survival, spatstat.data
VignetteBuilder:	quarto
NeedsCompilation:	no
Packaged:	2025-06-27 19:43:57 UTC; tingtingzhan
Author:	Tingting Zhan [aut, cre], Inna Chervoneva [aut]
Maintainer:	Tingting Zhan <tingtingzhan@gmail.com>
Repository:	CRAN
Date/Publication:	2025-06-27 20:10:10 UTC

groupedHyperframe: Grouped Hyper Data Frame: An Extension of Hyper Data Frame

Description

An S3 class 'groupedHyperframe' that inherits from hyper data frame. Batch processes on point-pattern hyper column. Aggregation of function-value-table hyper column(s) and numeric hyper column(s) over a nested grouping structure.

Note

Help files of individual functions are intentionally suppressed in the pdf manual. Users are encouraged to get started with the vignettes.

Author(s)

Maintainer: Tingting Zhan tingtingzhan@gmail.com (ORCID)

Authors:

• Inna Chervoneva Inna.Chervoneva@jefferson.edu (ORCID)

Syntactic Sugar for groupedHyperframe Object

Description

Syntactic Sugar for groupedHyperframe Object

Usage

## S3 replacement method for class 'groupedHyperframe'
x$name <- value

Arguments

Value

Syntactic sugar $<-.groupedHyperframe() returns a groupedHyperframe.

Note

Function $<-.hyperframe drops attributes.

Alternative Interface of nncross.ppp

Description

An alternative interface of function nncross.ppp.

Usage

.nncross(X, i, j, ...)

Arguments

Details

Function .nncross() creates an interface similar to functions Gcross, etc., which takes an is.multitype ppp.object and two mark values i and j, then calls the workhorse function nncross.ppp with parameter what = 'dist'. If mark values i and j does not exist in the ppp.object, a NULL value will be returned.

Value

Function .nncross() returns a numeric vector if i and j are valid mark values of ppp.object X; otherwise returns a NULL value.

Examples

library(spatstat.data)
library(spatstat.geom)

(xs = split.ppp(amacrine))
(a1 = nncross(X = xs$off, Y = xs$on, what = 'dist'))
a2 = .nncross(amacrine, i = 'off', j = 'on')
a3 = .nncross(amacrine, i = 1L, j = 2L)
stopifnot(identical(a1, a2), identical(a1, a3))

.nncross(amacrine, i = 'a', j = 'b') # exception handling

.slice

Description

.slice

Usage

.slice(x, j)

Arguments

Value

Function .slice() returns a vector

Ki67 Data

Description

Ki67 cell data containing 622 patients.

Usage

Ki67

Ki67.

Format

patientID

factor, unique patient identifier

tissueID

factor, TMA core identifier

recurrence

integer, recurrence indicator, 1 = Recurred, 0 = not Recurred

recfreesurv_mon

integer, recurrence-free survival time in months

logKi67

double, log-transformed cell signal intensity of the protein immunofloerscence signal

age

integer, age at diagnosis

Tstage

integer, tumor stage

node

factor, node stage

HR

logical, hormone positive status

histology

integer, histology grade

Her2

logical, Her2 status

race

character, race, White, Black, Asian, Native Hawaiian or Other Pacific Islander, American Indian or Alaska Native, Unknown

adj_chemo

logical, whether completed adjuvant chemo treatment

adj_rad

integer, adjuvant radiation treatment, 0 = unknown, 1 = done, 2 = NOT done

An object of class data.frame with 4088 rows and 15 columns.

Details

The groupedHyperframe Ki67 is the complete data, to be used in examples of downstream packages maxEff and hyper.gam.

The data.frame Ki67. is a subset of the complete data Ki67, which consists only the first 6 patients. This small data is used as examples for function as.groupedHyperframe.data.frame().

Extract Subset of groupedHyperframe

Description

Extract Subset of groupedHyperframe

Usage

## S3 method for class 'groupedHyperframe'
x[...]

Arguments

Value

Function [.groupedHyperframe returns a groupedHyperframe or a hyperframe.

Aggregate-By, for groupedHyperframe

Description

Aggregate-By, for groupedHyperframe

Usage

aggregate_by_(dots, X, by, f_aggr_ = pmean, ...)

Arguments

Details

Function aggregate_by_() checks by against attr(X,'group').

Value

Function aggregate_by_() returns a listof numeric matrixes.

Aggregate fv.objects by Cluster

Description

Aggregate information in fv.objects by sample clustering.

Usage

aggregate_fv(
  X,
  by = stop("must specify `by`"),
  f_aggr_ = pmean,
  mc.cores = getOption("mc.cores"),
  ...
)

Arguments

Value

Function aggregate_fv() returns a data.frame, with aggregated information stored in matrix-columns.

Note that hyperframe does not support matrix-column (for good reasons!). Therefore, function aggregate_fv() must return a data.frame, instead of a hyperframe.

Examples

library(spatstat.data)
library(spatstat.geom)
flu$pattern[] = flu$pattern |> 
 lapply(FUN = `mark_name<-`, value = 'stain') # read ?flu carefully
r = seq.int(from = 0, to = 100, by = 5)
flu |>
 subset(stain == 'M2-M1') |>
 as.groupedHyperframe(group = ~ virustype/frameid) |>
 Gcross_(i = 'M1', j = 'M2', r = r, correction = 'best') |>
 aggregate_fv(by = ~ virustype)

Aggregate numeric hypercolumns and/or marks, by Cluster

Description

Aggregate numeric hypercolumns and/or marks by sample clustering.

Usage

aggregate_num(
  X,
  by = stop("must specify `by`"),
  FUN,
  FUN.name = deparse1(substitute(FUN)),
  f_aggr_ = pmean,
  mc.cores = getOption("mc.cores"),
  ...
)

aggregate_quantile(X, ...)

aggregate_kerndens(X, ...)

Arguments

Details

Function aggregate_quantile() is a wrapper of workhorse function aggregate_num() with FUN = quantile.

Function aggregate_kerndens() is a wrapper of workhorse function aggregate_num() with FUN = kerndens.

Value

Function aggregate_num() returns a data.frame, with aggregated information stored in matrix-columns.

Creation of groupedHyperframe

Description

To create a groupedHyperframe object

Usage

as.groupedHyperframe(x, group, ...)

## S3 method for class 'hyperframe'
as.groupedHyperframe(x, group, ...)

## S3 method for class 'data.frame'
as.groupedHyperframe(x, group, ...)

Arguments

Value

Function as.groupedHyperframe() returns a groupedHyperframe.

Convert pairwise_cor_spatial to matrix

Description

Convert pairwise_cor_spatial to matrix

Usage

## S3 method for class 'pairwise_cor_spatial'
as.matrix(x, ...)

Arguments

Value

Function as.matrix.pairwise_cor_spatial() returns a matrix.

check_fvlist

Description

check_fvlist

Usage

check_fvlist(X)

Arguments

Details

Function check_fvlist() checks that

• if x-axis of all fv.objects are all same

• attr(,'fname') of all fv.objects are all same

Note that

• function key1.fv() returns of all fv.objects are not required to be all same

Value

Function check_fvlist() does not have a returned value.

groupedHyperframe with One-and-Only-One ppp-hypercolumn

Description

..

Usage

grouped_ppp(
  formula,
  data,
  coords = ~x + y,
  window = owin(xrange = range(.x), yrange = range(.y)),
  ...
)

Arguments

Value

Function grouped_ppp() returns a groupedHyperframe with one-and-only-one ppp-hypercolumn.

Kernel Density via density.default

Description

Kernel density estimates only.

Usage

kerndens(...)

Arguments

Details

Function kerndens() finds the estimated density values, i.e., element ⁠$y⁠ of function density.default return.

Value

Function kerndens() returns a numeric vector.

Examples

d = density(faithful$eruptions, bw = 'sj')
stopifnot(identical(d$y, kerndens(faithful$eruptions, bw = 'sj')))

Black-Solid-Curve in plot.fv

Description

Name and value of the black solid curve as shown in plot.fv, i.e., the primary outcome of an fv.object.

Usage

key1.fv(x)

key1val.fv(x)

trapz.fv(x)

cumtrapz.fv(x)

## S3 method for class 'fv'
is.finite(x)

Arguments

Details

Function key1.fv() finds the name of the primary outcome of an fv.object.

Function key1val.fv() finds the value of the primary outcome of an fv.object.

Functions trapz.fv() and cumtrapz.fv() obtain the (cumulative) trapzoidal integration of the area under the primary outcome of a function value fv.object.

Function is.finite.fv() (dispatch of S3 generic is.finite) finds the finite, i.e., non-NA, non-NaN and non-Inf, indices of the primary outcome of an fv.object.

Value

Function key1.fv() returns a character scalar.

Function key1val.fv() returns a numeric vector.

Function trapz.fv() returns a numeric scalar.

Function cumtrapz.fv() returns a numeric vector.

Function is.finite.fv() returns a logical vector.

Examples

library(spatstat.data)
library(spatstat.geom) # ?spatstat.geom::subset.ppp
library(spatstat.explore)

foo = function(x) {
 x |> plot()
 'Trapzoid\n' |> cat()
 x |> trapz.fv() |> print()
 '\nCumulative Trapzoid\n' |> cat()
 x |> cumtrapz.fv() |> tail() |> print()
}

# numeric mark
spruces |> Emark() |> foo()
spruces |> Vmark() |> foo()
spruces |> markcorr() |> foo()
spruces |> markvario() |> foo()

# multitype mark
(btc = subset.ppp(betacells, select = 'type'))
btc |> Gcross(i = 'off', j = 'on') |> foo()
btc |> Kcross(i = 'off', j = 'on') |> foo()
btc |> Lcross(i = 'off', j = 'on') |> foo()
btc |> Jcross(i = 'off', j = 'on') |> foo()
btc |> markconnect(i = 'off', j = 'on') |> foo()

# swedishpines |> roc.ppp(covariate = 'x') |> foo() 
# bug in devtools::check()

Extension of kmeans

Description

Extension of kmeans

Usage

.kmeans(x, formula, ...)

## S3 method for class 'ppp'
.kmeans(
  x,
  formula,
  centers = as.integer(ceiling((x[["n"]]/clusterSize))),
  clusterSize,
  ...
)

Arguments

Value

Function .kmeans() returns a kmeans object.

log.ppp

Description

...

Usage

## S3 method for class 'ppp'
log(x, base = exp(1))

## S3 method for class 'ppp'
log1p(x)

Arguments

Details

Function log.ppp() takes a log of continuous marks of a ppp.object.

Value

Function log.ppp() returns a ppp.object.

Examples

data(longleaf, package = 'spatstat.data')
longleaf |> plot()
longleaf |> log() |> plot()

Mark Names

Description

Get the names of marks. Assign a name to marks, when markformat is 'vector'.

Usage

mark_names(x)

mark_name(x) <- value

Arguments

Details

Syntactic sugar mark_name<-() converts a ppp.object of 'vector' markformat into 'dataframe' markformat, and name this ncol-1L data.frame marks by value.

Value

Function mark_names() returns the names of the marks of a ppp.object, when its markformat is 'dataframe'. Otherwise, an error is returned.

Syntactic sugar mark_name<-() returns a ppp.object of 'dataframe' markformat.

Examples

library(spatstat.data)
mark_names(betacells)
# ?waka
tryCatch(mark_names(waka), error = identity)
waka2 = waka
mark_name(waka2) = 'dbh' # tree diameter at breast height `dbh`
mark_names(waka2)
unstack(waka) # no name
unstack(waka2) # has name

Check if Data Column is Identical by Grouping

Description

Check if Data Column is Identical by Grouping

Usage

mc_identical_by(data, f, mc.cores = getOption("mc.cores"), ...)

Arguments

Note

Function aggregate.data.frame does not do parallel computing.

Function collapse::collap does not support Surv column.

Handle Missing marks in ppp.object.

Description

Handle Missing marks in ppp.object.

Usage

## S3 method for class 'ppp'
na.omit(object, ...)

Arguments

Details

Function na.omit.ppp() omits missing marks in a ppp.object.

Value

Function na.omit.ppp() returns a ppp.object.

Note

tzh suppose missing ⁠$x⁠ and ⁠$y⁠ are forbidden in ppp.object anyway.

Examples

library(spatstat.data)
library(spatstat.geom)

npoints(nbfires)
npoints(na.omit.ppp(nbfires))

npoints(amacrine)
npoints(na.omit.ppp(amacrine)) # no missing marks to be removed

nbfires_julian = unstack.ppp(nbfires)$out.julian
suppressWarnings(print.ppp(nbfires_julian))
suppressWarnings(plot.ppp(nbfires_julian))
na.omit.ppp(nbfires_julian)

Operations on hyperframe with One-and-Only-One ppp-hypercolumn

Description

Create hypercolumn(s) of fv.objects or distances from the one-and-only-one ppp-hypercolumn inside a hyperframe.

Usage

op_hyperframe(X, op, ...)

Arguments

Value

Function op_hyperframe() returns a hyperframe with additional

• fv.object hypercolumns if op = fv_ppp. One hypercolumn per numeric mark in the ppp-hypercolumn.

• numeric hypercolumns if op = dist_ppp. One hypercolumn per is.multitype mark in the ppp-hypercolumn.

Operations on ppp.object

Description

Create fv.objects or distances from a ppp.object.

Usage

dist_ppp(x, fn, ...)

fv_ppp(x, fn, ...)

Arguments

Details

First, the input ppp.object is unstack.ppp-ed.

Each of the numeric marks could be analyzed by following functions that return an fv.object,

• Emark

• Vmark

• markcorr

• markvario

If one of the functions above are provided but there is no numeric marks in the input, a NULL value will be returned.

Each of the marks that is.multitype could be analyzed by following functions that return an fv.object,

• Gcross

• Jcross

• Kcross

• Lcross

• markconnect

or by following functions that return a distance,

• .nncross()

If one of the functions above are provided but there is no marks is.multitype in the input, a NULL value will be returned.

Value

Function fv_ppp() returns a listof fv.objects, one per each eligible marks.

Function dist_ppp() returns a listof double vectors, one per each eligible marks.

Examples

library(spatstat.data)
library(spatstat.explore)

fv_ppp(betacells, fn = Emark) # applicable to numeric mark
fv_ppp(betacells, fn = Kmark) # applicable to numeric mark
fv_ppp(betacells, fn = Gcross, i = 'off', j = 'on') # applicable to multitype mark

dist_ppp(betacells, fn = .nncross, i = 'off', j = 'on')
dist_ppp(gorillas, fn = .nncross, i = 'major', j = 'minor')
dist_ppp(gorillas, fn = .nncross, i = 'rainy', j = 'dry')

Batch Operations of 'ppplist' Object

Description

Batch operations of function fv_ppp() or dist_ppp(), for a 'ppplist' input.

Usage

op_ppplist(x, op, mc.cores = getOption("mc.cores"), ...)

Arguments

Details

Function op_ppplist() is a parallel batch process of the workhorse function fv_ppp() or dist_ppp().

Value

Function op_ppplist() returns a listof

• function fv_ppp() returns, if op = fv_ppp.

• function dist_ppp() returns, if op = dist_ppp.

Examples

library(spatstat.data)
library(spatstat.geom) # for ?spatstat.geom::split.ppp
library(spatstat.explore) # for ?spatstat.explore::Emark, etc.

Vc = with(shapley$marks, expr = {
 cut.default(V, breaks = quantile(V, probs = c(0, 1/3, 2/3, 1)), labels = c('L', 'M', 'H'))
})

x1 = shapley |> 
 subset.ppp(select = c('Mag', 'SigV')) |>
 split.ppp(f = Vc) |>
 op_ppplist(op = fv_ppp, fn = markcorr)
names(x1)
names(x1$L)


x2 = nbfires |> 
  subset.ppp(select = c('fire.type', 'cause', 'ign.src')) |>
  na.omit.ppp() |> 
  split.ppp(f = 'fire.type')
x2 |> op_ppplist(op = dist_ppp, fn = .nncross, i = 'rrds', j = 'ltning')
x2 |> op_ppplist(op = dist_ppp, fn = .nncross, i = 'unknown', j = 'burn.no.perm')

Pairwise Tjostheim's Coefficient

Description

Pairwise Tjostheim's Coefficient

Usage

pairwise_cor_spatial(x, ...)

## S3 method for class 'ppp'
pairwise_cor_spatial(x, ...)

## S3 method for class 'ppplist'
pairwise_cor_spatial(x, ...)

Arguments

Details

Workhorse function cor.spatial.

Value

Function pairwise_cor_spatial() returns a dist object.

Examples

data(finpines, package = 'spatstat.data')
(r = finpines |> pairwise_cor_spatial.ppp())
r |> as.matrix()

Parallel mean and median

Description

Parallel mean and median

Usage

pmean(..., na.rm = TRUE)

pmedian(..., na.rm = TRUE)

Arguments

Value

Functions pmean() and pmedian() return a numeric vector.

Note

Functions pmean() and pmedian() mimic functions pmax.int and pmin.int. They are written in a very naive way. The pipeline cbind() |> rowMeans() is extremely slow.

Examples

pmean(1:3, 11:13, 21:23)

Print groupedHyperframe

Description

Print groupedHyperframe

Usage

## S3 method for class 'groupedHyperframe'
print(x, ...)

Arguments

Value

Function print.groupedHyperframe() does not have a returned value.

split by kmeans Clustering

Description

split by kmeans clustering

Usage

split_kmeans(x, ...)

## Default S3 method:
split_kmeans(x, ...)

## S3 method for class 'listof'
split_kmeans(x, ...)

## S3 method for class 'hyperframe'
split_kmeans(x, ...)

Arguments

Note

Function split_kmeans.default() is supposed to work with ppp.object.

User Interface of Operations on hyperframe with One-and-Only-One ppp-hypercolumn

Description

See workhorse function op_hyperframe().

Usage

Emark_(X, correction = "none", ...)

Vmark_(X, correction = "none", ...)

Kmark_(X, correction = "none", ...)

markcorr_(X, correction = "none", ...)

markvario_(X, correction = "none", ...)

Gcross_(X, correction = "none", ...)

Jcross_(X, correction = "none", ...)

Kcross_(X, correction = "none", ...)

Lcross_(X, correction = "none", ...)

nncross_(X, ...)

Arguments

Details

See explanations in workhorse function op_hyperframe().

Value

See explanations in workhorse function op_hyperframe().

Examples

library(spatstat.data)
library(spatstat.geom)
# no good example for [Emark_.hyperframe]
# no hyperframe with ppp-hypercolumn with numeric marks

flu$pattern[] = flu$pattern |> 
 lapply(FUN = `mark_name<-`, value = 'stain') # read ?flu carefully
 
r = seq.int(from = 0, to = 100, by = 5)
flu |>
 subset(stain == 'M2-M1') |>
 Gcross_(i = 'M1', j = 'M2', r = r, correction = 'best', mc.cores = 1L)
 
flu |>
 subset(stain == 'M2-M1') |>
 nncross_(i = 'M1', j = 'M2', mc.cores = 1L)

wrobel_lung

Description

From Dr. Julia Wrobel's data https://sph.emory.edu/profile/faculty/julia-wrobel.

Usage

wrobel_lung

Format

A data.frame