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")
#> To cite package 'bodycompref' in publications use:
#> 
#>   JP M, PE T, ND M, A G, B A, ML B, EJ S, DP K, FJ F (2024).
#>   "Subcutaneous and Visceral adipose tissue Reference Values from
#>   Framingham Heart Study Thoracic and Abdominal CT." _Investigative
#>   Radiology_.
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     title = {Subcutaneous and Visceral adipose tissue Reference Values from Framingham Heart Study Thoracic and Abdominal CT},
#>     author = {Marquardt JP and Tonnesen PE and Mercaldo ND and Graur A and Allaire B and Bouxsein ML and Samelson EJ and Kiel DP and Fintelmann FJ},
#>     journal = {Investigative Radiology},
#>     year = {2024},
#>   }

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.

NOTE: Due to an error in calculating the models still included in the 1.x versions, only the most recent version of the package can be used.

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 programmatically restricted to 38-80 but the data (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)
#> [1]  52 139