MuTE Settings, GUI

…and several examples

In this page I am going to explain how to set MuTE in order to perform several analyses. I will provide screenshoots and a description of the code to modify as detailed as possible. Furthermore, some examples will help to understand the whole procedure to properly set MuTE.

Toolbox Structure

MuTE has a very simple structure as we can notice from Fig1. The Main function allows the user to define the preliminary settings and to call the parametersAndMethods function. parametersAndMethods simply wraps the parameters defined in Main, calls the callingMethods function and calls the post precessing functions responsible to store the most informative quantities.

In Fig1. the schematic representation of the main toolbox’s parts and their relationship are shown.

The Pulpit Rock
Fig1. – Toolbox Structure.

In the following, the toolbox structure is illustrated in detail, step by step, in order to allow every user to use MuTE. The choice to show the function names in bold is aimed to let the user keep track of the most important functions.

Furthermore, the user will understand how to embed a new method within MuTE. The user who wants to share new method(s) can take a look at this page.

NB:

  • From now on the user is kindly asked to look at MuTE/exampleToolbox/exampleMain.m function
  • Parts of code will be showed either in blue boxes according to what is the current set up or in green providing some examples of possible set up
  • The % symbol is used for commented lines
  1. Data should be stored as files containing the field data. data should be a matrix of (number of series \times time points) dimensions. If the user wants to perform an analysis across many trials it is possible to store data as 3D matrices of (number of variables \times number of points \times number of trials) dimensions. It is possible to find an example of data files in MuTE/exampleToolbox/.
  2. Create a folder in which the data are stored. Let us call this folder as dataFolder from now on.
The Main script is the only one that should be modified by the user. The analyses can be set outside the specific functions. The examples will show how Main can be customized according to the user needs. The Main gives the opportunity to set the methods parameters, where to read the data, where to store the results. It is also possible to concatenate experiments in order to run Main only once. As soon as the set up is made, MuTE is ready to run and the user should not give any further contribution until the end of the experiments.

Some Useful Comments

At the very beginning of exampleMain there are what I hope are useful comments. First of all we can find the method order.


line 5:  %     Method order: please take the order into account because afterwards
line 6: % you should set autoPairwiseTarDriv or handPairwiseTarDriv that need
line 7: % the precise order of the methods
line 8: %
line 9: % binue
line 10: % binnue
line 11: % linue
line 12: % linnue
line 13: % nnue
line 14: % nnnue
line 15: % neunetue
line 16: % neunetnue

Afterwards the parameters for each method are listed. I explain them in detail in parametersAndMethods.

Folders Set Up

The folder set up is the first step to take into account. It is necessary to add MuTE to MATLAB path as follows:


line 204: % Set MuTE folder path including also all the subfolders, for instance
line 205: mutePath = ('/Users/alessandromontalto/Dropbox/MuTE/');
line 206: cd(mutePath);
line 207: addpath(genpath(pwd));
Change according to where you decide to store MuTE

% Set MuTE folder path including also all the subfolders, for instance
mutePath = '/Users/.../Desktop/MuTE/';
% Adjust according to your path -> just an example: mutePath = '/home/alessandro/Desktop/MuTE/';
cd(mutePath);
addpath(genpath(pwd));

Then, the user should set up the folder where the data are stored.


line 209: nameDataDir = 'exampleToolbox/'
line 211: % Set the directory in which the data files are stored. In this directory the outcome of the experiments will be stored too.
line 212: dataDir = ['/Users/alessandromontalto/Dropbox/MuTE/' nameDataDir];
Change according to where your data are stored

nameDataDir = 'folder_containing_your_data/'
% Set the directory in which the data files are stored. In this directory the outcome of the experiments will be stored too.
dataDir = ['/Users/.../folder_containing_your_data/'];
% Adjust according to your path -> just as example: dataDir = ['/home/alessandro/Dropbox/Phd/MuTE/' nameDaraDir];
cd(mutePath);
addpath(genpath(pwd));

Number of Processors

Set the number of processors you can use to run your experiments changing value to the following variable


line 216: numProcessors = 1;

File’s Variable Set Up

At this point two parameters should be set to load the correct data files:

  • dataFileName takes the part of the name file common to all the files involved in the analysis.
  • dataLabel is useful to distinguish files. If no label is required set dataLabel as an empty string.
  • dataExtension defines the file extension
Variables needed to load the data

line 226: %  Defining the strings to load the data files
line 227: dataFileName = 'realization5000p';
line 228: dataLabel = '';
line 229: dataExtension = '.mat';
Example 1
I have 100 trials named, for instance, realizations5000p_(…).mat where (…) can be a counter ranging from _1 to _100. In this case I do not to set dataLabel.

line 226: %  Defining the strings to load the data files
line 227: dataFileName = 'realization5000p';
line 228: dataLabel = '';
line 229: dataExtension = '.mat';
Example 2
I have 100 trials named, for instance, henonMaps_circular(…).mat and other 100 trials named henonMaps_sparse(…).mat where (…) can be a counter ranging from _1 to _100. In this case I would set the parameters as follows to perform the analysis taking into account henonMaps_sparse(…).mat.

line 226: %  Defining the strings to load the data files
line 227: dataFileName = 'henonMaps';
line 228: dataLabel = 'sparse';
line 229: dataExtension = '.mat';

General Parameters Set Up

Here I am going to describe the more general parameters useful to handle the methods:

  • channels is useful to select a subset of variables for a certain analysis. It is highly recommended to enter the series id from sorted in ascending order from left to right.
  • samplingRate should be greater than 1 if data should be downsampled
  • pointsToDiscard allows to discard a certain amount of points, starting from the last one. To better clarify samplingRate and pointsToDiscard, the meaningful part of line 315 in parametersAndMethods function is shown:
    data(channels,1:samplingRate:(end-pointsToDiscard))
  • realization may be left unchanged because it stores the files defined in dataFileName, dataLabel and dataExtension. It is worth taking a look at line 244 in exampleMain to get how realization is set:
    realization = dir([dataDir [dataFileName '*' dataLabel '*' dataExtension]]);
  • autoPairwiseTarDriv takes into account the opportunity to investigate all the pair wise combinations of the variables chosen by means of channels. autoPairwiseTarDriv is then a vector with either 0 or 1 entries. The methods order shown at the beginning of this section has to be preserved.
  • handPairwiseTarDriv is useful to when the user already know how many targets is going to choose for the analysis. If the the number of targets can be reshaped in a square matrix then it is worth setting as 1 the entriy of handPairwiseTarDriv corresponding to the method choosen. handPairwiseTarDriv is then a vector with either 0 or 1 entries. The methods order shown at the beginning of this section has to be preserved.
Variables useful to handle data

line 259: % Defining the experiment parameters
line 260: channels = 1:5;
line 261: samplingRate = 1;
line 262: pointsToDiscard = 4500;
line 263: realization = dir([dataDir [dataFileName '*' dataLabel '*' dataExtension]]);
line 264: autoPairwiseTarDriv = [0 1 0 1 0 1 0 0];
line 265: handPairwiseTarDriv = [0 0 0 0 0 0 0 0];
Example 1
Let’s say that we want to perform an analysis on henon_*.mat files in MuTE/exampleToolbox/. Those files contain a matrix called data with 6 time series of 2500 points. For instance, we want to analyse all the pair wise combinations taking into account only 3 variable out of the 6 available: variables 2, 5, 6. We also want to consider the first 2000 points out of the 2500 available. Finally, we only want to investigate binnue and nnnue performances. In this case we should set the parameters as follows:

line 259: %  Defining the experiment parameters
line 260: channels = [2 5 6];
line 261: samplingRate = 1;
line 262: pointsToDiscard = 500;
line 263: realization = dir([dataDir [dataFileName '*' dataLabel '*' dataExtension]]);
line 264: autoPairwiseTarDriv = [0 1 0 0 0 1 0 0];
line 265: handPairwiseTarDriv = [0 0 0 0 0 0 0 0];
Example 2
Taking into account the same data as “Example 1”, we do not want to analyse all the pairwise combinations, but we already know that we are going to choose a number of targets that can be reshaped in a square and that will involve all the variables. We want to downsample the time series at the half of the sampling rate and we want to take into account all the time points. This time we want to investigate binue, linue and linnue performances.

line 259: %  Defining the experiment parameters
line 260: channels = [1:6];
line 261: samplingRate = 2;
line 262: pointsToDiscard = 0;
line 263: realization = dir([dataDir [dataFileName '*' dataLabel '*' dataExtension]]);
line 264: autoPairwiseTarDriv = [0 0 0 0 0 0 0 0];
line 265: handPairwiseTarDriv = [1 0 1 1 0 0 0 0];
parametersAndMethods is the only funcion in the main script. It takes in input the parameters seen so far and the list of the methods with their own parameters. Inside parametersAndMethods the methods parameters are rearranged in only one structure used by other functions handle the proper parameters and perform the correct analyses.

It is worth seeing how parametersAndMethods is called in the exampleMain.

How to call parametersAndMethods
As we can see in the box below, parametersAndMethods accepts the general parameters followed by common parameters and particular parameters.

line 265: [output1,params1] = parametersAndMethods(realization,...
samplingRate,pointsToDiscard,channels,autoPairwiseTarDriv,...
handPairwiseTarDriv,resultDir,dataDir,copyDir,numProcessors,
...
'linue',[],[],[],5,'multiv',5,5,'bayesian',@linearEntropy,[1 0],[1 1],@generateConditionalTerm,0,...
'linnue',[],[],[],5,'multiv',@evaluateLinearNonUniformEntropy,[1 1],...
100,0.05,
@generateConditionalTerm,0,...
'binue',[],[],[],5,'multiv', 6,@conditionalEntropy,@quantization,[1 0],[1 1],100,0.05,20,@generateConditionalTerm,0,...
'binnue',[],[],[],5,'multiv',6, @evaluateNonUniformEntropy,@quantization,...
[1 1],100,0.05,
@generateConditionalTerm,0,0,...
'nnue',[],[],[],5,'multiv',[1 1],100,'maximum',10,nnMexa64Path,mutePath,...
0.05,10,
@generateConditionalTerm,0,...
'nnnue',[],[],[],5,'multiv',[1 1],100,'maximum',10,...
@nearNeiConditionalMutualInformation,@evalNearNeiTestSurrogates2rand,...
nnMexa64Path,mutePath,0.05,
@generateConditionalTerm,0,...
'neunetue',[],[],[],5,[1 1],'multiv',[],[],{@sigmoid @identity},30,0,4000,2/3,15,valThreshold,@resilientBackPropagation,1.1,0.9,1,numHiddenNodes,100,20,0.05,@generateConditionalTerm,0,...
'neunetnue',[],[],[],[],15,[1 0],[1 1],'multiv',[],[],{@sigmoid @identity},30,0,4000,threshold,2/3,15,valThreshold,@resilientBackPropagation,1.1,0.9,1,numHiddenNodes,@generateConditionalTerm,0);

In the following the screenshot of the call to parametersAndMethods.

  • Example

It is useful, then, to take a look in detail at the parameters that the user should set for each method. The parameters can be devided into two big groups: the common parameters that have to be set up for each of the 6 methods and the particular parameters that are useful to a particulr method only. I will provide some examples in order to make the meaning of the parameters as clear as possible.

Common Parameters

  1. idTargets is a row vector with entries the series id chosen as targets of the analysis. It may contain repeated indeces.
  2. idDrivers is a matrix with columns the series id whose influence on the corresponding target column wise in idTarget is going to be evaluated.
  3. idOtherLagZero is a matrix with columns the series id chosen among the conditioning variables for that analysis that should be taken into account with the instantaneous effect.
  4. modelOrder can be a vector indicating how many past states should be taken into account for each series chosen for the analisys by means of channels. If modelOrder is an integer the same amount of past states is considered for all the series in channels.
  5. multi_bivAnalysis is a string containing either “biv” or “multiv” according to whether perform a bivariate or multivariate analysis respectively.
  6. genCondTermFun is a pointer to function assuming either “@generateCondTermLagZero” or “@generateConditionalTerm” values. The first function, generateCondTermLagZero, takes into account the instantaneous effect for the drivers and for the variables indicated in idOtherLagZero. The second function, generateConditionalTerm, will not take into account the instantaneous effect, even if are explicitly mentioned in idOtherLagZero. This parameters should be set in accordance with usePresent.
  7. usePresent is an integer assuming 1 or 0 values according to whether genCondTermFun is set to “@generateCondTermLagZero” or “@generateConditionalTerm” respectively.
Example 1
Let’s assume that we have a matrix of (10 \times 3000) dimensions as data. We are interested in evaluating the adjacency matrix of the 10 variables: this means that we want to investigate all the pair wise combinations of the 10 time series taking into account all the time points. The implication is that we set idTargets and idDrivers as empy matrices.

Important: if we set an entry of autoPairWiseTarDriv as 1 idTargets and idDrivers of the correponding method will not be taken into account because autoPairWiseTarDriv has priority over idTargets and idDrivers.

Furthermore, we want a conditioned analysis taking 5 past states for all the variables and we do not want to consider the instantaneous effects. We select binnue, linnue and nnnue methods. The parameters should be set as follows:

  • channels = [1:10];
  • samplingRate = 1;
  • pointsToDiscard = 0;
  • […]
  • autoPairwiseTarDriv = [0 1 0 1 0 1 0 0];
  • handPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • idTargets = []
  • idDrivers = []
  • idOtherLagZero = []
  • modelOrder = 5
  • multi_bivAnalysis = ‘multiv’
  • genCondTermFun = @generateConditionalTerm
  • usePresent = 0
Example 2
Let’s assume that we have a matrix of (10 \times 3000) dimensions as data. We are interested, for instance, in evaluating the adjacency matrix of 4 variables out of 10.

Important: assume that we are choosing series 2, 5, 8, 9. the time series chosen for the analysis will be extracted from the original matrix. In this way the user should keep into account that idTargets and idDrivers will assume values from 1 to channels length. In this case they will assume values ranging from 1 to 4.

Furthermore, let’s assume that we do not want to investigate all the pair wise combinations. Instead, we only want to check whether there are information flows between certain driver-target couples and we need to have an idea about the directed dynamical links as soon as possible. Then we can use 500 points only. We also want a conditioned analysis taking 8 past states for all the variables and we want to consider the instananeous effects of certain conditioning variables. We select binnue, linnue and nnnue methods. The parameters should be set as follows:

  • channels = [2 5 8 9];
  • samplingRate = 1;
  • pointsToDiscard = 2500;
  • […]
  • autoPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • handPairwiseTarDriv = [0 1 0 1 0 1 0 0];
  • idTargets = [1 1 2 2 3 3 4 4 4]
  • idDrivers = [2 4 1 3 1 4 1 2 3]
  • idOtherLagZero = [3 0 0 0 2 0 0 1 2; 4 0 0 0 0 0 0 0 1]
  • modelOrder = 8
  • multi_bivAnalysis = ‘multiv’
  • genCondTermFun = @generateCondTermLagZero
  • usePresent = 1

As we can notice, I chose 9 targets so I could set a 1 in handPairwiseTarDriv vector corresponding to the right method. To better explain the set up I can say that we are going to take into account the instantaneous effects of the variables 3 and 4 (corresponding to the 5th and the 8th time series of the original matrix) when investigating how 2 is influencing 1, conditioned to the other two variables. At this point the instantaneous effects for the drivers are not taken into account.

Example 3
In this example we still want to deal with a matrix of (10 \times 3000) dimensions as data. This time, we want a bivariate analysis including the instantaneous effects for the drivers. The procedure is slightly different: the id of the driver should be repeated. The explanation of the difference between the set up of the instantaneous effects for the drivers and for the conditioning variables is that the conditioning variables are taken into account setting multi_bivAnalysis = ‘multiv’ so it is easy to arrange the specific instantaneous effects in another vector. We only want to use the first 5 time series without discarding any point. We want to use a vector to set a specific model order for each time series. Binue, linue and linnue will be the methods involved in the analysis.

  • channels = [1:5];
  • samplingRate = 1;
  • pointsToDiscard = 0;
  • […]
  • autoPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • handPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • idTargets = [1 1 2 3 3 4 5]
  • idDrivers = [2 4 3 1 4 2 3; 5 0 0 2 1 5 0]
  • idOtherLagZero = []
  • modelOrder = [4;3;5;3;3]
  • multi_bivAnalysis = ‘biv’
  • genCondTermFun = @generateCondTermLagZero
  • usePresent = 1

There are 7 targets so it is better to have handPairwiseTarDriv = [0 0 0 0 0 0 0 0] otherwise there will be an error when the results will be reshaped in a square matrix. idOtherLagZero will never be taken into account when multi_bivAnalysis = ‘biv’.

Example 4
Another example trying to combine the configurations that we have previously seen in Examples 1-3. I am assuming that I have a matrix of (10 \times 3000) dimensions as data. I will first show the set up and then I will provide some comments about it.

  • channels = [1 3 4 7 8];
  • samplingRate = 3;
  • pointsToDiscard = 100;
  • […]
  • autoPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • handPairwiseTarDriv = [0 0 0 0 0 0 0 0];
  • idTargets = [1 2 3 4 5]
  • idDrivers = [2 3 4 1 2; 3 0 5 0 4; 4 0 2 0 0]
  • idOtherLagZero = []
  • modelOrder = 8
  • multi_bivAnalysis = ‘multiv’
  • genCondTermFun = @generateCondTermLagZero
  • usePresent = 1

I am performing an analysis taking into account series 1, 3, 4, 7 and 8 downsampled at one third of the original sampling rate. I am discarding the last 100 time points. I am investigating how:

  1. variables 2, 3 and 4 are influencing 1 conditioned to 5. This is equivalent to say that I am interested in detecting the information flow from variables 3, 4 and 7 towards variable 1 conditioned to variable 8 of the original matrix. The same reasonining can be applied in the following;
  2. variable 3 is influencing 2 conditioned to variables 1, 4 and 5;
  3. variables 4, 5 and 2 are influencing 3 conditioned to 1;
  4. variable 1 is influencing 4 conditioned to the variables 2, 3 and 5;
  5. variables 2 and 4 are influencing 5 conditioned to 1 and 3.

Particular Parameters

LIN UE
We embedded “arfit” in linue in order to allow the user to look for the best model order. For further references the user is kindly asked to read arfit documentation.

  • minOrder \rightarrow integer: lower bound of the interval in which arfit can look for the best model order able to fit the data
  • maxOrder \rightarrow integer: upper bound of the interval in which arfit can look for the best model order able to fit the data
  • orderCriterion \rightarrow string: order selection criterion for arfit. If orderCriterion is not set to ‘bayesian’, the Akaike’s Final Prediction Error will be chosen as selection criterion
  • entropyFun \rightarrow pointer: pointer to the function that will evaluate the entropy
  • firstTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 0]). Set 1 according to wich candidates you want to take into account
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
LIN NUE
  • entropyFun \rightarrow pointer: pointer to the function that will evaluate the entropy
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold
  • alphaPercentile \rightarrow integer: significance level
BIN UE
  • numQuantLevels \rightarrow integer: number of quantum levels
  • entropyFun \rightarrow pointer: pointer to the function that will evaluate the entropy
  • preProcessingFun \rightarrow pointer: pointer to the function needed to pre-process of the data
  • firstTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 0]). Set 1 according to wich candidates you want to take into account
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold

  • alphaPercentile \rightarrow integer: significance level
  • tauMin \rightarrow integer: number of shifts to produce a surrogate
BIN NUE
  • numQuantLevels \rightarrow integer: number of quantum levels
  • entropyFun \rightarrow pointer: pointer to the function that will evaluate the entropy
  • preProcessingFun \rightarrow pointer: pointer to the function needed to pre-process of the data
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold
  • alphaPercentile \rightarrow integer: significance level
NN UE
  • firstTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 0]). Set 1 according to wich candidates you want to take into account
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold
  • metric \rightarrow string: it is possible to set the metric (either ‘euclidian’ or ‘maximum’) used to evaluate the distance in the phase space
  • numNearNei \rightarrow integer: number of nearest neighbors to compute
  • funcDir \rightarrow string: mex files path
  • homeDir \rightarrow string: MuTE path
  • alphaPercentile \rightarrow integer: significance level
  • tauMin \rightarrow integer: number of shifts to produce a surrogate
NN NUE
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold
  • metric \rightarrow string: it is possible to set the metric (either ‘euclidian’ or ‘maximum’) used to evaluate the distance in the phase space
  • numNearNei \rightarrow integer: number of nearest neighbors to compute
  • informationTransCriterionFun \rightarrow pointer: pointer to the function needed to evaluate the conditional mutual information;
  • surrogatesTestFun \rightarrow pointer: pointer to the function that performs the surrogates test;
  • funcDir \rightarrow string: mex files path
  • homeDir \rightarrow string: MuTE path
  • alphaPercentile \rightarrow integer: significance level
NeuNet UE
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • eta [1] \rightarrow real number: learning rate to update the weights with gradient descent and gradient descent with momentum
  • alpha [1] \rightarrow real number: parameter required in gradient descent with momentum [2]
  • actFunc \rightarrow cell array of pointers: it contains pointers to functions that are used as activation functions. There must be (number hidden layers + output layer) number of entries specifying the activation function for each layer
  • numEpochs \rightarrow integer: number of training epochs
  • bias \rightarrow integer: it allows to take into account the bias if it is set as 1. If bias nodes are not required, “bias” has to be set as 0
  • candidateEpochs \rightarrow integer: number of maximum iterations needed to train the network with the current candidate. It is used in the outer “while” of the non-uniform wrapper
  • dividingPoint \rightarrow real number: amount of points used to train the networks. It is expressed as percentage of the data set number of points
  • valStep \rightarrow integer: number of iterations after which the validation phase takes place
  • valThreshold \rightarrow real number: threshold needed during the validation phase
  • learnAlg \rightarrow pointer: points to the function used as learning algorithm
  • rbpIncrease \rightarrow real number: \eta^-, Riedmiller (1993)[3]
  • rbpDescrease \rightarrow real number: \eta^+, Riedmiller (1993)[3]
  • rangeW \rightarrow real number: it represents the range of values assumed by the weights when initialized. If rangeW is set as 1, the weights will be initialized between -1 and 1
  • coeffHidNodes \rightarrow real number: percentage of hidden nodes with respect to the amount of available candidates
  • numSurrogates \rightarrow integer: number of surrogates necessary to asses the statistical threshold
  • tauMin \rightarrow integer: number of shifts to produce a surrogate
  • alphaPercentile \rightarrow integer: significance level
NeuNet NUE
  • data \rightarrow matrix: data arranged differently with respect to data used by the other methods. It might be useful to arrange data in order to line up the realizations that the other methods would analyze separately
  • firstTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 0]). Set 1 according to wich candidates you want to take into account
  • secondTermCaseVect \rightarrow vector: the first position refers to idTargets, the second one refers to idDrivers ([1 1]). Set 1 according to wich candidates you want to take into account
  • eta [1] \rightarrow real number: learning rate to update the weights with gradient descent and gradient descent with momentum
  • alpha [1] \rightarrow real number: parameter required in gradient descent with momentum [2]
  • actFunc \rightarrow cell array of pointers: it contains pointers to functions that are used as activation functions. There must be (number hidden layers + output layer) number of entries specifying the activation function for each layer
  • numEpochs \rightarrow integer: number of training epochs
  • bias \rightarrow integer: it allows to take into account the bias if it is set as 1. If bias nodes are not required, “bias” has to be set as 0
  • candidateEpochs \rightarrow integer: number of maximum iterations needed to train the network with the current candidate. It is used in the outer “while” of the non-uniform wrapper
  • dividingPoint \rightarrow real number: amount of points used to train the networks. It is expressed as percentage of the data set number of points
  • valStep \rightarrow integer: number of iterations after which the validation phase takes place
  • valThreshold \rightarrow real number: threshold needed during the validation phase
  • learnAlg \rightarrow pointer: points to the function used as learning algorithm
  • rbpIncrease \rightarrow real number: \eta^-, Riedmiller (1993)
  • rbpDescrease \rightarrow real number: \eta^+, Riedmiller (1993)
  • rangeW \rightarrow real number: it represents the range of values assumed by the weights when initialized. If rangeW is set as 1, the weights will be initialized between -1 and 1
  • coeffHidNodes \rightarrow real number: percentage of hidden nodes with respect to the amount of available candidates

1. This parameter is not useful to set the method appeared in literature. Nonetheless, it might be useful for further analyses considering a variation of the published method. BACK TO POST
2. For further references – doi:10.1038/323533a0. BACK TO POST
3.

BACK TO POST

NB:

In parametersAndMethods lines 12-74 are devoted to convert the list of parameters given in input to a list of variables that will belong a particular method. Lines 180-288 are devoted to encapsulate the parameters of the chosen methods in a unique structure. This step is the needed brigde between the interface of MuTE with the user and the methods. To complete this step the funcion createNameMethodParams that locks the input parameters in the method structure is needed. After that the callingMethods is called.
callingMethods function calls the chosen methods. The function only requires the more general data structure built during the wrapping of the parameters and the data. The output is a structure that groups the results of the methods.
Three functions are involved in this step, called in parametersAndMethods:

  • storingOutput \rightarrow rearrange and store callingMethods output creating a different file for each realization and method. In this way each method will have its performances stored according to the analyzed file. Each file contains a structure named outputToStore. This is the most important post-processing function: starting from its output (the fields of outputToStore) the user can manage all the most useful informations in order to apply his own post-processing.
  • generateExpReport \rightarrow adds other fields to outputToStore structure such as pValue, modelOrder, testThreshold and bestOrder if those fields belong to the chosen method. The function, furthermore, generates the following files in entropyMatrices folder:
    • methodName_matrixPValues
    • methodName_testThresholdMtx
    • methodName_transferEntropyMtx
  • reshapeResults \rightarrow If either autoPairwiseTarDriv = 1 or handPairwiseTarDriv = 1 and the number of targets can be reshaped in a square, the function reshapes and stores the significance matrix and evaluates the mean values of the transfer entropy with respect to the number of trials obtaining a vector the same length as the number of targets. Then the mean transfer entropy values are reshaped and stored as well.

Let’s take a closer look at the output files stored during the post-processing phase. We can find two folders where the outputs are stored, entropyMatrices and results folders.

In entropyMatrices the following files can be found:

  • methodName_transferEntropyMtx contains a first column with the id of the data files. The other columns representing the entropy values: if the user sets allPairWiseCombinatins = 1 and he is dealing with 5 time series, he is going to evaluate 5 \times 4 = 20 pairwise combinations not considering each series as target of itself. This means that the number of targets is 20. transferEntropyMtx will have 21 columns and as much rows as the number of trials.
  • methodName_significanceOnDriv only contains as much columns as the number of targets and as much rows as the number of trials. Each entry may assume 1 or 0 values according to whether the link is significant or not.
  • methodName_reshapedSignificance contains the significance values reshaped to form the adjacency matrix if the experimental set up allows the reshaping.

In results the following files are stored:

  • methodName_typeAnalysis_patient_idTrial contains the outputToStore structure. This is the basic file from which everything can be evaluated during the post-processing phase.
  • methodName_meanReshapeMtx is provided in results folder. This file contains the average of the values stored in transferEntropyMtx reshaped (if the experimental set up allows the reshaping) in order to show the adjacency matrix and be able to see the directed dynamical links.

NB: the user is kindly invited to develop his own functions to evaluate what may be the most useful informations according to his particular experiment. The post processing that I provide should be considered as an example of what can be devaluated.

The MuTE GUI has been developed to make the MuTE toolbox more user-friendly. To launch the GUI, type “mute” at the MATLAB command prompt. The window in Fig2 will appear.

The Pulpit Rock
Fig2. – MuTE GUI main window.

How to use the GUI

The work flow can be separated into 3 parts: 1) Setting the general parameters and data selection, 2) setting method specific parameters and 3) generate script/execute the analysis.

General Parameters and Data

The general parameters refer to those parameters that apply to all the methods used (i.e. the methods selected in the 2nd step). These can be set by clicking the ‘General parameters and Data’ button on top of the main window. A new window will appear where the data can be selected and general parameters can be set, Fig3. In the new window, all the relevant parameter that need to be specified are listed. Most of the parameters have default values. In addition, every parameter is accompanied with a info (“?”) button. More info regarding specific parameters can be obtained by clicking on the info button. Once all the relevant parameters are set, you can save the settings by clicking the ‘Save settings’ button. The default values can be restored by clicking the ‘Restore default’ button.

The GUI does an automatic check with respect to the selected data. The number of data files selected by the MuTE GUI will be displayed at the command prompt. If for some reasons the GUI is unable to find the data files, an error will pop up. If no data is found, it will be impossible to save the settings and thus also to generate a script/execute the analysis. Once the correct general parameters are saved, the general parameters window will be closed and the checkbox next to the ‘general parameters and data’ button in the main window will be checked.

The Pulpit Rock
Fig3. – The general parameters and data pop-up window.

As soon as the general parameters are saved, if everything is set up correctly the following warning is printed on the workspace in order to remind the user to wait until the computation is done and to not worry about the prompt shown in the workspace: “WARNING: the computation is taking place in another workspace. Please wait until ‘…COMPUTATION DONE!’ is displayed.”

Method-specific Parameters

In the middle of the main window, there are 8 buttons listed vertically. Each of these buttons
will open a new window where you can specify method specific parameters, Fig4.

The Pulpit Rock
Fig4. – An example of a method specific pop-up window. Here the method specific
parameters can be specified. In figure, the linue method settings are displayed.

The methods listed from top to bottom are the following:

  • Binue: Binning uniform embedding
  • Binnue: Binning non-uniform embedding
  • Linue: Linear uniform embedding
  • Linnue: Linear non-uniform embedding
  • Nnue: Nearest neighbor, uniform embedding
  • Nnnue: Nearest neighbor, non-uniform embedding
  • Neunetue: Neural networks uniform embedding
  • Neunetnue: Neural networks non-uniform embedding
    • The method specific window is similar to the general parameters window. All the
      parameters have default values. It is recommended to keep the default values for most
      parameters. Each parameter is again provided with a (“?”) info button. The info button opens
      a window where more information regarding that specific parameter can be obtained.
      Once the settings are saved, the window will be closed and the checkbox next to the
      parameter will be checked. If one of the method specific checkboxes is unchecked, then
      that method will not be performed during the analysis.

      Generate Script/Execute the Analysis

      Once all the setting have been set, the user has two options: 1) generate a script or 2)
      execute the analysis. When clicking the “generate” button, a matlab scrip, a .m file with the date and hour of
      generation in the name e.g. mute\_analysis\_2016\_1\_28\_9h\_56min.m, will be generated in
      the data folder. The analysis can than be run by simply running the script.
      When clicking the “execute” button, the same script will be generated but now it will also be
      executed automatically. Our goal of generating a script is to make the transition from point-and-
      click to command line analysis easier.
      The user must specify at least one of the methods and the general parameters, otherwise an
      error will pop-up and no script will be generated/executed.
      The analyses are done once the main window is closed. The results can be found in a folder
      inside the data directory.

      Acknowledgments

      The GUI was developed in collaboration with Frederick Van de Steen who arranged the code. For further references about the GUI please do not hesitate to contact him at \textit{frederik.VandeSteen@ugent.be} or send an email by filling in the form available in Contacts page.