calc_rcsize: Constrained Display Sizes of Each Table Row, Column and Entry

Description Usage Arguments Details Value Note See Also

View source: R/calc_rcsize.bare.R

Description

Calculate the display widths (in mm) of each table column, heights of each table row, and horizontal and vertical dimensions of each table entry. Calculations may use the constraints imposed by minwidth and maxwidth for each entry. This is an internal utility function, not intended to be called by package users.

Usage

1
2
calc_rcsize(entryInfo, vrule_hsize, hrule_vsize, sizeAdjust, 
    nominal_rcmin, method)

Arguments

entryInfo

A prEntries data frame with one row per table entry. (Currently disabled entries are not allowed.)

vrule_hsize

Numeric vector with length (# table columns) + 1, giving the horizontal dimensions, in mm, of vertical rules in the table.

hrule_vsize

Numeric vector with length (# table rows) + 1, giving the vertical dimensions, in mm, of horizontal rules in the table.

sizeAdjust

Two-element numeric vector containing multipliers to adjust the calculated absolute size of table text, when determining row and column sizes. Essentially fudge factors. The first element is applied to the horizontal dimension and the second to the vertical dimension.

nominal_rcmin

A nominal minimum size for any row or column, in mm. It is used to avoid division by 0 when calculating the proportional change in size due to constraints, when method is 2-5. Large size adjustments are disfavored for rows or columns whose actual size is less than this value.

method

Which algorithm/objective function is used for the constrained optimization problem.

  • 0 : minwidth, maxwidth constraints on entries are ignored; no wrapping.

  • 1 : minwidth constraints are respected but maxwidth is ignored; no wrapping.

  • 2 : Proportional size changes are calculated with max(<natural width>, nominal_rcmin) replacing <natural width> in the denominator.

  • 3 : Proportional size changes are calculated with max(<natural width>, nominal_rcmin) replacing <natural width> in both the numerator and denominator.

  • 4 or 5 : Same as 2 or 3 but with the sum <natural width> + nominal_rcmin instead of their max.

Details

Entries can span multiple columns and rows, and can have constraints on their minimum and maximum widths. This function calculates row and column dimensions that satisfy the constraints while minimizing an objective function that measures deviations from their natural sizes. They are the solution to a quadratic programming problem. An error will be raised if the QP has no solution (e.g., if minwidth and maxwidth collectively, over all entries, are inconsistent).

minwidth and maxwidth are in the text's frame of reference, and may be expressed in two forms. Positive values are interpreted as absolute widths in millimeters, and *should* include the amount of any padding specified by hpad (when angle is 0 or 180 degrees) or vpad (when angle is 90 or 270 degrees), as well as scaling by sizeAdjust. Negative values are interpreted as multiples of the natural text width without wrapping and *without* including padding or sizeAdjust. Thus setting minwidth for an entry to -1 will guarantee that the width of the spanned cell(s) will be at least enough to contain it without wrapping.

method=0 ignores minwidth and maxwidth when determining row and column sizes. However a warning will be raised if the resulting sizes violate the constraints for any enabled entries.

Value

List with components:

hsizeCol

Numeric vector of display widths for each table column, in mm.

vsizeRow

Numeric vector of display heights for each table row, in mm.

sizeInfo

Data frame with one row per table entry. Columns are hsize and vsize (the horizontal and vertical dimensions of entry text, as it would be displayed by geom_text, geom_richtext, or geom_textbox after applying any min or max contraints); horiz (logical, TRUE if entry angle is 0 or 180 degrees); descender (amount of space included in vsize (if horiz is TRUE) or hsize (if horiz is FALSE) to allow for descenders); and wrap (logical; TRUE if text wrapping is needed to fit the text into a box with dimensions hsize and vsize). Row names will be the entry ID's. hsize, vsize, and descender do not include the effect of sizeAdjust, and do not include any padding specified by hpad or vpad. All columns will contain NA for disabled entries. (Not implemented–currently, disabled entries are not allowed.)

Note

Operation of this function is controlled by parameters in internal object internalOpt, specifically those with prefix rcsize_. Values of option rcsize_verbose greater than 2 will cause a data frame of calculated entry widths to be written to the global environment for each iteration.

Among methods 2-5, 2 and 4 seem best because they do not alter the target size in the numerator; method 5 encourages expanding row *and* column sizes by rcsize_rcmin even when no wrapping is required in a given direction.

See Also

entrySize_mm, called by this function to calculate the sizes in sizeInfo.


tablesgg documentation built on June 3, 2021, 1:06 a.m.