Latest revision as of 09:02, 22 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.
Remember the basics of command line interface:

Make my plugin runnable in command line

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

MATLAB/Python

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.)

edit 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;

C++

tototo

Make AnyWave recognize my arguments

If you have followed the steps above, your plugin can run in a batch script. However, there is no way AnyWave can guess the expected arguments key/value you would like to get in your plugin code.
Suppose we want to handle two files using eeg_file and meg_file arguments.
eeg_file will hold the path to an EEG data file and meg_file will handle the path to a MEG data file.

Run with a json file

One method to correctly parse our arguments is to define them in a json file and make AnyWave use that file:

"plugin" : "MyPlugin",
"eeg_file" : "d:\data\eeg\data.eeg",
"meg_file" : "d:\data\meg\data.meg"

Note the required plugin key that will inform AnyWave about the name of the plugin to run. In this case, our plugin called MyPlugin.
Then now run in command line:

anywave --run args.json

You can also add common argument keys defined in AnyWave like hp, lp, notch, output_dir, etc. either within the json file or directly in the command line:

anywave --run args.json --hp 1 --lp 100

Here we added two arguments for data filtering (assuming they will be handled in the plugin.).

Describe the arguments to AnyWave

One other method to make AnyWave recognize eeg_file and meg_file is to place a json file inside the folder containing our plugin files.
The file must be named args.json and must contains the following keys:

"parameters" : [ "eeg_file", "meg_file"]

An optional key may also be added to handle boolean flags:

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

Assuming our plugin will handle the boolean flags use_downsampling and vectorize_data.
Now the command line:

anywave --run MyPlugin --eeg_file d:\data\data.eeg --meg_file d:\data\data.meg --use_downsampling true

Retreive the arguments in my plugin

MATLAB

global args;  % this global structure will hold our arguments.
 
% get eeg_file path :
eeg_file = args.eeg_file;
% get meg_file path :
meg_file = args.meg_file;
% get flags (if specified)
if isfield(args, 'use_downsampling')
   downsampling = args.use_downsampling;
end

Python

TO BE DONE

C++

TO BE DONE