pointblank (version 0.7.0)

create_informant: Create a pointblank informant object

Description

The create_informant() function creates an informant object, which is used in an information management workflow. The overall aim of this workflow is to record, collect, and generate useful information on data tables. We can supply as information that is useful for describing a particular data table. The informant object created by the create_informant() function takes information-focused functions: info_columns(), info_tabular(), info_section(), and info_snippet().

The info_*() series of functions allows for a progressive build up of information about the target table. The info_columns() and info_tabular() functions facilitate the entry of info text that concerns the table columns and the table proper; the info_section() function allows for the creation of arbitrary sections that can have multiple subsections full of additional info text. The system allows for dynamic values culled from the target table by way of info_snippet(), for getting named text extracts from queries, and the use of {<snippet_name>} in the info text. To make the use of info_snippet() more convenient for common queries, a set of snip_*() functions are provided in the package (snip_list(), snip_stats(), snip_lowest(), and snip_highest()) though you are free to use your own expressions.

Because snippets need to query the target table to return fragments of info text, the incorporate() function needs to be used to initiate this action. This is also necessary for the informant to update other metadata elements such as row and column counts. Once the incorporation process is complete, snippets and other metadata will be updated. Calling the informant itself will result in a reporting table. This reporting can also be accessed with the get_informant_report() function, where there are more reporting options.

Usage

create_informant(
  tbl = NULL,
  read_fn = NULL,
  agent = NULL,
  tbl_name = NULL,
  label = NULL,
  lang = NULL,
  locale = NULL
)

Arguments

tbl

The input table. This can be a data frame, a tibble, a tbl_dbi object, or a tbl_spark object. Alternatively, a function can be used to read in the input data table with the read_fn argument (in which case, tbl can be NULL).

read_fn

A function that's used for reading in the data. Even if a tbl is provided, this function will be invoked to obtain the data (i.e., the read_fn takes priority). There are two ways to specify a read_fn: (1) using a function (e.g., function() { <table reading code> }) or, (2) with an R formula expression.

agent

A pointblank agent object. This object can be used instead of supplying a table in tbl or a table-prep formula in read_fn.

tbl_name

A optional name to assign to the input table object. If no value is provided, a name will be generated based on whatever information is available.

label

An optional label for the information report. If no value is provided, a label will be generated based on the current system time. Markdown can be used here to make the label more visually appealing (it will appear in the header area of the information report).

lang

The language to use for the information report (a summary table that provides all of the available information for the table. By default, NULL will create English ("en") text. Other options include French ("fr"), German ("de"), Italian ("it"), Spanish ("es"), Portuguese, ("pt"), Chinese ("zh"), and Russian ("ru").

locale

An optional locale ID to use for formatting values in the information report according the locale's rules. Examples include "en_US" for English (United States) and "fr_FR" for French (France); more simply, this can be a language identifier without a country designation, like "es" for Spanish (Spain, same as "es_ES").

Value

A ptblank_informant object.

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()). Here is an example of how a complex call of create_informant() is expressed in R code and in the corresponding YAML representation.

# R statement
create_informant(
  read_fn = ~ small_table,
  tbl_name = "small_table",
  label = "An example.",
  lang = "fr", 
  locale = "fr_CA"
)
# YAML representation
type: informant
read_fn: ~small_table
tbl_name: small_table
info_label: An example.
lang: fr
locale: fr_CA
table:
  name: small_table
  _columns: 8
  _rows: 13.0
  _type: tbl_df
columns:
  date_time:
    _type: POSIXct, POSIXt
  date:
    _type: Date
  a:
    _type: integer
  b:
    _type: character
  c:
    _type: numeric
  d:
    _type: numeric
  e:
    _type: logical
  f:
    _type: character

The generated YAML includes some top-level keys where type and read_fn are mandatory, and, two metadata sections: table and columns. Keys that begin with an underscore character are those that are updated whenever incorporate() is called on an informant. The table metadata section can have multiple subsections with info text. The columns metadata section can similarly have have multiple subsections, so long as they are children to each of the column keys (in the above YAML example, date_time and date are column keys and they match the table's column names). Additional sections can be added but they must have key names on the top level that don't duplicate the default set (i.e., type, table, columns, etc. are treated as reserved keys).

Writing an Informant to Disk

An informant object can be written to disk with the x_write_disk() function. Informants are stored in the serialized RDS format and can be easily retrieved with the x_read_disk() function.

It's recommended that table-prep formulas are supplied to the read_fn argument of create_informant(). In this way, when an informant is read from disk through x_read_disk(), it can be reused to access the target table (which may changed, hence the need to use an expression for this).

Figures

Function ID

1-3

See Also

Other Planning and Prep: action_levels(), create_agent(), db_tbl(), file_tbl(), scan_data(), tbl_get(), tbl_source(), tbl_store(), validate_rmd()

Examples

# NOT RUN {
# Let's walk through how we can
# generate some useful information for a
# really small table; it's actually
# called `small_table` and we can find
# it as a dataset in this package
small_table

# Create a pointblank `informant`
# object with `create_informant()`
# and the `small_table` dataset
informant <- 
  create_informant(
    read_fn = ~small_table,
    tbl_name = "small_table",
    label = "An example."
  )

# This function creates some information
# without any extra help by profiling
# the supplied table object; it adds
# the sections: (1) 'table' and
# (2) 'columns' and we can print the
# object to see the information report

# Alternatively, we can get the same report
# by using `get_informant_report()`
report <- get_informant_report(informant)
class(report)

# }