Package {GLBFP}

GLBFP: General Linear Blend Frequency Polygon Density Estimation

Description

GLBFP provides one-point and grid-based density estimators based on ASH, LBFP and GLBFP methodology, with sparse-prefix computation, visualization helpers and bandwidth selection utilities.

Details

Main entry points:

• ASH(), LBFP(), GLBFP()

• ASH_estimate(), LBFP_estimate(), GLBFP_estimate()

• compute_bi_optim()

Lowercase aliases such as glbfp() and glbfp_estimate() are also provided for users who prefer lower-snake-case function names.

Author(s)

Maintainer: Aurélien Nicosia aurelien.nicosia@mat.ulaval.ca

See Also

Useful links:

• https://aureliennicosiaulaval.github.io/GLBFP/

• https://github.com/AurelienNicosiaULaval/GLBFP

• Report bugs at https://github.com/AurelienNicosiaULaval/GLBFP/issues

Averaged Shifted Histogram (ASH) estimator at a single point

Description

Computes the ASH density estimate at point x.

Usage

ASH(
  x,
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  m = rep(1, ncol(data)),
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

Arguments

Details

m controls the number of shifted histograms used in each dimension. Missing and non-finite values are not accepted; remove or impute them before calling the estimator.

Value

A list with class c("glbfp_fit", "ASH") containing: x, estimation, b, m, method, and dimension.

Methods (by generic)

• print(ASH): Print method for object of class "ASH".

References

Scott, D. W. (1992). Multivariate Density Estimation: Theory, Practice, and Visualization. Wiley. doi:10.1002/9780470316849.

See Also

ASH_estimate(), LBFP(), GLBFP(), compute_bi_optim()

Examples

x <- c(200, 30)
b <- c(0.5, 0.5)
m <- c(1, 1)
ASH(x, ashua[, -3], b = b, m = m)

ASH density estimation on a grid

Description

Computes ASH density estimates on a regular or user-supplied grid.

Usage

ASH_estimate(
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  m = rep(1, ncol(data)),
  grid_size = 20,
  grid_points = NULL,
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

## S3 method for class 'ASH_estimate'
plot(x, contour = FALSE, ...)

Arguments

Details

When grid_points is NULL, a regular grid is constructed from min_vals to max_vals. Custom grids may be irregular; in that case plotting uses point or scatter representations instead of a surface.

Value

A list with class c("glbfp_grid", "ASH_estimate") containing grid coordinates, densities, and grid metadata.

Methods (by generic)

• print(ASH_estimate): Print method for object of class "ASH_estimate".

• plot(ASH_estimate): Plot method for object of class "ASH_estimate".

See Also

ASH(), LBFP_estimate(), GLBFP_estimate()

Examples

b <- c(0.5, 0.5)
# Use a small, representative subset so examples remain fast in checks.
sample_data <- as.matrix(ashua[seq_len(120), -3])
out <- ASH_estimate(sample_data, b = b, m = c(1, 1), grid_size = 10)
out

General Linear Blend Frequency Polygon (GLBFP) estimator at a single point

Description

Computes the GLBFP density estimate at point x.

Usage

GLBFP(
  x,
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  m = rep(1, ncol(data)),
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

Arguments

Details

GLBFP() generalizes the linear blend frequency polygon workflow through the positive integer shift vector m. Missing and non-finite values are not accepted; remove or impute them before calling the estimator.

Value

A list with class c("glbfp_fit", "GLBFP") containing: x, estimation, sd, IC, b, m, method, and dimension.

Methods (by generic)

• print(GLBFP): Print method for object of class "GLBFP".

References

Scott, D. W. (1992). Multivariate Density Estimation: Theory, Practice, and Visualization. Wiley. doi:10.1002/9780470316849.

The complete methodological citation for GLBFP has not yet been verified in this repository. Add it before using this help page as publication text.

See Also

GLBFP_estimate(), ASH(), LBFP(), compute_bi_optim()

Examples

x <- c(200, 30)
b <- c(0.5, 0.5)
m <- c(1, 1)
GLBFP(x, ashua[, -3], b = b, m = m)

GLBFP density estimation on a grid

Description

Computes GLBFP density estimates on a regular or user-supplied grid.

Usage

GLBFP_estimate(
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  m = rep(1, ncol(data)),
  grid_size = 20,
  grid_points = NULL,
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

## S3 method for class 'GLBFP_estimate'
plot(x, contour = FALSE, ...)

Arguments

Details

When grid_points is NULL, a regular grid is constructed from min_vals to max_vals. Custom grids may be irregular; in that case plotting uses point or scatter representations instead of a surface.

Value

A list with class c("glbfp_grid", "GLBFP_estimate") containing grid coordinates, densities, uncertainty estimates, and grid metadata.

Methods (by generic)

• print(GLBFP_estimate): Print method for object of class "GLBFP_estimate".

• plot(GLBFP_estimate): Plot method for object of class "GLBFP_estimate".

See Also

GLBFP(), ASH_estimate(), LBFP_estimate()

Examples

b <- c(0.5, 0.5)
# Use a small, representative subset so examples remain fast in checks.
sample_data <- as.matrix(ashua[seq_len(120), -3])
out <- GLBFP_estimate(sample_data, b = b, m = c(1, 1), grid_size = 10)
out

Compute the G(m_i) bandwidth constant

Description

Computes the scalar constant G(m_i) used by compute_bi_optim().

Usage

G_i(mi)

Arguments

Details

The implemented formula is

G(m_i) = \frac{1}{12}\left(1 + \frac{1}{2m_i^2}\right).

Value

A positive numeric scalar.

See Also

compute_bi_optim(), K_mi(), compute_G_star()

Examples

G_i(1)
G_i(2)

Compute the K(m_i) bandwidth constant

Description

Computes the scalar constant K(m_i) used by compute_bi_optim().

Usage

K_mi(mi)

Arguments

Details

The implemented formula is

K(m_i) = \sqrt{\frac{1}{6} + \frac{1}{12m_i^2}} + \frac{4m_i^2 - 1}{6\sqrt{2}m_i} \log\left( \frac{\sqrt{3} + \sqrt{4m_i^2 + 2}}{\sqrt{4m_i^2 - 1}} \right).

Value

A positive numeric scalar.

See Also

compute_bi_optim(), G_i(), compute_G_star()

Examples

K_mi(1)
K_mi(2)

Linear Blend Frequency Polygon (LBFP) estimator at a single point

Description

Computes the LBFP density estimate at point x.

Usage

LBFP(
  x,
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

Arguments

Details

The estimate is obtained by linear blending of neighboring histogram bin heights. Missing and non-finite values are not accepted; remove or impute them before calling the estimator.

Value

A list with class c("glbfp_fit", "LBFP") containing: x, estimation, sd, IC, b, method, and dimension.

Methods (by generic)

• print(LBFP): Print method for object of class "LBFP".

References

Scott, D. W. (1992). Multivariate Density Estimation: Theory, Practice, and Visualization. Wiley. doi:10.1002/9780470316849.

Terrell, G. R., and Scott, D. W. (1985). Oversmoothed Nonparametric Density Estimates. Journal of the American Statistical Association, 80(389), 209-214. doi:10.1080/01621459.1985.10477163.

See Also

LBFP_estimate(), ASH(), GLBFP(), compute_bi_optim()

Examples

x <- c(200, 30)
b <- c(0.5, 0.5)
LBFP(x, ashua[, -3], b = b)

LBFP density estimation on a grid

Description

Computes LBFP density estimates on a regular or user-supplied grid.

Usage

LBFP_estimate(
  data,
  b = compute_bi_optim(data, m = rep(1, ncol(data))),
  grid_size = 20,
  grid_points = NULL,
  min_vals = apply(data, 2, min),
  max_vals = apply(data, 2, max)
)

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

## S3 method for class 'LBFP_estimate'
plot(x, contour = FALSE, ...)

Arguments

Details

When grid_points is NULL, a regular grid is constructed from min_vals to max_vals. Custom grids may be irregular; in that case plotting uses point or scatter representations instead of a surface.

Value

A list with class c("glbfp_grid", "LBFP_estimate") containing grid coordinates, densities, uncertainty estimates, and grid metadata.

Methods (by generic)

• print(LBFP_estimate): Print method for object of class "LBFP_estimate".

• plot(LBFP_estimate): Plot method for object of class "LBFP_estimate".

See Also

LBFP(), ASH_estimate(), GLBFP_estimate()

Examples

b <- c(0.5, 0.5)
out <- LBFP_estimate(ashua[, -3], b = b, grid_size = 15)
out
plot(out, contour = TRUE)

Convert GLBFP objects to data frames

Description

Convert GLBFP objects to data frames

Usage

## S3 method for class 'glbfp_grid'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame representation of the object.

River Ashuapmushuan daily flow and level data

Description

Daily observations of river flow and level for the Ashuapmushuan river.

Usage

ashua

Format

A data frame with 4,389 rows and 3 variables:

flow

Flow rate in cubic meters per second.

level

Water level in meters.

day

Day code as integer in YYYYDDD format.

Details

Data cover 22 March 1992 to 30 September 2007 with a small number of missing calendar days.

Source

Environment and Climate Change Canada, Historical Hydrometric Data. The exact extraction query still needs to be documented in ⁠data-raw/⁠.

Examples

data(ashua)
summary(ashua)

Compute the G^* bandwidth constant

Description

Computes the dimension-dependent constant G^* used by compute_bi_optim().

Usage

compute_G_star(d)

Arguments

Details

The implemented formula is

G^* = 2^{\frac{3(d - 4)}{2(4 + d)}} \exp\left(\frac{1}{4 + d}\right) \frac{\pi^{d / 2}}{4 + d}.

Value

A positive numeric scalar.

See Also

compute_bi_optim(), G_i(), K_mi()

Examples

compute_G_star(1)
compute_G_star(2)

Compute bandwidth vector b_i

Description

Computes a plug-in bandwidth vector used by GLBFP/LBFP/ASH estimators. The function validates numeric inputs, stabilizes near-singular covariance matrices with a small ridge if needed, and returns strictly positive bandwidths.

Usage

compute_bi_optim(data, m = rep(1, ncol(data)))

Arguments

Details

The returned vector is intended as a starting value for examples and routine workflows. For applied analysis, sensitivity to the bandwidth should still be checked.

The plug-in expression follows the optimal cell-width calculation for multivariate frequency polygons in Carbon and Duchesne (2024).

Near-singular covariance matrices are stabilized with a small ridge term. If this fails, the function returns an error rather than silently producing non-finite bandwidths.

Value

A numeric vector of positive bandwidths with one value per column in data.

References

Carbon, M. and Duchesne, T. (2024). Multivariate frequency polygon for stationary random fields. Annals of the Institute of Statistical Mathematics, 76(2), 263-287. doi:10.1007/s10463-023-00883-5.

See Also

ASH(), LBFP(), GLBFP()

Examples

set.seed(1)
x <- cbind(rnorm(200), rnorm(200))
compute_bi_optim(x, m = c(1, 1))

Lowercase aliases for the public API

Description

These aliases follow common R naming style while preserving the original uppercase function names used in earlier versions of the package.

Usage

ash(...)

lbfp(...)

glbfp(...)

ash_estimate(...)

lbfp_estimate(...)

glbfp_estimate(...)

Arguments

Value

The same object returned by the corresponding uppercase function.

Predict from GLBFP fit objects

Description

Prediction helper for fitted GLBFP objects.

Usage

## S3 method for class 'glbfp_fit'
predict(object, newdata = NULL, ...)

Arguments

Value

Numeric vector of predicted densities.

Summarize GLBFP fit objects

Description

Summarizes objects returned by ASH(), LBFP(), GLBFP() and their grid counterparts.

Usage

## S3 method for class 'glbfp_fit'
summary(object, ...)

Arguments

Value

A list with class "summary.glbfp_fit" or "summary.glbfp_grid".