R/DistributionalDDA-package.R

In DistributionalDDA: Distributional Data Analysis in Bayes Spaces

#' DistributionalDDA: Distributional Density Data Analysis
#'
#' @description
#' Tools for the statistical analysis of *datasets of distributions* — where each
#' observation is a whole probability distribution rather than a single number — using
#' **Bayes space** calculus. A Bayes space is a Hilbert space whose elements are
#' distributions, so the usual operations (mean, variance, distance, principal component
#' analysis, clustering) carry over to densities once a reference measure and a
#' finite-dimensional basis are fixed.
#'
#' @details
#' ## Getting started — the typical workflow
#'
#' \enumerate{
#'   \item Choose a **reference measure** that defines the geometry of the space and
#'         matches the support of your data: [ReferenceMeasureUniform],
#'         [ReferenceMeasureTransformed] (e.g. a Gaussian support via its CDF), or
#'         [ReferenceMeasureDiscrete].
#'   \item Wrap it in a **Bayes space**: [BayesSpace] (predefined: `B2Unif01`, `B2N01`).
#'   \item Pick a finite-dimensional **basis**: [BayesSpaceBasis] (predefined:
#'         `B2Unif01Basis5`, `B2Unif01Basis7`, ...). The default basis uses zero-integral
#'         B-splines (ZB-splines); see [getMetricTensor] for the resulting metric.
#'   \item Put your data into a **BData** container that matches its form (see below).
#'   \item Analyse: [mean][mean.BDataSplines], [mvar][mvar.BData], [msd][mvar.BData],
#'         [dist][dist.BData], [scale][scale.BData], [princomp][princomp.BData] (SFPCA),
#'         and the plotting methods.
#' }
#'
#' ## BData representations (which container to use)
#'
#' \describe{
#'   \item{[BDataSamples]}{raw samples drawn from each distribution.}
#'   \item{[BDataFrequencyHistograms] / [BDataDensityHistograms]}{binned data.}
#'   \item{[BDataPDFs] / [BDataLogPDFs]}{densities w.r.t. the Lebesgue measure.}
#'   \item{[BDataDensities] / [BDataLogDensities]}{densities w.r.t. the reference measure.}
#'   \item{[BDataSplines]}{spline coefficients — the compact representation used for
#'         computation (PCA, distances, inner products).}
#' }
#' Convert between them with the `as.BData*` functions (e.g. [as.BDataDensities],
#' [as.BDataSplines]); the usual path is Samples/Histograms -> Densities -> Splines.
#'
#' ## Key concepts
#'
#' \describe{
#'   \item{Bayes space algebra}{In a Bayes space, addition of two distributions is the
#'         (closed) product of their densities, subtraction the ratio, and scalar
#'         multiplication a power transform. See [Add], [Sub], [Mul], [Div].}
#'   \item{clr / closure}{[clr] is the centred log-ratio transform into the L2 space;
#'         [clo] closes a density to integrate to one.}
#'   \item{Gram matrix / metric tensor}{The basis carries a Gram matrix `S` with
#'         `S[i,j] = <psi_i, psi_j>`; inner products in coefficient space are `c1' S c2`.
#'         For ZB-splines `S` is not the identity. See [getMetricTensor].}
#' }
#'
#' ## Datasets
#'
#' [age] (age distributions of Upper Austrian communes) and [DTD] (a simulated particle
#' dataset) are included for examples.
#'
#' @seealso
#' The package vignettes for worked examples:
#' \code{vignette("DistributionalDDA")} and
#' \code{vignette("PCA_distributional_data")}.
#'
#' @keywords internal
"_PACKAGE"