audit_trail: Facilitate the Creation and Modification of Audit Trails
In oro.nifti: Rigorous - NIfTI+ANALYZE+AFNI Input / Output

Description Usage Arguments Details Note Author(s) Examples

Facilitate the creation and modification of audit trails for NIfTI class objects.

oro.nifti.info(type)
enableAuditTrail()
newAuditTrail()
niftiExtensionToAuditTrail(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailToExtension(nim, workingDirectory = NULL,
                           filename = NULL, call = NULL)
niftiAuditTrailSystemNode(type="system-info",
                          workingDirectory = NULL,
                          filename = NULL, call = NULL)
niftiAuditTrailSystemNodeEvent(trail, type = NULL, call = NULL,
                               workingDirectory = NULL,
                               filename = NULL, comment=NULL)
niftiAuditTrailCreated(history = NULL, call = NULL,
                       workingDirectory = NULL, filename = NULL)
niftiAuditTrailEvent(trail, type = NULL, call = NULL,
                     comment = NULL)
getLastCallWithName(functionName)

`nim`	is an object of class `niftiAuditTrail` or can be converted to such.
`workingDirectory`	The working directory associated with the ‘filename’.
`filename`	The filename associated with the nifti object.
`call`	A `call`, function name in the call-stack or a string.
`type`	An identifier to add some meaning to the event.
`trail`	The `XMLAbstractNode` representing the audit trail or the `niftiAuditTrail` object with a trail that will be amended.
`comment`	Some textual comment
`history`	An `XMLAbstractNode` to store historical events for inclusion in the ‘trail’.
`functionName`	The name of a function on the call stack.

The function oro.nifti.info is used to find the ecode or the XML namespace relevant to the audit trail.

The function enableAuditTrail is turned “off” by default to minimize package dependencies. Should one wish to turn “on” the audit trail functionality, then one should set the option NIfTI.audit.trail to TRUE and call the function enableAuditTrail. Setting the option NIfTI.audit.trail to FALSE will disable the audit trail.

The function newAuditTrail returns an XMLAbstractNode representing the root node of an audit trail. This is mostly intended as an internal function.

The function niftiExtensionToAuditTrail takes an object representing a NIfTI object, casts it as a niftiAuditTrail and checks if there is an extension (a niftiExtensionSection) with ecode equal to oro.nifti.info("ecode"); i.e. has a extension with data representing a serialized audit trail. The function will then strip the object of this extension parsing the serialized edata into an audit trail and adding a ‘read’ event to the trail.

The function niftiAuditTrailToExtension takes a niftiAuditTrail and returns a niftiExtensionSection with edata containing the serialized form of the audit trail after adding a ‘saved’ event to the trail.

The function niftiAuditTrailSystemNodeEvent adds an element with name equal to type to the trail. It uses the niftiAuditTrailSystemNode function to create the node.

The function niftiAuditTrailSystemNode is an internal function creating an XMLAbstractNode element with name type and attributes giving information about the R system and library. The filename and call will also be added as attributes if available.

The function niftiAuditTrailEvent adds an element with name event to the trail. The arguments type, filename, call are added as attributes and the comment is the text value of the element.

The function niftiAuditTrailCreated will create a new audit trail containing a system node element created with the child history with the contents history. If the last element of the history given is an event with type="processing", then this node will be removed from the history and its call attribute will be used as the value of the call attribute on the created node.

The function getLastCallWithName will search the call stack for a call of the function functionName, returning last call to that function if possible. It will default to the call of the function which called the function which called getLastCallWithName if there was no such call (and if there was no such call it will return the call of itself).

These functions are mostly intended to be used internally in order to document the changes that occur to NIfTI objects due to functions that are audit-trail aware. However, as the precise manner in which these functions are used is not documented anywhere else, we shall proceed to describe which functions are audit-trail aware and how they interact with the audit trail.

as.nifti and its S4 alias as(nim, "nifti") will always produce niftiAuditTrail objects if the functionality is turned on. The function niftiAuditTrailCreated will be used and if an exemplar object is provided (e.g., as.nifti(array, niftiExemplar)) then the trail of the exemplar will be used as the history.

readNIfTI and writeNIfTI also always produce niftiAuditTrail objects if the functionality is turned on. The functions niftiExtensionToAuditTrail and niftiAuditTrailToExtension are used internally by these functions to facilitate this behaviour.

Andrew Thornton zeripath@users.sourceforge.net and Brandon Whitcher bwhitcher@gmail.com

## A good example of the use of these functions is shown by this
## wrapper function which takes a function fun(nim, ...) returning
## lists of arrays which are nifti-ized using as(...)
options("niftiAuditTrail"=TRUE)
enableAuditTrail()

wrapper <- function(functionToWrap, nameOfCallingFunction, nim, ...) {
  if (!is(nim, "nifti")) 
    nim <- as(nim, "nifti")
  
  if (is(nim, "niftiAuditTrail")) {
    ## This will force as(...) to set the call which created the
    ## results to the calling function's call rather than
    ## as(result, nifti) as it would otherwise do
    nim@trail <- niftiAuditTrailEvent(nim@trail, "processing",
                                      nameOfCallingFunction)
  }
  
  result <- functionToWrap(nim, ...)
  as(result, "nifti") <- nim
  return(result)
}

## An example of how wrapper is used follows:
functionToWrap <- function(ignored, x, y) {
  return (array(1, dim=c(x,y)))
}

## The niftiized form
niftiizedForm <- function(nim,...) {
  return(wrapper(functionToWrap, "niftiizedForm", nim, ...))
}

## Not run: 
## compare the trails
if (isTRUE(getOption("niftiAuditTrail"))) {
  print((as.nifti(functionToWrap(nifti(), 4, 4), nifti()))@trail)
  print(niftiizedForm(nifti(), 4, 4)@trail)
}

## End(Not run)