R/print.R

Defines functions pmsims_render_field render_pmsims_summary build_pmsims_items pmsims_section pmsims_compact pmsims_field pmsims_note pmsims_heading pmsims_blank pmsims_rule pmsims_footnote_marker print.pmsims

Documented in print.pmsims

# =============================================================================
# Console summary for pmsims results
#
# The output answers, in order: what scenario was specified, what criterion was
# set, how the simulation was run, what sample size was found, and what
# performance is expected there. Hierarchy is carried by grouping, indentation
# and wording first, so the structure survives a terminal without colour;
# colour and weight only reinforce it.
#
# Implementation-level detail (internal metric identifiers, engine settings,
# the CSSE search scale) is reserved for the verbose display, reached through
# `print(x, verbose = TRUE)` or `summary(x)`.
# =============================================================================

#' Print a `pmsims` result
#'
#' @param x A `pmsims` object.
#' @param ... Currently unused.
#' @param max_width Maximum console width used for the summary.
#' @param verbose Logical. If `TRUE`, add implementation-level detail:
#'   internal metric identifiers, the engine settings used for the search, and
#'   any quantities recorded on an internal search scale. [summary.pmsims()]
#'   is the same display with `verbose = TRUE` by default.
#'
#' @return `x`, invisibly.
#' @keywords internal
#' @export
print.pmsims <- function(x, ..., max_width = 80, verbose = FALSE) {
  if (!inherits(x, "pmsims")) {
    stop("Object is not of class 'pmsims'")
  }
  render_pmsims_summary(x, max_width = max_width, verbose = isTRUE(verbose))
  invisible(x)
}

# -----------------------------------------------------------------------------
# Items
#
# The summary is assembled as a flat list of items and only then rendered, so
# that label and value columns can be aligned across sections that are built
# independently of one another.
# -----------------------------------------------------------------------------

# Footnote marker for a value that needs a caveat. A marker sitting flush
# against its label has to read as an annotation rather than as part of the
# word, so it is a genuinely superscript glyph and is dimmed when rendered.
# cli substitutes a plain "1" for the superscript, which would read as part of
# the word when the marker sits flush against a label, so an asterisk stands in
# instead where the console cannot render the superscript. Resolved per call:
# cli::symbol re-evaluates against the current console, and a constant would
# bake in whatever the machine that built the package happened to support.
pmsims_footnote_marker <- function() {
  if (cli::is_utf8_output()) cli::symbol$sup_1 else "*"
}

pmsims_rule <- function(title = NULL) {
  list(kind = "rule", title = title)
}

pmsims_blank <- function() {
  list(kind = "blank")
}

pmsims_heading <- function(text, indent = 0L) {
  list(kind = "heading", text = text, indent = as.integer(indent))
}

pmsims_note <- function(text) {
  list(kind = "note", text = text)
}

# Returns NULL for an absent value, so that optional rows can be dropped by
# filtering the assembled list rather than by branching at every field.
pmsims_field <- function(
  label,
  value,
  indent = 2L,
  note = NULL,
  group = NA_character_,
  emphasis = "normal",
  marker = ""
) {
  if (!pmsims_is_present(value)) {
    return(NULL)
  }
  value <- as.character(value)[1]
  if (is.na(value)) {
    return(NULL)
  }
  list(
    kind = "field",
    label = as.character(label)[1],
    # A footnote marker sits flush against the label, but is held apart from it
    # so that it can be de-emphasised without dimming the label itself.
    marker = marker,
    value = value,
    indent = as.integer(indent),
    note = note,
    group = group,
    emphasis = emphasis
  )
}

pmsims_compact <- function(...) {
  Filter(Negate(is.null), list(...))
}

# A group of fields under a subheading, dropped entirely when no field in it
# has a value.
pmsims_section <- function(title, fields, indent = 0L) {
  fields <- Filter(Negate(is.null), fields)
  if (!length(fields)) {
    return(list())
  }
  c(list(pmsims_heading(title, indent = indent)), fields)
}

# -----------------------------------------------------------------------------
# Content
# -----------------------------------------------------------------------------

build_pmsims_items <- function(x, verbose = FALSE) {
  outcome <- x$outcome
  model <- x$model
  metric <- x$metric
  metric_2 <- x$metric_2
  target <- x$target_performance %||% x$minimum_acceptable_performance
  min_n <- x$min_n
  # min_n and perf_n are NA when no sample size was found (results from older
  # versions hold a diagnostic string instead); only finite values are shown
  # as estimates.
  numeric_only <- function(v) {
    if (is.numeric(v) && length(v) == 1L && is.finite(v)) v else NULL
  }
  has_n <- is.numeric(min_n) && length(min_n) == 1L && is.finite(min_n)
  perf_at <- numeric_only(x$perf_n)
  perf2_at <- numeric_only(x$metric_2_at_n)
  complexity <- x$complexity
  moa <- tolower(as.character(x$mean_or_assurance %||% "mean")[1])

  # A calibration slope obtained by searching on the CSSE scale internally is
  # flagged with a footnote marker and explained below the results, rather than
  # announced. The marker is defined once so that it cannot drift apart from the
  # footnote that explains it.
  derived_from_csse <- isTRUE(x$internal_csse)
  csse_mark <- if (derived_from_csse) pmsims_footnote_marker() else ""

  identifier <- function(id) {
    if (verbose && pmsims_is_present(id)) sprintf(" ('%s')", id) else ""
  }
  # Tagging an absent value would turn NA into the string "NA" and resurrect a
  # row that should have been dropped.
  with_identifier <- function(value, id) {
    if (!pmsims_is_present(value) || is.na(value)) {
      return(NA_character_)
    }
    paste0(value, identifier(id))
  }

  # --- Data-generating scenario ---------------------------------------------

  # nonlinear_strength is resolved to 0 for complexity 1 and 4, where it has no
  # effect, so only report it where it actually shapes the signal.
  nonlinear_strength <- if (
    pmsims_is_present(complexity) && complexity %in% c(2, 3)
  ) {
    pmsims_fmt_num(x$nonlinear_strength, 2)
  }
  # Objects from simulate_custom(), and those written before the 1.0 data
  # generators, carry predictor_type but no distribution; fall back to it.
  predictor_distribution <- x$predictor_distribution
  predictor_type <- if (is.null(predictor_distribution)) x$predictor_type
  predictor_prevalence <- if (identical(x$predictor_type, "binary")) {
    pmsims_fmt_num(x$binary_predictor_prevalence, 2)
  }
  signal_form <- pmsims_signal_form_label(complexity)
  if (verbose && !is.null(signal_form) && pmsims_is_present(complexity)) {
    signal_form <- sprintf("%s (complexity %s)", signal_form, complexity)
  }

  scenario <- pmsims_section(
    "Data-generating scenario",
    pmsims_compact(
      pmsims_field("Outcome", pmsims_outcome_label(outcome)),
      pmsims_field(
        "Prevalence",
        pmsims_fmt_num(x$outcome_prevalence %||% x$prevalence, 2)
      ),
      pmsims_field("Baseline hazard", pmsims_fmt_signif(x$baseline_hazard, 3)),
      pmsims_field("Censoring rate", pmsims_fmt_num(x$censoring_rate, 2)),
      pmsims_field(
        "Predictors",
        pmsims_predictor_counts(
          x$signal_parameters %||% x$parameters,
          x$noise_parameters
        )
      ),
      pmsims_field(
        "Predictor distribution",
        pmsims_distribution_label(predictor_distribution)
      ),
      pmsims_field("Predictor type", pmsims_distribution_label(predictor_type)),
      pmsims_field("Predictor prevalence", predictor_prevalence),
      pmsims_field("Predictor correlation", pmsims_fmt_num(x$correlation, 2)),
      pmsims_field("Signal form", signal_form),
      pmsims_field("Nonlinear strength", nonlinear_strength)
    )
  )

  # --- Model and performance -------------------------------------------------

  large_sample <- NULL
  cstatistic <- x$maximum_achievable_cstatistic %||%
    (if (identical(outcome, "binary")) x$cstatistic)
  cindex <- x$maximum_achievable_cindex %||%
    (if (identical(outcome, "survival")) x$cstatistic)
  rsquared <- x$maximum_achievable_rsquared %||% x$r2
  # Identifiers are appended to values rather than to labels: a label carrying
  # "maximum_achievable_cstatistic" would push the value column across the
  # screen for every other row as well.
  if (pmsims_is_present(cstatistic)) {
    large_sample <- pmsims_field(
      "Large-sample C-statistic",
      paste0(
        pmsims_fmt_num(cstatistic, 3),
        identifier("maximum_achievable_cstatistic")
      )
    )
  }
  if (pmsims_is_present(cindex)) {
    large_sample <- pmsims_field(
      "Large-sample C-index",
      paste0(
        pmsims_fmt_num(cindex, 3),
        identifier("maximum_achievable_cindex")
      )
    )
  }
  if (pmsims_is_present(rsquared)) {
    large_sample <- pmsims_field(
      "Large-sample R\u00B2",
      paste0(
        pmsims_fmt_num(rsquared, 3),
        identifier("maximum_achievable_rsquared")
      )
    )
  }

  metric_label <- pmsims_metric_label(metric, outcome)
  criterion <- if (pmsims_is_present(target)) {
    paste0(
      (metric_label %||% "Performance"),
      identifier(metric),
      " ",
      pmsims_metric_operator(metric, target),
      " ",
      pmsims_fmt_num(target, 3)
    )
  }

  model_performance <- pmsims_section(
    "Model and performance",
    pmsims_compact(
      pmsims_field(
        "Model",
        if (verbose) {
          paste0(pmsims_model_label(model, outcome), identifier(model))
        } else {
          pmsims_model_label(model, outcome)
        }
      ),
      large_sample,
      pmsims_field("Sample-size criterion", criterion)
    )
  )

  # --- Simulation ------------------------------------------------------------

  simulation_fields <- pmsims_compact(
    pmsims_field(
      "Mode",
      if (identical(moa, "assurance")) "Assurance" else "Mean"
    ),
    pmsims_field("Replications", pmsims_fmt_int(x$n_reps_total))
  )
  if (verbose) {
    search_range <- if (
      pmsims_is_present(x$min_sample_size) &&
        pmsims_is_present(x$max_sample_size)
    ) {
      paste0(
        pmsims_fmt_int(x$min_sample_size),
        " to ",
        pmsims_fmt_int(x$max_sample_size)
      )
    }
    simulation_fields <- c(
      simulation_fields,
      pmsims_compact(
        pmsims_field(
          "Replications per point",
          pmsims_fmt_int(x$n_reps_per)
        ),
        pmsims_field("Search method", x$method),
        pmsims_field("Search range", search_range),
        pmsims_field("Evaluation sample size", pmsims_fmt_int(x$test_n))
      )
    )
  }
  simulation <- pmsims_section("Simulation", simulation_fields)

  # A blank line between groups, but only between groups that survived.
  inputs <- list()
  for (section in Filter(
    length,
    list(scenario, model_performance, simulation)
  )) {
    if (length(inputs)) {
      inputs <- c(inputs, list(pmsims_blank()))
    }
    inputs <- c(inputs, section)
  }

  # --- Results ---------------------------------------------------------------

  # Results from older versions hold a diagnostic string when no sample size
  # was found; it is printed as it stands.
  min_n_text <- if (has_n) {
    pmsims_fmt_int(min_n)
  } else if (is.character(min_n)) {
    min_n
  } else {
    "Not found (see status)"
  }
  minimum <- pmsims_field(
    "Minimum sample size",
    min_n_text,
    emphasis = if (has_n) "strong" else "normal"
  )

  performance_heading <- if (has_n) {
    sprintf("Performance at N = %s", pmsims_fmt_int(min_n))
  } else {
    "Performance at the selected sample size"
  }
  target_note <- if (pmsims_is_present(target)) {
    sprintf(
      "(target %s %s)",
      pmsims_metric_operator(metric, target),
      pmsims_fmt_num(target, 3)
    )
  }
  performance_fields <- pmsims_compact(
    pmsims_field(
      metric_label %||% "Performance",
      with_identifier(pmsims_fmt_num(perf_at, 3), metric),
      indent = 4L,
      note = target_note,
      group = "performance",
      marker = csse_mark
    ),
    pmsims_field(
      pmsims_metric_label(metric_2, outcome) %||% "Other metric",
      with_identifier(pmsims_fmt_num(perf2_at, 3), metric_2),
      indent = 4L,
      group = "performance"
    )
  )
  if (verbose && derived_from_csse) {
    performance_fields <- c(
      performance_fields,
      pmsims_compact(pmsims_field(
        "Search scale ('csse')",
        pmsims_fmt_num(x$csse_perf_n, 4),
        indent = 4L,
        note = if (pmsims_is_present(x$csse_target_performance)) {
          sprintf(
            "(target %s %s)",
            cli::symbol$geq,
            pmsims_fmt_num(x$csse_target_performance, 4)
          )
        },
        group = "performance"
      ))
    )
  }
  performance <- pmsims_section(
    performance_heading,
    performance_fields,
    indent = 2L
  )

  status_field <- if (!is.null(x$status) && !identical(x$status, "ok")) {
    pmsims_field("Status", gsub("_", " ", x$status), emphasis = "strong")
  }
  results <- pmsims_compact(minimum, status_field)
  if (length(performance)) {
    results <- c(results, list(pmsims_blank()), performance)
  }
  running_time <- pmsims_field(
    "Running time",
    pmsims_fmt_duration(x$simulation_time),
    emphasis = "muted"
  )
  if (!is.null(running_time)) {
    results <- c(results, list(pmsims_blank(), running_time))
  }

  # --- Notes -----------------------------------------------------------------

  notes <- list()
  if (pmsims_is_present(x$status_message) && !identical(x$status, "ok")) {
    notes <- c(notes, list(pmsims_note(x$status_message)))
  }
  notes <- c(
    notes,
    list(pmsims_note(
      if (identical(moa, "assurance")) {
        "Assurance mode selects N so that the target is achieved with high probability across repeated datasets."
      } else {
        "Mean mode selects N so that the target is achieved on average across repeated datasets."
      }
    ))
  )
  if (derived_from_csse) {
    notes <- c(
      notes,
      # Flush against its text, as on the row it refers to: a space after a
      # small raised glyph reads as a hole rather than as separation.
      list(pmsims_note(paste0(
        pmsims_footnote_marker(),
        "Derived from the calibration-slope squared error, on which the ",
        "search was run."
      )))
    )
  }

  items <- list()
  if (length(inputs)) {
    items <- c(items, list(pmsims_rule("Inputs"), pmsims_blank()), inputs)
  }
  if (length(results)) {
    items <- c(
      items,
      list(pmsims_blank(), pmsims_rule("Results"), pmsims_blank()),
      results
    )
  }
  if (length(notes)) {
    items <- c(items, list(pmsims_blank(), pmsims_rule()), notes)
  }
  items
}

# -----------------------------------------------------------------------------
# Rendering
# -----------------------------------------------------------------------------

render_pmsims_summary <- function(x, max_width = 80, verbose = FALSE) {
  scr_width <- min(getOption("width", 80L), as.integer(max_width))
  items <- build_pmsims_items(x, verbose = verbose)

  fields <- Filter(function(it) identical(it$kind, "field"), items)

  # One value column across the whole summary, so Inputs and Results line up.
  # An unusually long label overflows into a two-space gap rather than pushing
  # every other value across the screen.
  value_col <- if (length(fields)) {
    ends <- vapply(
      fields,
      function(it) it$indent + nchar(it$label) + nchar(it$marker %||% ""),
      numeric(1)
    )
    min(max(max(ends) + 2, 27), max(30, floor(scr_width / 2)))
  } else {
    27
  }

  # Notes such as "(target >= 0.900)" align on the widest value in their group.
  group_width <- list()
  for (it in fields) {
    if (!is.na(it$group)) {
      current <- group_width[[it$group]] %||% 0
      group_width[[it$group]] <- max(current, nchar(it$value))
    }
  }

  cli::cat_boxx(
    cli::style_bold(" pmsims: Sample size simulation summary "),
    float = "center",
    padding = 0,
    width = scr_width
  )
  cat("\n")

  for (it in items) {
    switch(
      it$kind,
      blank = cat("\n"),
      rule = if (is.null(it$title)) {
        cli::cat_rule(width = scr_width)
      } else {
        cli::cat_rule(center = it$title, width = scr_width)
      },
      heading = cat(
        strrep(" ", it$indent),
        if (it$indent == 0L) {
          cli::style_bold(cli::col_cyan(it$text))
        } else {
          cli::style_bold(it$text)
        },
        "\n",
        sep = ""
      ),
      note = {
        for (line in strwrap(it$text, width = scr_width)) {
          cat(cli::col_silver(cli::style_italic(line)), "\n", sep = "")
        }
      },
      field = cat(
        pmsims_render_field(it, value_col, group_width),
        "\n",
        sep = ""
      )
    )
  }

  invisible(NULL)
}

pmsims_render_field <- function(it, value_col, group_width) {
  label_style <- switch(
    it$emphasis,
    strong = cli::style_bold,
    muted = cli::col_silver,
    identity
  )
  value_style <- switch(
    it$emphasis,
    strong = function(txt) cli::style_bold(cli::col_blue(txt)),
    muted = cli::col_silver,
    identity
  )

  marker <- it$marker %||% ""
  gap <- max(value_col - it$indent - nchar(it$label) - nchar(marker), 2)
  line <- paste0(
    strrep(" ", it$indent),
    label_style(it$label),
    if (nzchar(marker)) cli::col_silver(marker) else "",
    strrep(" ", gap),
    value_style(it$value)
  )

  if (!is.null(it$note)) {
    width <- if (!is.na(it$group)) {
      group_width[[it$group]] %||% nchar(it$value)
    } else {
      nchar(it$value)
    }
    line <- paste0(
      line,
      strrep(" ", max(width - nchar(it$value), 0) + 4),
      cli::col_silver(it$note)
    )
  }

  line
}

Try the pmsims package in your browser

Any scripts or data that you put into this service are public.

pmsims documentation built on Nov. 15, 2026, 5:07 p.m.