# getting_started

    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")
    #> 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.

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)
    #> [1]  52 139