.BG
.FN AUDIT
.TL
Audit the Data Analysis Process
.CS
S AUDIT [auditfile]
.AG auditfile
the name (unquoted) of an audit file,
by default,
.Co .Data/.Audit .
This file must contain lines of the form
.IP
#~get ...
.IP
#~put ...
.PP
in order for the auditing procedure to work.
This means that old-S diary files may not be auditable.
.PP
The `AUDIT' utility allows the user to review what has
happened during a set of S sessions.
When the `AUDIT' utility is invoked, it reads the file `auditfile'
(`.Data/.Audit' by default),
finding all top-level expressions, and which objects were
read and written by each expression.
It then allows the user (through an arcane syntax, see below)
to inquire about which expressions read or
wrote a specific object, to backtrack from a specific expression, or
to create a source file that will recreate an expression.
.PP
The `AUDIT' utility can also be executed independently
and in parallel with a copy of
S that is writing the `auditfile'.  `AUDIT' continuously
attempts to read new information that may be written to the file
by another process and updates its tables accordingly.
It also numbers and displays each expression as it is executed by S.
Thus, `AUDIT' is very useful on a multi-window workstation where
one window can be used for running S and another for asking audit
questions about the S session.
The display of expressions can also be used with cut/paste operations
to provide a means of re-executing or modifying previous expressions.
.SA
`history'.
.EX
$ S AUDIT diary   # audit the file "diary"
G x	# shows which statements "got" or read object x
S A	# show (in reverse order) all statements
E 100	# create script to recreate statement 100

.SH "COMMANDS TO AUDIT PROGRAM"
.nf

E n1 n2 n3 n4 ... x
	generates an Executable script on stdout that will
	incorporate all computations including statements n1 n2 ...

[L|G|P|B] name
	will Lookup, show Gets, Puts, or will Backtrack
	L will show the name from its symbol
		table.  The name can be the trailing portion of
		a name, e.g. abc will match xyz.abc
	G will show the statements in which it is used
	P will show the statements in which it is assigned
	B will backtrack, showing the statement
		that most recently set a value for the name
		and all statements that were predecessors of
		that statement

[L|G|P|B] number
	will Lookup, show Gets, Puts, or will Backtrack
	L will lookup a particular statement
	G will show the objects used (gotten) within the statement
	P will show the objects assigned (put) within the statement
	B will backtrack from the statement showing all predecessor
		statements

N [N|G|P|A|GP]
	will show names that were
	- N not assigned or used
	- G used but not assigned
	- P assigned but not used
	- GP assigned and used
	- A All names

S [N|G|P|A|GP]
	will show statements that contained various Gets or Puts
	of objects, along with the object names that were
	read or written

	- N no assignments or use of objects
	- G use of objects but no assignments
	- P assignments but no use of objects
	- GP assignments and use of objects
	- A All statements

	If you want all statements that created a object,
	you need to use both S P and S GP.
q
	quit
.ft P
.PP
If you interrupt in the middle of a printout, you will be brought back
to the "Command: " prompt.
.PP
Processing of the user statements once the audit program has
read the audit file is very fast.  Interactive users notice no delay.
.SH REFERENCE
Richard A. Becker and John M. Chambers,
"Auditing of Data Analyses"
.ul
SIAM J. Sci. Stat. Comput.
vol. 9 (no. 1), July, 1988.
.KW data
.KW utilities
.KW file
.KW documentation
.WR
