R/topics.R

In DistributionalDDA: Distributional Data Analysis in Bayes Spaces

## Concept / overview help pages (no functions, only documentation topics).

#' Distributional data containers (BData)
#'
#' @description
#' `BData` is the base class for the data containers in DistributionalDDA. A `BData`
#' object holds a data set of distributions together with the [BayesSpaceBasis] in
#' which they are represented. Several subclasses store the same information in
#' different forms; pick the one that matches how your data arrive, then convert to
#' splines for computation.
#'
#' @details
#' # Which representation should I use?
#' \describe{
#'   \item{Raw samples}{[BDataSamples] -- one numeric sample per distribution.}
#'   \item{Binned data}{[BDataFrequencyHistograms] (counts) or
#'         [BDataDensityHistograms] (densities).}
#'   \item{Density functions w.r.t. the Lebesgue measure}{[BDataPDFs] /
#'         [BDataLogPDFs].}
#'   \item{Density functions w.r.t. the reference measure}{[BDataDensities] /
#'         [BDataLogDensities].}
#'   \item{Spline coefficients}{[BDataSplines] -- the compact representation used for
#'         computation (PCA, distances, inner products).}
#' }
#'
#' # Conversion pipeline
#' The `as.BData*` converters move between representations. The usual flow is
#' \preformatted{  Samples / Histograms  ->  Densities  ->  Splines  ->  PDFs }
#' Converting towards densities/splines requires a basis and is an approximation (the
#' data are projected onto the finite-dimensional spline space); extracting samples or
#' re-expressing a representation as itself is lossless. For most analyses, convert to
#' [BDataSplines] with [as.BDataSplines].
#'
#' @seealso [BayesSpace], [BayesSpaceBasis], [ReferenceMeasure], [as.BDataSplines],
#'   [as.BDataDensities]
#' @name BData
NULL


#' Reference measures: the geometry of a Bayes space
#'
#' @description
#' A reference measure is the probability distribution that defines a [BayesSpace]: it
#' plays the role of the origin, and all modelled distributions are expressed relative
#' to it. Choosing it fixes the support and the geometry of the analysis.
#'
#' @details
#' # Choosing a reference measure
#' Pick a measure whose support matches your data, and ideally whose mass is
#' distributed similarly:
#' \describe{
#'   \item{[ReferenceMeasureUniform]}{uniform on an interval `(a, b)`; the simplest
#'         choice for data on a bounded interval (predefined: `B2Unif01`).}
#'   \item{[ReferenceMeasureTransformed]}{a transformed support, e.g. a Gaussian
#'         reference via its CDF (predefined: `B2N01`); useful for data on the real
#'         line or with a known reference shape.}
#'   \item{[ReferenceMeasureDiscrete]}{a finite set of categories with given
#'         probabilities.}
#' }
#' A poor choice (e.g. a uniform reference for strongly skewed data) still works but
#' gives a less informative geometry. Inspect a measure with [getReferenceMeasure] and
#' the resulting metric with [getMetricTensor].
#'
#' @seealso [BayesSpace], [BayesSpaceBasis], [BData]
#' @name ReferenceMeasure
NULL