Skip to contents

Overview

precmed is an R package for estimating average treatment effects (ATEs) and estimating and validating conditional average treatment effects (CATEs) in randomized trials and observational studies, with methods for binary, count and survival outcomes. The ATE describes an effect across a population, while the CATE describes an average effect among patients with particular observed characteristics. Together, they support the study of treatment effect heterogeneity and precision medicine.

Use precmed when you want to:

  • Estimate the ATE comparing two treatments using doubly robust methods.
  • Explore treatment effect heterogeneity by developing and assessing CATE models for binary, count and survival outcomes.
  • Visualize and compare estimated effects across patient subgroups.

The methods support causal inference under appropriate assumptions; for observational data, these include adequate control of confounding and sufficient treatment overlap. The package combines outcome-regression approaches, such as Poisson models fitted separately in each treatment group, with doubly robust methods for estimating and validating treatment effects. Its methods build on work by Zhao et al. (2013) and Yadlowsky et al. (2021); Jiang et al. (2026) illustrate their application and interpretation.

See Is precmed suitable for me? for a quick overview of supported data, outcomes and analyses.

Learning resources

For a broader introduction to personalized medicine using real-world data, see Comparative Effectiveness and Personalized Medicine Research Using Real-World Data (Debray, Nguyen, and Platt 2026). The following chapters are particularly relevant to precmed:

  • Chapter 5: defining causal effects and understanding marginal and conditional treatment effects (Nguyen et al. 2026).
  • Chapter 17: principles of CATE prediction and model development in randomized and non-randomized data (Hoogland et al. 2026).
  • Chapter 19: validation strategies and assessment of discrimination, calibration, and decision accuracy (Thao et al. 2026).
  • Chapter 20: visualization and interpretation of individualized treatment rules, validation curves, and responder diagnostics, with examples using precmed (Jiang et al. 2026).

The original methodological references are Yadlowsky et al. (2021) for ratio-based CATE estimation and validation, and Zhao et al. (2013) for target-population selection.

Two free courses complement the book and introduce precmed, its practical use, and the underlying statistical methods. An Introduction to Precision Medicine covers the foundations through recorded webinars, exercises, and readings. The free companion course to the book provides background materials, example R code, and curated references to support practical analyses.

Installation

The precmed package can be installed from CRAN as follows:

install.packages("precmed")

The latest version can be installed from GitHub as follows:

install.packages("devtools")
devtools::install_github(repo = "smartdata-analysis-and-statistics/precmed")

Try the quick start for a complete count-outcome example and validation plot.

Citation and support

To cite the installed version of precmed, run citation("precmed") in R, or see the authors and citation page. Please also cite the methodological references relevant to your analysis.

For questions, bug reports, or feature requests, use GitHub issues. For a bug report, please include your package and R versions, the error message, and a minimal reproducible example using simulated or non-sensitive data.

Package capabilities

The package compares two treatments using outcome-specific effect measures:

  • Binary: the risk difference in outcome probabilities (treatment 1 minus treatment 0). The binary example illustrates ATE and CATE estimation.
  • Count: the ratio of event rates (treatment 1 over treatment 0). The count example covers estimation and validation.
  • Survival: the ratio of restricted mean time lost at a specified follow-up horizon (treatment 1 over treatment 0). The survival example also illustrates population-level cumulative hazard ratios.

Count and survival ATE effect estimates and CATE scores are returned on the log-ratio scale; exponentiate them to obtain ratios. The ATE summarizes the population, while CATE scores describe effects conditional on observed characteristics.

The main functions in the precmed package are:

Function Description
catefit() Estimation of the conditional average treatment effect (CATE)
atefit() Doubly robust estimator for the average treatment effect (ATE)
catecv() Development and cross-validation of CATE scores
abc() Compute the area between the average treatment difference curve of competing models for the CATE (Zhao et al. 2013)
plot() Two side-by-side line plots of validation curves from the precmed object
boxplot() Plot the proportion of subjects with an estimated treatment effect no less than cc over a range of values for cc (Zhao et al. 2013).

For more info: https://smartdata-analysis-and-statistics.github.io/precmed/

For count and survival outcomes, the following workflow estimates the ATE and develops and validates a CATE model:

  1. Use atefit() to estimate the overall ATE between two treatment groups and its uncertainty using bootstrap resampling.
  2. Compare up to five modelling approaches (e.g., Poisson regression, boosting) for estimating the CATE using cross-validation through catecv.
  3. Select the best modelling approach using 3 metrics:
    • Compare the steepness of the validation curves in the validation samples across methods using plot(). Two side-by-side plots are generated, visualizing the estimated average treatment effects in a series of nested subgroups. On the left side the curve is shown for the training set, and on the right side the curve is shown for the validation set. Each line in the plots represents one scoring method (e.g., boosting, randomForest) specified under the argument score.method.
    • The area between curves (ABC) using abc quantifies a model’s ability to capture treatment effect heterogeneity. Higher ABC values are preferable as they indicate that more treatment effect heterogeneity is captured by the scoring method.
    • Compare the distribution of the estimated ATE across different levels of the CATE score percentiles using boxplot().
  4. Fit the chosen modelling approach using catefit(); assess performance in an independent dataset where possible.

For binary outcomes, the binary example illustrates atefit(), catefit() and a separate held-out subgroup assessment.

In the vignettes, we will adopt a different workflow to gradually expose the user from simple to more complex methods.

User input

When applying catefit() or catecv(), the user has to (at least) input:

  • response: outcome type, such as binary, count, or survival; see the relevant function’s documentation
  • data: a data frame with individual patient data
  • score.method: methods to estimate the CATE (e.g., boosting, poisson, twoReg, contrastReg)
  • cate.model: a formula describing the outcome model (e.g., outcome ~ age + gender + previous_treatment)
  • ps.model: a formula describing the treatment model (propensity-score model) used to adjust for confounding (e.g., treatment ~ age + previous_treatment)

References

Debray, Thomas P. A., Tri-Long Nguyen, and Robert W. Platt, eds. 2026. Comparative Effectiveness and Personalized Medicine Research Using Real-World Data. 1st ed. Chapman & Hall/CRC. https://doi.org/10.1201/9781003300809.
Hoogland, Jeroen, Thomas P. A. Debray, Guillaume Desachy, and Tri-Long Nguyen. 2026. “Introduction to Methods for Personalizing Medicine.” In Comparative Effectiveness and Personalized Medicine Research Using Real-World Data, edited by Thomas P. A. Debray, Tri-Long Nguyen, and Robert W. Platt, 421–63. Chapman & Hall/CRC. https://doi.org/10.1201/9781003300809-17.
Jiang, Xiaotong, Gabrielle Simoneau, Fabio Pellegrini, Changyu Shen, Carl de Moor, and Lu Tian. 2026. “Visualization and Interpretation of Individualized Treatment Rule Results.” In Comparative Effectiveness and Personalized Medicine Research Using Real-World Data, edited by Thomas P. A. Debray, Tri-Long Nguyen, and Robert W. Platt, 513–36. Chapman & Hall/CRC. https://doi.org/10.1201/9781003300809-20.
Nguyen, Tri-Long, Jessica L. Rohmann, Tat Thang Vo, Robert W. Platt, and Thomas P. A. Debray. 2026. “Understanding and Defining Causal Effects.” In Comparative Effectiveness and Personalized Medicine Research Using Real-World Data, edited by Thomas P. A. Debray, Tri-Long Nguyen, and Robert W. Platt, 65–80. Chapman & Hall/CRC. https://doi.org/10.1201/9781003300809-5.
Thao, Le Thi Phuong, Orestis Efthimiou, Tibor V. Varga, Jeroen Hoogland, and Thomas P. A. Debray. 2026. “Validation of Prediction Models for Patient Outcomes and Individualized Treatment Effect.” In Comparative Effectiveness and Personalized Medicine Research Using Real-World Data, edited by Thomas P. A. Debray, Tri-Long Nguyen, and Robert W. Platt, 485–512. Chapman & Hall/CRC. https://doi.org/10.1201/9781003300809-19.
Yadlowsky, Steve, Fabio Pellegrini, Federica Lionetto, Stefan Braune, and Lu Tian. 2021. “Estimation and Validation of Ratio-Based Conditional Average Treatment Effects Using Observational Data.” Journal of the American Statistical Association 116 (533): 335–52. https://doi.org/10.1080/01621459.2020.1772080.
Zhao, Lihui, Lu Tian, Tianxi Cai, Brian Claggett, and Lee-Jen Wei. 2013. “Effectively Selecting a Target Population for a Future Comparative Study.” Journal of the American Statistical Association 108 (502): 527–39. https://doi.org/10.1080/01621459.2013.770705.