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 | 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 |
workingDirectory |
The working directory associated with the ‘filename’. |
filename |
The filename associated with the nifti object. |
call |
A |
type |
An identifier to add some meaning to the event. |
trail |
The |
comment |
Some textual comment |
history |
An |
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
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 41 | ## 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)
|
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.