Description Usage Arguments Details Note Author(s) Examples
Facilitate the creation and modification of audit trails for NIfTI class objects.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 | 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)
|
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 |
workingDirectory |
The working directory associated with the ‘filename’. |
filename |
The filename associated with the nifti object. |
call |
A |
trail |
The |
comment |
Some textual comment |
history |
An |
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ## 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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.