Generate a useful text 'snippet' from the target table

Getting little snippets of information from a table goes hand-in-hand with mixing those bits of info with your table info. Call info_snippet() to define a snippet and how you'll get that from the target table. The snippet definition is supplied either with a formula, or, with a pointblank-supplied snip_*() function. So long as you know how to interact with a table and extract information, you can easily define snippets for a informant object. And once those snippets are defined, you can insert them into the info text as defined through the other info_*() functions (info_tabular(), info_columns(), and info_section()). Use curly braces with just the snippet_name inside (e.g., "This column has {n_cat} categories.").

info_snippet(x, snippet_name, fn)

Arguments

x	An informant object of class `ptblank_informant`.
snippet_name	The name for snippet, which is used for interpolating the result of the snippet formula into info text defined by an `info_*()` function.
fn	A formula that obtains a snippet of data from the target table. It's best to use a leading dot (`.`) that stands for the table itself and use pipes to construct a series of operations to be performed on the table (e.g., `~ . %>% dplyr::pull(column_2) %>% max(na.rm = TRUE)`). So long as the result is a length-1 vector, it'll likely be valid for insertion into some info text. Alternatively, a `snip_*()` function can be used here (these functions always return a formula that's suitable for all types of data sources).

Value

A ptblank_informant object.

Snip functions provided in pointblank

For convenience, there are several snip_*() functions provided in the package that work on column data from the informant's target table. These are:

snip_list(): get a list of column categories
snip_stats(): get an inline statistical summary
snip_lowest(): get the lowest value from a column
snip_highest() : get the highest value from a column

As it's understood what the target table is, only the column in each of these functions is necessary for obtaining the resultant text.

YAML

A pointblank informant can be written to YAML with yaml_write() and the resulting YAML can be used to regenerate an informant (with yaml_read_informant()) or perform the 'incorporate' action using the target table (via yaml_informant_incorporate()). Snippets are stored in the YAML representation and here is is how they are expressed in both R code and in the YAML output (showing both the meta_snippets and columns keys to demonstrate their relationship here).

# R statement
informant %>% 
  info_columns(
    columns = "date_time",
    `Latest Date` = "The latest date is {latest_date}."
  ) %>%
  info_snippet(
    snippet_name = "latest_date",
    fn = ~ . %>% dplyr::pull(date) %>% max(na.rm = TRUE)
  ) %>%
  incorporate()

# YAML representation
meta_snippets:
  latest_date: ~. %>% dplyr::pull(date) %>% max(na.rm = TRUE)
...
columns:
  date_time:
    _type: POSIXct, POSIXt
    Latest Date: The latest date is {latest_date}.
  date:
    _type: Date
  item_count:
    _type: integer

Figures

Function ID

3-4

Examples

# Take the `small_table` and
# assign it to `test_table`; we'll
# modify it later
test_table <- small_table

# Generate an informant object, add
# two snippets with `info_snippet()`,
# add information with some other
# `info_*()` functions and then
# `incorporate()` the snippets into
# the info text
informant <- 
  create_informant(
    read_fn = ~ test_table,
    tbl_name = "test_table",
    label = "An example."
  ) %>%
  info_snippet(
    snippet_name = "row_count",
    fn = ~ . %>% nrow()
  ) %>%
  info_snippet(
    snippet_name = "max_a",
    fn = snip_highest(column = "a")
  ) %>%
  info_columns(
    columns = vars(a),
    info = "In the range of 1 to {max_a}. (SIMPLE)"
  ) %>%
  info_columns(
    columns = starts_with("date"),
    info = "Time-based values (e.g., `Sys.time()`)."
  ) %>%
  info_columns(
    columns = "date",
    info = "The date part of `date_time`. (CALC)"
  ) %>%
  info_section(
    section_name = "rows",
    row_count = "There are {row_count} rows available."
  ) %>%
  incorporate()
#> Error in rlang::eval_tidy(., env = caller_env(n = 1)) object 'test_table' not found

# We can print the `informant` object
# to see the information report

# Let's modify `test_table` to give
# it more rows and an extra column
test_table <- 
  dplyr::bind_rows(test_table, test_table) %>%
  dplyr::mutate(h = a + c)

# Using `incorporate()` will cause
# the snippets to be reprocessed, and,
# the info text to be updated
informant <-
  informant %>% incorporate()
#> Error in incorporate(.) object 'informant' not found