addRefmark: Add a Reference Mark to Entries in a Table

Description

Add a reference mark (a symbol placed before or after entry text to indicate cross-references; e.g. for footnotes) to entries in a table.

Usage

addRefmark(x, mark, before=character(0), after=character(0), 
    parts=NULL, raise, ...)

Value

An object like x. The text of table cells/entries selected by before and after will be modified to include the reference mark, and if raise is TRUE, those cells/entries will be flagged to indicate that they should be treated as plotmath expressions.

Arguments

x: A textTable or pltdTable object.
mark: Character string containing the reference mark.
before, after: Character strings containing regular expressions (see ?regex) that will be matched against the _text_ of table entries (using grepl). One or both of before and after may be specified.
parts: Optional character vector listing table parts. If specified, only entries in those parts will be matched against before and after. The default is to use all table parts.
raise: Logical scalar. If TRUE, the reference mark will be displayed as a superscript, using plotmath. The default is TRUE except for asterisk marks, since that character is already raised relative to other characters.
...: Additional arguments passed to grepl when matching before and after to entry text.

Details

Reference marks are placed at the beginning or end of an entry's text. If raise is TRUE they will be displayed as superscripts. This is implemented by converting the text to make use of R's plotmath facility to create the superscript. A limitation of plotmath is that it ignores newline characters within text. Therefore raised reference marks will not work with multi-line entries, and a warning will be issued.

In addition to using numbers, letters, or asterisk as reference marks, traditional symbols can be specified by their unicode values: dagger ("\u2020"), double dagger ("\u2021"), paragraph symbol ("\u00B6"), section symbol ("\u00A7"), and double vertical bars ("\u2016"). However, unicode symbols may not be available for all OS's or graphics devices.

With this function the user identifies the entries to be marked by searching the entry text itself, via regular expressions before and/or after. For plotted tables (pltdTable objects), an alternative way to add reference marks is to use one of the props<- functions to assign an element_refmark to it. They allow selection of entries using other descriptors.

Examples

Run this code

# Add reference marks to a 'textTable':
ttbl <- textTable(iris2_tab, foot="sd = standard deviation")
ttbl <- addRefmark(ttbl, mark="a", before="sd =", after="sd$")
plot(ttbl)

# Add reference marks to a 'pltdTable':
plt <- plot(textTable(iris2_tab, foot="sd = standard deviation"))
plt <- addRefmark(plt, mark="*", before="sd =", after="sd$")
plt

# To add a reference mark to just the *first* appearance of "sd", use 
# 'propsa<-' instead:
plt <- plot(textTable(iris2_tab, foot="sd = standard deviation"))
plt <- addRefmark(plt, mark="a", before="sd =")
propsa(plt, arows=arow(plt, hpath=c("setosa", "sd")), 
       acols=acol(plt, "rowhead")[2]) <- element_refmark("a", side="after")
plt