hvtiRutilities

Overview

hvtiRutilities provides utility functions for working with clinical research data at the Cleveland Clinic Heart, Vascular and Thoracic Institute (HVTI) Clinical Outcomes Registries and Research (CORR) department. The package simplifies common data preparation tasks when working with SAS datasets in R.

Main Functions

• r_data_types(): Automatically infer and convert data types in a dataset

  • Converts character columns to factors
  • Detects binary numeric variables (0/1) and converts to logical
  • Converts numeric variables with few unique values to factors
  • Handles various NA representations ("NA", "na", etc.)
  • Preserves variable labels from SAS/labelled data

• proc_contents(): SAS PROC CONTENTS in R

  • One row per variable: creation position, name, SAS type (Num/Char), format, label
  • Plus R class, distinct-value count, and percent missing
  • Alphabetical by default, matching SAS; order = "varnum" gives creation order
  • Omits Len, Pos, and Informat, which haven cannot recover from a .sas7bdat

• proc_means(): SAS PROC MEANS in R

  • SAS statistic keywords (n, nmiss, mean, std, min, max, median, q1, q3, pNN, ...), defaulting to SAS's five plus the group's p15, median and p85
  • class = stratification, dropping missing class levels as SAS does
  • Quantiles use SAS's QNTLDEF=5 definition, not R's default

• label_map(): Extract variable labels from labeled datasets

  • Creates a lookup table mapping variable names to their labels
  • Useful for working with SAS datasets that have variable labels
  • Returns a data frame with key (variable name) and label columns

• sample_data(): Generate sample datasets for testing

  • Creates datasets with various column types for testing package functions
  • Useful for examples and unit tests

• generate_survival_data(): Simulate a cardiac surgery survival cohort

  • Generates realistic patient-level data including demographics, pre-operative labs, cardiac function, and surgical variables
  • Survival times from a Weibull model with clinically-motivated linear predictor (LVEF, age, hemoglobin, NYHA class, eGFR)
  • Includes reoperation outcome and administrative censoring up to 15 years
  • Variable labels attached for compatibility with haven and label_map()

Installation

hvtiRutilities is part of the HVTI R family. Install it with the rest of the family through hvtiR:

# install.packages("pak")
pak::pak("ehrlinger/hvtiR")
hvtiR::install()

hvtiR::install() installs every member in one call, so the versions the members require of one another resolve together. Update later with hvtiR::update(), from a fresh R session: it will not overwrite a package that is already loaded.

To install hvtiRutilities on its own:

# pak::pak("ehrlinger/hvtiRutilities")
install.packages("hvtiRutilities", repos = c('https://ehrlinger.r-universe.dev', 'https://cloud.r-project.org'))

Usage Examples

Automatic Type Conversion

library(hvtiRutilities)

# Create sample data
dta <- sample_data(n = 100)

# Examine original types
str(dta)
# boolean: int (values: 1, 2)
# logical: chr (values: "F", "T")
# char: chr (values: "male", "female")

# Apply automatic type conversion
dta_converted <- r_data_types(dta)

# Examine converted types
str(dta_converted)
# boolean: logi (binary 1/2 → TRUE/FALSE)
# logical: Factor (character → factor)
# char: Factor (character → factor)

Skip Specific Columns

# Skip conversion for specific variables
dta_partial <- r_data_types(dta, skip_vars = c("boolean", "char"))
# boolean and char remain unchanged, others are converted

Control Factor Creation

# Convert only variables with fewer than 5 unique values to factors
dta_strict <- r_data_types(dta, factor_size = 5)

# Keep binary variables as factors instead of logical
dta_factors <- r_data_types(dta, binary_factor = TRUE)

Working with Variable Labels

# Create labeled data (common with SAS imports)
library(labelled)
dta <- data.frame(
  age = c(25, 30, 35),
  sex = c("M", "F", "M"),
  bp = c(120, 130, 125)
)
var_label(dta$age) <- "Patient Age (years)"
var_label(dta$sex) <- "Patient Sex"
var_label(dta$bp) <- "Systolic Blood Pressure (mmHg)"

# Extract labels as a lookup table
labels <- label_map(dta)
print(labels)
#   key                              label
# 1 age        Patient Age (years)
# 2 sex                    Patient Sex
# 3  bp  Systolic Blood Pressure (mmHg)

# Use for matching/joining
summary_table <- data.frame(variable = c("age", "bp"))
summary_table$label <- labels$label[match(summary_table$variable, labels$key)]

Generating Survival Data

# Simulate a cardiac surgery cohort (reproducible)
dta <- generate_survival_data(n = 500, seed = 1024)

# Event and reoperation rates
mean(dta$dead)   # ~death rate
mean(dta$reop)   # ~reoperation rate

# Integrate with the rest of the package
model_data <- r_data_types(
  dta,
  factor_size = 5,
  skip_vars = c("ccfid", "iv_dead", "iv_reop")
)

# Extract variable labels for reporting
lmap <- label_map(model_data)

Key Features

• Preserves variable labels: All functions maintain SAS/labelled variable attributes
• Handles NA variants: Automatically converts "NA", "na", "Na", "nA" strings to actual NA values
• Type-safe: Returns the same data structure class as input (data.frame, tibble, data.table, etc.)
• Flexible control: Multiple parameters to customize type conversion behavior

Getting Help

• Package documentation: ?r_data_types, ?label_map, ?proc_contents, ?proc_means
• Vignettes: vignette("hvtiRutilities"), vignette("sas-procedures"), vignette("dataset-versioning")
• Running jobs on a study? vignette("registered-datasets") explains, for analysts, what registering a dataset does, why the parquet files are named <name>_YYYYMMDD_rN.parquet, which version a job reads, and how a report says so
• For bug reports and feature requests: GitHub Issues
• For package news and changes: Run hvtiRutilities.news() in R

License

GPL (>= 3)