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

In tablesgg: Presentation-Quality Tables, Displayed Using 'ggplot2'

Constrained Display Sizes of Each Table Row, Column and Entry

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

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.

• An NA value for minwidth means there is no constraint on minimum width, and is equivalent to 0. An Inf value for maxwidth means there is no constraint on maximum width. In the absence of constraints, the internal algorithm favors widths as close as possible to the natural width of the entry text, without wrapping.

• An NA value for maxwidth means the maximum width will be determined passively from the maxwidth values of other entries in the same table column(s) (if angle is 0 or 180) or row(s) (if angle is 90 or 270). (It will never be less than minwidth.) This may be useful for table titles and footnotes, where long text should be wrapped to fit widths implied by the other table entries.

• Setting maxwidth to NA or to a finite value > -1 and < Inf means the spanned cell(s) may not be wide enough to hold the text without wrapping it into multiple lines.

• The general effect of setting minwidth to a non-zero value is to reduce or prevent text wrapping, while the general effect of setting maxwidth to NA or a finite value is to encourage wrapping. Settings for one entry may affect the width and wrapping of other entries, because column widths and row heights for the table as a whole must satisfy the constraints for all their entries.

• Text representing plotmath expressions cannot be wrapped, so maxwidth should be Inf or <= -1 for such entries.

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 22, 2024, 11:02 a.m.