predictrpexa

A ModelsCloud wrapper for the preventr package, implementing the American Heart Association PREVENT equations for cardiovascular risk estimation.

predictrpexa is callable from the modelscloud R client.

---

How it fits in the stack

modelscloud (R client)
  └─ pexaclient (HTTP)
       └─ PexaCloud / OpenCPU
            └─ predictrpexa          ← this package
                 └─ preventr::estimate_risk()

---

Installation

# Install from GitHub
remotes::install_github("resplab/predictrpexa")

predictrpexa depends on preventr, which is installed automatically from CRAN.

---

Quick start via the ModelsCloud client

library(modelscloud)

connect_to_model("resplab/predictrpexa", access_key = "YOUR_API_KEY")

# Explore inputs
defaults <- get_default_input()
patients <- get_sample_input()

# Run the model
results <- model_run(patients)
print(results)

---

Direct usage

You can also use the package directly without the ModelsCloud client.

Single patient

Pass a named list with the patient's values:

library(predictrpexa)

result <- model_run(list(
  age     = 50,
  sex     = "female",
  sbp     = 160,
  bp_tx   = TRUE,
  total_c = 200,
  hdl_c   = 45,
  statin  = FALSE,
  dm      = TRUE,
  smoking = FALSE,
  egfr    = 90,
  bmi     = 35
))

print(result)
#>   total_cvd ascvd heart_failure   chd stroke model over_years input_problems
#> 1     0.147 0.092        0.081 0.044  0.054  base         10           <NA>
#> 2     0.530 0.354        0.390 0.198  0.221  base         30           <NA>

Batch (multiple patients)

Pass a data frame — one row per patient:

patients <- get_sample_input(n = 3)
results  <- model_run(patients)
print(results)

Using optional parameters

preventr can use HbA1c, UACR, and ZIP code (SDI) to select a richer PREVENT model automatically:

result <- model_run(list(
  age     = 66,
  sex     = "male",
  sbp     = 148,
  bp_tx   = FALSE,
  total_c = 188,
  hdl_c   = 52,
  statin  = TRUE,
  dm      = TRUE,
  smoking = TRUE,
  egfr    = 67,
  bmi     = 30,
  hba1c   = 7.5,   # enables HbA1c PREVENT model
  uacr    = 30,    # combined with hba1c → full model
  time    = "10yr" # only 10-year horizon
))

For batch mode, include these as columns in your data frame.

---

Core functions

Function	Description
model_run(model_input)	Run the PREVENT model; accepts a named list or data frame
get_sample_input(n = 3)	Return n example patients as a data frame (max 5)
get_default_input()	Return a named list of default parameter values

---

Input reference

Required fields

Field	Type	Range	Description
age	numeric	30–79	Age in years
sex	character	"female" / "male"	Biological sex
sbp	numeric	90–180	Systolic blood pressure (mmHg)
bp_tx	logical		On blood pressure treatment?
total_c	numeric	130–320	Total cholesterol (mg/dL)
hdl_c	numeric	20–100	HDL cholesterol (mg/dL)
statin	logical		Currently taking a statin?
dm	logical		Diabetes mellitus?
smoking	logical		Current smoker (last 30 days)?
egfr	numeric	15–140	eGFR (mL/min/1.73m²)
bmi	numeric	18.5–39.9	BMI (kg/m²)

Optional fields

Field	Type	Description
hba1c	numeric	HbA1c in % (4.5–15); enables HbA1c PREVENT model
uacr	numeric	Urine albumin-to-creatinine ratio in mg/g (0.1–25000)
zip	character	US ZIP code for Social Deprivation Index (SDI)
model	character / list	PREVENT model override (default NULL = auto-select)
time	character	Time horizon: "both" (default), "10yr", or "30yr"
chol_unit	character	"mg/dL" (default) or "mmol/L"
optional_strict	logical	Enforce strict validation of optional variables (default FALSE)

---

Output

model_run() always returns a data frame with the following columns:

Column	Type	Description
total_cvd	double	Estimated risk of total CVD event
ascvd	double	Estimated risk of ASCVD event
heart_failure	double	Estimated risk of heart failure
chd	double	Estimated risk of coronary heart disease
stroke	double	Estimated risk of stroke
model	character	PREVENT model used ("base", "hba1c", "uacr", "sdi", "full")
over_years	integer	Time horizon (10 or 30)
input_problems	character	Semicolon-separated list of any input issues (NA if none)

Risk estimates are proportions rounded to 3 decimal places. In batch mode, a preventr_id column is also included (row number from the input data frame).

---

Related packages

Package	Role
preventr	Implements the AHA PREVENT equations
modelscloud	ModelsCloud R client
pexaclient	Low-level HTTP client for PexaCloud

---

License

GPL-3 © Mehrshad Mokhtaran, RESP Lab, UBC