Software User Documentation

This appendix describes the use, configuration and design of the DBN software implemented for this project.

The software's program code can also be easily extended to handle different - such as networked - data sources, additions to the feature-extraction library and the implementation new methods for storing or displaying results. This flexibility proved very useful when it was used to extend the basic processing software to the Windows operating system (see section A.3).

   
Configuration command syntax

The following sections cover how a user can specify DBN models and parameters, configure feature extraction, data sources and results output.

The software retrieves its user-specified configuration information from two main sources. The first is the ``reference network'', which defines the structural and parametric configuration of the DBN model itself. The second is a text description of the input source format, required feature extraction functions, how evidence is added to the DBN and what information should be stored or displayed as output.

The reference network can be produced in the Netica GUI as a normal static belief network would, with node naming rules for discriminating between network slices. The textual configuration information could have been stored anywhere, but for convenience it was placed inside the Netica network's comment section (referred to as `description' in the Windows GUI). This allows the entire DBN software configuration to be stored in a single `.dne' file, which can be loaded, edited and saved using the existing Netica GUI.

   
DBN reference network

The reference network specifies a complete two-slice version of the required DBN model. The causal links between two slices can then be interpreted and used by the software to build networks of more (or less) slices.

The project's software uses the belief network node's names to discriminate between nodes in separate slices. All nodes may have a normal name (as specified by the Netica BN library), but must end in an underscore character, `_', followed by a positive integer slice number. The only requirement of the node's name before the underscore is that it is unique within its slice. By convention, the string `Obs' was used in node names in this project to denote ``observation nodes'' which receive evidence.

When specifying the reference network, only the slice numbers `0' and `1' should be used to specify nodes in the first and second reference slices respectively. An example of a reference network (actually the gait-1 DBN discussed in Section 8.1) which can be used by this software is shown in Figure A.1. Here the nodes `Support_0', `Action_0' and `ActObs_0' represent nodes in the first reference slice, and nodes `Support_1', `Action_1' and `ActObs_1' are from the second reference slice. The links from the nodes `Support_0' to `Action_0' and `Support_1' to `Action_1' represent static (or intra-slice) causal links within the first and second reference slices respectively. The causal links from node `Action_0' to `Status_1', and `Status_0' to `Status_1' represent forward temporal (or inter-slice) links. The software can also handle backwards temporal links (from nodes in higher to lower-numbered slices).

  

Figure A.1: Example reference network

Each node in the first slice must have an equivalent node in the second with the same number of states, same static (but not necessarily temporal) links and same name before the slice number (or name prefix). Reference networks that do not adhere to these rules may cause the software to produce an error message or unpredictable DBN network structures.

Equivalent nodes in separate reference slices need not have the same conditional probability distribution. In fact, identical conditional probability distributions are impossible for nodes such as `Support_0' and `Support_1' in Figure A.1, as `Support_0' has no parents it must therefore contain a prior distribution, but `Support_1' has two (inter-slice) parents, requiring a probability table conditioning on the states of nodes `Support_0' and `Action_0'.

   
Configuration commands

The following sections cover the software's textual configuration and its syntax. All the following configuration instructions are stored in the network description, which is interpreted by the software when loading the `.dne' file. This configuration information is split into separate sections describing input, feature/evidence extraction, `watching' node beliefs, defining default node states and defining parameters to be used in CPT expressions. The start of each configuration section is signified by a full stop (`.') followed by the section name. For example the `input' configuration is started with the string ``.input'' followed by a new line.

Comments may be inserted after a `#' character. When this character is found in the configuration description^12.1, the rest of that line is ignored.

This report uses some typesetting when describing the syntax used in the following sections. Any section describing syntax is in this typeface. Mandatory parameters are underlined, and optional parameters are indicated in a italic typeface. Characters within the syntax that are neither underlined or italic are required to be included as shown. The dots `...' signify a command or line may be repeated many times.

   
Input

The .input configuration section describes how the data source is organised, and in particular the number, sampling rate and voltage range (or gain) of the Siesta datalogger's recording channels. In this project's software implementation, this information should be copied from the Siesta's configuration, as specified through the SiestaView program. The information in the .input section is used to split the data into its separate channels so it can be passed on to the feature extraction system.

Syntax

.input
input-label sampling-rate gain;
...

input-label

This is an arbitrary name for a channel on the Siesta datalogger, which is used by the feature and evidence extraction filters to refer to data arriving on that channel. The name should start with a alphabetical character, cannot contain any spaces and is not case-sensitive.

sampling-rate

This is a positive integer specifying the sampling rate of the channel, as set up on the Siesta datalogger using the SiestaView program. Common sampling rates are 32 and 64, and 128 samples per second (Hertz or Hz).

gain

The gain value is a real number representing the peak-to-peak voltage that the related Siesta data channel is set to. The Siesta has a maximum signal peak-peak voltage of 0.5 Volts, which would be specified using `0.5'.

Example

.input
LHEEL 32 0.1;
RHEEL 32 0.1;
LTOE 32 0.1;
RTOE 32 0.1;
LACCEL 64 0.5;
RACCEL 64 0.5;

Notes

The input channel configuration section must include an entry for every active channel on the datalogger, and should appear in the same order as the Siesta's physical channel configuration. Even if data from a particular channel is not being used, it should still appear with some `dummy' label name so that the software knows which samples to ignore.

For the above example, if the siesta has sensors on channels 1, 2, 3, 4, 29, and 30 (with all other channels disabled), the input labelled ``LHEEL'' will receive data from the Siesta's channel 1 at 32Hz with a 100 mV peak-peak, ``RHEEL'' from channel 2 at 32Hz, ``LTOE'' channel 3, ``RTOE'' channel 4, ``LACCEL'' from channel 29 at 64Hz with a 500 mV peak-peak and ``RACCEL'' from channel 30 at 64Hz^12.2. Each channel description may span multiple lines, but must always end in the `;' character.

    
Feature and evidence extraction

The feature/evidence extraction network is configured using a number of `branch descriptions', each containing a list of statements which describe one `branch' of the feature extraction network. A branch specifies one path data from a particular input takes through the network of filtering functions. The `data' used in the network consists of an integer sample value (like that output from the Siesta), a real signal magnitude (calculated by each channel input from the sample value and gain) and the sample's time. This data is manipulated and output in different ways by different software filters.

Each branch configuration starts by specifying an input for that branch, followed by a combination of statements describing either filters or new input definitions separated by closing angled brace `>' characters. To discriminate between filter and input definitions, filter descriptions are surrounded by curly braces (`{' and `}'), and new input definitions by square parenthesis (`[' and ']'). The input node at the start of the branch description supplies data to the first filter in the list, which then performs some function on the data and passes the resulting data on to the next filter.

Syntax

.filters
[input] ...> ...
{filter description} ...> [new input definition] ...;
...

A branch definition may take up multiple lines (as long as a new line appears between statements) but always ends with the semicolon (';') character.

input

Each filter description must start with an already defined `label'. A label is a string representing a source of data, being either an input label (defined in the .input section), or a branch label already defined in the .filter description (see below). Note that an input cannot be used before it is defined, either as part of the .input section or as a new input definition in a preceding branch description.

filter description

Individual filter configuration start with a `{', and the filter's name, followed by a number of space-separated arguments specific to that filter. Each individual filter configuration is terminated with a closing brace `}'. Different filters generally require different (or no) configuration information, so the number of parameters between the filter's name and closing brace is variable. Section A.1.3 describes each of the filters implemented and their parameters.

new input definition

New input definitions are merely `place-holders' that may be used as inputs to subsequent branch definitions. Data passes through new input definitions to following filters unchanged, and if more than one branch starts with the same input, a separate (identical) copy of the data is distributed to each branch. Like inputs, new input definitions are distinguished from filters by surrounding square braces `[' and `]'.

Example

.filters
[LHEEL] > {abs} > {average 5} > [LHRAW];
[LTOE] > {abs} > {average 5} > [LTRAW];
[LHRAW] > {pass 0.01 r} > {*any ActObs ldown};
[LTRAW] > {pass 0.01 f} > [LTUP];
[LHRAW] > {pass 0.01 f} > {and LTUP 0.5} > {*any ActObs lup};

Notes

The above example shows the description for a reasonably simple feature extraction network, which could be used to extract `up' and `down' features from two heel and toe foot-sensor signal sources, assuming that the inputs LHEEL and LTOE have already been defined in the .input section. The description shown above could be explained graphically as in Figure A.2.

  

Figure A.2: Graphical representation of example feature extraction network

The line after .filters tells the software to create an `abs' filter that receives data from the LHEEL input and passes the result to an `average' filter, which is created with the parameter 5. The average filter outputs into a new input definition called `LHRAW', which is later used as the input to two other branches.

Node watches

Node watches specify which posterior beliefs should be `watched' while the DBN engine is processing the data and updating the network. A watch entry specifies the node and slice number relative to the current slice of a state to be watched. In this particular implementation, the posterior belief values of watched states are simply recorded to a text file named ``states.dat'', with watches for each DBN update stored on consecutive lines. Using watches provides the primary method for storing DBN results.

Other methods of recording or displaying posterior beliefs of watched states could easily added to the software -- features such as bar or line graphs that update with the DBN were considered possible but not implemented.

Syntax

node-name : state-name slice-offset;
...

node-name

Identifies the name of the node containing any states that need to be recorded or `watched'. The node name doesn't include the slice number suffix (i.e everything before the underscore), and is case-sensitive.

state-name

Specifies the state of the above specified node to be watched. The state name should appear exactly as it is described in the node's state list, and as such is case-sensitive. Alternatively, if all the states for the specified node need to be recorded the state name can be replaced with a `*'; this is effectively the same as specifying watches for every state in a particular node.

slice-offset

This parameter is an integer which specified from which slice - relative to the current slice - the node/state posterior should be recorded. For example, node/states from the newest history slice is specified by supplying a slice-offset of `-1', the oldest prediction slice by `1' or `+1', and the current slice by `0' (zero). If the slice-offset is not supplied, a `0' slice-offset is assumed, so beliefs are taken from the current slice.

Example

.watches
Support:left;
Support:right;
Support:left +1;
Support:right -1;
Action:* -2;

Notes

The above example shows how the software is instructed to store posterior beliefs the states `left' and `right' from the node `Support' in the current slice, `left' from node `Support' in the first prediction slice, `right' from node `Support' in the slice before the current, and all states of the node `Action' from two slices before the current.

Default node states

The default node states configuration was provided for situations where all observation nodes need to be instantiated for in each slice. For example, when interval timeout evidence is added to a gait DBN, the action observations (foot up/down evidence) may not necessarily be instantiated for that slice. After samples for all channels is processed, the software detects that (interval) evidence was added, so expands the network without any action observations being added. In theory, the DBN should be able to compensate for `missed' evidence, but to reduce confusion is was decided to implement a system to instantiate default states. A list of nodes with their default states is maintained in memory; before the DBN is updated, the software consults this list and sets any nodes that have not received evidence in this slice to their default state. In the above interval timeout example, the `action' nodes were given a default state of `none' which is then handled in the DBN model's CPTs.

Syntax

node-name = state-name;
...

node-name

The name of a node to specify a default state for. As for node watch definitions, the node name does not include the trailing underscore and slice number, and is case-sensitive.

state-name

Specifies the default state the node with node-name should be instantiated to if it has not received evidence.

Example

.defaultstates
ActObs = none;

The above example shows how one would set the default sate of node `ActObs' to `none'.

CPT expression parameters

The parameters section of the configuration provides a place to define `global' constants which can then be used in conditional probability table expressions for individual nodes (see next section). Parameters merely assign real values to text variable names which can then be included as part of a CPT expression.

Syntax

parameter-name = value;
...

parameter-name

This is a text name which should always start with an alphabetic character (`A'...`Z', `a'...`z'), which can then be followed by any alphanumeric. The parameter-name is terminated by either a space or the separating `=' character.

value

The value is any real number, and as such should start with the `+', `-' characters, or a number. The number may also include decimal-points, but no non-numeric characters.

Example

.parameters
a = 0.50;
a1 = 12;
fallprob = 0.15;

Notes

The parameter names are not case-sensitive when referred to in expressions. If a parameter is defined twice, it takes on the last defined value.

CPT expressions

The CPT expressions provide a method of defining entries in the conditional probability tables for individual nodes. Unlike the other text-based configuration information, CPT expressions are stored in the `description' section for each node.

state-name | parent-states-list = expression;
...

   
Command-line interface

The command-line interface provides a rudimentary method of providing the DBN software with the information it needs to start processing data. The command-line syntax is as follows:

process reference-network data-file history-slices prediction-slices expansion-slices

When the process program is run with valid commands, it processes the samples from the data file using the specified DBN model until reaches the end of the data file, then stops.

reference-network

This is the directory and name of the Netica `.dne' network file containing the reference network (see Section A.1.1) and software configuration (see Section A.1.2).

data-file

The data file specifies where the process program is to collect the data for processing. No checking is performed on this file, and it assumed to be in the format specified by the .input configuration (Section A.1.2).

history-slices

This option is a positive integer specifying the number of history slices should maintain in the DBN.

prediction-slices

This number specifies how many prediction slices the DBN should use

expansion slices

Optionally specifies number of slices to expand the DBN after evidence is added. In not specified, this defaults to 1.

   
WinDBN software application

The WinDBN application was the graphical user interface to the DBN processing software, written in C++ for the Win32 API [62,61]. This GUI provided a simpler (and slightly more user-friendly) method of controlling processing of different data with different DBN models. Figure A.3 shows the main features of the WinDBN window, with controls highlighted. The purpose these controls with descriptions of some of the features and inner workings of the WinDBN application are described below.

  

Figure A.3: The WinDBN graphical user interface

Specify data source

This button displays a file dialog box which can be used to specifying the file containing data to be processed. For this implementation, this should be a `rawdata.slp' binary raw sample file created by the SiestaView program (see Section 5.2.1).

Enable/disable polling

This control enables or disables file polling. When file polling is disabled, if the software reaches the end of the data file while processing it waits for the polling interval, then tries the read the file again. If the SiestaView program has written any new data received from the datalogger, it will be loaded by WinDBN and processed. To stop polling or processing click the `stop' button. If this option is disabled, processing stops as soon as WinDBN reaches the end of the data file (or the stop button is clicked).

Start processing

Once a data file and DBN reference network have been specified, this button is enabled, and can then be used to start processing. Clicking this button loads the specified reference network, opens the data source, and creates a new `worker' thread which performs DBN processing on the data in parallel with the WinDBN interface.

Stop processing

When enabled, this button can be used to stop processing. Clicking this button raises a synchronisation event, which causes the DBN thread to stop processing and destroy itself. If the thread doesn't stop on its own accord after a certain amount of time, it is forced to terminate.

Polling interval

This control is used to specify the file polling interval in milliseconds. When polling is enabled and the processing thread reaches the end of the data file, it `sleeps' for this amount of time then tries to read from the data file again. This method is used to avoid excessive load on the operating system. Lower polling values result in higher CPU and file-system load, but quicker response in data retrieval.

History slices

Specifies the number of history slices to be used by the DBN when processing data.

Prediction slices

Specifies the number of prediction slices to be used by the DBN software when processing data.

Expansion slices

Specifies the number of slices to expand the DBN each time evidence is added (used in Section 9.5.3).

Save slices

When this option is enabled, every time the DBN is expanded, it is saved to a Netica `.dne' file in the same directory as the data file. This is useful for viewing `snapshots' of the DBN while it was processing. Note that this will slow processing down considerably, and may result in hundreds of network files being created. Use sparingly.

Specify DBN

Similar to specifying the data source, this button displays a dialog box which can be used to specify the reference network to be used. The file should be of the Netica `.dne' format and contain the reference network (Section A.1.1) and configuration information (Section A.1.2).

Edit DBN

This loads the current specified DBN reference file into Netica GUI (if installed) so it can be edited. Before starting processing on the data, make sure the reference network is saved in Netica to enable any changes.

Close DBN

This button causes the program to flush buffers, close any remaining files and destroy the DBN processing thread object. This command was mainly added to force writing of data files to disk. Once the DBN is closed, processing cannot start until a new DBN file (and data source) is specified.

Exit

Stops processing, destroys any remaining objects and exits WinDBN.

General program information

This button displays another window containing some general program information and any Netica API messages.

Whenever the WinDBN program does something of note - such as starting or stopping processing, handling errors, exiting or starting up - it writes a message to a text log file. This file, `windbn.log' should be created in the same folder as the WinDBN program itself. Once the WinDBN program is no longer running, this file may be deleted if not required.