Convert raw indicator values to a 0-1 outcome score
Usage
util_outcome(
x,
type = c("continuous", "threshold", "category"),
from = NULL,
reverse = FALSE,
thresh = NULL,
op = "<",
smooth = "logistic",
pct = 0.1,
levels = NULL
)Arguments
- x
vector of raw values to convert
- type
chr string indicating how to interpret
x:"continuous"rescales a continuous value,"threshold"compares against a cutoff,"category"maps discrete categories to fixed outcome values- from
numeric vector of length 2, the
c(min, max)range ofxto rescale from whentype = "continuous". Defaults torange(x, na.rm = TRUE).- reverse
logical, if
TRUEthe outcome is flipped (1 - outcome) so a higher raw value inxindicates a worse outcome.- thresh
numeric, the cutoff value to compare
xagainst whentype = "threshold"- op
chr string, one of
"<","<=",">",">=". Defines the condition under whichxattains an outcome of 1 whentype = "threshold"- smooth
for
type = "threshold", one of"logistic"(the default),"ramp", or"none". See Details.- pct
numeric, the fraction of
abs(thresh)used as the steepness of the"logistic"/"ramp"transition whensmoothis one of those. Smaller values give a sharper transition. Defaults to0.1(10% ofthresh).- levels
named numeric vector mapping each category value in
xto a fixed outcome whentype = "category", e.g.c(Poor = 0, Fair = 0.5, Good = 1). Values ofxnot found inlevelsreturnNA.
Details
This is meant as the single point of modification for how a raw indicator
value becomes a 0-1 outcome, since that conversion is expected to change
as individual indicators are refined (e.g. moving a category-based
indicator to use its underlying continuous value instead, or a hard
threshold to a smooth one) without needing to change every anlz_*
function that calls it.
continuous: x is linearly rescaled from from to
c(0, 1) with rescale, then clamped to
c(0, 1). Values of x outside from are pinned to
0 or 1 rather than extrapolated. This lets from act
as a transition window narrower than the full range of x (e.g.
TBNI's 32-46 breakpoints within its 0-100 score).
threshold: x is compared to thresh using op,
in one of three ways selected by smooth:
"logistic"(the default): a smooth logistic transition centered atthresh, exactly0.5atthreshand approaching0/1on either side, in the directionopwould have used (e.g.op = "<"still means lowerxis better)."ramp":1oncexreaches the "good" side ofthresh(as defined byop). This is not just0.5there like"logistic". It decays exponentially toward0the furtherxis on the "bad" side. Use this when meeting or beating a target should already be full credit rather than half credit (e.g. an acreage target that's fine to exceed by any amount)."none": a hard0/1cutoff, no transition.
For "logistic" and "ramp", the steepness of the transition
is a percentage (pct) of thresh rather than a fixed
absolute value, so it stays meaningful across indicators/thresholds with
very different units and magnitudes (e.g. a threshold of 1 vs. a
threshold in the hundreds).
category: x is mapped to an outcome via levels.
In all cases, reverse = TRUE flips the result so a higher raw value
in x corresponds to a lower (worse) outcome.
Examples
# continuous, e.g. TBNI scores from 0-100
util_outcome(c(20, 46, 90), type = 'continuous', from = c(0, 100))
#> [1] 0.20 0.46 0.90
# continuous with a narrower transition window, e.g. TBNI's 32-46
# breakpoints. Values outside the window are clamped to 0/1
util_outcome(c(20, 32, 39, 46, 60), type = 'continuous', from = c(32, 46))
#> [1] 0.0 0.0 0.5 1.0 1.0
# threshold, e.g. chlorophyll attainment (lower is better). Smooth by
# default, a logistic transition rather than a hard cutoff
util_outcome(c(5, 10, 15), type = 'threshold', thresh = 10)
#> [1] 0.993307149 0.500000000 0.006692851
# a larger pct widens the transition (steepness relative to thresh)
util_outcome(12, type = 'threshold', thresh = 10, pct = 0.1)
#> [1] 0.1192029
util_outcome(12, type = 'threshold', thresh = 10, pct = 0.2)
#> [1] 0.2689414
# smooth = "none" instead gives a hard 0/1 cutoff
util_outcome(c(5, 15), type = 'threshold', thresh = 10, op = '<', smooth = 'none')
#> [1] 1 0
# smooth = "ramp": meeting/beating a target (op = ">=") is full credit,
# decaying toward 0 the further short of it a value falls
util_outcome(c(90, 95, 100, 105), type = 'threshold', thresh = 100, op = '>=', smooth = 'ramp')
#> [1] 0.3678794 0.6065307 1.0000000 1.0000000
# category, e.g. FIB grades
util_outcome(c('A', 'C', 'E'), type = 'category',
levels = c(A = 1, B = 0.75, C = 0.5, D = 0.25, E = 0))
#> [1] 1.0 0.5 0.0
