beezdemand (version 0.2.0)

calculate_amplitude_persistence: Calculate Amplitude and Persistence

Description

Calculates Amplitude and Persistence latent factors from demand metrics for various beezdemand model objects.

Usage

calculate_amplitude_persistence(
  fit,
  amplitude = c("Intensity", "Q0d", "Q0"),
  persistence = c("BP0", "Pmaxe", "Omaxe", "Alpha"),
  use_inv_alpha = TRUE,
  strict = TRUE,
  min_persistence_components = 2L,
  empirical_y_var = NULL,
  basis_means = NULL,
  basis_sds = NULL,
  ...
)

Value

A data frame with the original ID and calculated Amplitude and Persistence scores, along with the standardized (Z-scored) constituent metrics.

Arguments

fit

An object of class beezdemand_fixed, beezdemand_hurdle, beezdemand_nlme, or a data.frame.

amplitude

Character vector of column names to consider for the Amplitude factor. The function will use the first column found in the data. Default is c("Intensity", "Q0d", "Q0").

persistence

Character vector of column names to include in the Persistence factor. Default is c("BP0", "Pmaxe", "Omaxe", "Alpha"). All found columns will be used.

use_inv_alpha

Logical. If "Alpha" (or a variation) is present in persistence, should it be inverted (1/Alpha) before standardization? Default is TRUE.

strict

Logical. If TRUE (default), missing metrics, duplicated ids, and other data integrity problems produce errors instead of warnings.

min_persistence_components

Integer. Minimum number of non-missing standardized persistence components required to compute Persistence for a given id. If fewer are available, Persistence is set to NA. Default is 2.

empirical_y_var

For beezdemand_nlme objects, optional column name in fit$data to use when computing empirical indices (e.g., BP0). This is important when the fitted y_var is transformed (e.g., log10). If NULL, the method will attempt to choose a sensible default and may error in strict mode if ambiguous.

basis_means

Optional named numeric vector of means to use for Z-score standardization. Names must match the columns used (e.g., c(Intensity = 10, BP0 = 5)). If NULL (default), the sample means are used.

basis_sds

Optional named numeric vector of standard deviations to use for Z-score standardization. Names must match the columns used. If NULL (default), the sample SDs are used.

...

Additional arguments passed to methods.

Models

• beezdemand_fixed: Extracts metrics from fit$results.

• beezdemand_hurdle: Extracts metrics from fit$subject_pars.

• beezdemand_nlme: Calculates subject-specific parameters from fixed and random effects. Parameters Q0 and Alpha are assumed to be on log10 scale for zben and simplified equations and are converted to linear scale. Omax and Pmax are calculated empirically from predictions. Breakpoint is calculated empirically from the raw data.

Details

This function calculates Amplitude and Persistence by:

1. Extracting the relevant demand metrics from the fit object.

2. Resolving requested metric columns (case-insensitive, with limited synonym support for common beezdemand outputs).

3. Inverting Alpha if requested (1/Alpha).

4. Standardizing (Z-scoring) the metrics. If basis_means and basis_sds are provided, they are used; otherwise, the current sample's statistics are used.

5. Aggregating the Z-scores into the two latent factors.

Amplitude is defined by the variable specified in amplitude (typically Intensity/Q0). Persistence is defined as the mean of the standardized values of the variables specified in persistence (typically Breakpoint, Pmax, Omax, and 1/Alpha).

Examples

# \donttest{
data(apt, package = "beezdemand")
fit <- FitCurves(apt, "hs", k = "share")
calculate_amplitude_persistence(fit)
# }