Title:	Standardizing Physiological Composite Risk Endpoints
Version:	0.4.1
URL:	https://score-project.org, https://github.com/JWiley/score-project
BugReports:	https://github.com/JWiley/score-project/issues
Description:	Provides a number of functions to simplify and automate the scoring, comparison, and evaluation of different ways of creating composites of data. It is particularly aimed at facilitating the creation of physiological composites of metabolic syndrome symptom score (MetSSS) and allostatic load (AL). Provides a wrapper to calculate the MetSSS on new data using the Healthy Hearts formula.
License:	LGPL-3
Encoding:	UTF-8
Depends:	R (≥ 4.0.0), methods
Imports:	stats, ggplot2, reshape2, lavaan, JWileymisc (≥ 1.3.0)
Suggests:	testthat, covr, knitr, rmarkdown
VignetteBuilder:	knitr
LazyData:	false
RoxygenNote:	7.3.2
Collate:	'MetSSS.R' 'MetSSS_model.R' 'methods.R' 'misc.R' 'classes.R' 'composite.R' 'onLoad.R' 'predictions.R'
NeedsCompilation:	no
Packaged:	2025-07-17 22:56:07 UTC; jwile
Author:	Joshua F. Wiley [aut, cre]
Maintainer:	Joshua F. Wiley <jwiley.psych@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-17 23:10:02 UTC

Internal function to prepare data for prediction

Description

Internal function to prepare data for prediction

Usage

.preparePredict(object, newdata, groups)

Arguments

Value

An object of S4 class “CompositeReady”

Biomarker Thresholds Database

Description

This data set lists the clinical high risk thresholds for a variety of biomarkers

Format

a list.

Source

Various publications

An constructor function for the S4 CompositeData class

Description

An constructor function for the S4 CompositeData class

Usage

CompositeData(rawdata, groups, thresholds, higherisbetter, k, rawtrans)

Arguments

Value

An S4 object of class “CompositeData”

Examples

## no custom raw data transformations
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE))

## square root transform qsec
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE),
  rawtrans = list(
    mpg = function(x) x,
    hp = function(x) x,
    wt = function(x) x,
    qsec = sqrt))

## cleanup
rm(d)

A S4 class to represent data for creating a composite

Description

A S4 class to represent data for creating a composite

Slots

rawdata

A data frame of the data to be used for the composite scores

groups

A character string, the same length as the number of rows of the data indicating to which group each row belong. May be all the same if only one group present in the data.

thresholds

A list with as many elements as there are unique groups in the data, and where each element is a vector the same length as the number of columns in the data frame, indicating the reference thresholds for each variable, by group (all the same if only one group).

higherisbetter

A logical vector the same length as the number of columns in the data frame, indicating whether higher is better for each variable (if TRUE) and otherwise (if FALSE) that lower is better, indicating that variable should be reversed.

k

The number of variables as an integer.

rawtrans

A list of functions to transform the raw data (and thresholds).

An constructor function for the S4 CompositeReady class

Description

An constructor function for the S4 CompositeReady class

Usage

CompositeReady(
  data,
  covmat,
  sigma,
  standardize,
  use.prethreshold,
  distances,
  distanceDensity,
  winsorizedValues,
  better,
  rawdata,
  groups,
  thresholds,
  higherisbetter,
  k,
  rawtrans
)

Arguments

Value

An S4 object of class “CompositeReady”

Examples

#make me!

An S4 class to represent composite ready data

Description

An S4 class to represent composite ready data

Slots

data

A data frame ready for use to generate composite scores

covmat

A covariance matrix

sigma

The standard deviation of each variable

standardize

A logical value whether standardization was applied

distances

A data frame of the distance scores

distanceDensity

A ggplot2 density graph

winsorizedValues

A data frame of the values at which each variable was winsorized. If percentile is 0, that means no winsorization, and values will simply be min and max.

better

A logical value whether better scores than threshold were allowed

use.prethreshold

A logical value whether covariance matrix was calculated from pre threshold but post winsorizing data.

An S4 class to represent composite scores based on Mahalanobis distance

Description

An S4 class to represent composite scores based on Mahalanobis distance

An S4 class to represent composite scores based on summing

An S4 class to represent composite scores based on (confirmatory) factor analysis

Slots

scores

A vector of the final scores

scoreHistogram

A histogram of the final scores

screePlot

A screeplot from the PCA

loadingGraph

A graph of the component loadings

loadingTable

A table of all the component loadings

pca

Prinicipal component analysis results. A list (coercied from princomp output).

ncomponents

The number of components of the PCA to be used.

CompositeReady

The original CompositeReady class object passed in

scores

A vector of the final scores

scoreHistogram

A histogram of the final scores

transform

A character string of the type of transformation applied

type

A character string indicating whether data were summed or averaged

trans

A list of functions to transform data and backtransform it

systems

A list with as many elements as there are systems where each element is a character vector containing the variable names for each system. If all variables belong to one system, a list with one element that is missing.

CompositeReady

The original CompositeReady class object passed in

scores

A vector of the final scores

scoreHistogram

A histogram of the final scores

factorScores

A data frame with all factor score predictions

type

A character string indicating the type of factor model used

factors

A list with as many elements as there are specific factors, where each element is a character vector of the variables for a specific factor

Fit

A fitted model object from lavaan.

CompositeReady

The original CompositeReady class object passed in

Score the MetSSS

Description

Function requires systolic and diastolic blood pressure, triglycerides, waist circumference, HDL cholesterol, blood glucose, and sex.

Usage

MetSSS(input)

Arguments

Examples

mydata <- data.frame(
  sbp = c(122, 102.5),
  dbp = c(76.5, 64),
  trigs = c(1.47, 1.27),
  hdl = c(2.22, 1.59),
  waist = c(71, 91),
  glucose = c(5.16, 5.82),
  sex = c("Female", "Male"))

MetSSS(mydata)

MetSSS Model

Description

Simple example model that predicts hours of watching TV from age and marital status

Usage

MetSSS_model

Format

an object from mahalanobisComposite

Source

Healthy Hearts Study

Drop unnecessary data from a MahalanobisComposite object.

Description

This function removes graphs and other sensitive data.

Usage

dropData(object)

Arguments

Value

A MahalanobisComposite object with some slots replaced with missing values

Examples

# make me!!!

Score Data Using a Factor Model

Description

Create a composite using a Factor Model

Usage

factorComposite(
  object,
  type = c("onefactor", "secondorderfactor", "bifactor"),
  factors = list(NA_character_)
)

Arguments

Value

An S4 object of class FactorScores.

See Also

Other composite: mahalanobisComposite(), sumComposite()

Examples

# this example creates distances for the built in mtcars data
# see ?mtcars for more details
# The distances are calculated from the "best" in the dataset
# First we create an appropriate CompositeData class object
# higher mpg & hp are better and lower wt & qsec are better
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE))

# create the distance scores
# and the composite
# covariance matrix will be calculated from the data
# and data will be standardized to unit variance by default
dres <- prepareComposite(d)

# see a density plot of the distance scores
dres@distanceDensity
# regular summary of distance scores
summary(dres@distances)

# examine covariance matrix
round(dres@covmat,2)

# now we can create the composite based on summing the (standardized)
# distances from our defined thresholds
# by default, distances are squared, then summed, and then square rooted
# to be back on the original scale
fcomp <- factorComposite(dres, type = "onefactor")

# view a histogram of the composite scores
fcomp@scoreHistogram

# summarize the composite scores
summary(fcomp@scores)

## Not run: 
# we can also fit a second-order factor model
# there are not enough indicators to identify the factor
# and so lavaan gives us warning messages
fcomp2 <- factorComposite(dres, type = "secondorderfactor",
  factors = list(speed = c("hp", "qsec")))

# view a histogram of the composite scores
fcomp2@scoreHistogram

# summarize the composite scores
summary(fcomp2@scores)

# compare one and second-order factor model scores
plot(fcomp@scores, fcomp2@scores)

# cleanup
rm(d, dres, fcomp, fcomp2)

## End(Not run)

Density Plot for a Long Dataset

Description

Internal function only, not meant for general use Simple wrapper around ggplot2 functionaly to create density plots, potentially for many variables and coloured by group.

Usage

ldensity(data, melt = FALSE, x, facet, g, hist = FALSE)

Arguments

Value

A ggplot2 graph.

Examples

# simple facetted plot
pscore:::ldensity(mtcars, TRUE)
# simple coloured plot
pscore:::ldensity(mtcars, x = "mpg", g = "cyl")

Score Data Using the Mahalanobis Distance

Description

Create a composite using the Mahalanobis Distance

Usage

mahalanobisComposite(object, ncomponents, pca)

Arguments

Value

An S4 object of class MahalanobisScores.

See Also

Other composite: factorComposite(), sumComposite()

Examples

# this example creates distances for the built in mtcars data
# see ?mtcars for more details
# The distances are calculated from the "best" in the dataset
# First we create an appropriate CompositeData class object
# higher mpg & hp are better and lower wt & qsec are better
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE))

# create the distance scores
# and the composite
# covariance matrix will be calculated from the data
# and data will be standardized to unit variance by default
dres <- prepareComposite(d)

# see a density plot of the distance scores
dres@distanceDensity
# regular summary of distance scores
summary(dres@distances)

# examine covariance matrix
round(dres@covmat,2)

# now we can create the composite based on mahalanobis distances
# from our defined thresholds
mcomp <- mahalanobisComposite(dres, 1)

# view a histogram of the composite scores
mcomp@scoreHistogram

# summarize the composite scores
summary(mcomp@scores)

# check the screeplot and loadings
mcomp@screePlot
mcomp@loadingGraph
# examine the loadings as a table
mcomp@loadingTable

# one component is adequate to explain these data
# to be safe can pick first two and re-run model

# use only first two components
mcomp2 <- mahalanobisComposite(dres, ncomponents = 2)

# view a histogram of the updated composite scores
mcomp2@scoreHistogram

# summarize the composite scores
summary(mcomp2@scores)

# compare using all versus two components
plot(mcomp@scores, mcomp2@scores)

# cleanup
rm(d, dres, mcomp, mcomp2)

Internal function to prepare data for prediction

Description

Internal function to prepare data for prediction

Usage

predictCS(object, newdata, groups)

Arguments

Value

An object of S4 class “CompositeReady”

Examples

d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "disp")],
                   thresholds = list(one = with(mtcars, c(
                                     mpg = max(mpg),
                                     hp = max(hp),
                                     wt = min(wt),
                                     disp = min(disp)))),
                   higherisbetter = c(TRUE, TRUE, FALSE, FALSE))
## create the distance scores
## and prepare to create the composite
dres <- prepareComposite(d)

## create composite based on summing the (standardized)
scomp <- sumComposite(dres, "square", "sum")
## use model to generate predictions on new data
predictCS(scomp,
          newdata = mtcars[1, c("mpg", "hp", "wt", "qsec")],
          groups = "one")

## create composite based on mahalanobis distances
mcomp <- mahalanobisComposite(dres)
## use model to generate predictions on new data
predictCS(mcomp,
          newdata = mtcars[1, c("mpg", "hp", "wt", "qsec")],
          groups = "one")
## note in this too simple example, there are negative variance estimates
## create composite based on factor scores
fcomp <- factorComposite(dres, type = "onefactor")
## use model to generate predictions on new data
predictCS(fcomp,
          newdata = mtcars[1:5, c("mpg", "hp", "wt", "disp")],
          groups = rep("one", 5))

Prepare distance scores on data in preparation for composite scoring

Description

Prepare distance scores on data in preparation for composite scoring

Usage

prepareComposite(
  object,
  winsorize = 0,
  values,
  better = TRUE,
  covmat,
  standardize = TRUE,
  use.prethreshold = FALSE
)

Arguments

Value

An S4 object of class “CompositeReady”.

Examples

# this example creates distances for the built in mtcars data
# see ?mtcars for more details
# The distances are calculated from the "best" in the dataset
# First we create an appropriate CompositeData class object
# higher mpg & hp are better and lower wt & qsec are better
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE),
  rawtrans = list(
    mpg = function(x) x,
    hp = function(x) x,
    wt = function(x) x,
    qsec = sqrt))


# create the distance scores
dres <- prepareComposite(d)

# see a density plot of the distance scores
dres@distanceDensity
# regular summary of distance scores
summary(dres@distances)

# examine covariance matrix
round(dres@covmat,2)
# cleanup
rm(d, dres)

Score Data Using a simple sum

Description

Create a composite using summation

Usage

sumComposite(
  object,
  transform = c("square", "abs", "none"),
  type = c("sum", "mean"),
  systems
)

Arguments

Value

An S4 object of class SumScores.

See Also

Other composite: factorComposite(), mahalanobisComposite()

Examples

# this example creates distances for the built in mtcars data
# see ?mtcars for more details
# The distances are calculated from the "best" in the dataset
# First we create an appropriate CompositeData class object
# higher mpg & hp are better and lower wt & qsec are better
d <- CompositeData(mtcars[, c("mpg", "hp", "wt", "qsec")],
  thresholds = list(one = with(mtcars, c(
    mpg = max(mpg),
    hp = max(hp),
    wt = min(wt),
    qsec = min(qsec)))
  ),
  higherisbetter = c(TRUE, TRUE, FALSE, FALSE))

# create the distance scores
# and the composite
# covariance matrix will be calculated from the data
# and data will be standardized to unit variance by default
dres <- prepareComposite(d)

# see a density plot of the distance scores
dres@distanceDensity
# regular summary of distance scores
summary(dres@distances)

# examine covariance matrix
round(dres@covmat,2)

# now we can create the composite based on summing the (standardized)
# distances from our defined thresholds
# by default, distances are squared, then summed, and then square rooted
# to be back on the original scale
scomp <- sumComposite(dres, "square", "sum")

# view a histogram and summary of the composite scores
scomp@scoreHistogram
summary(scomp@scores)

# calculate average (mean) instead of sum
scomp2 <- sumComposite(dres, "square", "mean")

# view a histogram and summary of the composite scores
scomp2@scoreHistogram
summary(scomp2@scores)

# scores are still the same (just different scaling)
plot(scomp@scores, scomp2@scores)

# first average scores within a system, then sum
# within a system, scores are always averaged, never summed
scomp3 <- sumComposite(dres, "square", "sum",
  systems = list(
    environment = c("mpg"),
    performance = c("hp", "qsec", "wt")))

# view a histogram and summary of the composite scores
scomp3@scoreHistogram
summary(scomp3@scores)

# compare all three scores
# because of the different number of indicators within each system
# there is a re-weighting for S3
plot(data.frame(S1 = scomp@scores, S2 = scomp2@scores, S3 = scomp3@scores))

# cleanup
rm(d, dres, scomp, scomp2, scomp3)