Take in a data frame containing circumplex scales, angle definitions for each scale, and an instrument whose normative data will be used, and return that same data frame with each specified circumplex scale transformed into standard scores (i.e., z-scores) based on comparison to that instrument's normative sample.
norm_standardize(
data,
scales,
angles = octants(),
instrument,
sample = 1,
prefix = "",
suffix = "_z",
append = TRUE,
quiet = FALSE
)A data frame that contains the norm-standardized versions of
scales. It carries a "norm_sample" attribute -- a list with elements
Instrument, Sample, Size, Population and Kind -- recording which
normative sample produced the scores and what kind of reference
distribution it is (see norms() for the three kinds), so a script that
never sees the console can still report what its z-scores are relative to.
Retrieve it with attr(x, "norm_sample").
Required. A data frame or matrix containing at least circumplex scales.
Required. A character vector containing the column names, or a numeric vector containing the column indexes, for the variables (scale scores) to be standardized.
Required. A numeric vector containing the angular displacement
of each circumplex scale included in scales (in degrees). Can use the
octants(), poles(), or quadrants() convenience functions. Each angle
is matched to the instrument's normative data by angular position, so 0
and 360 degrees are treated as the same angle; an angle with no matching
normative row (or with more than one) produces an informative error.
Required. An instrument object from the package. To see the
available circumplex instruments, see instruments().
Required. An integer corresponding to the normative sample to
use in standardizing the scale scores (default = 1). See ?norms to
see the normative samples available for an instrument. Two conditions are
refused with an error rather than used: a sample the instrument does not
carry (the error lists the sample numbers it does), and a sample whose
mean scores fall outside the instrument's own response range, which cannot
be on the same metric as the scores being standardized. norms() lists
the alternatives in both cases.
Optional. A string to include at the beginning of the newly
calculated scale variables' names, before the scale name and suffix
(default = "").
Optional. A string to include at the end of the newly
calculated scale variables' names, after the scale name and prefix
(default = "_z").
Optional. A logical that determines whether the calculated
standardized scores should be added as columns to data in the output or
the standardized scores alone should be output (default = TRUE).
Optional. A logical that suppresses the message naming the
normative sample used (default = FALSE). Set to TRUE in loops, knitted
documents, and anywhere else the message is noise; the returned attribute
below records the same facts either way.
The sample the scores are compared against is a result-determining choice,
not a technicality: different samples of the same instrument can move a
respondent's z-scores by more than half a standard deviation. So unless
quiet = TRUE, every successful call reports which sample it used, how
large that sample was, and how it is described, and every call attaches the
same facts to the result (see the Value section below). Use norms() to see
the samples an instrument carries before choosing one.
Other tidying functions:
ipsatize(),
score(),
self_standardize()
data("jz2017")
norm_standardize(jz2017, scales = 2:9, instrument = iipsc, sample = 1)
# The IIP-SC carries more than one normative sample. Omitting `sample` takes
# the first, and the message says which one that was.
z <- norm_standardize(jz2017, scales = 2:9, instrument = iipsc)
attr(z, "norm_sample")
Run the code above in your browser using DataLab