Skip to content

Commit

Permalink
Merge branch 'main' into 80_speedup_derive_funcs
Browse files Browse the repository at this point in the history
  • Loading branch information
@zdz2101
zdz2101 authored Aug 5, 2024
2 parents 29878ee + b73922a commit 8498059
Show file tree
Hide file tree
Showing 4 changed files with 106 additions and 125 deletions.
2 changes: 1 addition & 1 deletion DESCRIPTION
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Type: Package
Package: admiralpeds
Title: Pediatrics Extension Package for ADaM in 'R' Asset Library
Version: 0.1.0.9000
Version: 0.1.0.9001
Authors@R: c(
person("Fanny", "Gautier", , "[email protected]", role = c("aut", "cre")),
person("Ross", "Farrugia", role = "aut"),
Expand Down
2 changes: 1 addition & 1 deletion NEWS.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# admiralpeds 0.1.0.9000
# admiralpeds 0.1.0.9001

- Initial package release focused mainly on Anthropometric indicators (i.e. child growth
development charts).
1 change: 1 addition & 0 deletions inst/WORDLIST
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Hoffmann
LMS
LOCF
SDTM
SDs
anthropometric
bds
der
Expand Down
226 changes: 103 additions & 123 deletions vignettes/advs.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,17 +19,13 @@ library(admiraldev)

# Introduction

This article describes creating a vital signs ADaM for pediatric
clinical trials. The main focus is around Anthropometric indicators
(i.e. growth development chart) parameter derivations for Height, Weight, Body
Mass Index (BMI), and Head Circumference.
This article describes creating a vital signs ADaM for pediatric clinical trials. This package creates SD scores (z-scores) and percentiles among children and adolescents for various body measures, such as Height, Weight, Body Mass Index (BMI), Weight-for-Length, and Head Circumference. Among adults, standard cut-points can be used (e.g., a BMI \>= 30 for obesity), but because of the large changes that occur during growth and development, these measures are typically expressed relative to other children of the same sex and age. For example, the CDC classifies obesity as a BMI-for-age \>= 95th percentile (a z-score of 1.645), while the WHO cut point is a weight-for-length \>= 3 SDs among children under 2 years of age.

We advise you first consult the `{admiral}` [Creating a BDS Finding ADaM
vignette](https://pharmaverse.github.io/admiral/articles/bds_finding.html).
The programming workflow around how to create the general set-up of an
ADVS using `{admiral}` functions is the same as this, so to save
repeating information and maintaining the same content in two places we
have instead opted to only focus on the pediatric-specific steps here.
The programming workflow around creating the general set-up of an ADVS using
`{admiral}` functions is the same. We focus on only the pediatric-specific steps here to avoid repeating
information and maintaining the same content in two places.

**Note**: *All examples assume CDISC SDTM and/or ADaM format as input
unless otherwise specified.*
Expand All @@ -46,8 +42,7 @@ unless otherwise specified.*

## Metadata {#metadata}

Once the required packages have been loaded, the first step is then to
prepare the metadata.
Once the required packages have been loaded, the first step is preparing the metadata.

```{r message=FALSE}
library(admiral)
Expand All @@ -58,17 +53,16 @@ library(rlang)
library(stringr)
```

Here we have made some default decisions in the package as to which
metadata to use but you are free to replace these with any other source
you prefer (as long as you keep the structure of the dataframe
consistent - as expected by our downstream functions). For example, you
might want to use a different age range selection of WHO metadata
Here, we have made some default decisions regarding which metadata to use in the
package. But you are free to replace these with any other source you prefer
(as long as you keep the structure of the dataframe consistent - as expected by our
downstream functions). For example, you might want to use a different age range selection of WHO metadata
(such as including WHO reference data for between ages [5-19
years](https://www.who.int/tools/growth-reference-data-for-5to19-years/indicators))
or even alternatively the International Obesity Task Force standards.
or the International Obesity Task Force reference data.

The selection of standard reference files we included and used as
metadata for this package are as follows:
The selection of growth reference files we included and used as metadata
for this package are as follows:

- [2000 CDC Growth
Charts](https://www.cdc.gov/growthcharts/percentile_data_files.htm)
Expand All @@ -80,28 +74,33 @@ metadata for this package are as follows:

### Reference Files for Parameters by Age

As growth rates and patterns differ between sex, different reference
values are used accordingly and for different age groups.

For the applicable parameters here (height/weight/BMI), we made the
default decision to rely on the WHO standards for children \<2 years of
age (\<730.5 days) and CDC standards for children \>=2 years of age
(\>=730.5 days). This is made in accordance with the [CDC
recommendation](https://www.cdc.gov/growthcharts/who_charts.htm).

So, the first step here needed is to combine the various metadata by
parameter and ensuring sex and age are shown in a consistent way.
For weight-based indicators we keep WHO and CDC metadata separate due to the WHO
adjustment (restricted application of the LMS method) needed for the
anthropometric indicator derivations.

Additionally, as the CDC growth charts only offer monthly intervals we
took advice from an ex-CDC expert in this area and made the decision in
our template to add interpolation code so that we have a record for each
day of age. When converting the CDC months into days we use rounding
to bring them to a whole number of days. If you would prefer to rely
solely on the monthly chart here, then you could remove the rounding
and the call to the `derive_interp_records()` function.
As growth rates and patterns differ by age and sex, reference values differ by
these two characteristics.

For the various measures, we use the WHO reference data for children <2 years
of age (\<730.5 days) and CDC growth charts for children >=2 years of age
(\>=730.5 days).
This is in accord with the [CDC
recommendation](https://www.cdc.gov/growthcharts/who_charts.htm). The reference
data for both charts include the LMS parameters, in which L is the Box-Cox
transformation for normality, M is the median, and S is the coefficient of
variation.

So, the first step is combining the metadata for each measure and ensuring sex
and age are shown consistently.
We separate WHO and CDC metadata for weight-based derivations due to
(1) the WHO adjustment (restricted application of the LMS method) and
(2) the CDC extended method for high BMIs.

Additionally, as the CDC growth charts only offer monthly age intervals, on the
advice of a retired CDC expert in this area, we added interpolation code in our
template to have a record for each day of age.
When converting the CDC months into days (30.4375 days in a month), we rounded
to the nearest whole number of days. Relying on the monthly charts will result
in less accurate calculations, particularly for weight and height values among
children who are 2 years of age.
If you would prefer to rely solely on the monthly chart here, then you could
remove the rounding and the call to the `derive_interp_records()` function.

We do this pre-processing of the metadata using the following code for BMI
as an example:
Expand Down Expand Up @@ -157,7 +156,7 @@ dataset_vignette(
)
```

As well as similar for the CDC metadata:
Similarly, for the CDC metadata:

```{r, eval=TRUE, echo=FALSE}
cdc_bmi_for_age <- cdc_bmi_for_age %>%
Expand All @@ -169,33 +168,27 @@ dataset_vignette(
)
```

To help interpret this metadata: the LMS parameters are the median (M), the
generalized coefficient of variation (S), and the power in the Box-Cox
transformation (L).
For BMI in the CDC metadata, a dispersion parameter (Sigma) is used to calculate
BMI percentiles and z-scores above the sex- and age-specific 95th percentile (P95).

For CDC metadata only, Sigma is the dispersion parameter used in the calculation
of BMI percentiles and z-scores above the 95th percentile, and P95 represents
this sex and age-specific 95th percentile.

The above example only shows the parameter BMI, but similar follows for the
other parameters like weight and height (except no Sigma and P95 for those),
and for height we are able to combine WHO and CDC metadata as there is no WHO
adjustment needed.
Note that the head circumference parameter metadata comes only from
the WHO standards, as no equivalent for \>2 years of age are provided by CDC.
The above example only shows the parameter BMI, but this follows other parameters
like weight and height. We can combine WHO and CDC metadata for height as a
WHO adjustment is unnecessary.
Note that the head circumference parameter metadata comes only from the WHO reference data,
as CDC provides no equivalent for children \> 2 years of age.

### Reference Files for Weight by Length/Height

WHO provides additional standards for weight by body length (recumbent length),
instead of age. For these we again combined the metadata for sex so that we have
a single reference file.
WHO provides additional reference data for weight-for-length (recumbent length),
instead of age. Again, we combined the metadata for sex to create a single
reference file.

There are also weight by height files available, but upon advice from an ex-CDC
expert in this area we chose to only include the by body length files, as once
children are able to stand then BMI by age is a more appropriate measure to use.
However, in our template we do give the metadata values variable a more generic
name as `HEIGHT_LENGTH` so that any user could equally choose to pass weight by
height files if they so preferred.
There are also weight-by-height files available, but upon advice from a retired
CDC expert in this area, we chose only to include the weight-for-length files,
as once children can stand, BMI by age is a more appropriate measure to use.
However, in our template, we give the metadata values variable a generic name,
`HEIGHT_LENGTH`, so that any user could equally choose to pass weight-for-height
files if preferred.

We do this using the following code:

Expand All @@ -222,8 +215,8 @@ dataset_vignette(

## Initial ADVS Set-up {#advs_start}

The next step would be reading in the source data, merging ADSL
variables and deriving the usual ADVS analysis variables. The
The following steps are to read in the source data, merge ADSL variables,
and derive the usual ADVS analysis variables. The
`{admiral}` [Creating a BDS Finding ADaM
vignette](https://pharmaverse.github.io/admiral/articles/bds_finding.html)
gives detailed guidance on all these steps.
Expand Down Expand Up @@ -310,27 +303,14 @@ advs <- advs %>%

## Derive Additional Variables for Anthropometric indicators {#derive_vars}

In order to be able to compare against the reference files we need to
know each child's age and length/height respectively at the time of each
vital signs assessment. So these need to be first derived as variables
in your ADVS.
To compare against the reference files, we need to know each child's age and
length/height at the time of each vital signs assessment.
So, these need to be first derived as variables in your ADVS.

Remember to ensure that the unit of these matches that of the reference
files metadata you are comparing against, i.e. "days" for age and "cm"
for length/height in our examples here.

Note that some of the standard reference files we use here have
different units and intervals themselves. For example when you look at
the "by Age" charts WHO provides this by day but CDC gives this every
half month. So when converting all as days this still leaves the
challenge of how to join when the patient's current age falls between an
interval (e.g. between 24.5 and 25 months for CDC). Here in our package
functions we took the simple approach to use the nearest age from the
metadata, rather than apply some form of interpolation. An alternative
method you could use would be to derive current age according to the
exact same intervals as the metadata in order for an exact join, but in
our examples we just kept this by days.

### Derived Variables for Parameters by Age

A variable for current analysis age could be achieved using the
Expand Down Expand Up @@ -376,14 +356,14 @@ advs <- advs %>%

## Derive Additional Parameters for Anthropometric indicators {#derive_params}

Now we get to the most important section where we show how to create the
new records for each derived pediatrics parameter. Only certain examples
are included here, but you'll find more parameters in the example
template script referenced at the bottom of this vignette.
Now, we get to the most important section, which shows how to create new records
for each derived pediatrics parameter.
Only specific examples are included here, but you'll find more parameters in the
example template script referenced at the bottom of this vignette.

### Derived Parameters by Age

Parameters for BMI by Age z-score and percentile could be achieved using
Parameters for BMI-for-age z-scores and percentiles could be achieved using
the `derive_params_growth_age()` function as follows:

```{r eval=TRUE}
Expand Down Expand Up @@ -424,31 +404,33 @@ advs <- advs %>%
)
```

In the rare case where only z-score or percentile was needed and not
both then you could leave out either of the respective `set_values_to_`
If only a z-score or percentile were needed, you leave out one of the `set_values_to_`
arguments.

Here it is important once again to remind of the importance of the
metadata being supplied to the above function via the `meta_criteria`
argument. In our default case from this package this is taking WHO
standards for children \<2 years of age and CDC standards for children
\>=2 years of age. You as the user are free to supply any other choice
of metadata here from the reference files you prefer.

For BMI parameters only, you'll notice from the code above that we have
set `bmi_cdc_correction = TRUE`. This is because we opted to use the CDC
developed extended percentiles (\>95%) to monitor high BMI values here.
If you left this argument as default `FALSE` value then from the CDC metadata
only the 2000 CDC Growth Chart for BMI would be used.

For any weight-based indicator (including BMI), you'll also see in the code
Once again, it is essential to remember the importance of the metadata being
supplied to the above function via the `meta_criteria` argument.
Our default case from this package uses WHO reference data for children \< 2 years of
age and CDC reference data for children \>= 2 years of age. As the user, you can
use other (e.g., International Obesity Task Force) reference data files created with the LMS method.

For BMI only, you'll notice from the code above that we have
set `bmi_cdc_correction = TRUE`. This is because we used the CDC
extended percentiles (\> 95th percentile) to monitor high BMI values here.
If you left this argument as default `FALSE` value, only the 2000 CDC Growth
Chart for BMI would be used from the CDC metadata. In 2022, the CDC released
extended percentiles (and z-scores) for BMIs \> 95th percentile because the
original CDC method did not accurately characterize very high BMIs.

For all weight-based parameters (including BMI), you'll also see in the code
above that we have set `who_correction = TRUE`. This comes from the
[WHO Child Growth Standards Guidelines](https://www.who.int/publications/i/item/924154693X)
(see document page 302). The rationale is that WHO constructed a restricted
application of the LMS method here.
Of course if you were choosing to not use WHO metadata then you could
equally leave `who_correction = FALSE` and only the usual LMS method would
be applied.
(pages 301-304). This correction is made because the WHO used the LMS method only
for weight-based measures for which the calculated z-scores were
between -3 and +3; this correction allows for the calculation of more
extreme z-scores. If you are not using the WHO metadata
(or WHO metadata for length or head circumference), you could leave
`who_correction = FALSE`, and only the usual LMS method would be applied.
WHO recommends using this correction for all parameters that involve weight (including BMI).

Here is how these newly derived parameters look:

Expand All @@ -462,18 +444,18 @@ dataset_vignette(
```

For height parameters by age, it should be noted that the WHO growth chart
that we use for children \<2 years of age refers to body length, whereas
we use for children \<2 years of age refers to body length, whereas
the CDC growth chart for children \>=2 years of age refers to height.
This is explained thoroughly in the next section.

### Derived Weight by Length/Height

Parameters for Weight by Length/Height z-score and percentile for children under
2 years of age could be achieved using the following code, where it assumes the
"HEIGHT" parameter is always collected as body length (recumbent length).
The following code is for Weight by Length/Height z-score and percentile for
children \< 2 years of age, which assumes the "HEIGHT" parameter is always
collected as recumbent length.

You'll notice the `derive_params_growth_height()` function used is very similar
to that used above, but now passing in height instead of age.
to that used above, but now passing in height or length instead of age.

```{r eval=FALSE}
advs <- advs %>%
Expand All @@ -500,24 +482,22 @@ advs <- advs %>%
)
```

We consulted with an acting pediatrician who advised that rarely investigators
are guided as to which measure to use. It depends mainly on the age
at which the child is able to stand (2 years on average) as well
as the preference of the measurer.
We consulted with a pediatrician with extensive experience working with length
and height data, who advised that analysts rarely know whether standing height
or recumbent length was measured. It depends mainly on the age at which the
child can stand (on average, two years) and the preference of the measurer.

If you have strict CRF (case report form) guidelines that standing height
(rather than body length) was measured, you could add 0.7 cm to these values to
approximate the child’s body length. Or alternatively you could provide a
different source of reference files by height which could allow for this
parameter derivation for children \>2 years of age, but this is not our package
recommendation.
approximate the child’s body length.

## Remaining ADVS Set-up {#advs_end}

All remaining steps such as merging on the parameter level values and
variables such as analysis flags are all covered in the `{admiral}`
The `{admiral}`
[Creating a BDS Finding ADaM
vignette](https://pharmaverse.github.io/admiral/articles/bds_finding.html).
vignette](https://pharmaverse.github.io/admiral/articles/bds_finding.html)
covers all remaining steps, such as merging the parameter-level values,
variables, and analysis flags.

# Example Scripts {#example}

Expand Down

0 comments on commit 8498059

Please sign in to comment.