Class: wsim.logger¶
A matlab class for logging data and/or various events during the
execution of a matlab script/function. This class is mainly a container
class for logged data, with some additional functionality to operate on
the stored data in generating plots, applying functions etc.
The main aim of this class is to consolidate and store all the outputs
and messages from a MATLAB script/function into a single object. These
objects can be saved, and retrieved later, with all the information in
one place Several utility functions (mainly for plotting) make it easy to
operate on the stored data.
There are several ways in which you can use this class. You can either
(1) create a logger object, and start logging into the class
(2) user's class can be inherited from logger
(3) you can use matlab's event framework to log events by adding
appropriate listeners.
wsim.logger Methods:
logger - constructs a logger object
addVariable - adds a variable to be logged (initialises data structures)
getInfo - get information in a structure for one or more logged variables
logErr - log an error message
logMesg - log a general message
logWarn - log a warning message
logObj - append and object to a logged object series
logVal - append a value to a logged variable to the
plot2Vars - plot two scalar logged variables against each other
plotFofVar - plot funcitno of variable
plotVar - plot a scalar variable
setDefaultDesc - set the default description
setDesc - set the description for a logged variable
setMesgFunc - set the function called when logging a message
setPlotFunc - set the function to be used for plotting
setSeries - set an entire data series directly
setSilent - turn off all messages except errors and warnings
truncateVariable - strip preallocated space from variable
truncateAllVariables - strip preallocated space from all variables
Parent Class Properties and Methods¶
handle¶
Inheirited Properties¶
None
Inheirited Methods¶
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- addlistener : ADDLISTENER Add listener for event.
- delete : DELETE Delete a handle object.
- eq : == (EQ) Test handle equality.
- findobj : FINDOBJ Find objects matching specified conditions.
- findprop : FINDPROP Find property of MATLAB handle object.
- ge : >= (GE) Greater than or equal relation for handles.
- gt : > (GT) Greater than relation for handles.
- isvalid : ISVALID Test handle validity.
- le : <= (LE) Less than or equal relation for handles.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- listener : LISTENER Add listener for event without binding the listener to the source object.
- lt : < (LT) Less than relation for handles.
- ne : ~= (NE) Not equal relation for handles.
- notify : NOTIFY Notify listeners of event.
- notify : NOTIFY Notify listeners of event.
Properties¶
- data
- defaultXLabel
- defaultfield
- errors
- expandPreallocFactor
- fieldNames
- info
- mesgfunc
- messages
- numVariables
- plotfunc
- silent
- warnings
data¶
A structure in which the logged data will be stored.
defaultXLabel¶
axis when plotting single variables.
defaultfield¶
errors¶
expandPreallocFactor¶
fieldNames¶
info¶
mesgfunc¶
messages¶
numVariables¶
plotfunc¶
silent¶
warnings¶
Methods¶
- logger
- addVariable
- disp
- getInfo
- getPrevLoggedVal
- lastLoggedVals
- logErr
- logMesg
- logObj
- logVal
- logWarn
- plot2Vars
- plotFofVar
- plotVar
- setDefaultDesc
- setDesc
- setMesgFunc
- setPlotFunc
- setSeries
- setSilent
- truncateAllVariables
- truncateVariable
logger¶
Summary¶
constructs a logger object.
Syntax¶
obj = wsim.logger ()
obj = wsim.logger ('Parameter', Value)
Description¶
Initializes basic plotting functions, verbosity and messaging
options. Initializes the structures used for storing
messages/warnings/errors etc.
Inputs¶
All arguments are supplied as parameter-value pairs:
ExpandPreallocFactor¶
variables can have data
preallocated to improve speed. This option can be used to
control how the preallocated arrays expand when the end of
the preallocated array is reached. When this occurs the
arrays are expanded by this factor multiplied by the
current array length. Default is 0.25 if not supplied.
PlotFcn¶
handle to function to be used for plotting
variables. Default is @plot if not supplied.
MesgFcn¶
handle to function to be called when reporting
messages. By default this is @warning, but it could, for
example, be made @error to result in more stringent
checking.
Silent¶
Sets the silent property true or false. If true,
then the internal error messages of the logger class are
not printed out. Whatever the user specifies by setting
the show variable in the logWarn, logMesg functions are
still printed out to the command window. Defualt is true.
DefaultDescription¶
character vector containing the
default description for variables, which is used as the x
axis label in plots. Default is '' (an empty character
vector).
Outputs¶
obj¶
wsim.logger object
addVariable¶
Summary¶
add a variable to be logged
Syntax¶
addVariable (lo, name, varsize)
addVariable (..., 'Parameter', value)
Description¶
addVariable adds a variable to the logger. Variables can
scalars, vectors or matrices of any size. In the case of
matrices and vectors logging is performed by expanding the
variables along the first singleton dimension (which will be
created if there are no singleton dimensions). Storage for
the logged data can be preallocated to improve speed.
Inputs¶
lo¶
wsim.logger object
name¶
name of the variable to be logged
varsize¶
size of the variable to be logged in the same
format as would be reported by the 'size' function, i.e. a
vector of integers. The log of the variable will be made by
expanding the first singleton dimension (dimension of size
1) of the variable, i.e. new values of the variable at each
logging step will be appended to this dimension. If there
are no singleton dimensions, an extra dimension will be
created. The logging dimesion can also be specified using
the 'ForceLogDimension' option described below.
Additional arguments may be supplied as parameter-value pairs:
Description¶
optional string containing a description of
the variable
ForceLogDimension¶
optional scalar integer giving the
dimension along which the logged variable is to be
appended at each logging step.
PreallocateStorage¶
optional scalar integer giving the
number of samples for which to preallocate storage in
advance. When this limit is reached, the storage space is
expanded, unless the 'Windowed' option is used (see
below).
IndependentVariable¶
string containing the name of
another variable, already added to the logger, which is
the independant variable for the new variable. Primarily
used for plotting, but, also for preallocation. If the
PreallocateStorage option is not specified, the new
variable is by default preallocated the same storage as
the independant variable.
AxisLabel¶
optional charachter vector which will be used
as the axis label for this variable when plotting it. Will
appear on the axis against which this variable is plotted,
which could be either X or Y.
Windowed¶
optional true/false flag indicating whether the
data should be 'windowed' i.e. once the number of values
logged equals the value in PreallocateStorage (see above),
instead of increasing storage space, the earlier values
will be overwritten with new data, where the earliest
logged value is lost with each new value, and all current
values are shifted earlier in the log. Default is false,
meaning the storage space will increase once the
preallocated space is reached.
disp¶
Summary¶
Overriden disp function for the logger class.
Description¶
Displays the logger object with all its variables and their
sizes.
getInfo¶
Summary¶
get info on the logging settings for a variable
Syntax¶
info = getInfo (lg, reqvarnames)
Description¶
Returns a structure containing information on one or more
logged variables in the wsim.logger object. This is a subset
of the structure in the wsim.logger.info property. Variables
can be found by usng their full exact name or any unambiguous
cases insensitive matching shorter string.
Inputs¶
lg¶
wsim.logger object
reqvarnames¶
character vector with a single variable
name, or a cell array of character vectors with multiple
variable names. If no exact match is found a case
insensitive search is performed and any unambiguous
shortening of a variable name is allowed. e.g. to get the
info for a logged variable named 'ExampleLoggedVariable'
one can use the string 'ExampleLog'.
Outputs¶
info¶
structure array (one for each requested variable name
in reqvarnames, with the following fields:
Description : string containing a description of the
variable
Size : vector of integers specifying the size of the
variable being logged for all dimensions.
PreallocatedLogLength : length of reserved log space for
the variable
IndexAssignment : indexing structure used to aid indexing
into the logged variable matrix (see help for subsasgn
for more information)
IndexDimension : The matrix dimension along which the
logging takes place
DataDimensions : A vector containing the dimesions which
contain the variable data for each logged value of a
variable. This excludes the log index dimension, and any
singleton dimensions created in order to force logging
along a certain dimension.
LastLogIndex : The index of the last logged item in the
matrix
IndependentVariable : string containing the name of the
independant variable associated with this variable. Can
be empty if none is assigned, typically this is 'Time'.
LoggedSize : This is the size of the logged variable
internally to the logger object, after adding any
dimensions in order to log along the first singleton, or
user specified dimension, but before preallocation.
See Also¶
getPrevLoggedVal¶
Summary¶
get the (end - n) logged value of a variable
Syntax¶
val = getPrevLoggedVal(obj, varname, n)
Description¶
If a variable exists, the (last-n)th value logged to that
variable is returned.
Inputs¶
obj¶
wsim.logger object
varname¶
name of the variable to be for which to obtain the
last logged value
Outputs¶
vals¶
The last-n logged value for the supplied variable,
in the same shape as in the corresponding stored data
field.
See Also¶
lastLoggedVals¶
Summary¶
get last ‘n’ logged values of a variable
Syntax¶
val = lastLoggedVal(obj, varname, n)
Description¶
If a variable exists, the last 'n' values logged to that
variable are returned. If the number of logged variables is
less than this, all available data will be returned.
Inputs¶
obj¶
wsim.logger object
varname¶
name of the variable to be for which to obtain the
last logged value
Outputs¶
vals¶
The last 'n' logged values for the supplied variable,
in the same shape as in the corresponding stored data
field.
See Also¶
logErr¶
Summary¶
log an error text message
Syntax¶
logErr(obj, mesg, show)
Description¶
Logs text messages given as an error, which are stored in
the errors property of the logger class.
Inputs¶
obj¶
wsim.logger object
mesg¶
character vector to be stored in the errors log.
show¶
true/false flag indicating whether to also print the
message to the command line.
See Also¶
logMesg¶
Summary¶
log a general text message
Syntax¶
logMesg(obj, mesg, show)
Description¶
Logs text messages given for information, which are stored in
the messages property of the logger class.
Inputs¶
obj¶
wsim.logger object
mesg¶
character vector to be stored in the message log.
show¶
true/false flag indicating whether to also print the
message to the command line.
See Also¶
logObj¶
Summary¶
logs non-numeric objects, and stores them in a field as a cell array.
Description¶
Log a non-numeric object. Non-numeric object data cannot be
plotted.
Inputs¶
obj¶
wsim.logger object
field¶
The field name you are logging.
val¶
The value any matlab object.
logVal¶
Summary¶
log a new value of a variable
Syntax¶
status = logVal(obj, varname, val, ignoremissing)
Description¶
If a field exists, the element is added to the next index of
the field.
Inputs¶
obj¶
wsim.logger object
varname¶
name of the variable to be appended
val¶
value to be appended to the history of values
ignoremissing¶
optional true/false flag indicating whether
an error should be thrown if varname does not exist in the
logger. If false, an error is thrown if varname does not
exist. If true an error will not be thrown, and the success
is indicated in the status output. Default is false if not
supplied.
Outputs¶
status¶
0 if the variable varname exists, -1 if not.
See Also¶
logWarn¶
Summary¶
log a warning text message
Syntax¶
logWarn(obj, mesg, show)
Description¶
Logs text messages given as a warning, which are stored in
the warnings property of the logger class.
Inputs¶
obj¶
wsim.logger object
mesg¶
character vector to be stored in the warnings log.
show¶
true/false flag indicating whether to also print the
message to the command line.
See Also¶
plot2Vars¶
Summary¶
plot two logged variables against each other
Syntax¶
plot2Vars (obj, f1, f2)
plot2Vars (obj, f1, f2, plotarg1, plotarg2, ..., plotargn)
[h, hax, hfig] = plot2Vars (...)
Description¶
plot two logged variables against each other, e.g. if a user
logs two variables 'height' and 'weight', giving
logger.plotvars('height','weight') will plot height vs.
weight. The parameters to the plot can be provided after the
variables, and all those arguments go to the plot function.
For example,
logger.plotvars('height','weight','LineWidth',2,'Color','r');
will pass the last four arguments to plot.
Inputs¶
obj¶
wsim.logger object
f1¶
name of first variable to plot
PlotFcnArgs¶
cell array of additional arguments that are
to be sent to the plotting function.
Skip¶
integer defining a number of values to skip between
plotted values (to reduce plot size for large series)
Scale¶
two element vector containing the values by which
to scale the data values for each variable when plotting.
Default is [1,1] if not supplied.
FigureArgs¶
cell array of additional arguments that are
to be sent to the figure function when creating the
figure.
Outputs¶
hax¶
handle to the axes object in which the plot was drawn.
hfig¶
handle to the figure object in which the plot was
drawn
See Also¶
plotFofVar¶
Summary¶
apply function to logged variable and plot the result
Syntax¶
h = plotFofVar(obj, varname, func)
h = plotFofVar(obj, varname, func, plotarg1, plotarg2, ..., plotargn)
Description¶
plotFofVar applies a function to a logged variable and plots
the result. For example, if a user logs a variable 'height',
the log(heights) can be plotted as
logger.plotFofVar('height',@log). The parameters to the plot
can be provided after the fields, and all those arguments go
to the plot function. For example,
logger.plotFofVar('height','@log','LineWidth',2,'Color','r');
will pass the last four arguments to plot.
Inputs¶
obj¶
wsim.logger object
varname¶
name of logged variable to be plotted
func¶
function handle containing function to be applied to
the variable before plotting.
Outputs¶
hplot¶
A handle (or array of handles) for the plot series
generated. Useful for formatting by the user.
hax¶
handle to the axes object in which the plot was drawn.
hfig¶
handle to the figure object in which the plot was
drawn
See Also¶
plotVar¶
Summary¶
given a string specifying a numeric scalar field, it is plotted.
Syntax¶
plotVar(obj, field)
plotVar(obj, field, plotarg1, plotarg2, ..., plotargn)
[hplot, hax, hfig] = plotVar(...)
Description¶
plotVar Plots one of the logged variables. If a user logs a
fields 'height', using logger.plotVar('height') will plot
height. Additional arguments for the plotting funtion (e.g.
plot) can be provided using the 'PlotFcnArgs' option.
Inputs¶
obj¶
logger object
field¶
a string specifying the name of logged field 1.
Additional arguments may be supplied as parameter-value pairs:
PlotFcnArgs¶
cell array of additional arguments that are
to be sent to the plotting function.
Skip¶
integer defining a number of values to skip between
plotted values (to reduce plot size for large series)
Scale¶
scalar value by which to scale the data values
when plotting
FigureArgs¶
cell array of additional arguments that are
to be sent to the figure function when creating the
figure.
Outputs¶
hplot¶
A handle (or array of handles) for the plot series
generated. Useful for formatting by the user.
hax¶
handle to the axes object in which the plot was drawn.
hfig¶
handle to the figure object in which the plot was
drawn
setDefaultDesc¶
Summary¶
set the default description which is used for labeling the x-axis.
Description¶
The default description is used when plotting, for the X axis
label when there is no independant variable associated with a
variable.
setDesc¶
Summary¶
set the description for a variable to be used for x-y labels in plots
Syntax¶
setDesc(obj, varname, desc)
Description¶
setDesc set the description for one or more variables. The
description is used when plotting as the label for the
appropriate axis.
Inputs¶
obj¶
wsim.logger object
varname¶
either a character vector containing the name of
logged variable for which the description is to be set, or
a cell array of character vectors containing the names of
several variables for which the descriptions are to be set.
If a cell array, it must be the same size as desc (see
below).
desc¶
character vector containing the new description for
the variable in varname, or a cell array of character
vectors containing a description for each variable in
varname (when it is a cell array).
setMesgFunc¶
Summary¶
set the default waring/error function for the logger object
Syntax¶
setMesgFunc(obj, mf)
Description¶
setMesgFunc sets the function which is run when an internal
warning is issued (this is NOT related to the logMesg,
logWarn or logErr methods). By default @warning is used for
most internal warnings/errors, but this can be replaced, e.g.
with @error for more strict treatment of problems.
Inputs¶
obj¶
wsim.logger object
mf¶
function handle to new function to be run when an
internal error occurs. Should take a single character
vector input.
setPlotFunc¶
Summary¶
Set the plotting function to be used.
Syntax¶
setPlotFunc(obj, pf_handle)
Description¶
Set the plotting function to be used when calling plotVar,
plotFofVar, plot2Vars etc.
Inputs¶
obj¶
wsim.logger object
pf_handle¶
function handle containing plotting function to
be used.
See Also¶
wsimlogger.plot2Vars
setSeries¶
Summary¶
set values for an entire data series directly
Syntax¶
setSeries (obj, varname, newdata)
Description¶
setSeries set the values for an entire data series for a
logged variable directly. All existing logged data will be
wiped, and the new data will be put into the variable. If the
variable is associated with an independant variable, the
length of the new data series must match the length of the
associated independant variable.
Inputs¶
obj¶
wsim.logger object
varname¶
character vector with a single variable
name for which the entire data series is to be set. If no
exact match is found for the name in varname, a case
insensitive search is performed and any unambiguous
shortening of a variable name is allowed. e.g. to get the
info for a logged variable named 'ExampleLoggedVariable'
one can use the string 'ExampleLog'.
newdata¶
a new data series for the logged variable. This
will replace any existing data.
See Also¶
setSilent¶
Summary¶
turn off messages (but not warning or error messages)
Syntax¶
setSilent(obj, bool)
Description¶
Sets the silent property true or false. If true, then the
internal error messages of the logger class are not printed
out. Whatever the user specifies by setting the show variable
in the logWarn, logMesg functions are still printed out to
the command window.
Inputs¶
obj¶
wsim.logger object
bool¶
true/false flag. If true, messages will be silenced,
but warning and error messages will still be displayed.
See Also¶