audit_trail: Facilitate the Creation and Modification of Audit Trails

In oro.nifti: Rigorous - 'NIfTI' + 'ANALYZE' + 'AFNI' : Input / Output

Facilitate the Creation and Modification of Audit Trails

Description

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

Usage

oro.nifti.info(type)

enableAuditTrail()

getLastCallWithName(functionName)

newAuditTrail()

niftiExtensionToAuditTrail(
  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)

Arguments

type	An identifier to add some meaning to the event.
functionName	The name of a function on the call stack.
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.
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’.

Details

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).

Note

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.

Author(s)

Andrew Thornton [e-mail] and Brandon Whitcher [e-mail]

Examples

## 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
    slot(nim, "trail") <- niftiAuditTrailEvent(slot(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 nifti-ized form
niftiizedForm <- function(nim,...) {
  return(wrapper(functionToWrap, "niftiizedForm", nim, ...))
}
 
## Not run: 
  if (isTRUE(getOption("niftiAuditTrail"))) {
    print(slot(as.nifti(functionToWrap(nifti(), 4, 4), nifti()), "trail"))
    print(slot(niftiizedForm(nifti(), 4, 4), "trail"))
  }

## End(Not run)

oro.nifti documentation built on Aug. 10, 2022, 5:09 p.m.