define: Define objects per FDA guidance.
In define: Create FDA-Style Data and Program Definitions

Description Usage Arguments Value Methods (by class) See Also Examples

Defines (documents) a set of files in a manner intended to comply with FDA guidance on submission of study data and related documentation. In particular, files in csv format are converted to SAS Transport (xpt), extensions for other files (presumably ASCII) are coerced to txt, files are copied to a directory tree, and define.pdf is created at the top level to describe the files in more detail.

Define a set of files per FDA guidance.

tag is taken by default as the names of x, but may be supplied explicitly. The following should have the same length as x: tag, description, subdir. subdir may also be length one. Other arguments have length one.

The function iterates across the elements of x to create a 'submission' object, a side effect of which is to copy (conditionally, transformed) each corresponding file to (subdir of) dir. The 'submission' object is then converted to a pdf, written directly to dir as '<stem>.pdf'.

Arguments short, protocol, sponsor, program, author, and date are length-one character that define attributes of the pdf title page. Alternatively, they may be specified by names that reflect position rather than semantics: lhead1, lhead2, rhead1, rhead2, lfoot, rfoot (respectively).

define(x, ...)

## S3 method for class 'character'
define(x, stem = "define", tag = names(x),
  description = basename(x), title = dirname(x[[1]]), short = title,
  protocol = "~", sponsor = "~", program = "~", author = "~",
  date = "\\mydate \\today", logo = NULL, logoscale = 1,
  dir = "./define", subdir = ".", clear = TRUE, units = FALSE, ...)

`x`	paths to existing files to be documented; possibly a named character vector
`...`	passed to as.submission and as.pdf
`stem`	the base of the file name for the pdf to be created
`tag`	short object names for each element of x; appears in pdf menu, and as table name in XPT file
`description`	informative labels for each element of x
`title`	a title to appear in the pdf
`short`	short title a.k.a. lhead1 (upper left pdf header)
`protocol`	relevant protocols a.k.a. lhead2 (lower left pdf header)
`sponsor`	study sponsor a.k.a. rhead1 (upper right pdf header)
`program`	drug development program a.k.a. rhead2 (lower right pdf header)
`author`	document author a.k.a. lfoot left pdf footer, italicized)
`date`	date format string a.k.a. rfoot (right footer) today's date by default
`logo`	file path for logo to include on cover page
`logoscale`	size adjustment for logo
`dir`	path to directory in which to place pdf and copied (transformed) files
`subdir`	path to subdirectories to which to copy each (transformed) file represented by x; use NULL to suppress archiving
`clear`	should dir be deleted if it exists?
`units`	should units for continuous varables be printed in Codes column?

invisible result of as.pdf. Used for side effects.

character: character method for define

http://tinyurl.com/fda-pdf-spec-4-0

http://tinyurl.com/fda-study-data-spec-2-0

library(spec)                   # read and write data specifications
library(latexpdf)               # make dummy logo for pdf
library(encode)                 # encode factor levels for spec file

dir <- tempdir()                # a place to experiment
dir <- gsub('\\\\','/',dir)     # clean up windows path
outdir <- file.path(dir,'out')  # where to put the define archive
csv <- file.path(dir,'theoph.csv')    # path to data
script <- file.path(dir,'theoph.R')   # path to script making data
spec <- file.path(dir,'theoph.spec')  # path to data specification

# make dummy logo
## Not run: 
as.pdf('{\\huge \\em Pharma, Inc.}',wide = 50, long = 8,stem = 'logo', dir = dir)

## End(Not run)
# browseURL(system.file(package = 'define', 'logo.pdf')) # cached
logo <- system.file(package = 'define', 'logo.pdf')     # path to dummy logo

# make data more interesting
Theoph$renal <- 0

# create script
code <- "write.csv(x = Theoph,file = csv,row.names = FALSE,quote = FALSE)"
writeLines(code,script)

# 'run' the script
eval(parse(text = code))

# make data specification
s <- specification(Theoph)
renalcat <- c(
 'GFR >= 90 mL/min/1.73m^2',
 '60 <= GFR < 90 mL/min/1.73m^2',
 '45 <= GFR < 60 mL/min/1.73m^2',
 '30 <= GFR < 45 mL/min/1.73m^2',
 'GFR < 30 mL/min/1.73m^2'
)
codes <- encode(0:4, renalcat)
codes
s$guide[s$column == 'renal'] <- codes

write.spec(s,spec)

file.exists(csv)
file.exists(spec)
# define(c(theoph = csv),stem = 'minimal',dir = outdir, clean=FALSE)
# browseURL(file.path(outdir,'minimal.pdf'))
# browseURL(system.file(package = 'define', 'minimal.pdf')) # cached

## Not run: 
define(
  x = c(
    theodat = csv,
    theoprg = script
   ),
  subdir = c(
    'm5/datasets/analysis/datasets',
    'm5/datasets/analysis/programs'
  ),
  description = c(
    'Theophylline PK Dataset',
    'Theophylline PK Script'
  ),
  title = 'Pharmacokinetics of Theophylline',
  short = 'Theophylline PK',
  protocol = 'Protocol tpk-001',
  sponsor = 'Pharma, Inc.',
  program = 'Theophylline',
  author = 'define package for R',
  logo = logo,
  logoscale = 2,
  clear = FALSE,
  dir = outdir
)
# browseURL(file.path(outdir,'define.pdf'))

## End(Not run)
# browseURL(system.file(package = 'define','define.pdf')) # cached
# browseURL(system.file(package = 'define','poster.pdf')) # earlier work

# Alternatively, supply aesthetics by position:
## Not run: 
define(
  x = c(
    theodat = csv,
    theoprg = script
   ),
  subdir = c(
    'm5/datasets/analysis/datasets',
    'm5/datasets/analysis/programs'
  ),
  description = c(
    'Theophylline PK Dataset',
    'Theophylline PK Script'
  ),
  title = 'Pharmacokinetics of Theophylline',
  lhead1 = 'Theophylline PK',
  lhead2 = 'Protocol tpk-001',
  rhead1 = 'Pharma, Inc.',
  rhead2 = 'Theophylline',
  lfoot = 'define package for R',
  rfoot = '\\mydate \\today',
  logo = logo,
  logoscale = 2,
  clear = FALSE,
  dir = outdir
)

## End(Not run)

# Tags for elements of x can be given explicitly rather than as names:
## Not run: 
define(
  x   = c(csv, script),
  tag = c('theodat','theoprg'),
  subdir = c(
    'm5/datasets/analysis/datasets',
    'm5/datasets/analysis/programs'
  ),
  description = c(
    'Theophylline PK Dataset',
    'Theophylline PK Script'
  ),
  title = 'Pharmacokinetics of Theophylline',
  lhead1 = 'Theophylline PK',
  lhead2 = 'Protocol tpk-001',
  rhead1 = 'Pharma, Inc.',
  rhead2 = 'Theophylline',
  lfoot = 'define package for R',
  rfoot = '\\mydate \\today',
  logo = logo,
  logoscale = 2,
  clear = FALSE,
  dir = outdir
)

## End(Not run)

# If the title is short, no need to supply a short version.
# Most arguments have suitable defaults. But be sure to
# supply tags, or names for elements of x.
## Not run: 
define(
  x = c(
    theodat = csv,
    theoprg = script
   ),
  description = c(
    'Theophylline PK Dataset',
    'Theophylline PK Script'
  ),
  title = 'Theophylline PK',
  dir = outdir
)

## End(Not run)