Reference

API reference.

The two main plotting functions accept raw-data formulas or precomputed fitted nuisance columns. Both return a CPplot_result.

`cp_plot()`

cp_plot(formula = NULL, data, e_hat = NULL, tau_hat = NULL,
        treatment = NULL, e_method = "logistic", tau_method = "ols",
        point_labels = c("Control", "Treated"),
        title = NULL, alpha = 0.35, point_size = 1)

Draw an observational CP plot.

Argument	What to pass
`formula`	Optional formula. For outcome `y`, binary treatment `z`, and covariates `x1` and `x2`, use `y ~ z + x1 + x2`.
`data`	A data frame.
`e_hat`	Optional name of a precomputed propensity-score column.
`tau_hat`	Optional name of a precomputed CATE column.
`treatment`	Optional 0/1 treatment column for point shapes in fitted-input mode.
`e_method`	`logistic` or `random_forest`.
`tau_method`	`ols` or `random_forest`.
`point_labels`	Two labels for 0 and 1 points. Default is `Control` and `Treated`.
`title`, `alpha`, `point_size`	Optional plot title and point styling.

Mode 1: estimate from a formula

Use this when the data contain the outcome, treatment, and covariates, and you want CPplot to estimate e_hat and tau_hat.

fit <- cp_plot(y ~ z + x1 + x2, data = df)

Mode 2: pass fitted inputs directly

Use this when you already have estimated propensity scores and CATEs from your preferred model.

fit <- cp_plot(
  data = df,
  e_hat = "e_hat",
  tau_hat = "tau_hat",
  treatment = "z"
)

`local_cp_plot()`

local_cp_plot(formula = NULL, data, e_hat = NULL,
              tau_c_hat = NULL, pi_c_hat = NULL, iv = NULL,
              e_method = "logistic", contrast_method = "ols",
              min_first_stage = 1e-6,
              point_labels = c("Unencouraged", "Encouraged"),
              title = NULL, alpha = 0.35, point_size = 0.8)

Draw a local CP plot for an IV study.

Argument	What to pass
`formula`	Optional local CP formula. For outcome `y`, treatment `d`, binary IV `z`, and covariates `x1` and `x2`, use `y ~ d + x1 + x2 \| z + x1 + x2`.
`data`	A data frame.
`e_hat`	Optional name of a precomputed IV propensity-score column.
`tau_c_hat`	Optional name of a precomputed conditional complier treatment-effect column.
`pi_c_hat`	Optional name of a precomputed complier score or first-stage column used as weights.
`iv`	Optional 0/1 IV column for point shapes in fitted-input mode.
`e_method`	`logistic` or `random_forest`.
`contrast_method`	`ols` or `random_forest`.
`min_first_stage`	Threshold for setting unstable plug-in conditional complier-effect estimates to missing in formula mode.
`point_labels`, `title`, `alpha`, `point_size`	Optional labels and styling. Point labels default to `Unencouraged` for IV = 0 and `Encouraged` for IV = 1.

Mode 1: estimate from a formula

Use this when the data contain the outcome, treatment, IV, and covariates, and you want CPplot to estimate the local CP inputs.

fit <- local_cp_plot(y ~ d + x1 + x2 | z + x1 + x2, data = df)

Mode 2: pass fitted inputs directly

Use this when you already have estimated IV propensity scores, plug-in conditional complier-effect estimates, and complier weights.

fit <- local_cp_plot(
  data = df,
  e_hat = "e_hat",
  tau_c_hat = "tau_c_hat",
  pi_c_hat = "pi_c_hat",
  iv = "z"
)

Return value

Element	Meaning
`plot`	The ggplot object.
`slopes`	Slopes, standard errors, and p-values for the three diagnostic fits.
`intersections`	The three pairwise fitted-line intersections. Their vertical coordinates are plug-in ATT, ATO, and ATC estimates, or their local complier analogs.
`bracketing`	Slope signs and their bracketing implications.
`bracketing_summary`	A compact text summary of the ATO bracketing diagnostic.
`data_used`	The finite observations retained for plotting.

Slope helpers

cp_slopes(data, e_hat, tau_hat, treatment = NULL)
local_cp_slopes(data, e_hat, tau_c_hat, pi_c_hat, iv = NULL)

These return the slope table without drawing the plot. The local helper uses weights pi_c_hat, pi_c_hat * e_hat, and pi_c_hat * (1 - e_hat).

Estimation helpers

estimate_cp_inputs(data, outcome, treatment, covariates,
                   e_method = "logistic", tau_method = "ols",
                   family = stats::binomial())

estimate_local_cp_inputs(data, outcome, treatment, instrument, covariates,
                         e_method = "logistic", contrast_method = "ols",
                         family = stats::binomial(),
                         min_first_stage = 1e-6)

`estimate_cp_inputs()`	Returns the original data plus `e_hat` and `tau_hat`.
`estimate_local_cp_inputs()`	Returns the original data plus `e_hat`, `delta_y`, `delta_d`, `pi_c_hat`, and `tau_c_hat`.

Bundled paper data

paper_datasets()
load_paper_cp_data(setting)
load_paper_401k_data()

`paper_datasets()`	Dataset index with name, type, treatment column, loader, and description.
`load_paper_cp_data(setting)`	One observational paper-demo dataset with `propensity_scores`, `tau_hat`, and the treatment column.
`load_paper_401k_data()`	The 401(k) plug-in local CP dataset with `e_hat`, `Z`, `delta_y`, `delta_d`, and `tau_c_hat`.

Citation

citation("CPplot")

Tian, P., Yang, F., & Ding, P. (2026). Introducing the CP-plot for Causal Inference with Observational Studies. arXiv preprint arXiv:2606.11715.