| Type: | Package |
| Title: | Z-Score Calculator for Biomarkers: Childhood to Young Adulthood |
| Version: | 0.1.1 |
| Description: | Provides tools to compute individual percentile ranks and z-scores for clinical biomarkers in children, adolescents and young adults, based on age-, sex-, and height-specific reference data from the IDEFICS (Identification and prevention of Dietary and lifestyle-induced health EFfects In Children and infantS) study and the Biomarkers4Pediatrics collaboration. Supports the computation of a composite Metabolic Syndrome (MetS) score and associated monitoring/action levels for health monitoring. For more details see Ahrens et al. (2014) <doi:10.1038/ijo.2014.130>. |
| License: | GPL-3 |
| Encoding: | UTF-8 |
| URL: | https://github.com/bips-hb/pediatric.zcalc |
| BugReports: | https://github.com/bips-hb/pediatric.zcalc/issues |
| LazyData: | true |
| Depends: | R (≥ 3.5.0) |
| Imports: | gamlss.dist, pracma |
| Config/roxygen2/version: | 8.1.0 |
| Suggests: | testthat (≥ 3.0.0) |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2026-09-21 13:27:56 UTC; maendle |
| Author: | Andreas Mändle [aut, cre], Timm Intemann [aut], Zülal Bekerecioglu [aut] |
| Maintainer: | Andreas Mändle <maendle@leibniz-bips.de> |
| Repository: | CRAN |
| Date/Publication: | 2026-09-30 09:40:02 UTC |
Calculate Metabolic Syndrome (MetS) Score
Description
Computes a composite MetS score from individual z-scores of clinical biomarkers.
Usage
MetSScore(df)
Arguments
df |
A data frame containing the following columns: 'waist_z.score', 'homa_z.score', 'sbp_z.score', 'dbp_z.score', 'trg_z.score', and 'hdl_z.score'. These are expected to be numeric vectors representing z-scores. |
Details
The MetS score is computed as:
'waist_z + homa_z + 0.5 × (sbp_z + dbp_z + trg_z - hdl_z)'
Value
A numeric vector representing the calculated MetS score for each row in the input data.
Examples
df <- data.frame(
waist_z.score = c(1.2, 0.5),
homa_z.score = c(0.8, 0.6),
sbp_z.score = c(0.7, 0.3),
dbp_z.score = c(0.6, 0.4),
trg_z.score = c(1.0, 0.9),
hdl_z.score = c(-0.5, -0.2)
)
MetSScore(df)
Compute IDEFICS and B4P Scores for Multiple Variables
Description
Applies 'get_scores()' to multiple clinical biomarkers in a data frame and optionally returns MetS and cutoff levels.
Usage
ScoreCalc(
df,
return_input = FALSE,
return_values = c("percentile", "z.score", "MetS", "cutoff.levels")
)
Arguments
df |
A data frame with columns: 'sex', 'age', 'height', and observed values for any of the supported variables: 'bmi', 'glu', 'hdl', 'height', 'homa', 'insu', 'trg', 'waist', 'sbp', 'dbp', 'crp'. Variables must be supplied using the units of the corresponding reference model:
'height' is required for the height-dependent blood-pressure models ('sbp' and 'dbp'). |
return_input |
Logical. If 'TRUE', includes original input columns in the result. Defaults to 'FALSE'. |
return_values |
Character vector. Specifies which scores to compute. Options include '"percentile"', '"z.score"', '"MetS"', and '"cutoff.levels"'. |
Details
The function applies 'get_scores()' to each recognized variable in the input and combines the results. If '"MetS"' is requested, a Metabolic Syndrome score is computed and optionally transformed to percentile ranks/z-scores.
Value
A data frame with score columns named as '<variable>_percentile', '<variable>_z.score', etc. Includes additional columns like 'MetS' or cutoff levels if requested.
Examples
df <- data.frame(
sex = c("f", "m"),
age = c(8, 15),
height = c(120, 125),
waist = c(55, 60),
homa = c(1.2, 1.4),
sbp = c(100, 105),
dbp = c(65, 70),
trg = c(80, 90), # mg/dL
crp = c(6, 2), # mg/L
hdl = c(50, 45) # mg/dL
)
ScoreCalc(df, return_values = c("percentile", "cutoff.levels"))
# for the 15 year old male everything except CRP is NA (outside IDEFICS age range)
Compute Action Levels
Description
Assigns monitoring or action levels based on individual percentile ranks using standard IDEFICS thresholds.
Usage
action_levels(
df,
sex = NULL,
lvl_name = c("none", "monit", "action"),
perc_level = c(0.9, 0.95),
append = FALSE,
filter = NULL
)
Arguments
df |
A data frame containing percentile columns such as 'waist_percentile', 'sbp_percentile', 'hdl_percentile', etc. |
sex |
Character vector. Same length as 'age', 'height', and 'values'. Accepts "f" for female or "m" for male. |
lvl_name |
Character vector of level labels. Defaults to 'c("none", "monit", "action")'. |
perc_level |
Numeric vector of two percentiles used as cutoffs. Defaults to 'c(0.9, 0.95)' for 90th and 95th percentile. |
append |
Logical. If 'TRUE', appends action level columns to 'df'. If 'FALSE', returns only the computed levels. |
filter |
Character. Optional. Limits calculation to a specific domain: '"adiposity"', '"blood_pressure"', '"blood_lipids"', '"blood_glu_insu"', or '"overall"'. |
Details
Action levels are derived using 'cut()' on percentile values. For example, a value > 95th percentile maps to '"action"'. HDL is reversed ('1 - hdl_percentile') since low HDL values are considered unhealthy.
Value
A list (or a modified data frame if 'append = TRUE') containing action level classifications for each domain.
Examples
df <- data.frame(waist_percentile = c(0.85, 0.96))
action_levels(df)
df <- data.frame(
hdl_percentile = c(0.1,0.5),
homa_percentile = c(0.4,0.9),
trg_percentile = c(0.6,0.5),
waist_percentile = c(0.9,0.99),
sbp_percentile = c(0.8,0.01)
)
action_levels(df)
df <- data.frame(
#sex = c("m", "m"),
hdl_percentile = c(0.1,0.5),
homa_percentile = c(0.4,0.9),
trg_percentile = c(0.6,0.5),
crp_percentile = c(0.95, 0.9),
waist_percentile = c(0.9,0.99),
sbp_percentile = c(0.8,0.01)
)
action_levels(df, sex = c("m", "m"))
2D Interpolation Function Constructor
Description
Creates a closure that performs 2D interpolation over a grid using pracma::interp2.
Usage
approxfun2(x, y, Z, method = "linear")
Arguments
x |
Numeric vector. Grid values along the x-axis. |
y |
Numeric vector. Grid values along the y-axis. |
Z |
Matrix. Grid values corresponding to (x, y). |
method |
Character. Interpolation method; default is "linear". |
Value
A function that takes 'x' and 'y' (e.g. for age and height) vectors and returns interpolated values for 'z'.
Calculate Scores for Children and Young Adults
Description
Computes age-, sex- and (for 'sbp' and 'dbp') height-specific percentile ranks or z-scores for clinical biomarkers using IDEFICS study reference data and Biomarkers4Pediatrics collaboration (for 'crp').
Usage
get_scores(
variable = "waist",
sex = c("f", "m"),
age = 6:5,
height = NULL,
values = c(20, 21),
return_values = c("percentile", "z.score")
)
Arguments
variable |
Character. The variable to assess. Must be one of the supported variables ("waist", "bmi", "hdl", "sbp", "dbp", "trg", "homa", "glu", "height","insu", or "crp"). |
sex |
Character vector. Same length as 'age', 'height', and 'values'. Accepts "f" for female or "m" for male. |
age |
Numeric vector. Ages of the children/young adults in years. Must be between 1 and 22.5 for 'crp', and between 2 and 11 otherwise. |
height |
Numeric vector or NULL. Required for height-dependent models ('sbp' and 'dbp'). Defaults to NULL. |
values |
Numeric vector. Observed values of the variable to score.
Values must be supplied in the units used by the corresponding reference
model: 'waist' and 'height' in cm; 'bmi' in kg/m^2; 'sbp' and 'dbp'
in mmHg; 'trg' and 'hdl' in mg/dL; 'glu' in mg/dL; 'insu' in
|
return_values |
Character vector. Specifies which outputs to return. Options include "percentile", "z.score". |
Details
For triglycerides ('trg'), the original IDEFICS scoring procedure applies sex-specific percentile and z-score values at 45 mg/dL, corresponding to the lower measurement limit used in the IDEFICS study. These values are retained here to reproduce the original IDEFICS score calculation.
Value
A named list containing the requested scores. Each element is a numeric vector of the same length as 'values'.
Examples
get_scores(
variable = "crp",
sex = c("f","f"),
age = c(3, 12),
values = c(4, 0.5)
)
get_scores(
variable="dbp",
sex=c("f","m"),
age=c(5,5),
height=c(120,110),
values=c(70,60)
)
get_scores(
variable = "trg",
sex = c("f", "m"),
age = c(5.8, 6.5),
values = c(50, 48) # mg/dL
)
Internal distribution parameter tables for percentile curve models to derive z-scores used by the scoring system
Description
These datasets provide the distribution parameters (e.g., mu, sigma, nu, tau) used internally for score calculation across different variables and sex categories.
Usage
par_bmi_boys
par_bmi_girls
par_waist_boys
par_waist_girls
par_MetS_shifted_boys
par_MetS_shifted_girls
par_sbp_boys
par_sbp_girls
par_dbp_boys
par_dbp_girls
par_glu_boys
par_glu_girls
par_hdl_boys
par_hdl_girls
par_height_boys
par_height_girls
par_homa_boys
par_homa_girls
par_insu_boys
par_insu_girls
par_trg_boys
par_trg_girls
par_crp_girls
par_crp_boys
Format
A data frame containing distribution parameters for each variable and sex.
An object of class data.frame with 91 rows and 5 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 80 rows and 5 columns.
An object of class data.frame with 80 rows and 5 columns.
An object of class data.frame with 2411 rows and 7 columns.
An object of class data.frame with 2385 rows and 7 columns.
An object of class data.frame with 2411 rows and 7 columns.
An object of class data.frame with 2385 rows and 7 columns.
An object of class data.frame with 80 rows and 4 columns.
An object of class data.frame with 80 rows and 4 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 90 rows and 6 columns.
An object of class data.frame with 80 rows and 6 columns.
An object of class data.frame with 80 rows and 6 columns.
An object of class data.frame with 80 rows and 6 columns.
An object of class data.frame with 80 rows and 6 columns.
An object of class data.frame with 90 rows and 5 columns.
An object of class data.frame with 90 rows and 5 columns.
An object of class data.frame with 2151 rows and 7 columns.
An object of class data.frame with 2151 rows and 7 columns.
Details
Not intended for direct use by end users.
Create a Sex- and Age-Specific Interpolation Function
Description
Constructs a closure that returns interpolated values based on sex and age. Internally selects from precomputed interpolation functions.
Usage
mkfun_sex_age(vname, param)
Arguments
vname |
Character. Variable name (e.g., "bmi", "waist"). |
param |
Character. Distribution parameter (e.g., "mu", "sigma"). |
Value
A function with signature '(sex, age)' returning interpolated values.
Create a Sex-, Age-, and Height-Specific Interpolation Function
Description
Constructs a closure for interpolating values that depend on sex, age, and height. Chooses appropriate internal spline function based on 'vname' and 'param'.
Usage
mkfun_sex_age_height(vname, param)
Arguments
vname |
Character. Variable name (e.g., "bmi", "waist"). |
param |
Character. Distribution parameter (e.g., "mu", "sigma"). |
Value
A function with signature '(sex, age, height)' returning interpolated values.
Calculate Percentile Ranks for the Hurdle Model
Description
Computes individual percentile ranks using a hurdle model described by p1, mu, sigma, nu, and tau by combining the probability from the first part of the hurdle model ('p1') with the conditional distribution of the second part.
Usage
p_hurdle(y, p1, mu, sigma, nu, tau)
Arguments
y |
Numeric vector. Observed values of the variable to assess. |
p1 |
Numeric vector. Probability from the first part of the hurdle model. |
mu |
Numeric vector. Location parameter of the continuous distribution. |
sigma |
Numeric vector. Scale parameter of the continuous distribution. |
nu |
Numeric vector. Shape parameter of the continuous distribution. |
tau |
Numeric vector. Tail parameter of the continuous distribution. |
Value
A numeric vector of the same length as 'y' containing the calculated individual percentile ranks.