Difference between revisions of "AnyWave:MATLAB Batch"

From WikiMEG
Jump to: navigation, search
(3. Define the arguments required by your plugin)
 
(37 intermediate revisions by one user not shown)
Line 1: Line 1:
 
=Introduction=
 
=Introduction=
One of the features of AnyWave is to run some processes in batch.<br/>
+
One of the features of AnyWave is to run some processing from the command line.<br/>
This means that you can use a dedicated GUI to program several processing on many files and execute all this processing<br/>
+
This is called batch processing, allowing to process many files in different locations using a script file run by the OS.<br/>
This feature is accessible from here:<br/>
+
=Make my plugin runnable in command line=
[[File:Process_batch_processing.png]]
+
If you want AnyWave to handle your plugin using the command line, you must do as follow:<br/>
=Make my plugin compatible=
+
== 1 - edit the desc.txt==
This is quite simple. First, you need to edit the desc.txt and add a flag:<br/>
+
 
<syntaxhighlight lang="text">
 
<syntaxhighlight lang="text">
 
name = MyPlugin
 
name = MyPlugin
Line 11: Line 10:
 
category = Process:Test:MyPlugin
 
category = Process:Test:MyPlugin
 
flags = CanRunFromCommandLine
 
flags = CanRunFromCommandLine
 +
</syntaxhighlight>
 +
Note: we've added a line with the flags keyword. This keyword will inform AnyWave of the capabilities of your plugin.<br/>
 +
You may combine flags using the : (the colon character). Example:<br/>
 +
flags = CanRunFromCommandLine:NoDataRequired<br/>
 +
This indicates that the plugin can be called from the command line but also indicates that no data file is required. (The plugin will not run on a data file.)<br/>
 +
== 2 - edit your MATLAB code ==
 +
Modify the main.m file:<br/>
 +
<syntaxhighlight lang="matlab">
 +
function main(varargin)
 +
global args;  %% IMPORTANT: this variable will hold the arguments set by the user on the command line.
 +
if isdeployed  % this is the code to use if you plan to Compile your plugin to distribute it.
 +
% STANDALONE AnyWave Plugin code
 +
  global host; 
 +
  global port;
 +
  global pid;
 +
 +
  if (nargin < 3) % basic argument checking
 +
      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
 +
 +
% code your stuff here
 +
% use args to get the arguments:
 +
% args is a structure containing fields named upon the arguments set by the command line.
 +
%
 +
% one of the common argument set by AnyWave is input_file which contains the path to the data file to process.
 +
% so to get the file use :  file = args.input_file;
 +
 +
</syntaxhighlight>
 +
== 3. Define the arguments required by your plugin==
 +
AnyWave offers a set of predefined arguments name, let's call them common arguments.<br/>
 +
See here to view all the common arguments name to use.<br/>
 +
But sometimes, you will need to use specific arguments for your plugin and you will need to let AnyWave know about them.<br/>
 +
To inform AnyWave about the argument key it will recognize from the command line and pass them to your plugin, you need to add a json file to the folder containing your plugin.<br>
 +
<br/>
 +
The file must be named '''args.json''' and must contain at least one key called '''parameters'''.<br/>
 +
An optional key named '''flags''' may also  be added. flags will be used as boolean arguments for the plugin.<br/>
 +
Example:<br/>
 +
<syntaxhighlight lang="java">
 +
{
 +
"parameters" : [ "eeg_file", "meg_file"],
 +
"flags" : [ "downsample", "use_threshold"]
 +
}
 +
</syntaxhighlight>
 +
Hence, AnyWave will be able to parse --eeg_file and --meg_file keys from the command line and pass them to your plugin (in the args global variable):<br/>
 +
AnyWave will also parse arguments --downsample <true|yes|false|no> and set the corresponding boolean value.<br/>
 +
<syntaxhighlight lang="matlab">
 +
function main(varargin)
 +
global args;  %% DO NOT FORGET
 +
% init code
 +
% ...
 +
 +
eeg = args.eeg_file;
 +
meg = args.meg_file;
 +
 +
% compute something...
 +
end
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 15:30, 21 April 2020

Introduction

One of the features of AnyWave is to run some processing from the command line.
This is called batch processing, allowing to process many files in different locations using a script file run by the OS.

Make my plugin runnable in command line

If you want AnyWave to handle your plugin using the command line, you must do as follow:

1 - edit the desc.txt

name = MyPlugin
description = do something in MATLAB
category = Process:Test:MyPlugin
flags = CanRunFromCommandLine

Note: we've added a line with the flags keyword. This keyword will inform AnyWave of the capabilities of your plugin.
You may combine flags using the : (the colon character). Example:
flags = CanRunFromCommandLine:NoDataRequired
This indicates that the plugin can be called from the command line but also indicates that no data file is required. (The plugin will not run on a data file.)

2 - edit your MATLAB code

Modify the main.m file:

function main(varargin)
global args;  %% IMPORTANT: this variable will hold the arguments set by the user on the command line. 
if isdeployed  % this is the code to use if you plan to Compile your plugin to distribute it.
% STANDALONE AnyWave Plugin code
   global host;   
   global port;
   global pid;
 
   if (nargin < 3) % basic argument checking
       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
 
% code your stuff here
% use args to get the arguments:
% args is a structure containing fields named upon the arguments set by the command line.
%
% one of the common argument set by AnyWave is input_file which contains the path to the data file to process.
% so to get the file use :  file = args.input_file;

3. Define the arguments required by your plugin

AnyWave offers a set of predefined arguments name, let's call them common arguments.
See here to view all the common arguments name to use.
But sometimes, you will need to use specific arguments for your plugin and you will need to let AnyWave know about them.
To inform AnyWave about the argument key it will recognize from the command line and pass them to your plugin, you need to add a json file to the folder containing your plugin.

The file must be named args.json and must contain at least one key called parameters.
An optional key named flags may also be added. flags will be used as boolean arguments for the plugin.
Example:

{
"parameters" : [ "eeg_file", "meg_file"],
"flags" : [ "downsample", "use_threshold"]
}

Hence, AnyWave will be able to parse --eeg_file and --meg_file keys from the command line and pass them to your plugin (in the args global variable):
AnyWave will also parse arguments --downsample <true|yes|false|no> and set the corresponding boolean value.

function main(varargin)
global args;  %% DO NOT FORGET
% init code
% ...
 
eeg = args.eeg_file;
meg = args.meg_file;
 
% compute something...
end