paginate_indices: Paginate a table-like object for rendering

Description

These functions perform or diagnose bi-directional pagination on an object.

paginate_to_mpfs renders obj into the MatrixPrintForm (MPF) intermediate representation, and then paginates that MPF into component MPFs each corresponding to an individual page and returns those in a list.

paginate_indices renders obj into an MPF, then uses that representation to calculate the rows and columns of obj corresponding to each page of the pagination of obj, but simply returns these indices rather than paginating obj itself (see details for an important caveat).

diagnose_pagination attempts pagination via paginate_to_mpfs and then returns diagnostic information which explains why page breaks were positioned where they were, or alternatively why no valid paginations could be found.

Usage

paginate_indices(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = character(),
  colwidths = NULL,
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  rep_cols = num_rep_cols(obj),
  col_gap = 3,
  verbose = FALSE
)
paginate_to_mpfs(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = character(),
  colwidths = NULL,
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  rep_cols = num_rep_cols(obj),
  col_gap = 2,
  verbose = FALSE
)
diagnose_pagination(
  obj,
  page_type = "letter",
  font_family = "Courier",
  font_size = 8,
  lineheight = 1,
  landscape = FALSE,
  pg_width = NULL,
  pg_height = NULL,
  margins = c(top = 0.5, bottom = 0.5, left = 0.75, right = 0.75),
  lpp = NA_integer_,
  cpp = NA_integer_,
  min_siblings = 2,
  nosplitin = character(),
  colwidths = propose_column_widths(matrix_form(obj, TRUE)),
  tf_wrap = FALSE,
  max_width = NULL,
  indent_size = 2,
  pg_size_spec = NULL,
  rep_cols = num_rep_cols(obj),
  col_gap = 2,
  verbose = FALSE,
  ...
)

Value

for paginate_indices a list with two elements of the same length: pag_row_indices, and pag_col_indices. For paginate_to_mpfs, a list of MatrixPrintForm objects representing each individual page after pagination (including forced pagination if necessary).

For diagnose_pagination a list containing:

lpp_diagnostics: diagnostic information regarding lines per page

row_diagnostics

basic information about rows, whether pagination was attempted after each row, and the final result of such an attempt, if made

cpp_diagnostics}{diagnostic information regarding columns per page} \item{col_diagnostics`

(very) basic information about leaf columns, whether pagination was attempted after each leaf column, ad the final result of such attempts, if made

Arguments

obj: ANY. object to be paginated. Must have a matrix_form method.
page_type: character(1). Name of a page type. See page_types. Ignored when pg_width and pg_height are set directly.
font_family: character(1). Name of a font family. An error will be thrown if the family named is not monospaced. Defaults to Courier.
font_size: numeric(1). Font size, defaults to 12.
lineheight: numeric(1). Line height, defaults to 1.
landscape: logical(1). Should the dimensions of page_type be inverted for landscape? Defaults to FALSE, ignored when pg_width and pg_height are set directly.
pg_width: numeric(1). Page width in inches.
pg_height: numeric(1). Page height in inches.
margins: numeric(4). Named numeric vector containing 'bottom', 'left', 'top', and 'right' margins in inches. Defaults to .5 inches for both vertical margins and .75 for both horizontal margins.
lpp: numeric(1) or NULL. Lines per page. if NA (the default, this is calculated automatically based on the specified page size). NULL indicates no vertical pagination should occur.
cpp: numeric(1) or NULL. Width in characters per page. if NA (the default, this is calculated automatically based on the specified page size). NULL indicates no horizontal pagination should occur.
min_siblings: numeric. Minimum sibling rows which must appear on either side of pagination row for a mid-subtable split to be valid. Defaults to 2.
nosplitin: character. List of names of sub-tables where page-breaks are not allowed, regardless of other considerations. Defaults to none.
colwidths: numeric vector. Column widths (in characters) for use with vertical pagination.
tf_wrap: logical(1). Should the texts for title, subtitle, and footnotes be wrapped?
max_width: integer(1), character(1) or NULL. Width that title and footer (including footnotes) materials should be word-wrapped to. If NULL, it is set to the current print width of the session (getOption("width")). If set to "auto", the width of the table (plus any table inset) is used. Ignored completely if tf_wrap is FALSE.
indent_size: numeric(1). Indent size in characters. Ignored when x is already a MatrixPrintForm object in favor of information there.
pg_size_spec: page_size_spec. A pre-calculated page size specification. Typically this is not set in end user code.
rep_cols: numeric(1). Number of columns (not including row labels) to be repeated on every page. Defaults to 0
col_gap: numeric(1). Currently unused.
verbose: logical(1). Should additional informative messages about the search for pagination breaks be shown. Defaults to FALSE.
...: Passed to individual methods.

Details

All three of these functions generally support all classes which have a corresponding matrix_form method which returns a valid MatrixPrintForm object (including MatrixPrintForm objects themselves).

paginate_indices is directly called by paginate_to_mpfs (and thus diagnose_pagination). For most classes, and most tables represented by supported classes, calling paginate_to_mpfs is equivalent to a manual paginate_indices -> subset obj into pages -> matrix_form workflow.

The exception to this equivalence is objects which support 'forced pagination', or pagination logic which built into the object itself rather than being a function of space on a page. Forced pagination generally involves the creation of, e.g., page-specific titles which apply to these forced paginations. paginate_to_mpfs and diagnose_pagination support forced pagination by automatically calling the do_forced_pagination generic on the object and then paginating each object returned by that generic separately. The assumption here, then, is that page-specific titles and such are handled by the class' do_forced_pagination method.

paginate_indices, on the other hand, does not support forced pagination, because it returns only a set of indices for row and column subsetting for each page, and thus cannot retain any changes, e.g., to titles, done within do_forced_paginate. paginate_indices does call do_forced_paginate, but instead of continuing, it throws an error in the case that the result is more than a single "page".

diagnose_pagination attempts pagination and then, regardless of success or failure, returns diagnostic information about pagination attempts (if any) after each row and column.

The diagnostics data reflects the final time the pagination algorithm evaluated a page break at the specified location, regardless of how many times the position was assessed total.

To get information about intermediate attempts, perform pagination with verbose = TRUE and inspect the messages in order.

Examples

Run this code

mpf <- basic_matrix_form(mtcars)

paginate_indices(mpf, pg_width = 5, pg_height = 3)

paginate_to_mpfs(mpf, pg_width = 5, pg_height = 3)

diagnose_pagination(mpf, pg_width = 5, pg_height = 3)
clws <- propose_column_widths(mpf)
clws[1] <- floor(clws[1]/3)
dgnost <- diagnose_pagination(mpf, pg_width = 5, pg_height = 3, colwidths = clws)
try(diagnose_pagination(mpf, pg_width = 1)) #fails