Difference between revisions of "AnyWave:MATLAB Batch GUI"

From WikiMEG
Jump to: navigation, search
(→‎Make my plugin GUI compatible)
(→‎inputs)
 
(17 intermediate revisions by one user not shown)
Line 1: Line 1:
 
=Introduction=
 
=Introduction=
−
AnyWave can process files using the command line, but you will have to create a script file compatible with your platform and run it.<br/>
+
AnyWave can run plugin code using the command line as mentioned here: [[File:Menu_cli.png|400px|link=AnyWave:CommandLine|'''The Command Line Interface of AnyWave''']]<br>
−
On alternative is to batch processing using AnyWave and a GUI.<br/>
+
That implies the user has to write his own shell scripts to accomplish that.<br/>
−
This is a way to batch process several processes and several different files without writing a shell script.<br/>
+
One alternative is to use the AnyWave built-in Batch GUI that allows to program your batch operations using a user friendly interface.<br/>
−
But first, your plugin must be able to run in batch mode from the command line.<br/>
+
This features allows to run your batching operations within AnyWave, in the background with a monitoring of what it is done.<br/>
−
See the [[AnyWave:MATLAB Batch|dedicated section to make it compatible]].<br/>
+
If we want our plugin to be processed using this feature we must make it compatible with AnyWave Batch GUI system.<br/>
  
 
=Make my plugin GUI compatible=
 
=Make my plugin GUI compatible=
−
This can be done by creating two json files to place in your plugin folder.<br>
+
First, the plugin must be callable using the command line.<br/>
−
==ui.json==
+
Reminder on how to do that:
−
There are some important things to setup in ui.json file:<br/>
+
[[File:Menu_matlab_batch.png|400px|link=AnyWave:Plugin_Batch|'''Make your plugin batchable''']]
−
There is a key describing the input parameters of the plugin. Suppose that you want to compute something on several files, you must then set several input_keys in the json file.<br/>
+
==args.json==
−
This is done by creating the '''input_keys''' key.<br/>
+
Remember, we have defined an arg.json file to describe the command line arguments we would like AnyWave to parse for us:<br/>
−
This key will hold the names of all the other keys that must be considered as files that AnyWave will provide to our plugin when running it.<br/>
+
−
In our example below, there is only ONE file key, that we called input_file which is the default key name for the file argument.<br/>
+
−
Hence, AnyWave will bring a GUI to pick up all the files we want, and run our plugin on all those files.<br/>
+
−
Once you setup the FILES entries keys, you must also describe them in the file by setting two values to the corresponding key.<br/>
+
−
The first value is always the decorated readable name of the key that will be used to create the GUI.<br/>
+
−
The second value is a string. If you set "check" as the value, that will tell AnyWave to check that the file setup is a data file and not a side car file.<br/>
+
−
If you don't want a data file to be set, just set an empty string as the value.<br/>
+
−
 
+
−
Let's setup an example using one input file and two parameters:<br/>
+
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
−
{
+
"parameters" : [ "eeg_file", "meg_file"],
−
"input_keys" : [ "input_file"],
+
"flags" : [ "use_downsampling", "vectorize_data"]
−
"input_file" : ["Input File", "check"],
+
</syntaxhighlight>
−
"hp" : ["High Pass Filter", "double"],
+
We must add several keys to the json file:<br/>
−
"lp" : ["Low Pass Filter", "double"],
+
<syntaxhighlight lang="java">
−
"fields_ordering" : ["hp", "lp"]
+
"parameters" : [ "eeg_file", "meg_file"],
−
}
+
"flags" : [ "use_downsampling", "vectorize_data"]
 +
  "inputs": {
 +
    "eeg_file": "any file",
 +
    "meg_file": "any file"
 +
  },
 +
  "batch_ui": {
 +
    "use_downsampling": [ "Downsampling data", "boolean" ],
 +
    "vectorize_data": [ "Vectorize data", "boolean" ],
 +
    "fields_ordering": [ "use_downsampling", "vectorize_data" ]
 +
  },
 +
  "batch_defaults": {
 +
    "use_downsampling": false,
 +
    "vectorize_data": false
 +
  }
 
</syntaxhighlight>
 
</syntaxhighlight>
−
'''input_keys''' : mandatory key. Here, we setup only one input file, and the key is called "input_file".<br/>
+
===inputs===
−
Then we must describe that key:
+
The '''inputs''' key describes the argument keys that will be set up with a file path as input for the plugin to process.<br/>
−
* "Input File" is the name used in the GUI to describe the parameter.
+
This is a special object telling AnyWave that the GUI should allow a file selection method to set up the files to be processed by the plugin using that particular keys.<br/>
−
* "check" indicates that the file MUST be a data file that AnyWave can read.
+
−
'''fields_ordering''': mandatory key. Describe the GUI fields order. Here we set up HP before LP in the GUI.<br/>
+
−
<br/>
+
−
Between the mandatory keys, you have the other parameters:<br/>
+
−
* hp described as High Pass Filter, and "double" indicates this parameter is a double value.
+
−
* lp described as Low Pass Filter, and "double" indicates this parameter is a double value.
+
  
−
Others possible parameter values:<br/>
+
===batch_ui===
 +
the '''batch_ui''' key describes how the GUI will be setup. Here we defined an alias for each argument key and a type of value.<br/>
 +
So '''batch_ui''' object must contain the argument keys and the values must be an array containing the alias in the UI and the value type.<br/>
 +
The special key '''fields_ordering''' defines the order from top to bottom, where the arguments will appear in the GUI.<br/>
  
 +
===batch_defaults===
 +
The batch_defauls key describes the default values for each arguments we want to get in our plugin.<br/>
 +
When specifying in batch_ui a value type of list, you must describe the list of possible values in batch_defaults using the same key name:<br/>
 +
=GUI/defaults=
 +
Complete list of possible value types to be used in batch_ui key (object):<br/>
 
{| class="wikitable"
 
{| class="wikitable"
 
|-
 
|-
Line 54: Line 60:
 
| "string" || string value
 
| "string" || string value
 
|-
 
|-
−
| "stringList" || an array of strings.
+
| "stringlist" || an array of strings.
 +
|-
 +
| "boolean" || a boolean value.
 
|}
 
|}
  
−
==default.json==
+
Example based on ica plugin:<br/>
−
This file comes to se the default values for parameters described in ui.json.<br/>
+
−
So you need to define the same keys and set a default value for them.<br/>
+
−
In our skeleton that will be:<br/>
+
 
<syntaxhighlight lang="java">
 
<syntaxhighlight lang="java">
 
{
 
{
−
"input_file" : "",  
+
  "parameters": [ "modality", "comp" ],
−
"hp" : 0.,
+
  "flags": [ "infomax_extended", "skip_bad", "downsampling" ],
−
"lp" : 0.
+
  "inputs": {
 +
    "input_file": "any file"
 +
  },
 +
  "batch_ui": {
 +
    "hp": [ "High Pass", "double" ],
 +
    "lp": [ "Low Pas", "double" ],
 +
    "comp": [ "Components", "int" ],
 +
    "modality": [ "Modality", "list" ],
 +
    "downsampling": [ "Downsampling data", "boolean" ],
 +
    "skip_markers": [ "Avoid markers", "stringlist" ],
 +
    "use_markers": [ "Use markers", "stringlist" ],
 +
    "infomax_extended": [ "Infomax extended mode", "boolean" ],
 +
    "skip_bad": [ "Skip bad channels", "boolean" ],
 +
    "fields_ordering": [ "comp", "hp", "lp", "modality", "skip_bad", "downsampling", "infomax_extended", "skip_markers", "use_markers" ]
 +
  },
 +
  "batch_defaults": {
 +
    "input_file" :  "File",
 +
    "hp": 0,
 +
    "lp": 0,
 +
    "comp": 50,
 +
    "modality": [ "MEG", "EEG", "SEEG", "EMG" ],
 +
    "downsampling": false,
 +
    "skip_markers": "",
 +
    "use_markers": "",
 +
    "infomax_extended": false,
 +
    "skip_bad": true
 +
  }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
−
 
+
'''Note 1''': You can use common arguments like hp, hp. The default inputs is always the key called input_file if no inputs are specified.<br/>
−
=GUI representation of ui.json=
+
That means that the default behavior for a batch processing is to have ONE input file to process held by the input_file argument key.<br/>
−
See below the GUI representation of keys inserted in the ui.json:<br/>
+
'''Note 2''': The list type will make a combobox list selection of items. Define the possible items in default.json file:<br/>
−
{| class="wikitable"
+
−
|-
+
−
! key !! GUI
+
−
|-
+
−
| "hp" : ["High Pass", "double"] || [[File:Json_ui_key_double.png]]
+
−
|-
+
−
| "n_iter" : ["#Iterations", "int"] || [[File:Json_ui_key_int.png]]
+
−
|-
+
−
| "modality" : ["Modality", "list"] || [[File:Json_ui_key_list.png]]
+
−
|-
+
−
| "output_prefix" : ["Output Prefix", "string"] || [[File:Json_ui_key_string.png]]
+
−
|}
+
−
 
+
−
'''Note''': The list type will make a combobox list selection of items. Define the possible items in default.json file:<br/>
+
 
"modality" : ["MEG", "EEG", "SEEG"]<br/>
 
"modality" : ["MEG", "EEG", "SEEG"]<br/>
−
 
−
=Example=
 
−
A small test plugin that takes TWO files as input:<br/>
 
−
* a MEG file
 
−
* an EEG file
 
−
==desc.txt==
 
−
<syntaxhighlight lang="text">
 
−
name = MAT_BATCH
 
−
description = TEST_BATCH
 
−
category = Process:TEST:MAT_BATCHING
 
−
flags = CanRunFromCommandLine:NoDataRequired
 
−
</syntaxhighlight>
 
−
==ui.json==
 
−
<syntaxhighlight lang="java">
 
−
{
 
−
"input_keys" : [ "meg_file", "eeg_file"],
 
−
"meg_file" : ["MEG File", "check"],
 
−
"eeg_file" : ["EEG File", "check"],
 
−
"output_file_prefix" : ["Output File Prefix", "string"],
 
−
"fields_ordering": [ "output_file_prefix" ]
 
−
}
 
−
</syntaxhighlight>
 
−
We set up two files as input (eeg_file, meg_file).<br/>
 
−
output_file_prefix is a string variable we will use to prefix our output filename.<br/>
 
−
There is only one '''field''' because meg_file and eeg_file are input files keys, so they won't appear in the left part of the GUI but in the input file part.<br/>
 
−
==default.json==
 
−
<syntaxhighlight lang="java">
 
−
{
 
−
"meg_file" : "",
 
−
"eeg_file" : "",
 
−
"output_file_prefix" : "resampled"
 
−
}
 
−
</syntaxhighlight>
 
−
==main.m==
 
−
<syntaxhighlight lang="matlab">
 
−
function main(varargin)
 
−
global args;
 
−
if isdeployed
 
−
% STANDALONE AnyWave Plugin code
 
−
  global host;
 
−
  global port;
 
−
  global pid;
 
−
 
−
  if (nargin < 3)
 
−
      error('missing arguments.');
 
−
  end
 
−
  host = varargin{1};
 
−
  port = str2num(varargin{2});
 
−
  pid = str2num(varargin{3});
 
−
  if (nargin > 3)
 
−
    args = varargin{4};
 
−
  end
 
−
 
 
−
  assignin('base', 'host',  host);
 
−
  assignin('base', 'port', port);
 
−
  assignin('base', 'pid', pid);
 
−
  assignin('base', 'args', args);
 
−
% end of STANDALONE AnyWave Plugin code
 
−
end
 
−
 
−
% we assume here that the code will always run in batch mode.
 
−
% To check if the plugin was called in batch mode, just check if args variable is empty or not.
 
−
if isempty(args)
 
−
  error('this plugin will only run in batch mode');
 
−
end
 
−
 
−
 
−
pathMEG = args.meg_file;
 
−
pathEEG = args.eeg_file;
 
−
infosMEG = aw_getfileinfo(pathMEG);
 
−
if isempty(infosMEG)
 
−
    error('Could not open MEG file');
 
−
end
 
−
infosEEG = aw_getfileinfo(pathEEG);
 
−
if isempty(infosEEG)
 
−
  error('Could not open EEG file');
 
−
end
 
−
 
−
cfg=[];
 
−
cfg.file = pathEEG;
 
−
markersEEG = aw_getmarkers(cfg);
 
−
cfg.file = pathMEG;
 
−
cfg.channels = { 'Trigger' };
 
−
markersMEG = aw_gettriggers(cfg);
 
−
 
−
cfg = [];
 
−
cfg.file = pathEEG;
 
−
cfg.filtering = 'yes';
 
−
cfg.start = 0;
 
−
cfg.duration = -1;
 
−
cfg.eeg_lp = infosEEG.max_sr / 3;
 
−
 
−
eegdata = aw_getdata(cfg);
 
−
assert(~isempty(eegdata));
 
−
disp(eegdata);
 
−
end
 
−
</syntaxhighlight>
 

Latest revision as of 08:57, 22 April 2020

Introduction

AnyWave can run plugin code using the command line as mentioned here: The Command Line Interface of AnyWave
That implies the user has to write his own shell scripts to accomplish that.
One alternative is to use the AnyWave built-in Batch GUI that allows to program your batch operations using a user friendly interface.
This features allows to run your batching operations within AnyWave, in the background with a monitoring of what it is done.
If we want our plugin to be processed using this feature we must make it compatible with AnyWave Batch GUI system.

Make my plugin GUI compatible

First, the plugin must be callable using the command line.
Reminder on how to do that: Make your plugin batchable

args.json

Remember, we have defined an arg.json file to describe the command line arguments we would like AnyWave to parse for us:

"parameters" : [ "eeg_file", "meg_file"],
"flags" : [ "use_downsampling", "vectorize_data"]

We must add several keys to the json file:

"parameters" : [ "eeg_file", "meg_file"],
"flags" : [ "use_downsampling", "vectorize_data"]
  "inputs": {
    "eeg_file": "any file",
    "meg_file": "any file"
  },
  "batch_ui": {
    "use_downsampling": [ "Downsampling data", "boolean" ],
    "vectorize_data": [ "Vectorize data", "boolean" ],
    "fields_ordering": [ "use_downsampling", "vectorize_data" ]
  },
  "batch_defaults": {
     "use_downsampling": false,
     "vectorize_data": false
  }

inputs

The inputs key describes the argument keys that will be set up with a file path as input for the plugin to process.
This is a special object telling AnyWave that the GUI should allow a file selection method to set up the files to be processed by the plugin using that particular keys.

batch_ui

the batch_ui key describes how the GUI will be setup. Here we defined an alias for each argument key and a type of value.
So batch_ui object must contain the argument keys and the values must be an array containing the alias in the UI and the value type.
The special key fields_ordering defines the order from top to bottom, where the arguments will appear in the GUI.

batch_defaults

The batch_defauls key describes the default values for each arguments we want to get in our plugin.
When specifying in batch_ui a value type of list, you must describe the list of possible values in batch_defaults using the same key name:

GUI/defaults

Complete list of possible value types to be used in batch_ui key (object):

value description
"double" double precision value
"int" integer value
"list" indicates we want a combo list selection among predefined item.
"string" string value
"stringlist" an array of strings.
"boolean" a boolean value.

Example based on ica plugin:

{
  "parameters": [ "modality", "comp" ],
  "flags": [ "infomax_extended", "skip_bad", "downsampling" ],
  "inputs": {
    "input_file": "any file"
  },
  "batch_ui": {
    "hp": [ "High Pass", "double" ],
    "lp": [ "Low Pas", "double" ],
    "comp": [ "Components", "int" ],
    "modality": [ "Modality", "list" ],
    "downsampling": [ "Downsampling data", "boolean" ],
    "skip_markers": [ "Avoid markers", "stringlist" ],
    "use_markers": [ "Use markers", "stringlist" ],
    "infomax_extended": [ "Infomax extended mode", "boolean" ],
    "skip_bad": [ "Skip bad channels", "boolean" ],
    "fields_ordering": [ "comp", "hp", "lp", "modality", "skip_bad", "downsampling", "infomax_extended", "skip_markers", "use_markers" ]
  },
  "batch_defaults": {
    "input_file" :  "File",
    "hp": 0,
    "lp": 0,
    "comp": 50,
    "modality": [ "MEG", "EEG", "SEEG", "EMG" ],
    "downsampling": false,
    "skip_markers": "",
    "use_markers": "",
    "infomax_extended": false,
    "skip_bad": true
  }
}

Note 1: You can use common arguments like hp, hp. The default inputs is always the key called input_file if no inputs are specified.
That means that the default behavior for a batch processing is to have ONE input file to process held by the input_file argument key.
Note 2: The list type will make a combobox list selection of items. Define the possible items in default.json file:
"modality" : ["MEG", "EEG", "SEEG"]

Retrieved from "https://meg.univ-amu.fr/index.php?title=AnyWave:MATLAB_Batch_GUI&oldid=26064"