diff --git a/inst/WORDLIST b/inst/WORDLIST index 43df49d..328dced 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -16,6 +16,7 @@ Hoffmann LMS LOCF SDTM +SDs anthropometric bds der diff --git a/vignettes/advs.Rmd b/vignettes/advs.Rmd index e7b5501..c2d4009 100644 --- a/vignettes/advs.Rmd +++ b/vignettes/advs.Rmd @@ -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.* @@ -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) @@ -57,17 +52,16 @@ library(lubridate) 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) @@ -79,28 +73,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: @@ -156,7 +155,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 %>% @@ -168,33 +167,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: @@ -221,8 +214,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. @@ -309,27 +302,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 @@ -375,14 +355,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} @@ -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: @@ -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 %>% @@ -501,24 +483,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}