Package {mirrorslope}

Attach the between-arm difference to a mirror_data object

Description

Optional pipeline step. Stores the comparator-minus-reference difference and its optional precision and p-value on the comparator SUMM row, per the specification.

Usage

add_difference(
  mirror_data,
  estimate,
  se = NULL,
  ci_lower = NULL,
  ci_upper = NULL,
  ci_level = 0.95,
  p_value = NULL
)

Arguments

Value

The mirror_data object with difference fields populated on the comparator SUMM row.

See Also

add_summary, mirror_slope_plot

Attach per-arm precision (SE or CI) to a mirror_data object

Description

Optional pipeline step. Adds standard errors or confidence intervals for each arm's estimate to the existing SUMM rows. Either se or ci may be supplied; if both are given, ci is used for display.

Usage

add_precision(mirror_data, se = NULL, ci = NULL, ci_level = 0.95)

Arguments

Value

The mirror_data object with precision columns populated on the SUMM rows.

See Also

add_summary

Attach group-level summary estimates to a mirror_data object

Description

Second step of the pipeline. Adds one SUMM row per arm carrying the endpoint summary estimate, the baseline value the mean line is drawn from, and a free-text statistic label.

Usage

add_summary(mirror_data, estimates, stat_label = "Mean", baseline = NULL)

Arguments

Details

This function accepts pre-computed estimates and is deliberately model-agnostic. A future release may add a method to populate estimates directly from a model object (e.g. an emmGrid); the named-vector interface here is forward-compatible with that addition.

Value

The mirror_data object with two SUMM rows added.

See Also

prep_mirror_data, add_difference

Coerce a mirror_data object to a plain data frame

Description

Strips the mirror_data class and metadata, returning the underlying tabular structure as an ordinary data frame.

Usage

## S3 method for class 'mirror_data'
as.data.frame(x, ...)

Arguments

Value

A plain data frame.

Color palettes for mirror slope plots

Description

Returns a length-2 character vector of hex colors for the reference and comparator arms, in that order. Pair the result with trt_levels by naming it, or pass it directly to mirror_slope_plot, which assigns the first color to the reference arm and the second to the comparator arm.

Usage

mirror_palette(name = c("default", "colorblind", "capricor"), reversed = FALSE)

Arguments

Value

An unnamed length-2 character vector of hex color codes: c(reference_color, comparator_color).

Examples

mirror_palette("default")
mirror_palette("colorblind")
# Name it to bind explicitly to arms:
stats::setNames(mirror_palette("capricor"), c("Placebo", "Active"))

Render a mirror slope plot

Description

Produces a publication-quality mirror slope plot from a mirror_data object built with prep_mirror_data and add_summary (and optionally add_precision and add_difference).

Usage

mirror_slope_plot(
  mirror_data,
  show_spaghetti = FALSE,
  spaghetti_alpha = 0.15,
  spaghetti_size = 0.4,
  show_difference = FALSE,
  show_slowing = FALSE,
  show_precision = FALSE,
  show_n = TRUE,
  direction = NULL,
  outcome_label = NULL,
  benefit_label = NULL,
  x_center = 12,
  x_offset = NULL,
  x_min = NULL,
  x_max = NULL,
  y_lim = NULL,
  trt_colors = mirror_palette("default"),
  band_color = NULL,
  band_alpha = 0.12,
  line_size = 1,
  point_shape = 18,
  point_size = 3.2,
  base_size = 11,
  y_percent = TRUE,
  jitter_points = FALSE,
  title = NULL,
  subtitle = NULL,
  y_label = NULL,
  caption = NULL,
  footnote = NULL,
  seed = NULL,
  return_data = FALSE,
  save_path = NULL,
  width = 8,
  height = 6,
  dpi = 300
)

Arguments

Details

Both arms share one x-axis and converge at a central endpoint position, so the between-arm gap at the endpoint is the primary visual quantity. All optional elements are off by default: the object stores everything available, and this function exposes only what is requested.

Value

A ggplot object, or a list of $plot and $data when return_data = TRUE. The plot can be extended with standard ggplot2 syntax.

Direction and labels

direction describes the direction of numeric movement of the value, derived by comparing the reference arm endpoint estimate to its baseline ("decrease" if the value moved down, "increase" if up). The default benefit label is phrased accordingly (e.g. “percent less decline”). For outcomes where the favourable direction is unusual (for example a score where a lower number is better), supply outcome_label and benefit_label explicitly rather than relying on the defaults.

See Also

prep_mirror_data, add_summary, add_difference, add_precision, theme_mirror, mirror_palette

Examples

df <- data.frame(
  USUBJID = rep(paste0("S", 1:20), each = 2),
  TRTP    = rep(c("Placebo", "Active"), each = 20),
  AVISIT  = rep(c("Baseline", "Month 12"), times = 20),
  AVAL    = c(rbind(rep(0, 20),
                    c(rnorm(10, -10, 3), rnorm(10, -6, 3))))
)
md <- prep_mirror_data(df, trt_levels = c("Placebo", "Active"),
                       time_baseline = "Baseline", time_endpoint = "Month 12")
md <- add_summary(md, c("Placebo" = -10.1, "Active" = -5.8),
                  stat_label = "LS-Mean")
md <- add_difference(md, estimate = 4.3, p_value = 0.01)
mirror_slope_plot(md, show_difference = TRUE, show_slowing = TRUE)

Prepare analysis data for a mirror slope plot

Description

First step of the mirror slope pipeline. Validates and structures a long analysis data frame into a mirror_data object containing subject-level (OBS) rows, ready to receive group-level summaries via add_summary.

Usage

prep_mirror_data(
  data,
  subject_var = "USUBJID",
  trt_var = "TRTP",
  trt_levels,
  time_var = "AVISIT",
  time_baseline,
  time_endpoint,
  value_var = "AVAL",
  pop_flags = NULL,
  value_label = "Change from Baseline",
  population_label = NULL
)

Arguments

Details

The function filters to exactly two treatment arms, applies optional population flags, retains only the baseline and endpoint visits, assigns the ARMROLE and TIMEROLE role columns, counts the analyzed N per arm, and records provenance metadata. It does not compute any statistics.

Value

A mirror_data object containing OBS rows and populated metadata, including schema_version and provenance.

See Also

add_summary, add_difference, add_precision, mirror_slope_plot

Examples

df <- data.frame(
  USUBJID = rep(paste0("S", 1:6), each = 2),
  TRTP    = rep(c("Placebo", "Active"), each = 6),
  AVISIT  = rep(c("Baseline", "Week 24"), times = 6),
  AVAL    = c(0, -8, 0, -11, 0, -9, 0, -4, 0, -6, 0, -5),
  SAFFL   = "Y"
)
md <- prep_mirror_data(
  df,
  trt_levels    = c("Placebo", "Active"),
  time_baseline = "Baseline",
  time_endpoint = "Week 24",
  pop_flags     = list(SAFFL = "Y")
)
md

Print a mirror_data object

Description

Shows a structured summary: arms and roles, timepoints, population, analyzed N per arm, the statistic label, and which optional elements (summary, precision, difference) are attached.

Usage

## S3 method for class 'mirror_data'
print(x, ...)

Arguments

Value

x, invisibly.

Summarize a mirror_data object

Description

Returns per-arm, per-timepoint N, mean, and range of the observed values.

Usage

## S3 method for class 'mirror_data'
summary(object, ...)

Arguments

Value

A data frame, invisibly, with one row per arm/timepoint.

A publication theme for mirror slope plots

Description

A ggplot2 theme tuned for journal figures: a clean sans typeface, a coherent family of light hairline rules, no x-axis ticks (the x-axis is positional, not numeric), a clear type hierarchy, and proportionally scaled text. Because mirror_slope_plot returns a standard ggplot object, you can apply this theme and then override any element with + theme(...).

Usage

theme_mirror(base_size = 11, base_family = NULL)

Arguments

Details

The theme hides x-axis ticks and the minor grid because the horizontal axis in a mirror slope plot encodes position (baseline versus endpoint for each arm), not a continuous numeric scale. A single set of very light horizontal guides is retained to aid reading values off the y-axis. Rule weights (axis lines, ticks, gridlines) are deliberately kept to a light, consistent family so that no chart furniture competes with the data.

For submission-quality output, render to a vector format (PDF or SVG) or to a raster at 300 dpi or higher, and ensure the chosen base_family is available to and embedded by the graphics device.

Value

A ggplot2 theme object.

Examples

# Applied automatically inside mirror_slope_plot(), or layer it yourself:
# p + theme_mirror(base_size = 13)