-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
454 lines (389 loc) · 24 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%",
dev.args = list(png = list(type = "cairo"))
)
intergrowth21st <- knitr::asis_output(x = "INTERGROWTH-21<sup>st</sup>")
library(gigs)
```
```{r srr-tags-1, eval = FALSE, echo = FALSE}
#' srr-tags-readme
#'
#' @srrstats {G1.1} Addressed existence of other packages/implementations in
#' section on 'Other packages'.
#' @srrstats {EA1.0, EA1.1, EA1.2} Addressed target audience, kinds of data,
#' and kinds of questions addressable through gigs.
```
# gigs <img src="man/figures/logo.png" align="right" height="138" />
<!-- badges: start -->
[](https://github.com/lshtm-gigs/gigs/actions/workflows/R-CMD-check.yaml)
[](https://www.repostatus.org/#active)
[](https://www.r-pkg.org/pkg/gigs)
[](https://github.com/lshtm-gigs/gigs/actions?query=workflow%3Apkgcheck)
[](https://github.com/lshtm-gigs/gigs/actions/workflows/test-coverage.yaml)
[](https://codecov.io/github/lshtm-gigs/gigs)
<!-- badges: end -->
## Overview
Produced as part of the Guidance for International Growth Standards project at
the London School of Hygiene & Tropical Medicine, **gigs** provides a single,
simple interface for working with the WHO Child Growth standards and outputs
from the `r intergrowth21st` project. You will find functions for converting
from anthropometric measures (e.g. weight or length) to z-scores and centiles,
and the inverse. Also included are functions for classifying newborn and infant
growth according to literature-based cut-offs.
**gigs** is of use to anyone interested in fetal and child growth, including
child health researchers, policymakers, and clinicians. This package is best
suited to growth data where the gestational age (GA) of each child is known, as
the use of the growth standards included in **gigs** is GA-dependent.
We recommend you check out the
[available standards](#available-international-growth-standards) section to
see if your anthropometric measurements can be converted to z-scores/centiles by
**gigs**. We recommend using **gigs** to generate continuous or categorical
measures of fetal/newborn/child growth, which can then be used in downstream
analyses.
## Installation
```{r installation, eval = FALSE}
# You can install the development version from GitHub with `remotes`:
# install.packages("remotes")
remotes::install_github(repo = "lshtm-gigs/gigs")
```
## Terminology
```{r srr-tags-2, eval = FALSE, echo = FALSE}
#' @srrstats {G1.3} Explained z-scores and centiles prior to discussing
#' functions which convert between these and measured values.
```
GIGS operates on anthropometric measurements, and can convert between these and
*z-scores*/*centiles*. Z-scores and centiles represent the location of a
measurement within a normal distribution of values, such that:
* A *z-score* is the number of standard deviations from the mean for a given
anthropometric measurement (e.g. height or weight).
* A *centile* represents the proportion of measurements in some distribution
which we would expect to be lower than a measurement we've taken. In *gigs*,
these are represented as a value between `0` and `1`. For example, `0.5`
corresponds to the 50<sup>th</sup> centile (i.e. the mean), whereas `0.75`
corresponds to the 75<sup>th</sup> centile.
In growth data, z-scores and centiles represent the size a fetus, newborn, or
child relative to its peers. Its size is considered relative to some
standardising variable, which is usually age but could also be another variable
such as their length. By tracking a child's relative size as they
grow, you can see if they are achieving their growth potential or not. If not,
this may indicate underlying issues such as ill health or undernutrition.
## Classification functions
GIGS includes a number of functions which permit fast identification of at-risk
infants through classification of suboptimal growth. The cut-offs used are
sourced from research literature; you can check the function documentation to
see these sources.
### Growth classification in `data.frame`-like objects
Use the `classify_growth()` function to quickly compute growth indicators in
`data.frame`-like objects. All `classify_*()`-style functions in GIGS use
[data-masking](https://rlang.r-lib.org/reference/args_data_masking.html), so you
provide a `data.frame`-like object in the `.data` argument and then refer to
your column names directly. In `classify_growth()`, you can also use the
`.analyses` argument to specify which growth indicators you want to classify.
```{r examples_classification}
life6mo_newborns <- gigs::life6mo[life6mo$age_days == 0, ]
# Use classify_growth() to get multiple growth indicators at once
life6mo_classified <- classify_growth(
.data = life6mo_newborns,
gest_days = gestage,
age_days = age_days,
sex = as.character(sex),
weight_kg = wt_kg,
lenht_cm = len_cm,
id = as.factor(id),
.outcomes = c("svn", "stunting")
)
head(life6mo_classified, n = 4)
```
When using `classify_growth()`, you will be informed which of the analyses you
wanted to run were successful. In the example below, because `lenht_cm` is not
specified, stunting indicators cannot be computed.
```{r examples_classification3}
life6mo_classified <- classify_growth(
.data = life6mo_newborns,
gest_days = gestage,
age_days = age_days,
sex = as.character(sex),
weight_kg = wt_kg,
id = as.factor(id),
.outcomes = c("svn", "stunting")
)
head(life6mo_classified, n = 4)
```
You can also use `classify_*()` functions which are specific to the growth
indicator you'd like to calculate, for example `classify_svn()` to get small,
vulnerable newborn classifications for each infant:
```{r examples_classification2}
# Small vulnerable newborns - note no ID parameter, as it is assumed that all
# measures are taken at birth
life6mo_svn <- classify_svn(
.data = life6mo_newborns,
weight_kg = wt_kg,
gest_days = gestage,
sex = as.character(sex)
)
head(life6mo_svn, n = 4)
```
## Conversion functions
### Available international growth standards
GIGS facilitates the proper use of international growth standards, which
are growth charts developed using international samples of healthy singleton
children born to mothers that had their health needs met during pregnancy.
They represent an international standard of 'optimal' growth. GIGS implements
international growth standards from the WHO and `r intergrowth21st` project:
* `ig_nbs` - `r intergrowth21st` Newborn Size standards (including very preterm)
<details><summary>Component standards</summary>
| Acronym | Description | Unit | `x` range |
|----------|-------------------------------|-------|-----------------|
| `wfga` | weight-for-GA | kg | 168 to 300 days |
| `lfga` | length-for-GA | cm | 168 to 300 days |
| `hcfga` | head circumference-for-GA | cm | 168 to 300 days |
| `wlrfga` | weight-to-length ratio-for-GA | kg/cm | 168 to 300 days |
| `ffmfga` | fat-free mass-for-GA | kg | 266 to 294 days |
| `bfpfga` | body fat percentage-for-GA | % | 266 to 294 days |
| `fmfga` | fat mass-for-GA | kg | 266 to 294 days |
</details>
* `ig_png` - `r intergrowth21st` Postnatal Growth of Preterm Infants standards
<details><summary>Component standards</summary>
| Acronym | Description | Unit | `x` range |
|---------|----------------------------|------|-----------------------|
| `wfa` | weight-for-age | kg | 27 to ≤64 exact weeks |
| `lfa` | length-for-age | cm | 27 to ≤64 exact weeks |
| `hcfa` | head circumference-for-age | cm | 27 to ≤64 exact weeks |
| `wfl` | weight-for-length | kg | 35 to 65 cm |
</details>
* `ig_fet` - `r intergrowth21st` Fetal standards
<details><summary>Component standards</summary>
| Acronym | Description | Unit | `x` range |
|-----------|--------------------------------------------------------------|------|-----------------|
| `hcfga` | head circumference-for-GA | mm | 98 to 280 days |
| `bpdfga` | biparietal diameter-for-GA | mm | 98 to 280 days |
| `acfga` | abdominal circumference-for-GA | mm | 98 to 280 days |
| `flfga` | femur length-for-GA | mm | 98 to 280 days |
| `ofdfga` | occipito-frontal diameter for-GA | mm | 98 to 280 days |
| `efwfga` | estimated fetal weight-for-GA | g | 154 to 280 days |
| `sfhfga` | symphisis-fundal height-for-GA | mm | 112 to 294 days |
| `crlfga` | crown-rump length-for-GA | mm | 58 to 105 days |
| `gafcrl` | GA-for-crown-rump length | days | 15 to 95 mm |
| `gwgfga` | gestational weight gain-for-GA | kg | 98 to 280 days |
| `pifga` | pulsatility index-for-GA | | 168 to 280 days |
| `rifga` | resistance index-for-GA | | 168 to 280 days |
| `sdrfga` | systolic/diastolic ratio-for-GA | | 168 to 280 days |
| `tcdfga` | transcerebellar diameter-for-GA | mm | 98 to 280 days |
| `tcdfga` | GA-for-transcerebellar diameter | mm | 98 to 280 days |
| `poffga` | parietal-occipital fissure-for-GA | mm | 105 to 252 days |
| `sffga` | Sylvian fissue-for-GA | mm | 105 to 252 days |
| `avfga` | anterior horn of the lateral ventricle-for-GA | mm | 105 to 252 days |
| `pvfga` | atrium of the posterior horn of the lateral ventricle-for-GA | mm | 105 to 252 days |
| `cmfga` | cisterna magna-for-GA | mm | 105 to 252 days |
| `hefwfga` | Hadlock estimated fetal weight-for-GA | g | 126 to 287 days |
</details>
* `who_gs` - WHO Child Growth Standards for term infants
<details><summary>Component standards</summary>
| Acronym | Description | Unit | `x` range |
|---------|------------------------------|------------------|-----------------|
| `wfa` | weight-for-age | kg | 0 to 1856 days |
| `bfa` | BMI-for-age | kg/m<sup>2</sup> | 0 to 1856 days |
| `lhfa` | length/height-for-age | cm | 0 to 1856 days |
| `hcfa` | head circumference-for-age | cm | 0 to 1856 days |
| `wfl` | weight-for-height | kg | 45 to 110 cm |
| `wfh` | weight-for-length | kg | 65 to 120 cm |
| `acfa` | arm circumference-for-age | cm | 91 to 1856 days |
| `ssfa` | subscapular skinfold-for-age | mm | 91 to 1856 days |
| `tsfa` | triceps skinfold-for-age | mm | 91 to 1856 days |
</details>
### Usage
Conversion functions are named according to the conversion they perform. Either
they convert measured values to z-scores/centiles
(`value2zscore()`/`value2centile()`), or they generate expected values for given
z-scores/centiles (`zscore2value()`/`centile2value()`).
You tell gigs which international growth standard to use with the `family` and
`acronym` parameters. The `family` parameter tells gigs which set of standards
you want to use - e.g. `"ig_nbs"` for the `r intergrowth21st` Newborn Size
standards (including very preterm). The `acronym` parameter describes which
exact growth standard you want out of all the growth standards in your 'family'
of standards.
For example, to convert *values to z-scores* in the *weight-for-GA* standard
from the *`r intergrowth21st` Newborn Size standards*, you would run
`value2zscore(..., family = "ig_nbs", acronym = "wfga")`.
Similarly, the conversion of length-for-age values to centiles in term and
preterm infants could be performed with the *WHO Child Growth standards* and
*`r intergrowth21st` Postnatal Growth of Preterm Infants standards*,
respectively:
* Preterm infants: `value2centile(..., family = "ig_png", acronym = "lfa")`
* Term infants: `value2centile(..., family = "who_gs", acronym = "lhfa")`
If you don't know which units are used for a given growth standard, the
`report_units()` function will help you. Run it with your `family` and `acronym`
combination to get help:
```{r report_units}
report_units(family = "ig_nbs", acronym = "wfga")
```
### Values to z-scores/centiles
These functions allow easy conversion from measured values to z-scores or
centiles for the standard used.
```{r example_v2zp}
# Convert from z-scores for individual values...
value2zscore(y = 0.785, x = 182, sex = "F",
family = "ig_nbs", acronym = "wfga") |>
round(digits = 2)
# .. or for multiple inputs
value2centile(y = 0.785, x = seq(175, 196, by = 7), sex = "F",
family = "ig_nbs", acronym = "wfga") |>
round(digits = 2)
# You can also get centiles
value2centile(y = c(2.86, 3.12, 3.12, 3.43, 3.77, 4.10), x = 40, sex = "M",
family = "ig_png", acronym = "wfa") |>
round(digits = 2)
```
### Z-scores/centiles to values
These functions convert z-scores to expected anthropometric measurements. They
are mostly useful for the creation of reference curves (see below).
```{r example_zp2v}
# Convert from z-scores for individual values...
zscore2value(z = 0, x = 182, sex = "F",
family = "ig_nbs", acronym = "wfga") |>
round(digits = 3)
# .. or for multiple inputs
zscore2value(z = 0, x = seq(182, 204, by = 7), sex = "F",
family = "ig_nbs", acronym = "wfga") |>
round(digits = 3)
# You can do the same for centiles
centile2value(p = c(0.1, 0.25, 0.5, 0.75, 0.9), x = 40, sex = "M",
family = "ig_png", acronym = "wfa") |>
round(digits = 2)
```
#### Reference curves
We can use gigs to generate reference curves for the standards by getting
curves for the expected weight at multiple z-scores across multiple gestational
ages. We would usually recommend [`ggplot2`](https://ggplot2.tidyverse.org/) for
such visualisation, but do not use it here to reduce our package's dependencies.
```{r example_zp2v_curves, dev = "png", fig.alt = "A growth chart for weight against gestational age, with lines for each SD from +2 to -2."}
z_score_range <- -2:2
gestage_range <- 168:230
ref <- mapply(z_score_range,
FUN = function(z) {
gigs::zscore2value(z = z,
x = gestage_range,
sex = "F",
family = "ig_nbs",
acronym = "wfga")
})
matplot(ref, x = gestage_range, col = 1:5, type = "l", lty = 2:6,
xlab = "Gestational age (days)",
ylab = "Weight (kg)")
title(main = "Weight-for-GA in very preterm newborns")
legend(x = min(gestage_range) + 1, y = ref[length(ref)], legend = 2:-2,
title = "Z-score", col = 5:1, lty = 2:6)
```
# Other packages
```{r arrows_and_bench_data, echo = FALSE}
ig21st <- if (knitr::is_html_output()) {
knitr::asis_output(x = "IG-21<sup>st</sup>")
} else {
knitr::asis_output(x = "IG-21\textsupercript{st}")
}
larr <- knitr::asis_output(x = "←")
rarr <- knitr::asis_output(x = "→")
harr <- knitr::asis_output(x = "↔")
yes <- if (knitr::is_html_output()) {
knitr::asis_output(x = "✅")
} else {
knitr::asis_output(x = "✓")
}
no <- if (knitr::is_html_output()) {
knitr::asis_output(x = "❌")
} else {
knitr::asis_output(x = "✘")
}
half <- if (knitr::is_html_output()) {
knitr::asis_output(x = "⚠️")
} else {
knitr::asis_output(x = "⚠")
}
anthro <- knitr::asis_output(x = "[anthro](https://cran.r-project.org/web/packages/anthro/index.html)")
AGD <- knitr::asis_output(x = "[AGD](https://cran.r-project.org/web/packages/AGD/index.html)")
childsds <- knitr::asis_output(x = "[childsds](https://cran.r-project.org/web/packages/childsds/index.html)")
gigs_r <- knitr::asis_output(x = "[gigs](https://www.github.com/lshtm-gigs/gigs/)")
growthstans <- knitr::asis_output(x = "[ki-tools/growthstandards](https://www.github.com/ki-tools/growthstandards/)")
sitar <- knitr::asis_output(x = "[sitar](https://cran.r-project.org/web/packages/sitar/index.html)")
zscorer <- knitr::asis_output(x = "[zscorer](https://cran.r-project.org/web/packages/zscorer/index.html)")
gigs_stata <- knitr::asis_output(x = "[gigs](https://www.github.com/lshtm-gigs/gigs-stata/) (Stata)")
zanthro <- knitr::asis_output(x = "[zanthro](https://journals.sagepub.com/doi/epdf/10.1177/1536867X1301300211) (Stata)")
intergrowth <- knitr::asis_output(x = "[nutriverse/intergrowth](https://github.com/nutriverse/intergrowth/)")
load("vignettes/articles/benchmarking.rda")
```
Other R packages can be used to analyse growth data with international
standards, but have limitations which are not present in gigs. There are also
software packages external to R which implement these standards. The table
below describes these packages, and to what extent they have implemented
functions that let users convert anthropometric measurements to
z-scores/centiles in each set of standards implemented in gigs - the WHO Child
Growth standards, `r intergrowth21st` Newborn Size standards (including Very
Preterm), and the `r intergrowth21st` Postnatal Growth standards for preterm
infants. A tick (`r yes`) indicates that all possible standards are included in
a package, a red cross (`r no`) indicates that these standards are completely
missing, and a warning sign (`r half`) indicates that some of these standards
are implemented but not others.
| Software | Platform | WHO (0-5 years) | `r ig21st` NBS | `r ig21st` PNG | `r ig21st` Fetal | Functionality |
|-----------------|----------|-----------------|----------------|----------------|------------------|-----------------------------------|
| `r gigs_r` | R | `r yes` | `r yes` | `r yes` | `r yes` | Values `r harr` z-scores/centiles |
| `r anthro` | R | `r yes` | `r no` | `r no` | `r no` | Values `r rarr` z-scores |
| `r AGD` | R | `r yes` | `r no` | `r no` | `r no` | Values `r harr` z-scores |
| `r childsds` | R | `r yes` | `r no` | `r no` | `r no` | Values `r rarr` z-scores/centiles |
| `r growthstans` | R | `r yes` | `r yes` | `r half` | `r half` | Values `r harr` z-scores/centiles |
| `r intergrowth` | R | `r no` | `r no` | `r no` | `r half` | Values `r rarr` z-scores/centiles |
| `r gigs_stata` | Stata | `r yes` | `r yes` | `r yes` | `r yes` | Values `r harr` z-scores/centiles |
| `r zanthro` | Stata | `r yes` | `r no` | `r no` | `r no` | Values `r rarr` z-scores/centiles |
We have benchmarked some of these implementations against each other for
conversion of values to z-scores in the WHO Child Growth Standards and different
sets of `r intergrowth21st` standards. The table below shows relative speed of
each software package when processing 100,000 inputs. The code used to generate
these timings can be seen online in the GIGS benchmarking
[article](https://lshtm-gigs.github.io/gigs/articles/benchmarking.html).
| Software | Platform | WHO (0-5 years) (ms) | `r ig21st` NBS (ms) | `r ig21st` PNG (ms) | `r ig21st` Fetal (ms) |
|:----------------|----------|-------------------------------------------|----------------------------------------|----------------------------------------|-----------------------------------------|
| `r gigs_r` | R | `r max_len_bench[[1]][["gigs"]]` | `r max_len_bench[[2]][["gigs"]]` | `r max_len_bench[[3]][["gigs"]]` | `r max_len_bench[[4]][["gigs"]]` |
| `r anthro` | R | `r max_len_bench[[1]][["anthro"]]` | `r no` | `r no` | `r no` |
| `r AGD` | R | `r max_len_bench[[1]][["AGD"]]` | `r no` | `r no` | `r no` |
| `r childsds` | R | `r max_len_bench[[1]][["childsds"]]` | `r no` | `r no` | `r no` |
| `r growthstans` | R | `r max_len_bench[[1]][["gs"]]` | `r max_len_bench[[2]][["gs"]]` | `r max_len_bench[[3]][["gs"]]` | `r max_len_bench[[4]][["gs"]]` |
| `r intergrowth` | R | `r no` | `r no` | `r no` | `r max_len_bench[[4]][["intergrowth"]]` |
| `r sitar` | R | `r max_len_bench[[1]][["sitar"]]` | `r no` | `r no` | `r no` |
| `r zscorer` | R | NA | `r no` | `r no` | `r no` |
| `r gigs_stata` | Stata | `r max_len_bench[[1]][["stata_gigs"]]` | `r max_len_bench[[2]][["stata_gigs"]]` | `r max_len_bench[[3]][["stata_gigs"]]` | `r max_len_bench[[4]][["stata_gigs"]]` |
| `r zanthro` | Stata | `r max_len_bench[[1]][["stata_zanthro"]]` | `r no` | `r no` | `r no` |
Note: `zscorer` is NA because we couldn't time it for 100,000 inputs (it takes
too long).
```{r srr-tags-3, eval = FALSE, echo = FALSE}
#' @srrstats {G1.5, G1.6} The linked article contains code for both performance
#' and accuracy claims when comparing this package with other software
#' packages.
```
The WHO and `r intergrowth21st` standards are also available in standalone form,
available from the [WHO
website](https://www.who.int/tools/child-growth-standards/software) and
[`r intergrowth21st`
website](https://intergrowth21.com/),
respectively. The `r intergrowth21st` website also includes download links for
Excel-based calculators in some standards.
## Authors + Citation
**S. R. Parker** Maternal, Adolescent, Reproductive, and Child Health
Centre, London School of Hygiene & Tropical Medicine
**Dr L. Vesel** Ariadne Labs, Brigham and Women’s Hospital Harvard T.H.
Chan School of Public Health
**Professor E. O. Ohuma** Maternal, Adolescent, Reproductive, and Child
Health Centre, London School of Hygiene & Tropical Medicine
### Citation
Parker S, Vesel L, Ohuma EO (2024). *gigs: Assess Fetal, Newborn, and
Child Growth*. <https://github.com/lshtm-gigs/gigs/>.
## Code of Conduct
Please note that the gigs project is released with a [Contributor Code of
Conduct](https://ropensci.org/code-of-conduct/). By contributing to this project
you agree to abide by its terms.