Package {Dcurvature}

Type: Package
Title: Discrete Curvature with 'shiny' Explorer
Version: 0.0.4
Description: Implements discrete curvature estimation for ordered planar point sequences using circumcenter geometry on consecutive triplets, exposed through compiled C plus plus (C++) code via 'Rcpp' for speed and numerical robustness. The package is useful for objective elbow detection in multivariate workflows, especially principal component analysis (PCA), where selecting the number of retained components can be subjective. It provides a 'shiny' interface that supports upload of raw datasets or explained-variance tables, computes Kaiser-Meyer-Olkin (KMO) sampling-adequacy diagnostics, evaluates individual and cumulative variance curves, and reports curvature- based decision rules (m* and m**) with visual summaries for reproducible component-selection decisions. References: Arney et al. (2001); Axler (2024) <doi:10.1007/978-3-031-41026-0>; Bjorklund (2019) <doi:10.1111/evo.13835>; Burden and Faires (2015); Chang et al. (2023) https://CRAN.R-project.org/package=shiny; Christensen (2019); Cui (2020) <doi:10.18637/jss.v040.i08>; Eddelbuettel and Sanderson (2014) <doi:10.1016/j.csda.2013.02.005>; Engelke et al. (2023) <doi:10.1016/j.jseint.2023.04.010>; Gniazdowski (2021) <doi:10.26348/znwwsi.24.35>; Haynes et al. (2017); Jameel and Al-Salami (2023) <doi:10.24086/cuejhss.v7n1y2023.pp121-125>; Jolliffe (2002); Jolliffe and Cadima (2016) <doi:10.1098/rsta.2015.0202>; Kaiser (1974); Lehnert et al. (2019) <doi:10.18637/jss.v089.i12>; Ma and Dai (2011) <doi:10.1093/bib/bbq090>; Milligan (1995); Onumanyi et al. (2022) <doi:10.3390/app12157515>; Park (2010); Revelle (2024) https://CRAN.R-project.org/package=psych; Rodionova et al. (2021) <doi:10.1016/j.chemolab.2021.104304>; Sen and Cohen (2025) <doi:10.1177/01466216251344288>; Serneels and Verdonck (2008) <doi:10.1016/j.csda.2007.05.024>; Shi et al. (2021) <doi:10.1186/s13638-021-01910-w>; Shaukat et al. (2016) <doi:10.1515/eko-2016-0014>; Syakur et al. (2018) <doi:10.1088/1757-899X/336/1/012017>; Wickham and Bryan (2023) https://CRAN.R-project.org/package=readxl; Wu et al. (2017) <doi:10.1088/1755-1315/61/1/012054>; Youssef et al. (2023) <doi:10.21303/2461-4262.2023.002582>.
License: MIT + file LICENSE
Encoding: UTF-8
Imports: Rcpp, shiny, readxl
Suggests: ggplot2, psych, testthat (≥ 3.0.0)
LinkingTo: Rcpp
Config/testthat/edition: 3
RoxygenNote: 7.3.2
NeedsCompilation: yes
Packaged: 2026-07-20 15:59:49 UTC; jorgeandresjolahernandez
Author: Aquiles Darghan [aut], Jorge Jola [aut, cre]
Maintainer: Jorge Jola <jjolaher@purdue.edu>
Repository: CRAN
Date/Publication: 2026-07-20 16:50:02 UTC

Discrete Curvature for an Ordered 2D Curve

Description

Compute pointwise discrete curvature from an ordered sequence of 2D points using circumcenter-based geometry on consecutive triplets.

Usage

curvature(data)

Arguments

data

A numeric matrix/data frame with at least two columns representing ordered x and y coordinates. Additional columns are ignored.

Value

A numeric vector of curvature values with one value per input row. Boundary points are set to 0.

Examples

pts <- cbind(
  x = seq(0, 1, length.out = 8),
  y = sin(seq(0, pi, length.out = 8))
)
curvature(pts)

Load the bundled example data as a data frame

Description

Reads ‘data.xlsx’ from the package via read_excel.

Usage

load_example_data(sheet = NULL, ...)

Arguments

sheet

Sheet to read; passed to read_excel. Default is the first sheet.

...

Optional arguments passed to read_excel.

Value

A data frame.

Examples

x <- load_example_data()
head(x)

Run the curvature Shiny app

Description

Launches the discrete-curvature criterion app. You can start from an explained-variance table (upload CSV/Excel or use the bundled example), or from raw variables (Excel, then PCA). Elbow detection uses curvature on the variance curves, with optional KMO in PCA mode.

Usage

run_curvature_app(..., .runApp = shiny::runApp)

Arguments

...

Optional arguments passed to runApp (e.g. port, launch.browser, host).

.runApp

Internal app runner used for testing. Defaults to runApp.

Value

Invisibly returns the result of shiny::runApp. Called for its side effect of starting a Shiny app.

Examples

if (interactive()) {
  run_curvature_app()
}

Discrete-curvature selection of the number of components

Description

Applies the discrete-curvature elbow criterion to an explained-variance sequence and returns the adaptive selection m^* (first/second-order difference operators). When a minimum cumulative-variance threshold tau is supplied, it also returns the extended selection m^{**} = \max(m^*, \min\{i : V_i \ge \tau\}).

Usage

select_components(
  variance,
  type = c("cumulative", "individual"),
  axis_range = c("0p", "01"),
  tau = NULL
)

Arguments

variance

Numeric vector of individual explained variance per component (percent or proportion), ordered from the first component.

type

Curve the criterion is applied to: "cumulative" (default) or "individual".

axis_range

Axis normalization: "0p" (default, x in [0, p]) or "01" (both axes scaled to [0, 1]).

tau

Optional minimum cumulative-variance threshold (same units as variance). If supplied, mstar_ext is computed.

Details

This exposes, as a single reproducible call, the same logic used by the interactive application run_curvature_app.

Value

A list with mstar, order_used (1 or 2), mstar_ext (NA when tau is NULL), type, axis_range, tau, and table: a data frame with per-component individual/cumulative variance, normalized curvature (kappa_norm) and normalized second differences (d2_norm).

See Also

curvature, run_curvature_app

Examples

v <- c(35.2, 22.8, 15.1, 9.5, 6.2, 4.1, 2.8, 1.9, 1.3, 1.1)
select_components(v, type = "cumulative", tau = 90)