make_output: Create output sink

In mbojan/outputter: Backend for Dumping Outputs from Iterative Simulations

Description

Function make_output() returns an output sink function of a type determined by the class of the output argument. Output sink is a function that has a single argument ... through which one can pass multiple named arguments. These arguments are expected to be vectors of the same length. Repeated calls to an output sink write supplied data to a target, i.e. append a data frame, write to a connection, or append a table in a database. Implemented methods include:

• Appending an existing data frame

• Appending a table in a database

• Writing to a connection

• Creating a data frame "on the fly"

Usage

make_output(output, ...)

## S3 method for class 'data.frame'
make_output(output, ...)

## S3 method for class 'tbl_dbi'
make_output(output, ...)

## S3 method for class 'connection'
make_output(output, ...)

## Default S3 method:
make_output(output, ...)

Arguments

output	an object determining the type of output sink to be created
...	additional arguments, see Details

Details

A call to make_output() returns a function, which we call "output sink". Output sink function has a signature ... and expects named arguments to be vectors of the same length (shorter vectors will be recycled). Output sink is called for its side effect fo writing the supplied data somewhere.

Handling additional arguments passed through ... to make_output() is method-dependent. If not stated otherwise below these arguments need to be named and can be used to insert extra columns which are "iteration-independent". See Examples.

If output is a data frame then the calls to the output sink created will append that data frame. Appending uses bind_rows() which tries to match the columns by name. If output sink is called with an argument not used in previous calls then the result will have a new column and associated rows will have NAs.

If output is an object inheriting from tbl_dbi then each call to the output sink will append the table in the database the tbl_dbi object is pointing to.

If output is a connection object then arguments in ... are passed directly to cat() with argument file given the connection. Argument names are not included in the output nor checked. The order of the values "printed" by cat() is determined by the order of the arguments given to the output sink.

If output is NULL then the result is an "blank" data frame output sink. The first call to the sink will instantiate the columns and subsequent calls will append it, as described above w.r. to the data frame method.

Value

A function, say, output with signature ... which will write data supplied in its arguments.

Examples

# --- Appending a data frame ---

# Do note that the data frame does not have to be "empty"
out <- make_output(data.frame(a=numeric(0), b=numeric(0)))

# A mock-up of iterative simulation
for( i in 1:5) {
  # Here some very intensive computations producing some `a` and `b`
  # and finally we call out() to write the results
  out(a=i+1, b=i-1)
}

# Calling out() without arguments return the collected results
out()


# --- Appending a data frame with a static column ---

out <- make_output(data.frame(a=numeric(0), b=numeric(0)), static=1)

for( i in 1:5) {
  out(a=i+1, b=i-1)
}

# Now the result has also column `static` always equal to 1
out()


# --- Appending a table in a database ---

if(requireNamespace("RSQLite", quietly=TRUE)) {
  # In-memory SQLite database
  con <- DBI::dbConnect(RSQLite::SQLite(), ":memory:")
  # An empty table in database
  DBI::dbWriteTable(con, "output", data.frame(a=numeric(0), b=numeric(0)))
  # A tbl_dbi table "pointing to" the database table
  d <- dplyr::tbl(con, "output")

  out <- make_output(d)

  # A mock-up of iterative simulation
  for( i in 1:5) {
    # Here some very intensive computations producing some `a` and `b`
    # and finally we call out() to write the results
    out(a=i+1, b=i-1)
  }

  # Table has the results
  d
  # Calling out() without arguments return the tbl_dbi object
  out()
}


# --- If `output` is NULL columns are created when out() is called ---

out <- make_output(NULL)

# A mock-up of iterative simulation
for( i in 1:5) {
  # Here some very intensive computations producing some `a` and `b`
  # and finally we call out() to write the results
  out(a=i+1, b=i-1)
}

# A dataframe with columns `a` and `b`
out()

# Calling out() with an argument to used earlier
for( i in 1:5) {
  out(c=i+10)
}

# We have a new column with NAs in other columns in last 5 iterations
out()

mbojan/outputter documentation built on May 18, 2019, 3:43 p.m.