*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},
#> }
```

To install the package from CRAN use the usual installation:

Alternatively, install directly from github:

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

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: