getting_started"
In bodycompref: Reference Values for CT-Assessed Body Composition

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(bodycompref)

Using bodycompref

Purpose

bodycompref aims to provide a fast, batch-compatible way to calculate different versions of reference values of CT-assessed skeletal muscle and adipose tissue.

Briefly, the underlying LMSP models model the distribution of a body composition metric (e.g. cross-sectional skeletal muscle area at the T5 vertebral level) based on age. Separate models are available for females and males. For more information about the underlying research and a visual representation please visit https://bodycomp-metrics.mgh.harvard.edu

If you use this package, please make sure you credit us with a citation:

citation("bodycompref")

Installation

To install the package from CRAN use the usual installation:

install.packages("bodycompref")

Alternatively, install directly from github:

install.packages("devtools")
devtools::install_github("p-mq/bodycompref")

Since CRAN has strict limits on file size, the reference LMSP models for the reference values are stored in their own data repositories. Install these using the following commands:

# Models for adipose tissue, ~60Mb
install.packages("adiposerefdata", repos="https://p-mq.github.io/drat")
# Models for skeletal muscle, ~45Mb
install.packages("musclerefdata", repos="https://p-mq.github.io/drat")

Note that this option might require installation of the drat package.

Alternatively, version 1.0.0 and 1.1.0 still contain all the models inside the main package are still available on GitHub

Usage

You can use a dedicated method to calculate each of the four possible transformations:

reference_percentile calculates the percentile of a given measurement, i.e. how many out of 100 evenly distributed values would be lower
reference_z_scores calculates how many standard deviations above (positive values) or below (negative values) the median a given value is
percent_predicted calculates how many percent of the expected (i.e. median) value a given value is, e.g. 200 for a value double that of the median
reference_values reverses these transformations and returns the absolute measurement value corresponding to a given input (either a percentile or a z-score)

Alternatively, you can use the wrapper bodycomp_reference, which wraps all four of these functions, and specify the desired return.

Input parameters are mostly equal among all functions. Data inputs can be passed as vectors to use batch-processing. Naturally, vectors need to be of equal length:

metric: A character (vector), body composition metric. Available metrics are "CSMA", "SMI", "SMRA", "SMG", "CSFA", "SATI", "SATRA", "SATG", "CSVFA", "VATI", "VATRA", "VATG", "TAT", "TATI", and "VAT_SAT_ratio"
sex: A character (vector), ""Female" or "Male"
level: A character (vector), target vertebral level, options are "T5", "T8", "T10", "L3". Please note that for metrics derived from visceral adipose tissue only L3 is available.
age: An integer (vector), age. Please not that the age range is restricted to 39-79 (see citation paper for more information)
measurement: A numeric (vector), raw value of measurement

reference_values replaces the input 'measurement' with one of the following: + percentile: A numeric (vector), percentile to return value for. If both percentile and z_score are given, only percentile is evaluated + z_score numeric (vector), z score to return value for. If both percentile and z_score are given, only percentile is evaluated

In a practical setting, batch-calculation of percent of predicted value for cross-sectional fat area of a 40-yo Female and a 60-yo male might look like this:

# Creating example data
metric <- c("CSFA", "CSFA")
sex <- c("Female", "Male")
level <- c("T5", "T8")
age <- c(40, 60)
measurement <- c(109, 220)

# Actual calculation
bodycompref::percent_predicted(metric, sex, level, age, measurement)