Skip to contents

Emit named values as a generated include file

Source: R/report-macros.R
cr_macros.Rd

Writes every number a write-up quotes into one machine-generated file, so the text can reference the value by name instead of repeating the digits. A number that lives in exactly one place cannot disagree with itself: re-run the analysis, re-emit the file, and the document is current. Splicing an estimate from one run beside an interval from another stops being possible.

Usage

cr_macros(
  values,
  file,
  format = c("tex", "json", "yaml"),
  prefix = NULL,
  header = NULL,
  digits = 3,
  big_mark = ",",
  na = "--"
)

Arguments

values

A named list or named atomic vector of scalars. Nested named lists are flattened, joining the names.

file

Output path. When NULL the formatted lines are returned instead of being written.

format

"tex" (default) writes \newcommand definitions with presentation-formatted values; "json" and "yaml" write the underlying values, rounded but otherwise raw, for downstream tools.

prefix

Optional prefix prepended to every name. A prefix is worth setting for "tex" output: it keeps generated names clear of the commands LaTeX already defines, such as \label or \date, which cannot be redefined with \newcommand.

header

Optional character vector of header lines. NULL emits a default "generated file, do not edit" banner; character() emits none.

digits

Decimal places used when formatting numbers. Counts — integers, and round values of 1000 or more — are written without decimals and with big_mark separators.

big_mark

Thousands separator used in "tex" output.

na

Placeholder for non-finite values in "tex" output.

Value

The output path (invisibly), or a character vector of lines when file is NULL.

Details

LaTeX control sequences may contain letters only, so names are transliterated by cr_macro_name() — "CompoundA_5min" becomes \CompoundAfivemin. Two source names that transliterate to the same macro are an error rather than a silent overwrite.

See also

cr_macros_from() to derive the values from a report, cr_macro_name(), cr_format_number(), cr_enumerate().

Other macros: cr_enumerate(), cr_format_number(), cr_macro_name(), cr_macros_from()

Examples

vals <- list(cells_analyzed = 128400L, units_analyzed = 96L,
             top_estimate = 1.42, top_ci_low = 0.55)
cat(cr_macros(vals, file = NULL), sep = "\n")
#> % Generated by cellreportR -- do not edit by hand.
#> % Every value is derived from the analysis object. If one looks
#> % wrong, fix the analysis and emit this file again.
#> 
#> \newcommand{\cellsanalyzed}{128,400}
#> \newcommand{\unitsanalyzed}{96}
#> \newcommand{\topestimate}{1.420}
#> \newcommand{\topcilow}{0.550}

f <- tempfile(fileext = ".tex")
cr_macros(vals, f, prefix = "screen")
cat(readLines(f)[1:2], sep = "\n")
#> % Generated by cellreportR -- do not edit by hand.
#> % Every value is derived from the analysis object. If one looks