Composites

Introduction

As of version 2.6, ANSLAB allows to compute composites from different result variables from other ANSLAB analyses. This feature is of particular interest whenever a single physiological variable on its own seems to be rather unreliable. In such a case, computing a composite and using it for further analyses may help to cancel out such unreliabilities. In case of response coherence analyses using a composite instead of single physiological variables is of particular interest. Therefore the coherence module in ANSLAB allows to use composite signals directly.

ANSLAB provides two different ways of creating composites, which are described in more details below: through a simple user interface (UI) and script-based composites, which provide much more flexibility for advanced needs.

Once the composite configuration is done, the composite computation can be started.

[Top]

General options

The options for composites can be configured under 'tools -> options -> composites':

In this dialog various general aspects of composites can be configured:

• Saving sample rate
  The setting 'Saving sample rate [Hz]' allows to specify the sampling rate used to save the resulting composites.
• Enabling script-based composites
  By checking the option 'Use scripts' the script-based composites are enabled. Once enabled, the lower part in the options dialog for the UI-based configuration gets disabled.
• NaN-removal in source signals
  Since some source signals (i.e. result variables from other analyses) may contain NaN-values (i.e. missing values), for instance, due to signal editing, this option allows to enable removal of such values in the source signals. If enabled, the NaN-values are removed by a simple linear interpolation between valid values.
• Enabling z-transform for source signals
  If the option 'Apply z-transform to signals prior to composite computation' is enabled, the source signals are subject to a z-transform prior to the actual composite computation.
• Output folder for composites
  Within a study folder the subdirectory 'composite' exists. In order to allow more than one composite to reside in this directory for each subject, an output folder must be specified for the composite computation. If not existing, this folder is created inside the 'composite'-folder and the results of the composite computation are stored within this subfolder.

[Top]

UI-based composites

The UI-based configuration allows to configure the desired composite through a simple UI. This is especially well-suited for cases in which rather simple composites should be configured.

The figure above shows the composite configuration in the options dialog below the general settings. Configuring a composite in this mode is just a matter of entering the desired configuration in the table shown. In this table the columns have the following meanings:

Column	Meaning
Category	Type of signal (e.g. ecg, eda, pulse, ...). This corresponds to the analyses abbreviations used for the result folders inside the study-folder.
Variable	The variables available for the composite configuration. While composites can be computed from a vast number of result variables of ANSLAB analyses, one restriction which applies is, that these must be stored as uniformly sampled variables (variable names ending with a '0', e.g. ibi0 from the ecg-analysis).
Include?	Determines whether the variable on the respective line should be included in the composite.
Sign	Allows to specify how the respective variable should be used in the composite. If set to 'Negative', the source signal is inverted prior to inclusion in the composite (i.e. the sign of the source signal is reversed).
Weight	This option allows to give a lower/higher weight to certain variables such that these contribute less/more to the final composite.
Channel label	Since ANSLAB supports more than one channel for analyses, the source folder used for the respective variable must be specified. If, for example, for ecg-data two channels exist (two sub-folders inside the 'ecg'-folder), the channel to draw the respective variable from must be specified accordingly. Important: even if only a single channel exists, the respective name must be entered here.

The following configuration,

for example, results in the composite

    composite = ((-ztrans(ibi0) - ztrans(tv0))/2 + ztrans(sc0))/2
			

where 'ztrans' denotes the z-transform, which is enabled in this example.

There are also different buttons available in the configuration section, which have the following meanings:

• Import
  If a composite has already been computed previously, this button allows to import the configuration for UI-based composites. While this button also allows to import UI-based configurations from result files generated using script-based composites, these settings may be useless since they have not been used for the respective composite results. Hence, in such a case a confirmation dialog is shown.
• Set all positive
  Sets the signs for all variables to 'Positive'.
• Set all negative
  Sets the signs for all variables to 'Negative'.
• Clear inclusion flags
  Clears all inclusion flags for the variables. In other words, all variables are removed from the currently configured composite.
• Reset weights to 1
  Sets all weights for the variables to 1.

[Top]

Script-based composites

In contrast to the UI-based composites, the script-based composites offer much more flexibility with respect to the complexity of a composite.

Basically, a script for composites needs two things to be specified:

• a list of signal folders to be used as source for the composite.
• a computation rule for the composite fromm within which the variables of the different signal folders may be accessed.

This is done by writing a simple text file (extension '.txt') and saving it inside the 'composite'-folder within the study folder. While the script may be saved practically anywhere, ANSLAB always opens the 'composite'-folder when the user is prompted to choose a script file.

The general structure of a composite script can be outlined as follows:

    [sourcefolders]
    channel1 = 'subfolder of channel 1'
    channel2 = 'subfolder of channel 2'
    ...
    channelN = 'subfolder of channel N'
    
    [compositerule]
    composite = 'the computation rule to be used'		
			

Hence, two sections need to be specified ([sourcefolders] and [compositerule]). These section names are case-sensitive.

The names for 'channel1' to 'channelN' must be one of the following names (shown in bold), representing the different analyses of ANSLAB supported for composites:

• resp - respiration analysis
• ecg - ecg analysis
• eda - eda analysis
• bp - blood pressure analysis
• pulse - pulse analysis
• co2 - pCO2 analysis
• emg - emg analysis
• startle - startle analysis
• accel - accelerometry analysis
• temp - temperature analysis
• eog - eog analysis

Important: the channel names are case sensitive since they are directly used to load the data from the respective folders. In addition, they must be enclosed by single quotes (').

The subfolders specified for the different analysis types must be the subfolders inside the result folders for the respective analysis type (inside of the study folder). In other words, these subfolders denote the channel names used for the different signals analyzed in ANSLAB.

The composite rule must always be of the form:

    composite = 'the computation rule to be used'			
			

Again, the word 'composite' is case-sensitive and the rule should be surrounded by single quotes. The rule can basically be any valid mathematical expression, supported by MATLAB (this is the main reason for the great flexibility of script-based composites). Just keep in mind that the result variables from ANSLAB are passed in into the formula as vectors.

In addition, ANSLAB result variables from channels can be accessed by

    channel.variablename			
			

where 'channel' is one of the valid channel names above (a sourcefolder must have been specified for the channel) and 'variablename' denotes a valid variable as stored in the result files from the respective analysis. Similar to the UI-based composites usually only uniformly sampled variables (ending with a '0') should be used. For example,

    ecg.ibi0
			

accesses the ibi0 variable from the ecg data of the channel specified in the sourcefolders section.

To allow the user to add comments to the script file, lines starting with a '%' are ignored.

An example for a complete composite script is shown below:

    [sourcefolders]
    ecg = 'ECG Lead II'
    eda = 'EDA'
    pulse = 'Pulse'

    [compositerule]
    % a simple comment which could be a brief explanation
    % of what exactly is included and why it is included
    % in the composite
    composite = '((ztrans(ecg.ibi0) + ztrans(pulse.pa0))/2 + ztrans(eda.sc0))/2'			
			

In this example, the ecg analysis result variables are drawn from the subfolder 'ECG Lead II' inside the ecg-folder, the eda analysis result variables are drawn from the subfolder 'EDA' inside the eda-folder, and the pulse analysis result variables are drawn from the subfolder 'Pulse' inside the pulse-folder inside the study folder.

The composite is then computed as the mean between skin conductance levels and the mean between inter-beat-intervals and the pulse wave amplitudes. The function 'ztrans' simply applies the z-transform to the variables prior to the actual composite computation. While in this example the z-transform has been applied to each variable used, this is not necessary, which, in contrast to UI-based composites, is another example for the flexibility offered by composite scripts.

[Top]

Which composite type should be used?

The decision on the composite type to use is completely up to the user.

The UI-based composites are probably slightly easier to use than the script-based counterparts. But when configuring composites through the UI there is less flexibility (e.g. the z-transform is enabled/disabled globally). In addition, for some weights for variables it might not be possible to express them to the full precision needed (e.g. if the weight involves a repeating decimal such as for example 1/3).

The script-based composites involve writing a small script. But this is rewarded with a very high flexibility in terms of what can be computed with a composite (e.g. a z-transform for single variables is possible, many functions known to MATLAB may be used directly within a composite). In addition, weights can be entered as fractions (i.e. this provides the full precision available in MATLAB).

[Top]

Starting the composite computation

The steps required to carry out a composite computation are as follows:

1. If you want to compute composites for more than one raw file you may load a batch file, containing the full paths and file names of the respective raw files.
2. Select 'calculate > compute composites' from the ANSLAB menu. If you loaded a batch file previously you will be asked if you want to use that or if you want to select a single raw file. If no batch file is loaded you have to select a raw file.
3. If script-based composites are enabled, you have to select a composite script file.
4. The composite analysis is now carried out, involving the following steps:
   • The needed source signals are loaded and resampled to 4 Hz (if necessary). Depending on the setting in the composite options, NaN-values will be removed at this step.
   • All signals involved in the composite will be shortened to the shortest signal length among all involved source signals.
   • The actual composite is computed. In case of UI-based composites a z-transform will be applied to all source signals if the respective option is set in the options.
   • The composite data is resampled to the saving sampling rate set in the options.
   • Finally, the composite results will be stored inside the composite output folder set in the options (inside the composite folder inside the study folder).
     
     

The important variable within a composite result file for use in other modules (e.g. the coherence module) is named 'DATA'.

[Top]