R/datasets.R

In DistributionalDDA: Distributional Data Analysis in Bayes Spaces

#DATASETS for DDA

## Drafts for datasets that are not (yet) shipped (UACH_data_chem_2, us_data,
## asfr_new) were moved to data-raw/datasets_pending.R on 2026-06-12 (P0.3#4 in
## TODO_documentation_review.md): their roxygen was disabled, no data files
## exist in data/, and the bare quoted names were dead code. Restore a block
## from data-raw/ once its .rda actually ships.

#' An example dataset for distributional data analysis
#'
#' This is a simulated dataset, which can be used to try different
#' tools for distributional data analysis. The idea is that there is a
#' set of samples 'sample' from three regions, each containing many
#' particles. From each particle we have observed a size parameter
#' 'size' (volume equivalent diameter), a density 'density', and a
#' shape parameter 'shape'
#'
#' @format A data frame with 20 rows (material samples) and 9 columns. Several
#'   columns hold one *function* per row (the particle PDFs / CDFs), and
#'   \code{data} holds one nested data frame per row:
#'
#' \describe{
#'
#'   \item{sample}{The id of the material sample}
#'
#'   \item{region}{The region the sample comes from.}
#'
#'   \item{d50}{A measured median particle size of the sample}
#'
#'   \item{shapePDF}{Particle shape distribution in sample, provide as
#'   a probability density function. Shape is measured by a measure for
#'   sphericity.}
#'
#'   \item{shapeCDF}{Particle shape distribution in sample, provided
#'                   as Cummulative distribution.}
#'
#'   \item{sizePDF}{Particle size distribution in the sample
#'                   (diameter), provide as probability density
#'                   function. Size is measured by equivalent
#'                   diameter. The sieving diameter relevant for d50
#'                   is slightly different.}
#'
#'   \item{sizeCDF}{Particle size distribution in the sample
#'                   provided as cummulative distribution function (cdf).}
#'
#'   \item{rhoCDF}{Particle mass density distribution provided as
#'   cummulative distribution function (CDF). Particle density does
#'   not have probability density, because liberated particles
#'   containing only one mineral all can only have very specific
#'   densities (e.g. Quarz 2.25 kg/l and Magnetit at 5.2 kg/l)}
#'
#'   \item{data}{data.frames containing samples of the particles in
#'    each material sample. It has four columns: sample (the id of the
#'    sample), size (equivalent diameter of the particle), shape
#'    (sphericity), and density (mass density) of the particle.}
#' }
#' @source Simulated data, not based on real measurements. Generated by
#'   \code{data-raw/DTD.R} with \code{set.seed(47)} (N = 20 samples drawn from
#'   three regions A/B/C). Shipped as \code{data/DTD.rda}; see \code{data-raw/DTD.R}
#'   to regenerate.
#' @importFrom stats rpois
#' @importFrom stats rbeta
#' @importFrom stats dbeta
#' @importFrom stats pbeta
#' @importFrom stats rlnorm
#' @importFrom stats dlnorm
#' @importFrom stats plnorm
#' @importFrom stats runif
#' @importFrom stats rpois
#' @importFrom stats rnorm
#' @importFrom stats dnorm
#' @importFrom stats pnorm
#'
#' @examples
#' data("DTD")
#' DTD
#' boxplot(DTD$d50)
#' # Looking at the size variable
#' plotFuncs(DTD$sizePDF)
#' plotFuncs(\(x)(dlnorm(x,meanlog=-0.2,sdlog=0.5)),add=TRUE,col="red",lwd=3)
#' RMForSize = ReferenceMeasureTransformed("plnorm",meanlog=-0.2,sdlog=0.5)
#' B2ForSize  = BayesSpace(RMForSize)
#' BasisForSize = BayesSpaceBasis(B2ForSize,nbasis=6)
#'
#' sizePDFs = BDataPDFs(DTD$sizePDF,basis=BasisForSize)
#' plot(sizePDFs)
#' sizeDensities = as.BDataDensities(sizePDFs)
#' plot(sizeDensities)
#' sizeSplines   = as.BDataSplines(sizeDensities)
#' #plot(sizeSplines,add=TRUE,col="blue")
#' DTD$data[[1]]
#' summary(DTD$data[[1]])
"DTD"

#
# #DTD_size_s = BDataSamples(lapply(DTD$data,\(x)(x$size)),
#
#
# #DTDx = BDataSamples(tapply(DTD$x,DTD$sample,simplify=FALSE),basis=B2Unif01Basis5)
# #obsMean = tapply(DTD$x,DTD$sample,mean)
# #obsSd   = tapply(DTD$x,DTD$sample,sd)
# #DTD_PDF = BDataPDFs(mapply(function(mean,sd) \(x)(dnorm(x,mean,sd)),obsMean,obsSd),basis=B2N01Basis5)
# #plot(DTD_PDF,col=1:length(DTD_PDF))
# #DTDf = as.BDataDensities(DTD_PDF)
# #plot(DTDf,col=1:length(DTDf))
#
#
#  "DTD"


#' Age Distribution Data for Upper Austrian Communes
#'
#' Age distributions for 57 communes in Upper Austria (Oberoesterreich),
#' separated by sex. Each observation represents the age distribution of
#' either the male or female population in a commune, given as proportions
#' across 19 five-year age groups.
#'
#' The data originates from the Austrian Register Census 2021 (Registerzaehlung 2021),
#' which provides population counts by gender, age, and citizenship at the
#' municipality level. The original counts have been converted to proportions
#' (probability distributions) for distributional data analysis.
#'
#' This dataset is useful for demonstrating PCA on distributional data,
#' as it contains real-world probability distributions that vary in shape
#' (e.g., rural vs urban communes have different age structures).
#'
#' @format A list with three components:
#' \describe{
#'   \item{data}{A data frame with 114 rows (57 communes x 2 sexes) and 22 columns:
#'     \describe{
#'       \item{commune}{Character. Four-digit commune code.}
#'       \item{municipality}{Character. Name of the municipality (e.g., "Linz", "Steyr").
#'           German umlauts have been transliterated to ASCII (ue, oe, ae, ss).}
#'       \item{sex}{Factor with levels "male" and "female".}
#'       \item{AGE_2, AGE_7, ..., AGE_92}{Numeric. Proportions for each age group.
#'           Column names indicate the midpoint of the 5-year age interval
#'           (e.g., AGE_2 = ages 0-4, AGE_7 = ages 5-9, ..., AGE_92 = ages 90+).}
#'     }
#'   }
#'   \item{ages}{Numeric vector of length 19. The midpoint ages: 2, 7, 12, ..., 92.}
#'   \item{distributions}{A 114 x 19 matrix of age proportions. Row names are
#'       formatted as "municipality_sex" (e.g., "Linz_male"). Each row sums to 1.}
#' }
#'
#' @source Data from the Austrian Register Census 2021 (Registerzaehlung 2021),
#' provided by the State of Upper Austria (Land Oberoesterreich) via the
#' Open Data Portal Austria.
#'
#' @references
#' Land Oberoesterreich (2021). Bevoelkerung nach Geschlecht und Alter.
#' Open Data Oesterreich.
#' Old broken link: https://www.data.gv.at/katalog/dataset/land-ooe_bevolkerung-geschlecht-und-alter
#' Current dataset: \url{https://www.data.gv.at/katalog/datasets/cd33f19a-7bcc-4454-987c-9f2d76542872}
#' @section License:
#' Creative Commons Attribution 4.0 International (CC BY 4.0).
#' \url{https://creativecommons.org/licenses/by/4.0/}
#'
#' @note Municipality names have been transliterated from German to ASCII for
#' cross-platform compatibility, following the convention ae / oe / ue / ss for the
#' umlauts and sharp-s (so e.g. the German "Altmuenster" and "Schoenegg" are stored
#' with ue / oe). For an unambiguous key independent of spelling, use the four-digit
#' codes in the `commune` column.
#'
#' @examples
#' data("age")
#'
#' # Examine the structure
#' str(age)
#' head(age$data)
#'
#' # The age midpoints
#' age$ages
#'
#' # Plot a few age distributions
#' matplot(age$ages, t(age$distributions[1:6, ]), type = "l",
#'         xlab = "Age", ylab = "Proportion",
#'         main = "Age distributions for first 6 observations")
#'
#' # Convert to BData for distributional analysis
#' # First, create a basis for age distributions (support 0-100)
#' rmAge <- ReferenceMeasureUniform(0, 100)
#' B2Age <- BayesSpace(rmAge)
#' basisAge <- BayesSpaceBasis(B2Age, nbasis = 7)
#'
#' # Create histograms from the proportional data
#' breaks <- c(5*(0:18), 100)
#' ageHist <- BDataDensityHistograms(
#'     age$distributions, breaks = breaks, basis = basisAge
#'     )
#'
#' # Convert to splines: histograms -> densities -> splines
#' ageDensities <- as.BDataDensities(ageHist)
#' ageSplines <- as.BDataSplines(ageDensities)
#' pcaAge <- princomp(ageSplines)
#' summary(pcaAge)
#'
#' # Visualize PCA results
#' plot(pcaAge, type = "screeplot")
#' plot(pcaAge, type = "scores")
#'
#' # Score plot with municipality labels
#' plot(pcaAge, type = "scores", labels = age$data$municipality, cex = 0.6)
#'
#' # Color by sex
#' sexColors <- ifelse(age$data$sex == "male", "blue", "red")
#' plot(pcaAge, type = "scores", col = sexColors)
#' legend("topright", c("Male", "Female"), col = c("blue", "red"), pch = 19)
#'
"age"