Version: 0.7-4
Date: 2023-09-02
Title: Graphical Reporting for Clinical Trials
Author: Frank E Harrell Jr <fh@fharrell.com>
Maintainer: Frank E Harrell Jr <fh@fharrell.com>
Depends: Hmisc (≥ 4.0-0),
Imports: rms (≥ 5.0-0), lattice, latticeExtra, ggplot2, Formula, survival, methods, data.table
Description: Contains many functions useful for monitoring and reporting the results of clinical trials and other experiments in which treatments are compared. LaTeX is used to typeset the resulting reports, recommended to be in the context of 'knitr'. The 'Hmisc', 'ggplot2', and 'lattice' packages are used by 'greport' for high-level graphics.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL: http://hbiostat.org/R/greport/, https://github.com/harrelfe/greport/
RoxygenNote: 7.2.3
NeedsCompilation: no
Packaged: 2023-09-02 18:22:59 UTC; harrelfe
Repository: CRAN
Date/Publication: 2023-09-02 22:20:02 UTC

Graphical Reporting for Clinical Trials

Description

Graphical clinical trial reporting based on Rmarkdown, LaTeX, and pdf

Usage

.noGenerics

Format

An object of class logical of length 1.

Author(s)

Frank E Harrell Jr fh@fharrell.com

Merge Multiple Data Frames or Data Tables

Description

Merges an arbitrarily large series of data frames or data tables containing common id variables (keys for data tables). Information about number of observations and number of unique ids in individual and final merged datasets is printed. The first data frame has special meaning in that all of its observations are kept whether they match ids in other data frames or not. For all other data frames, by default non-matching observations are dropped. The first data frame is also the one against which counts of unique ids are compared. Sometimes merge drops variable attributes such as labels and units. These are restored by Merge. If all objects are of class data.table, faster merging will be done using the data.table package's join operation. This assumes that all objects have identical key variables and those of the variables on which to merge.

Usage

Merge(..., id, all = TRUE, verbose = TRUE)

Arguments

...

two or more dataframes or data tables

id

a formula containing all the identification variables such that the combination of these variables uniquely identifies subjects or records of interest. May be omitted for data tables; in that case the key function retrieves the id variables.

all

set to FALSE to drop observations not found in second and later data frames (only applies if not using data.table)

verbose

set to FALSE to not print information about observations

Examples

a <- data.frame(sid=1:3, age=c(20,30,40))
b <- data.frame(sid=c(1,2,2), bp=c(120,130,140))
d <- data.frame(sid=c(1,3,4), wt=c(170,180,190))
all <- Merge(a, b, d, id = ~ sid)
# For data.table, first file must be the master file and must
# contain all ids that ever occur.  ids not in the master will
# not be merged from other datasets.
require(data.table)
a <- data.table(a); setkey(a, sid)
# data.table also does not allow duplicates without allow.cartesian=TRUE
b <- data.table(sid=1:2, bp=c(120,130)); setkey(b, sid)
d <- data.table(d); setkey(d, sid)
all <- Merge(a, b, d)

Accrual Report

Description

Generate graphics and LaTeX to analyze subject accrual

Usage

accrualReport(
  formula,
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  dateRange = NULL,
  zoom = NULL,
  targetN = NULL,
  targetDate = NULL,
  closeDate = NULL,
  enrollmax = NULL,
  studynos = TRUE,
  minrand = 10,
  panel = "accrual",
  h = 2.5,
  w = 3.75,
  hb = 5,
  wb = 5,
  hdot = 3.5
)

Arguments

formula

formula object, with time variables on the left (separated by +) and grouping variables on the right. Enrollment date, randomization date, region, country, and site when present must have the variables in parenthesis preceeded by the key words enrollment, randomize, region, country, site.

data

data frame.

subset

a subsetting epression for the entire analysis.

na.action

a NA handling function for data frames, default is na.retain.

dateRange

Date or character 2-vector formatted as yyyy-mm-dd. Provides the range on the x-axis (before any zooming).

zoom

Date or character 2-vector for an option zoomed-in look at accrual.

targetN

integer vector with target sample sizes over time, same length as targetDate

targetDate

Date or character vector corresponding to targetN

closeDate

Date or characterstring. Used for randomizations per month and per site-month - contains the dataset closing date to be able to compute the number of dates that a group (country, site, etc.) has been online since randomizating its first subject.

enrollmax

numeric specifying the upper y-axis limit for cumulative enrollment when not zoomed

studynos

logical. Set to FALSE to suppress summary study numbers table.

minrand

integer. Minimum number of randomized subjects a country must have before a box plot of time to randomization is included.

panel

character string. Name of panel, which goes into file base names and figure labels for cross-referencing.

h

numeric. Height of ordinary plots, in inches.

w

numeric. Width of ordinary plots.

hb

numeric. Height of extended box plots.

wb

numeric. Weight of extended box plots.

hdot

numeric. Height of dot charts in inches.

Details

Typically the left-hand-side variables of the formula, in order, are date of enrollment and date of randomization, with subjects enrolled but not randomized having missing date of randomization. Given such date variables, this function generates cumulative frequencies optionally with target enrollment/randomization numbers and with time-zooming. Makes a variety of dot charts by right-hand-side variables: number of subjects, number of sites, number of subjects per site, fraction of enrolled subjects randomized, number per month, number per site-month.

Examples

## Not run: 
# See test.Rnw in tests directory

## End(Not run)

Issue LaTeX section and/or subsection in appendix

Description

This is useful for copying section and subsection titles in the main body of the report to the appendix, to help in navigating supporting tables. LaTeX backslash characters need to be doubled.

Usage

appsection(section = NULL, subsection = NULL, main = FALSE, panel = "")

Arguments

section

a character string that will cause a section command to be added to app.tex

subsection

a character string that will cause a subsection command to be added to app.tex

main

set to TRUE to also write a section or subsection command to the console to be used in building the main report body (graphical section), in which case you should also specify panel if option texdir is not an empty string

panel

panel string; must be given if main=TRUE and option texdir is not ""

Draw Needles

Description

Create a LaTeX picture to draw needles for current sample sizes. Uses colors set by call to setgreportOptions.

Usage

dNeedle(sf, name, file = "", append = TRUE)

Arguments

sf

output of sampleFrac

name

character string name of LaTeX variable to create

file

output file name (character string)

append

set to FALSE to start a new file

Descriptive Statistics Report

Description

Generate graphics and LaTeX with descriptive statistics

Usage

dReport(
  formula,
  groups = NULL,
  what = c("box", "proportions", "xy", "byx"),
  byx.type = c("violin", "quantiles"),
  violinbox = TRUE,
  violinbox.opts = list(col = adjustcolor("blue", alpha.f = 0.25), border = FALSE),
  summaryPsort = FALSE,
  exclude1 = TRUE,
  stable = TRUE,
  fun = NULL,
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  panel = "desc",
  subpanel = NULL,
  head = NULL,
  tail = NULL,
  continuous = 10,
  h = 5.5,
  w = 5.5,
  outerlabels = TRUE,
  append = FALSE,
  sopts = NULL,
  popts = NULL,
  lattice = FALSE
)

Arguments

formula

a formula accepted by the bpplotM or summaryP functions. formula must have an id(subjectidvariable) term if there are repeated measures, in order to get correct subject counts as nobs.

groups

a superpositioning variable, usually treatment, for categorical charts. For continuous analysis variables, groups becomes the y-axis stratification variable. This is a single character string.

what

"box" (the default) or "xy" for continuous analysis variables, or "proportions" (or shorter) for categorical ones. Instead, specifying what="byx" results in an array of quantile intervals for continuous y, Wilson confidence intervals for proportions when y is binary, or means and parametric confidence limits when y is not continuous but is not binary. If what is omitted or what="byx", actions will be inferred from the most continuous variable listed in formula. When fun is given, different behavior results (see below).

byx.type

set to "quantiles" to show vertical quantile intervals of y at each x for when what="byx" and the y variable is continuous numeric, or set byx.type="violin" (the default) to plot half-violin plots at each x.

violinbox

set to TRUE to add violin plots to box plots

violinbox.opts

a list to pass to panel.violin

summaryPsort

set to TRUE to sort categories in descending order of frequencies

exclude1

logical used for latex methods when summaryM or summaryP are called by dReport, or for plot methods for summaryP. The default is TRUE to cause the most frequent level of any two-level categorical variable to not be used as a separate category in the graphic or table. See summaryM.

stable

set to FALSE to suppress creation of backup supplemental tables for graphics

fun

a function that takes individual response variables (which may be matrices, as in Surv objects) and creates one or more summary statistics that will be computed while the resulting data frame is being collapsed to one row per condition. Dot charts are drawn when fun is given.

data

data frame

subset

a subsetting epression for the entire analysis

na.action

a NA handling function for data frames, default is na.retain

panel

character string. Name of panel, which goes into file base names and figure labels for cross-referencing

subpanel

If calling dReport more than once for the same type of chart (by different values of what), specify subpanel to distinguish the multiple calls. In that case, -subpanel will be appended to panel when creating figure labels and cross-references.

head

character string. Specifies initial text in the figure caption, otherwise a default is used

tail

optional character string. Specifies final text in the figure caption, e.g., what might have been put in a footnote in an ordinary text page. This appears just before any needles.

continuous

the minimum number of numeric values a variable must have in order to be considered continuous. Also passed to summaryM.

h

numeric. Height of plot, in inches

w

numeric. Width of plot

outerlabels

logical that if TRUE, pass lattice graphics through the latticeExtra package's useOuterStripsfunction if there are two conditioning (paneling) variables, to put panel labels in outer margins.

append

logical. Set to FALSE to start a new panel

sopts

list specifying extra arguments to pass to bpplotM, summaryP, or summaryS

popts

list specifying extra arguments to pass to a plot method. One example is text.at to specify some number beyond xlim[2] to leave extra space for numerators and denominators when using summaryP for categorical analysis variables. Another common use is for example popts=list(layout=c(columns,rows)) to be used in rendering lattice plots. key and panel are also frequently used.

lattice

set to TRUE to use lattice instead of ggplot2 for proportions. When this option is in effect, numerators and denominators are shown.

Details

dReport generates multi-panel charts, separately for categorical analysis variables and continuous ones. The Hmisc summaryP function and its plot method are used for categorical variables, and bpplotM is used to make extended box plots for continuous ones unless what='byx'. Stratification is by treatment or other variables. The user must have defined a LaTeX macro \eboxpopup (which may be defined to do nothing) with one argument. This macro is called with argument extended box plot whenever that phrase appears in the legend, so that a PDF popup may be generated to show the prototype. See the example in report.Rnw in the tests directory. Similarly a popup macro \qintpopup must be defined, which generates a tooltip for the phrase quantile intervals.

Examples

# See test.Rnw in tests directory

Event Report

Description

Generates graphics for binary event proportions

Usage

eReport(
  formula,
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  minincidence = 0,
  conf.int = 0.95,
  etype = "adverse events",
  panel = "events",
  subpanel = NULL,
  head = NULL,
  tail = NULL,
  h = 6,
  w = 7,
  append = FALSE,
  popts = NULL
)

Arguments

formula

a formula with one or two left hand variables (the first representing major categorization and the second minor), and 1-2 right hand variables. One of these may be enclosed in id() to indicate the presence of a unique subject ID, and the other is treatment.

data

input data frame

subset

subsetting criteria

na.action

function for handling NAs when creating analysis frame

minincidence

a number between 0 and 1 specifying the minimum incidence in any stratum that must hold before an event is included in the summary

conf.int

confidence level for difference in proportions

etype

a character string describing the nature of the events, for example "adverse events", "serious adverse events". Used in figure captions.

panel

panel string

subpanel

a subpanel designation to add to panel

head

character string. Specifies initial text in the figure caption, otherwise a default is used.

tail

a character string to add to end of automatic caption

h

height of graph

w

width of graph

append

set to TRUE if adding to an existing sub-report

popts

a list of options to pass to graphing functions

Details

Generates dot charts showing proportions on left and risk difference with confidence intervals on the right, if there is only one level of event categorization. Input data must contain one record per event, with this record containing the event name. If there is more than one event of a given type per subject, unique subject ID must be provided. Denominators come from greport options and it is assumed that only randomized subjects have records. Some of the graphics functions are modifications of those found in the HH package. The data are expected to have one record per event, and non-events are inferred from setgreportOption('denom'). It is also assumed that only randomized subjects are included in the dataset.

Author(s)

Frank Harrell

Examples

# See test.Rnw in tests directory

Exclusion Report

Description

Generates graphics for sequential exclusion criteria

Usage

exReport(
  formula,
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  ignoreExcl = NULL,
  ignoreRand = NULL,
  plotExRemain = TRUE,
  autoother = FALSE,
  sort = TRUE,
  whenapp = NULL,
  erdata = NULL,
  panel = "excl",
  subpanel = NULL,
  head = NULL,
  tail = NULL,
  apptail = NULL,
  h = 5.5,
  w = 6.5,
  hc = 4.5,
  wc = 5,
  adjustwidth = "-0.75in",
  append = FALSE,
  popts = NULL,
  app = TRUE
)

Arguments

formula

a formula with only a right-hand side, possibly containing a term of the form pending(x) to inform the function of which subjects have incomplete randomization ("randomization pending"). The pending variable is ignored if a subject has an exclusion marked. A randomized variable is an optional logical vector specifying which subjects are considered to have been randomized. The presence of this variable causes consistency checking against exclusions. One or more cond variables provide binary/logical vectors used to define subsets of subjects for which denominators are used to compute additional fractions of exclusions that are reported in a detailed table. The arguments of the cond function are the name of the original variable (assumed to be provided as a regular variable in formula, a single character string giving the label for the condition, and the vector of essentially binary values that specify the condition.

data

input data frame

subset

subsetting criteria

na.action

function for handling NAs when creating analysis frame

ignoreExcl

a formula with only a right-hand side, specifying the names of exclusion variable names that are to be ignored when counting exclusions (screen failures)

ignoreRand

a formula with only a right-hand side, specifying the names of exclusion variable names that are to be ignored when counting randomized subjects marked as exclusions

plotExRemain

set to FALSE to suppress plotting a 2-panel dot plot showing the number of subjects excluded and the fraction of enrolled subjects remaining

autoother

set to TRUE to add another exclusion Unspecified that is set to TRUE for non-pending subjects that have no other exclusions

sort

set to FALSE to not sort variables by descending exclusion frequency

whenapp

a named character vector (with names equal to names of variables in formula). For each variable that is only assessed (i.e., is not NA) under certain conditions, add an element to this vector naming the condition

erdata

a data frame that is subsetted on the combination of id variables when randomized is present, to print auxiliary information about randomized subjects who have exclusion criteria

panel

panel string

subpanel

If calling exReport more than once (e.g., for different values of sort), specify subpanel to distinguish the multiple calls. In that case, -subpanel will be appended to panel when creating figure labels and cross-references.

head

character string. Specifies initial text in the figure caption, otherwise a default is used.

tail

a character string to add to end of automatic caption

apptail

a character string to add to end of automatic caption for appendix table with listing of subject IDs

h

height of 2-panel graph

w

width of 2-panel graph

hc

height of cumulative exclusion 1-panel graph

wc

width of this 1-panel graph

adjustwidth

used to allow wide detailed exclusion table to go into left margin in order to be centered on the physical page. The default is '-0.75in', which works well when using article document class with default page width. To use the geometry package in LaTeX with margin=.45in specify adjustwidth='+.90in'.

append

set to TRUE if adding to an existing sub-report

popts

a list of options to pass to graphing functions

app

set to FALSE to prevent writing appendix information

Details

With input being a series of essentially binary variables with positive indicating that a subject is excluded for a specific reason, orders the reasons so that the first excludes the highest number of subjects, the second excludes the highest number of remaining subjects, and so on. If a randomization status variable is present, actually randomized (properly or not) subjects are excluded from counts of exclusions. First draws a single vertical axis graph showing cumulative exclusions, then creates a 2-panel dot chart with the first panel showing that information, along with the marginal frequencies of exclusions and the second showing the number of subjects remaining in the study after the sequential exclusions. A pop-up table is created showing those quantities plus fractions. There is an option to not sort by descending exclusion frequencies but instead to use the original variable order. Assumes that any factor variable exclusions that have only one level and that level indicates a positive finding, that variable has a denominator equal to the overall number of subjects.

Author(s)

Frank Harrell

Examples

# See test.Rnw in tests directory

Get greport Options

Description

Get greport options, assigning default values of unspecified optios.

Usage

getgreportOption(opts = NULL)

Arguments

opts

character vector containing list of option names to retrieve. If only one element, the result is a scalar, otherwise a list. If opts is not specified, a list with all current option settings is returned.

Setup lattice plots using greport options

Description

Initializes colors and other graphical attributes based on what is stored in system option greport.

Usage

latticeInit()

Mask Variables in a Data Frame

Description

Given a list of applicable variable names in a formula, runs maskVal on any variables in a data frame x whose name is found in formula.

Usage

maskDframe(x, formula, ...)

Arguments

x

an input data frame or data table

formula

a formula specifying the variables to perturb

...

parameters to pass to maskVal

Mask Values of a Vector

Description

Modifies the value of a vector so as to mask the information by generating random data subject to constraints and keeping the length, type, label, and units attributes of the original variable. For a binary numeric or logical variable a random vector with prevalence (by default) of 0.5 replaces the original. For a factor variable, a random multinomial sample is drawn, with equal expected frequencies of all levels. For a numeric variable, the range is preserved but the distribution is uniform over that range, and generated values are rounded by an amount equal to the minimum spacing between distinct values. Character variables are just randomly reordered. In the special case where the input vector contains only one unique non-NA value, the variable is assumed to be the type of variable where NA represents FALSE or "no", and the variable is replaced by a logical vector with the specified prevalence.

Usage

maskVal(x, prev = 0.5, NAs = TRUE)

Arguments

x

an input vector

prev

a numeric scalar specifying the prevalence for binary variables

NAs

if the variable contains NAs, keep the same expected proportion of NAs but distribute them randomly. Otherwise, the new vector will have no missing values.

Compute mfrow Parameter

Description

Compute a good par("mfrow") given the number of figures to plot.

Usage

mfrowSuggest(n, small = FALSE)

Arguments

n

numeric. Total number of figures to place in layout.

small

logical. Set to ‘TRUE’ if the plot area should be smaller to accomodate many plots.

Value

return numeric vector. oldmfrow <- mfrowSet(8)

Number at Risk Report

Description

Graph number of subjects at risk

Usage

nriskReport(
  formula,
  groups = NULL,
  time0 = "randomization",
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  ylab = "Number Followed",
  panel = "nrisk",
  head = NULL,
  tail = NULL,
  h = 5.5,
  w = 5.5,
  outerlabels = TRUE,
  append = FALSE,
  popts = NULL
)

Arguments

formula

a formula with time and the left hand side, and with variables on the right side being possible stratification variables. If no stratification put 1 as the right hand side. Specify unique subject IDs by including a term id() if subjects have more than one observation.

groups

a character string naming a superpositioning variable. Must also be included in formula.

time0

a character string defining the meaning of time zero in follow-up. Default is "randomization".

data

data frame

subset

a subsetting epression for the entire analysis

na.action

a NA handling function for data frames, default is na.retain

ylab

character string if you want to override "Number Followed"

panel

character string. Name of panel, which goes into file base names and figure labels for cross-referencing. The default is 'nrisk'.

head

character string. Specifies initial text in the figure caption, otherwise a default is used

tail

optional character string. Specifies final text in the figure caption, e.g., what might have been put in a footnote in an ordinary text page. This appears just before any needles.

h

numeric. Height of plot, in inches

w

numeric. Width of plot

outerlabels

logical that if TRUE, pass lattice graphics through the latticeExtra package's useOuterStripsfunction if there are two conditioning (paneling) variables, to put panel labels in outer margins.

append

logical. Set to FALSE to start a new panel

popts

list specifying extra arguments to pass to Ecdf. A common use is for example popts=list(layout=c(columns,rows)) to be used in rendering lattice plots. key and panel are also frequently used.

Details

nriskReport generates multi-panel charts, separately for categorical analysis variables. Each panel depicts the number at risk as a function of follow-up time. The Hmisc Ecdf function is used. Stratification is by treatment or other variables. It is assumed that this function is only run on randomized subjects. If an id variable is present but groups and stratification variables are not, other plots are also produced: a histogram of the number of visits per subject, a histogram of times at which subjects have visits, the average number of contacts as a function of elapsed time, and a histogram showing the distribution of the longest gap between visits over subjects.

Examples

# See test.Rnw in tests directory

Put Figure

Description

Included a generated figure within LaTex document. tcaption and tlongcaption only apply if setgreportOption(tablelink="hyperref").

Usage

putFig(
  panel,
  name,
  caption = NULL,
  longcaption = NULL,
  tcaption = caption,
  tlongcaption = NULL,
  poptable = NULL,
  popfull = FALSE,
  sidecap = FALSE,
  outtable = FALSE,
  append = TRUE
)

Arguments

panel

character. Panel name.

name

character. Name for figure.

caption

character. Short caption for figure.

longcaption

character. Long caption for figure.

tcaption

character. Short caption for supporting table.

tlongcaption

character. Long caption for supporting table.

poptable

an optional character string containing LaTeX code that will be used as a pop-up tool tip for the figure (typically a tabular). Set to NULL to suppress supplemental tables that back up figures.

popfull

set to TRUE to make the pop-up be full-page

sidecap

set to TRUE (only applies if greportOption(figenv="SCfigure")) to assume the figure is narrow and to use side captions

outtable

set to TRUE to only have the caption and hyperlink to graphics in a LaTeX table environment and to leave the tabulars to free-standing LaTeX markup. This is useful when the table is long, to prevent hyperlinking from making the table run outside the visable area. Instead of the hyperlink area being the whole table, it will be the caption. A clearpage is issued after the tabular.

append

logical. If ‘TRUE’ output will be appended instead of overwritten.

Compute Sample Fractions

Description

Uses denominators stored with setgreportOption along with counts specified to SampleFrac to compute fractions of subjects in current analysis

Usage

sampleFrac(n, nobsY = NULL, table = TRUE)

Arguments

n

integer vector, named with "enrolled","randomized" and optionally also including treatment levels.

nobsY

a result of the the nobsY Hmisc function

table

set to TRUE to return as an attribute "table" a character string containing a LaTeX tabular showing the pertinent frequencies created from n and the denom option, and if nobsY is present, adding another table with response variable-specific counts.

Set greport Options

Description

Set greport Options

Usage

setgreportOption(...)

Arguments

...

a series of options for which non-default values are desired:

  • tx.pch:symbols corresponding to treatments

  • tx.col:colors corresponding to treatments

  • tx.linecol:colors for lines in line plots

  • nontx.col:colors for categories other than treatments

  • tx.lty:line types corresponding to treatments

  • tx.lwd:line widths corresponding to treatments

  • tx.var:character string name of treatment variable

  • er.col:2-vector with names "enrolled","randomized" containing colors to use for enrolled and randomized in needle displays

  • alpha.f:single numeric specifying alpha adjustment to be applied to all colors. Default is 0.7

  • denom:named vector with overall sample sizes

  • tablelink:a character string, either "tooltip" or "hyperref" (the default); use the latter to make supporting data tables be hyperlinked to tables in the appendix rather than using a pop-up tooltip

  • figenv:LaTeX figure environment to use, default is "figure". Use figenv="SCfigure" if using the LaTeX sidecap package. SCfigure is only used for narrow images, by calling putFig with sidecap=TRUE.

  • codefigpos:LaTeX figure environment position; default is "htb!"

  • gtype:graphics type, "pdf" or "interactive"

  • pdfdir:name of subdirectory in which to write pdf graphics

  • texdir:name of subdirectory in which to write LaTeX code

  • texwhere:default is "texdir" to use location specified by texdir. Set to "" to write generated non-appendix LaTeX code to the console as expected by knitr

  • defs:fully qualified file name to which to write LaTeX macro definitions such as poptables

Plot Initialization

Description

Toggle plotting. Sets options by examining setgreportOption(gtype=).

Usage

startPlot(file, h = 7, w = 7, lattice = TRUE, ...)

endPlot()

Arguments

file

character. Character string specifying file prefix.

h

numeric. Height of plot in inches, default=7.

w

numeric. Width of plot in inches, default=7.

lattice

logical. Set to FALSE to prevent latticeInit from being called.

...

Arguments to be passed to spar.

Survival Report

Description

Generate a Survival Report with Kaplan-Meier Estimates

Usage

survReport(
  formula,
  data = NULL,
  subset = NULL,
  na.action = na.retain,
  ylab = NULL,
  what = c("S", "1-S"),
  conf = c("diffbands", "bands", "bars", "none"),
  cause = NULL,
  panel = "surv",
  subpanel = NULL,
  head = NULL,
  tail = NULL,
  h = 3,
  w = 4.5,
  multi = FALSE,
  markevent = TRUE,
  mfrow = NULL,
  y.n.risk = 0,
  mylim = NULL,
  bot = 2,
  aehaz = TRUE,
  times = NULL,
  append = FALSE,
  opts = NULL,
  ...
)

Arguments

formula

a formula with survival (Surv) objects on the left hand side and an optional stratification factor on the right (or 1 if none). The survival object component variables should be labeled; these labels are used for graph annotation. If any of the Surv objects are competing risk objects (see Surv), event labels come from the factor levels in the variable that was the second argument to Surv, and the first factor level must correspond to right-censored observations.

data

data.frame

subset

optional subsetting criteria

na.action

function for handling NAs while creating a data frame

ylab

character. Passed to survplot.npsurv as the ylab argument. Constructed by default.

what

"S" (the default) to plot survival functions or "1-S" to plot cumulative incidence functions. If any of the survival time objects on the left hand side are competing risk objects, the default is "1-S" and you may not change it.

conf

character. See survplot.npsurv.

cause

character vector or list. If a vector, every Surv term on the left hand side of formula will have cumulative incidence plotted for all causes that appear in cause. If a list, the list elements must correspond to the Surv terms in order, and specify which causes to display from the corresponding Surv object. When cause is a list and one of its elements contains more than one character string, or when cause is a vector and for one Surv object it matches multiple causes, survReport produces more plots than there are Surv objects.

panel

character string. Name of panel, which goes into file base names and figure labels for cross-referencing.

subpanel

character string. If calling dReport more than once for the same type of chart (categorical or continuous), specify subpanel to distinguish the multiple calls. In that case, -subpanel will be appended to panel when creating figure labels and cross-references.

head

character string. Specifies initial text in the figure caption, otherwise a default is used.

tail

optional character string. Specifies final text in the figure caption, e.g., what might have been put in a footnote in an ordinary text page. This appears just before any needles.

h

numeric. Height of plots.

w

numeric. Width of plots in inches.

multi

logical. If TRUE, multiple figures are produced, otherwise a single figure with a matrix of survival plots is made.

markevent

logical. Applies only if multi=TRUE. Specify FALSE to not put the event label in the extreme upper left of the plot.

mfrow

numeric 2-vector, used if multi=FALSE. If not specified, default plot matrix layout will be figured.

y.n.risk

used if what="1-S", to specify y coordinate for putting numbers at risk, typically below the x-axis label

mylim

numeric 2-vector. Used to force expansion of computed y-axis limits. See survplot.

bot

number of spaces to reserve at bottom of plot for numbers at risk, if what="1-S"

aehaz

logical. Set to FALSE to not print number of events and hazard rate on plots.

times

numeric vector. If specified, prints cumulative incidence probabilities at those times on the plots.

append

logical. If TRUE output will be appended instead of overwritten.

opts

list. A list specifying arguments to survReport and startPlot that override any other arguments. This is useful when making a long series of survReport calls with the same options, as the options can be defined up front in a list.

...

ignored

Examples

## See tests directory test.Rnw for a live example
## Not run: 
  set.seed(1)
  n <- 400
  dat <- data.frame(t1=runif(n, 2, 5), t2=runif(n, 2, 5),
                    e1=rbinom(n, 1, .5), e2=rbinom(n, 1, .5),
                    treat=sample(c('a','b'), n, TRUE))
  dat <- upData(dat,
                labels=c(t1='Time to operation',
                         t2='Time to rehospitalization',
                         e1='Operation', e2='Hospitalization',
                         treat='Treatment')
                units=c(t1='year', t2='year'))
  survReport(Surv(t1, e1) + Surv(t2, e2) ~ treat, data=dat)

  dat <- upData(dat, labels=c(t1='Follow-up Time', t2='Time'),
                cause=factor(sample(c('death','MI','censor'), n, TRUE),
                             c('censor', 'MI', 'death')))
  survReport(Surv(t1, cause) ~ treat, cause='death', data=dat)
  survReport(Surv(t1, cause) + Surv(t2, cause) ~ treat,
             cause=list(c('death', 'MI'), 'death'), data=dat)
  # Two plots for t1, one plot for t2

## End(Not run)