From ebd55ed425b2254f09694933825e7bb04ef00b8c Mon Sep 17 00:00:00 2001 From: Simon Parker <65285181+awadafuk@users.noreply.github.com> Date: Sat, 9 Nov 2024 02:13:59 +0000 Subject: [PATCH] docs: Re-generate all roxygen docs --- R/srr-stats-standards.R | 75 ------------------- man/classify_growth.Rd | 10 ++- man/classify_sfga.Rd | 4 - man/classify_svn.Rd | 4 - man/dot-gigs_options.Rd | 4 + man/gigs-package.Rd | 5 +- man/gigs_zscoring.Rd | 57 ++++++++++++++ man/ig_fet.Rd | 15 ++-- man/ig_fet_estimate_fetal_weight.Rd | 5 -- man/ig_nbs.Rd | 13 ++-- man/life6mo.Rd | 2 +- man/report_units.Rd | 35 +++++++++ man/shared_roxygen_params.Rd | 4 +- man/shared_value2zscore_returns.Rd | 15 ---- man/shared_zscore2value_returns.Rd | 15 ---- man/value2zscore.Rd | 112 ++++++++++++++++++++++++++++ man/who_gs_coeffs.Rd | 9 --- man/zscore2value.Rd | 97 ++++++++++++++++++++++++ 18 files changed, 336 insertions(+), 145 deletions(-) delete mode 100644 R/srr-stats-standards.R create mode 100644 man/report_units.Rd delete mode 100644 man/shared_value2zscore_returns.Rd delete mode 100644 man/shared_zscore2value_returns.Rd create mode 100644 man/value2zscore.Rd create mode 100644 man/zscore2value.Rd diff --git a/R/srr-stats-standards.R b/R/srr-stats-standards.R deleted file mode 100644 index d6c04a8..0000000 --- a/R/srr-stats-standards.R +++ /dev/null @@ -1,75 +0,0 @@ -#' srr_stats -#' -#' All of the following standards initially have `@srrstatsTODO` tags. -#' These may be moved at any time to any other locations in your code. -#' Once addressed, please modify the tag from `@srrstatsTODO` to `@srrstats`, -#' or `@srrstatsNA`, ensuring that references to every one of the following -#' standards remain somewhere within your code. -#' -#' @srrstatsVerbose TRUE -#' @noRd -NULL - -#' fulfilled_standards -#' -#' This block describes any SRR standards which are met, but do not have the -#' `@srrstats` tag placed next to all examples of the standard being met. -#' -#' @srrstats {G1.2} `.github/CONTRIBUTING.md` contains a lifecycle -#' statement/roadmap. -#' @srrstats {G5.1} Datasets used to check gigs package are exported. -#' @srrstats {G2.15} No exported gigs functions assume non-missingness. -#' @noRd -NULL - -#' NA_standards -#' -#' Any non-applicable standards can have their tags changed from `@srrstatsTODO` -#' to `@srrstatsNA`, and placed together in this block, along with explanations -#' for why each of these standards have been deemed not applicable. -#' (These comments may also be deleted at any time.) -#' @srrstatsNA {G2.14c} Imputation of values is not something we want to include -#' in gigs, so we haven't included an option for it. -#' @srrstatsNA {G2.4, G2.4a, G2.4b, G2.4c ,G2.4d, G2.4e} No gigs functions use -#' `as.*` functions to convert between data types. -#' @srrstatsNA {G2.5} No gigs functions request a factor variable as input. -#' @srrstatsNA {G2.7, G2.8, G2.9, G2.10, G2.11, G2.12} No gigs functions take -#' tabular input. -#' @srrstatsNA {G3.1, G3.1a} No gigs functions use covariance calculations. -#' @srrstatsNA {G4.0} No gigs functions write to disk. -#' @srrstatsNA {G5.3} No gigs functions are expected to return strictly non-`NA` -#' or non-`Inf`/non-`-Inf`/non-`NaN` values. -#' @srrstatsNA {G5.7} We don't have specific expectations for how our -#' implementation will perform as the properties of our data change. -#' @srrstatsNA {G5.10, G5.11, G5.11a, G5.12} Presently, the gigs test suite -#' runs fast enough that extended tests are not required. -#' @srrstatsNA {EA2.0, EA2.1, EA2.2, EA2.2a, EA2.2b, EA2.3, EA2.4, EA2.5} No -#' gigs functions accept tabular/multi-tabular input, so no index column -#' standards need to be met. -#' @srrstatsNA {EA3.0, EA3.1} We are still working on exact guidelines for which -#' growth standards to use when several are available, and do not want to -#' explicitly implement an algorithm that selects the 'best' growth standards -#' before this guidance is written. An early implementation of this reasoning -#' can be found in `gigs_zscoring.R`. Once we have published our guidelines, -#' we will update the package code and documentation to reflect this, and move -#' these standards to an `srrstats` tag at that point. -#' @srrstatsNA {EA4.0} Adherence to this standard is not suitable given the -#' nature of analyses facilitated by gigs. For example, a user wanting -#' centiles from anthropometric measurements encoded as integer values would -#' not want to receive their centiles as integers. Similarly, limiting -#' z-scores or predicted values based on the precision of units inputted by a -#' user would not be appropriate. -#' @srrstatsNA {EA4.1} We would rather output double precision floats and let -#' users round them, instead of implementing methods to artificially restrict -#' gigs outputs to a set number of decimal places. This is for reasons similar -#' to our reasoning for not fulfilling **EA4.0**. -#' @srrstatsNA {EA4.2} The objects returned by gigs are numeric vectors and -#' factors, so do not need custom `print()` behaviour. -#' @srrstatsNA {EA5.0, EA5.0a, EA5.0b, EA5.1, EA5.2, EA5.3, EA5.4, EA5.5, -#' EA5.6} The gigs package does not currently offer visualisation functions. -#' @srrstatsNA {EA6.0b, EA6.0c, EA6.0d} No exported gigs functions return -#' tabular data. -#' @srrstatsNA {EA6.1} The gigs package does not currently offer visualisation -#' functions. -#' @noRd -NULL diff --git a/man/classify_growth.Rd b/man/classify_growth.Rd index fb21693..b5004d6 100644 --- a/man/classify_growth.Rd +++ b/man/classify_growth.Rd @@ -92,14 +92,20 @@ messages about which analyses were requested versus which were performed will be printed to the console. Warnings from \code{classify_growth()} will still be printed even if \code{.verbose} is \code{FALSE}.} } +\value{ +A tabular object of the same class that was provided as \code{.data}, +with new columns named according to \code{.new}. The new columns will depend +on the values supplied for \code{.outcomes}. +} \description{ This function permits classification of multiple growth indicators (stunting, wasting, weight-for-age, and more) at once in \code{data.frame}-like objects. } \note{ For size-for-GA and small vulnerable newborn analyses, centiles and -categorisations will only be applied on birthweights, i.e. rows where -the column referred to by \code{age_days} is between \code{0} and \code{0.5}. +categorisations will only be applied for birth measurements. These are +considered to be the observation per level of \code{id} where \code{age_days} is +smallest, provided that \code{age_days} is between \verb{<3}. } \examples{ # This dummy dataset contains data from two people, from birth (<3 days) to diff --git a/man/classify_sfga.Rd b/man/classify_sfga.Rd index c0a3ef0..ca6b9a2 100644 --- a/man/classify_sfga.Rd +++ b/man/classify_sfga.Rd @@ -93,7 +93,3 @@ Management of the Small-for-Gestational-Age Fetus: Green-top Guideline No. 31.} \emph{Technical report, Royal College of Obstetricians and Gynaecologists, London, 2013.} } -\seealso{ -\code{\link[=ig_nbs_wfga_value2centile]{ig_nbs_wfga_value2centile()}}, which this function uses to get -a centile for each observation. -} diff --git a/man/classify_svn.Rd b/man/classify_svn.Rd index 5e9a230..9098657 100644 --- a/man/classify_svn.Rd +++ b/man/classify_svn.Rd @@ -101,7 +101,3 @@ Management of the Small-for-Gestational-Age Fetus: Green-top Guideline No. 31.} \emph{Technical report, Royal College of Obstetricians and Gynaecologists, London, 2013.} } -\seealso{ -\code{\link[=ig_nbs_wfga_value2centile]{ig_nbs_wfga_value2centile()}}, which this function uses to get -a centile for each observation. -} diff --git a/man/dot-gigs_options.Rd b/man/dot-gigs_options.Rd index 7c4d5ea..4aac3b5 100644 --- a/man/dot-gigs_options.Rd +++ b/man/dot-gigs_options.Rd @@ -3,6 +3,10 @@ \name{.gigs_options} \alias{.gigs_options} \title{Package-level gigs options} +\value{ +A named environment, where each name maps onto a specific option for +the GIGS package. +} \description{ An environment containing six named character vectors. These define how gigs handles inputs with missing, undefined, or invalid diff --git a/man/gigs-package.Rd b/man/gigs-package.Rd index f67b72e..543f01c 100644 --- a/man/gigs-package.Rd +++ b/man/gigs-package.Rd @@ -33,7 +33,10 @@ Other contributors: \itemize{ \item Linda Vesel (\href{https://orcid.org/0000-0003-3753-4172}{ORCID}) [data contributor] \item Eric Ohuma (\href{https://orcid.org/0000-0002-3116-2593}{ORCID}) [data contributor] - \item Bill & Melinda Gates Foundation [funder, copyright holder] + \item Chitra Saraswati (\href{https://orcid.org/0000-0002-8159-0414}{ORCID}) [reviewer] + \item Victor Ordu (\href{https://orcid.org/0000-0003-3716-0668}{ORCID}) [reviewer] + \item Bill & Melinda Gates Foundation [funder] + \item London School of Hygiene & Tropical Medicine [copyright holder] } } diff --git a/man/gigs_zscoring.Rd b/man/gigs_zscoring.Rd index 818b308..3ef37f7 100644 --- a/man/gigs_zscoring.Rd +++ b/man/gigs_zscoring.Rd @@ -41,6 +41,12 @@ height when \code{age_days >= 731}.} \item{headcirc_cm}{Numeric vector of length one or more with head circumference in cm.} } +\value{ +A numeric vector of z-scores, derived using the appropriate growth +standard for each element-wise combination of \code{gest_days} and \code{age_days}. +For \code{gigs_wlz()}, all birth WLZs will be missing (\code{NA}), as there is no +INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Newborn standard for weight-for-length. +} \description{ These functions calculate z-scores for weight-for-age (WAZs), length/height-for-age (LHAZs), weight-for-length/height (WLZs), or @@ -90,3 +96,54 @@ For \code{gigs_wlz()}, two WHO standards are available: These functions expect vectors which are recyclable with \code{\link[vctrs:vec_recycle]{vctrs::vec_recycle_common()}}. } +\examples{ +gest_days <- c(rep(35 * 7, 3), rep(35 * 7, 3)) +age_days <- c(0, 100, 500, 2, 100, 500) +sex <- rep.int(c("M", "F"), c(3, 3)) +wt_kg <- c(3, 6, 9, 3, 6, 9) +len_cm <- rep.int(c(52.2, 60.4, 75), 2) +head_cm <- rep.int(c(30, 40, 49), 2) +ids <- factor(rep.int(c("A", "B"), c(3, 3))) + +# Weight-for-age z-score (WAZ) +waz <- gigs_waz(weight_kg = wt_kg, + age_days = age_days, + gest_days = gest_days, + sex = sex, + id = ids) +print(waz) + +# Note - if you don't specify 'id' you'll get different results! +waz_no_id <- gigs_waz(weight_kg = wt_kg, + age_days = age_days, + gest_days = gest_days, + sex = sex) +print(waz == waz_no_id) + +# Length/height-for-age z-score (LHAZ) +lhaz <- gigs_lhaz(lenht_cm = len_cm, + age_days = age_days, + gest_days = gest_days, + sex = sex, + id = ids) +print(lhaz) + +# Weight-for-length/height z-score (WLZ) +# Note: There's no at-birth standards for weight-for-length, so elements 1 +# and 4 have `NA` values +wlz <- gigs_wlz(weight_kg = wt_kg, + lenht_cm = len_cm, + age_days = age_days, + gest_days = gest_days, + sex = sex, + id = ids) +print(wlz) + +# Head circumference-for-age z-score (HCAZ) +hcaz <- gigs_hcaz(headcirc_cm = head_cm, + age_days = age_days, + gest_days = gest_days, + sex = sex, + id = ids) +print(hcaz) +} diff --git a/man/ig_fet.Rd b/man/ig_fet.Rd index a839148..c1fa41f 100644 --- a/man/ig_fet.Rd +++ b/man/ig_fet.Rd @@ -5,15 +5,15 @@ \alias{ig_fet} \title{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Standards growth curve data} \source{ -\href{https://intergrowth21.tghn.org/pregnancy-dating/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Pregnancy Dating (CRL)} +\href{https://intergrowth21.com/tools-resources/pregnancy-dating/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Pregnancy Dating (CRL)} -\href{https://intergrowth21.tghn.org/symphysis-fundal-height/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Symphysis-Fundal Height standard} +\href{https://intergrowth21.com/tools-resources/symphysis-fundal-height/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Symphysis-Fundal Height standard} -\href{https://intergrowth21.tghn.org/fetal-growth/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Growth standards} +\href{https://intergrowth21.com/tools-resources/fetal-growth/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Growth standards} -\href{https://intergrowth21.tghn.org/fetal-doppler/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Doppler standards} +\href{https://intergrowth21.com/tools-resources/fetal-doppler/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Doppler standards} -\href{https://intergrowth21.tghn.org/gestational-weight-gain/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Gestational Weight Gain standard} +\href{https://intergrowth21.com/tools-resources/gestational-weight-gain/}{INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Gestational Weight Gain standard} } \description{ A set of nested lists containing tables with reference values at different @@ -21,6 +21,11 @@ z-scores/centiles for valid gestational ages in days. The list is ordered by acronym first, then by z-score/centile (as available - some Fetal standards only have centile tables). } +\note{ +Where possible, tables were taken from the online sources here. If not +available on the INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} website, they were taken from +the publications listed here. +} \examples{ names(gigs::ig_fet) head(gigs::ig_fet$hcfga$zscores) diff --git a/man/ig_fet_estimate_fetal_weight.Rd b/man/ig_fet_estimate_fetal_weight.Rd index 233fd48..bc8ebbc 100644 --- a/man/ig_fet_estimate_fetal_weight.Rd +++ b/man/ig_fet_estimate_fetal_weight.Rd @@ -40,8 +40,3 @@ Stirnemann J, Villar J, Salomon LJ, Ohuma EO, Lamber A, Victoria CG et al. Project.} \emph{Ultrasound Obstet Gynecol} 2016, \strong{49:478-486} \doi{10.1002/uog.17347} } -\seealso{ -Get z-scores/centiles for estimated fetal weights at known -gestational ages using the \code{\link[=ig_fet_value2zscore]{ig_fet_value2zscore()}} or -\code{\link[=ig_fet_value2centile]{ig_fet_value2centile()}} functions, respectively. -} diff --git a/man/ig_nbs.Rd b/man/ig_nbs.Rd index 498d7f7..dea76c3 100644 --- a/man/ig_nbs.Rd +++ b/man/ig_nbs.Rd @@ -27,20 +27,19 @@ names(gigs::ig_nbs) head(gigs::ig_nbs$wfga$male$zscores) } \references{ -Villar J, Giuliani F, Fenton TR, Ohuma EO, Ismail LC, Kennedy SH et al. -\strong{INTERGROWTH-21st very preterm size at birth reference charts.} \emph{Lancet} -2016, \strong{387(10021):844-45.} \doi{10.1016/S0140-6736(16)00384-6} - Villar J, Cheikh Ismail L, Victora CG, Ohuma EO, Bertino E, Altman DG, et al. \strong{International standards for newborn weight, length, and head circumference by gestational age and sex: the Newborn Cross-Sectional Study of the INTERGROWTH-21st Project.} \emph{Lancet} 2014, \strong{384(9946):857-68.} \doi{10.1016/S0140-6736(14)60932-6} +Villar J, Giuliani F, Fenton TR, Ohuma EO, Ismail LC, Kennedy SH et al. +\strong{INTERGROWTH-21st very preterm size at birth reference charts.} \emph{Lancet} +2016, \strong{387(10021):844-45.} \doi{10.1016/S0140-6736(16)00384-6} + Villar J, Puglia FA, Fenton TR, Ismal LC, Staines-Urias E, Giuliani F, et al. \strong{Body composition at birth and its relationship with neonatal anthropometric -ratios: the newborn body composition study of the INTERGROWTH-21st -project.} \emph{Pediatric Research} 2017, \strong{82:305-316.} -\doi{10.1038/pr.2017.52} +ratios: the newborn body composition study of the INTERGROWTH-21st project.} +\emph{Pediatric Research} 2017, \strong{82:305-316.} \doi{10.1038/pr.2017.52} } \keyword{data} diff --git a/man/life6mo.Rd b/man/life6mo.Rd index bd66174..866ed69 100644 --- a/man/life6mo.Rd +++ b/man/life6mo.Rd @@ -6,7 +6,7 @@ \title{Data extract from the Low birthweight Infant Feeding Exploration (LIFE) study} \format{ A data frame with 2,191 rows and 10 variables: -\itemize{ +\describe{ \item{\code{id}:}{ Unique ID for each infant in the dataset (1--300).} \item{\code{visitweek}:}{ Chronological age in weeks (±1) when study visit occurred (0--26).} diff --git a/man/report_units.Rd b/man/report_units.Rd new file mode 100644 index 0000000..d9a0fdf --- /dev/null +++ b/man/report_units.Rd @@ -0,0 +1,35 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/conversion.R +\name{report_units} +\alias{report_units} +\title{Check required units for a conversion using gigs} +\usage{ +report_units(family, acronym) +} +\arguments{ +\item{family}{A single string denoting the family of growth standards in use. +Must be one of \code{"ig_fet"}, \code{"ig_nbs"}, \code{"ig_png"}, or \code{"who_gs"}, or the +function will throw an error. This argument is case-sensitive.} + +\item{acronym}{A single string denoting the specific growth standard in use. +The allowed values of \code{acronym} depend on the value of \code{family}, and are +listed in the documentation for the \code{x} argument. Incompatible \code{family} and +\code{acronym} values will cause errors to be thrown. This argument is +case-sensitive.} +} +\value{ +Returns a message describing which units are required for conversion +in the desired growth standard. +} +\description{ +Check required units for a conversion using gigs +} +\examples{ +# Get units for working with the IG-21st Newborn Size Standard for +# weight-for-GA +report_units("ig_nbs", "wfga") + +# Get units for working with the IG-21st Fetal Standard for +# gestational weight gain +report_units("ig_fet", "gwgfga") +} diff --git a/man/shared_roxygen_params.Rd b/man/shared_roxygen_params.Rd index 415436b..61209da 100644 --- a/man/shared_roxygen_params.Rd +++ b/man/shared_roxygen_params.Rd @@ -6,7 +6,7 @@ \arguments{ \item{y}{Numeric vector of length one or more with anthropometric measurement(s) to convert to centiles/z-scores. Units depend on which -\code{acronym}(s) are in use.} +\code{acronym} is in use.} \item{z, p}{Numeric vector of length one or more with centiles/z-scores to convert to values. For \code{p}, gigs will warn you if elements of \code{p} are not @@ -22,7 +22,7 @@ Many of the parameters in \verb{[gigs]} are shared between different functions. This roxygen block makes sharing these parameters more simple. } \note{ -Input vectors other than \code{acronym} are recycled by +Input vectors other than \code{acronym} and \code{family} are recycled by \code{\link[vctrs:vec_recycle]{vctrs::vec_recycle_common()}}, and must adhere to the \link{vctrs} recycling rules. } diff --git a/man/shared_value2zscore_returns.Rd b/man/shared_value2zscore_returns.Rd deleted file mode 100644 index 4f8f6ee..0000000 --- a/man/shared_value2zscore_returns.Rd +++ /dev/null @@ -1,15 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/data.R -\name{shared_value2zscore_returns} -\alias{shared_value2zscore_returns} -\title{Shared value to z-score/centile roxygen parameters} -\value{ -Numeric vector of z-scores/centiles with length equal to the longest -input vector. -} -\description{ -Much of the roxygen content in \verb{[gigs]} is shared between different -functions. This roxygen block is designed to make inheriting these parameters -more simple. -} -\keyword{internal} diff --git a/man/shared_zscore2value_returns.Rd b/man/shared_zscore2value_returns.Rd deleted file mode 100644 index d58362f..0000000 --- a/man/shared_zscore2value_returns.Rd +++ /dev/null @@ -1,15 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/data.R -\name{shared_zscore2value_returns} -\alias{shared_zscore2value_returns} -\title{Shared z-score/centile to value roxygen parameters} -\value{ -Numeric vector of expected measurements with length equal to the -longest input vector. -} -\description{ -Much of the roxygen content in \verb{[gigs]} is shared between different -functions. This roxygen block is designed to make inheriting these parameters -more simple. -} -\keyword{internal} diff --git a/man/value2zscore.Rd b/man/value2zscore.Rd new file mode 100644 index 0000000..5010d9a --- /dev/null +++ b/man/value2zscore.Rd @@ -0,0 +1,112 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/conversion.R +\name{value2zscore} +\alias{value2zscore} +\alias{value2centile} +\title{Convert anthropometric measures to z-scores/centiles using international +growth standards} +\usage{ +value2zscore(y, x, sex = NULL, family, acronym) + +value2centile(y, x, sex = NULL, family, acronym) +} +\arguments{ +\item{y}{Numeric vector of length one or more with anthropometric +measurement(s) to convert to centiles/z-scores. Units depend on which +combination of \code{family} and \code{acronym} are in use, which you can check with +\code{\link[=report_units]{report_units()}}. By default, GIGS will warn you if elements in \code{y} are +missing (\code{NA}) or undefined (\code{NaN}/\code{Inf}), and replace the latter with +\code{NA}. You can customise this behaviour using the \link[=gigs_options]{GIGS package-level options}.} + +\item{x}{Numeric vector of x values, which take on different units depending +on the growth standard in use. To know which units to use, run +\code{report_units(family, acronym)}. Limits for each combination are as +follows: +\itemize{ +\item WHO Growth Standards (family = \code{"who_gs"}) +\itemize{ +\item Between 0 and 1856 days for \code{"wfa"}, \code{"bfa"}, \code{"lhfa"}, and \code{"hcfa"}. +\item Between 45 and 110 cm for \code{"wfl"}. +\item Between 65 and 120 cm for \code{"wfh"}. +\item Between 91 and 1856 days for \code{"acfa"}, \code{"ssfa"}, \code{"tsfa"}. +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Standards (family = \code{"ig_fet"}) +\itemize{ +\item Between 98 and 280 days for \code{"hcfga"}, \code{"bpdfga"}, \code{"acfga"}, +\code{"flfga"}, \code{"ofdfga"}, and\if{html}{\out{
}} \code{"tcdfga"}. +\item Between 154 and 280 days for \code{"efwfga"}. +\item Between 112 and 294 days for \code{"sfhfga"}. +\item Between 58 and 105 days for \code{"crlfga"}. +\item Between 19 and 95 mm for \code{"gafcrl"}. +\item Between 105 and 280 days for \code{"gwgfga"}. +\item Between 168 and 280 days for \code{"pifga"}, \code{"rifga"}, and \code{"sdrfga"} (the +INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Doppler standards). +\item Between 12 and 55 mm for\code{"tcdfga"}. +\item Between 105 and 252 days for \code{"poffga"}, \code{"sffga"}, \code{"avfga"}, \code{"pvfga"}, +and \code{"cmfga"} (the INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Brain Development +standards). +\item Between 126 and 287 days for \code{"hefwfga"} (the INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} +standard for Hadlock-based estimated fetal weight). +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Newborn Size Standards (family = \code{"ig_nbs"}) +\itemize{ +\item Between 168 and 300 days for \code{"wfga"}, \code{"lfga"}, \code{"hcfga"}, and +\code{"wlrfga"}. +\item Between 266 and 280 days for \code{"fmfga"}, \code{"bfpfga"}, and \code{"ffmfga"}. +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Postnatal Growth Standards (family = +\code{"ig_png"}) +\itemize{ +\item Between 27 and 64 weeks for \code{"wfa"}, \code{"lfa"}, and \code{"hcfa"}. +\item Between 35 and 65 cm for \code{"wfl"}. +} +} + +By default, gigs will replace out-of-bounds elements in \code{x} with \code{NA} and +warn you. It will also warn you about elements in \code{x} which are missing +(\code{NA}) or undefined (\code{NaN}/\code{Inf}). You can customise this behaviour using +the \link[=gigs_options]{GIGS package-level options}.} + +\item{sex}{Character vector of length one or more with sex(es), either \code{"M"} +(male) or \code{"F"} (female). This argument should be left as \code{NULL} (the +default) if \code{family == "ig_fet"}. This argument is case-sensitive. By +default, gigs will replace elements of \code{sex} which are not \code{"M"} or \code{"F"} +with \code{NA} and warn you. You can customise this behaviour using the \link[=gigs_options]{GIGS package-level options}.} + +\item{family}{A single string denoting the family of growth standards in use. +Must be one of \code{"ig_fet"}, \code{"ig_nbs"}, \code{"ig_png"}, or \code{"who_gs"}, or the +function will throw an error. This argument is case-sensitive.} + +\item{acronym}{A single string denoting the specific growth standard in use. +The allowed values of \code{acronym} depend on the value of \code{family}, and are +listed in the documentation for the \code{x} argument. Incompatible \code{family} and +\code{acronym} values will cause errors to be thrown. This argument is +case-sensitive.} +} +\value{ +Numeric vector of z-scores/centiles with length equal to the longest +input vector. +} +\description{ +Convert anthropometric measures to z-scores/centiles using international +growth standards +} +\note{ +Inputs other than \code{acronym} and \code{family} will be recycled by +\code{\link[vctrs:vec_recycle]{vctrs::vec_recycle_common()}}, and must adhere to the \link{vctrs} recycling +rules. +} +\examples{ +# Convert in the weight-for-age standard from the WHO Child Growth Standards +value2zscore(3, 0, "M", family = "who_gs", acronym = "wfa") + +# Or obtain centiles... +value2centile(3, 0, "M", family = "who_gs", acronym = "wfa") + +# Inputs will be recycled if necessary +value2centile(3, 0, c("M", "F"), family = "ig_nbs", acronym = "wfga") +} +\seealso{ +\code{\link[=report_units]{report_units()}} will tell you the units needed for \code{y} and \code{x}, for +any combination of \code{family} and \code{acronym}. +} diff --git a/man/who_gs_coeffs.Rd b/man/who_gs_coeffs.Rd index dbd4007..bc575a8 100644 --- a/man/who_gs_coeffs.Rd +++ b/man/who_gs_coeffs.Rd @@ -17,11 +17,6 @@ names(gigs::who_gs_coeffs) head(gigs::who_gs_coeffs$lhfa$male) } \references{ -de Onis M, Garza C, Victora CG, Onyango AW, Frongillo EA, Martines J. \strong{The -WHO Multicentre Growth Reference Study: planning, study design, and -methodology} \emph{Food Nutr Bull.} 2004, \strong{25(1 Suppl):S15-26.} -\doi{10.1177/15648265040251s104} - World Health Organisation. \strong{WHO child growth standards: length/height-for-age, weight-for-age, weight-for-length, weight-for-height and body mass index-for-age: methods and development.} \emph{Technical report, @@ -31,9 +26,5 @@ World Health Organisation. \strong{WHO child growth standards: head circumference-for-age, arm circumference-for-age, triceps skinfold-for-age and subscapular skinfold-for-age: methods and development.} \emph{Technical report, WHO, Geneva}, 2007. - -Cole TJ. \strong{The LMS method for constructing normalized growth standards.} -\emph{Eur J Clin Nutr.} 1990, \strong{44(1):45-60.} PMID: -\href{https://pubmed.ncbi.nlm.nih.gov/2354692/}{2354692} } \keyword{data} diff --git a/man/zscore2value.Rd b/man/zscore2value.Rd new file mode 100644 index 0000000..c241d10 --- /dev/null +++ b/man/zscore2value.Rd @@ -0,0 +1,97 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/conversion.R +\name{zscore2value} +\alias{zscore2value} +\alias{centile2value} +\title{Convert z-scores/centiles to anthropometric measures using international +growth standards} +\usage{ +zscore2value(z, x, sex = NULL, family, acronym) + +centile2value(p, x, sex = NULL, family, acronym) +} +\arguments{ +\item{z, p}{Numeric vector of length one or more with centiles/z-scores to +convert to values. For \code{p}, gigs will warn you if elements of \code{p} are not +between \code{0} and \code{1}. You can customise this behaviour using the \link[=gigs_options]{GIGS package-level options}.} + +\item{x}{Numeric vector of x values, which take on different units depending +on the growth standard in use. To know which units to use, run +\code{report_units(family, acronym)}. Limits for each combination are as +follows: +\itemize{ +\item WHO Growth Standards (family = \code{"who_gs"}) +\itemize{ +\item Between 0 and 1856 days for \code{"wfa"}, \code{"bfa"}, \code{"lhfa"}, and \code{"hcfa"}. +\item Between 45 and 110 cm for \code{"wfl"}. +\item Between 65 and 120 cm for \code{"wfh"}. +\item Between 91 and 1856 days for \code{"acfa"}, \code{"ssfa"}, \code{"tsfa"}. +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Standards (family = \code{"ig_fet"}) +\itemize{ +\item Between 98 and 280 days for \code{"hcfga"}, \code{"bpdfga"}, \code{"acfga"}, +\code{"flfga"}, \code{"ofdfga"}, and\if{html}{\out{
}} \code{"tcdfga"}. +\item Between 154 and 280 days for \code{"efwfga"}. +\item Between 112 and 294 days for \code{"sfhfga"}. +\item Between 58 and 105 days for \code{"crlfga"}. +\item Between 19 and 95 mm for \code{"gafcrl"}. +\item Between 105 and 280 days for \code{"gwgfga"}. +\item Between 168 and 280 days for \code{"pifga"}, \code{"rifga"}, and \code{"sdrfga"} (the +INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Doppler standards). +\item Between 12 and 55 mm for\code{"tcdfga"}. +\item Between 105 and 252 days for \code{"poffga"}, \code{"sffga"}, \code{"avfga"}, \code{"pvfga"}, +and \code{"cmfga"} (the INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Fetal Brain Development +standards). +\item Between 126 and 287 days for \code{"hefwfga"} (the INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} +standard for Hadlock-based estimated fetal weight). +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Newborn Size Standards (family = \code{"ig_nbs"}) +\itemize{ +\item Between 168 and 300 days for \code{"wfga"}, \code{"lfga"}, \code{"hcfga"}, and +\code{"wlrfga"}. +\item Between 266 and 280 days for \code{"fmfga"}, \code{"bfpfga"}, and \code{"ffmfga"}. +} +\item INTERGROWTH-21\if{html}{\out{}}st\if{html}{\out{}} Postnatal Growth Standards (family = +\code{"ig_png"}) +\itemize{ +\item Between 27 and 64 weeks for \code{"wfa"}, \code{"lfa"}, and \code{"hcfa"}. +\item Between 35 and 65 cm for \code{"wfl"}. +} +} + +By default, gigs will replace out-of-bounds elements in \code{x} with \code{NA} and +warn you. It will also warn you about elements in \code{x} which are missing +(\code{NA}) or undefined (\code{NaN}/\code{Inf}). You can customise this behaviour using +the \link[=gigs_options]{GIGS package-level options}.} + +\item{sex}{Character vector of length one or more with sex(es), either \code{"M"} +(male) or \code{"F"} (female). This argument should be left as \code{NULL} (the +default) if \code{family == "ig_fet"}. This argument is case-sensitive. By +default, gigs will replace elements of \code{sex} which are not \code{"M"} or \code{"F"} +with \code{NA} and warn you. You can customise this behaviour using the \link[=gigs_options]{GIGS package-level options}.} + +\item{family}{A single string denoting the family of growth standards in use. +Must be one of \code{"ig_fet"}, \code{"ig_nbs"}, \code{"ig_png"}, or \code{"who_gs"}, or the +function will throw an error. This argument is case-sensitive.} + +\item{acronym}{A single string denoting the specific growth standard in use. +The allowed values of \code{acronym} depend on the value of \code{family}, and are +listed in the documentation for the \code{x} argument. Incompatible \code{family} and +\code{acronym} values will cause errors to be thrown. This argument is +case-sensitive.} +} +\value{ +Numeric vector of expected measurements with length equal to the +longest input vector. +} +\description{ +Convert z-scores/centiles to anthropometric measures using international +growth standards +} +\examples{ +# Convert in the weight-for-age standard from the WHO Child Growth Standards +zscore2value(-2:2, 0, "M", family = "who_gs", acronym = "wfa") + +# Or obtain centiles... +centile2value(pnorm(-2:2), 0, "M", family = "who_gs", acronym = "wfa") +}