Get an approximate ordinal cumulative distribution function or probability mass function from quantiles for a continuous variable.

Given quantiles that characterize a continuous random variable and a set of cutpoints for binning that variable into ordinal categories, return the approximate CDF or PMF for the ordinal variable.

Usage

quantiles_to_category_cdf(
  quantile_levels,
  values,
  category_cutpoints,
  labels = names(category_cutpoints),
  ...
)

quantiles_to_category_pmf(
  quantile_levels,
  values,
  category_cutpoints,
  labels = names(head(category_cutpoints, -1)),
  ...
)

Arguments

quantile_levels

Vector of quantile levels, passed as the ps argument to distfromq::make_p_fn().

values

Vector of associated values of the random variable at those quantiles, passed as the qs argument to distfromq::make_p_fn().

category_cutpoints

Vector (optionally named) of category cutpoints that could be supplied to base::cut() or similar to bin the continuous random variable. forecasttools functions such as get_prism_cutpoints() supply cutpoints in this format.

To follow base::cut() conventions, the cutpoint vector should be of length \(n+1\), where \(n\) is the number of categories. Entries \(1, ..., n\) should be the left endpoints of of each categorical bin. Entry \(n+1\) should be the right endpoint of the final bin, i.e. the upper bound of the underlying continuous variable's support, or Inf if there is no upper bound. Similarly, if there is no lower bound to the underlying variable's support, entry \(1\) should be -Inf.

labels

Labels for the CDF or PMF categories. For CDFs, the labels vector should be equal in length to the cutpoints vector. For PMFs, the labels vector should have one fewer entry than the cutpoints vector (since the last cutpoint is the right endpoint of the final bin). If no labels vector is specified, the function uses the names of the cutpoints vector itself, if any, and otherwise returns an unnamed vector. For PMFs, that means all cutpoint names except the last.

...

Additional keyword arguments passed to distfromq::make_p_fn().

Value

The values of the approximate CDF or PMF for each provided category, as a vector (a named vector if the category bounds vector is named)

Details

Wraps distfromq::make_p_fn() to approximate the continuous CDF, then applies category cutpoints in the form used by base::cut().

The category cutpoints must cover the entire support of the continuous random variable: the first cutpoint should be the lower bound of the support; the final cutpoint should be the upper bound of the support.

The function will error if the input quantile values include values outside this support.

The approximate continuous CDF will be estimated on the unconstrained real interval \((-\infty, \infty)\) with an appropriate monotonic transform for the support, picked via get_transform_to_real_line(). It will then be evaluated against the transformed values of the cutpoints.

Examples

cutpoints <- get_prism_cutpoints("US", "COVID-19", signal = "NSSP")[[1]]
quantile_levels <- c(0.25, 0.5, 0.75)
values <- c(0.05, 0.2, 0.3)
quantiles_to_category_cdf(
     quantile_levels,
     values,
     cutpoints,
)
#>    very_low         low    moderate        high   very_high upper_bound 
#>  0.00000000  0.04839822  0.12140138  0.17372454  0.21538645  1.00000000 

quantiles_to_category_pmf(
     quantile_levels,
     values,
     cutpoints,
)
#>   very_low        low   moderate       high  very_high 
#> 0.04839822 0.07300317 0.05232316 0.04166191 0.78461355