z2y: Convert Z-scores into measurements

In growthcharts/centile: Translate Measurements, Z-Scores and Centiles with the RIF format

Convert Z-scores into measurements

Description

Converts age- or hgt-conditional standard deviation scores into measurements (KG, CM, ...) using one or more external reference distributions.

Usage

z2y(
  z,
  x,
  refcode,
  pkg = "centile",
  verbose = FALSE,
  dec = 3L,
  rule = 1L,
  tail_adjust = FALSE,
  ...
)

Arguments

z	A numerical vector with Z-scores.
x	A vector containing length(y) values of the numerical covariate (typically decimal age or height) at which conversion is desired. A scalar x will be expanded to length(y).
refcode	A character vector with length(y) elements, each of which is the name of a reference. Scalar refcode expands to length(y). Alternatively, refcode may be an object of class reference, typically produced by import_rif(). If NULL the procedure returns NA's.
pkg	The package containing the references in the R/sysdata.dta object. The package needs to be loaded. The default pkg = "centile" searches in the centile package.
verbose	Set to TRUE to turn on warnings
dec	A scalar value indicating the number of decimals used to round the value. The default is 3 decimals.
rule	an integer (of length 1 or 2) describing how interpolation is to take place outside the interval [min(x), max(x)]. If rule is 1 then NAs are returned for such points and if it is 2, the value at the closest data extreme is used. Use, e.g., rule = 2:1, if the left and right side extrapolation should differ.
tail_adjust	Logical. If TRUE the procedure applies the WHO method for tail adjustment under the LMS distribution. We do not recommend this. The default is FALSE.
...	Not used.

Value

A vector with length(z) elements containing the measurements.

Note

The type of reference distribution is defined by the distribution field of the study attribute in the reference. The function executes transformations specified by the tx field (before calculation of y) and the yt field (after calculating of y), so that the y have the original units even if the reference is based on some transform of y.

Functions y2z() and z2y() functions are the inverse of each other.

Author(s)

Stef van Buuren, 2021

Examples

# height centiles SD -2:2 according to WHO standard for 6 month year old girl
# using built-in reference
z2y(z = -2:2, x = rep(0.5, 5), "who_2006_hgt_female_", pkg = "centile")

# same using external Dutch reference
fn <- system.file("testdata/nl_2009_hgt_female_nl.txt", package = "centile")
myref <- import_rif(fn)
head(myref)
head(attr(myref, "study"))
z2y(z = -2:2, x = rep(0.5, 5), myref)

# find location of -2 SD line for 6 months old boys and girls, WHO Standard
z2y(c(-2, -2), c(0.5, 0.5), c("who_2006_hgt_male_", "who_2006_hgt_female_"))

growthcharts/centile documentation built on Oct. 26, 2024, 3:10 p.m.