Difference between revisions of "AnyWave:CommandLine"

From WikiMEG
Jump to: navigation, search
(Setup parameters and run a processing plugin)
 
(21 intermediate revisions by one user not shown)
Line 1: Line 1:
This is a way to run AnyWave in non GUI mode to process files.<br/>
+
__NOTOC__
=Operations=
+
{| style="text-align: center; margin: auto;"
What can AnyWave do in a command line?<br/>
+
|+ Command Line Operations
==Convert files to BIDS==
+
|-
AnyWave is used by some third party softwares to process eeg/ieeg/meg files and convert them to BIDS format.<br/>
+
| [[File:Menu_cli_tobids.png|400px|link=AnyWave:CLi_toBIDS|'''convert a file to BIDS''']] || [[File:Menu_cli_process.png|400px|link=AnyWave:CLI_runPlugin|'''Run a plugin''']]
Here is the complete list of options to use to do so:<br/>
+
|-
'''--toBIDS''' indicates we want to convert a file to BIDS.<br />
+
|}
'''--bids_modality <ieeg|eeg|meg>''' defines the data modality.'''REQUIRED'''<br />
+
AnyWave allows the user to process data using the command line.<br/>
'''--bids_sub <subject>''' sets the BIDS subject  '''REQUIRED'''<br />
+
Passing arguments to anywave can be done using the double dash syntax:<br/>
'''--bids_task <task>''' sets the BIDS task  '''REQUIRED'''<br />
+
'''--bids_ses <session>''' sets the BIDS session (optional)<br />
+
'''--bids_run <run>''' sets the BIDS run index (optional)<br />
+
'''--bids_acq <acq>''' sets the BIDS acquisition (optional)<br />
+
'''--bids_proc <proc>''' sets the processing applied to the file. (optional)<br />
+
'''--bids_output <sidecars|all>'''  defines what output files will be generated (sidecars : only generates .json and .tsv files. all: full conversion)<br />
+
'''--bids_format <edf | vhdr>''' this implies the bids_modaliy was set to eeg or ieeg. Specifies the output file format. Default is vhdr. (optional)<br />
+
===Examples===
+
Convert a file data.eeg containing SEEG recordings to BIDS for subject JohnDoe.<br />
+
 
<syntaxhighlight lang='bash'>
 
<syntaxhighlight lang='bash'>
anywave --toBIDS --bids_modality ieeg --input_file d:\data\data.eeg --output_dir d:\data\BIDS --bids_sub johndoe --bids_task rest
+
anywave --arg1 <value> --arg2 <value> --arg3
 
</syntaxhighlight>
 
</syntaxhighlight>
Convert a MEG data file (4DNI) to BIDS for subject JohnDoe.<br />
+
An argument may have a value.<br/>
The run number must be specified. Note also that the input is the folder containing the MEG run, not a single file.<br/>
+
There is a list of common arguments that can be used anytime for every command line operation:<br/>
<syntaxhighlight lang='bash'>
+
anywave --toBIDS --bids_modality meg --input_dir d:\data\MEG\run1 --output_dir d:\data\BIDS --bids_sub johndoe --bids_task rest --bids_run 01
+
</syntaxhighlight>
+
Convert a MEG data file (Elekta) to BIDS for subject JohnDoe.<br />
+
As everything is stored in one file (.fif), no need here to specify a run number (but you can). <br/>
+
However, the input is still a folder, so specifiy the folder in which the fif file is located.<br/>
+
<syntaxhighlight lang='bash'>
+
anywave --toBIDS --bids_modality meg --input_dir d:\data\MEG --output_dir d:\data\BIDS --bids_sub johndoe --bids_task rest
+
</syntaxhighlight>
+
==Process files==
+
AnyWave can also process data files, running a specific process (plugin) to a bunch a files or directories.<br/>
+
The keyword to do that kind of opteration is :<br/>
+
'''--run <plugin name | json file | json string>'''<br/>
+
To run a plugin, the user must set all the required parameters as well as input and output options.<br/>
+
The other requirement is that the plugin CAN run in batch mode.<br/>
+
See the dedicated section to see how to make your plugin compatible or simply browse the list of compatible built-in plugins.<br/>
+
There is a list of common command line keywords that can be used anytime by every plug-ins:<br/>
+
 
'''--input_file <file>''' set the file to process.<br/>
 
'''--input_file <file>''' set the file to process.<br/>
 +
'''--input_dir <dir>''' sets the input directory to use.<br/>
 +
'''--marker_file <file>''' sets the marker file (.mrk) to use. (path must be absolute)<br/>
 +
'''--montage_file <file>''' sets the montage file (.mtg) to use. (path must be absolute)<br/>
 
'''--input_dir <dir>''' sets the input directory to use.<br/>
 
'''--input_dir <dir>''' sets the input directory to use.<br/>
 
'''--output_dir <dir>''' sets the output directory. The location where the plugin should generate its results.<br/>
 
'''--output_dir <dir>''' sets the output directory. The location where the plugin should generate its results.<br/>
Line 47: Line 24:
 
'''--lp <value>''' sets the low pass filter value to use.<br/>
 
'''--lp <value>''' sets the low pass filter value to use.<br/>
 
'''--notch <value>''' sets the notch filter value to use.<br/>
 
'''--notch <value>''' sets the notch filter value to use.<br/>
 +
'''--skip_bad_chanels <true|false|yes|no>''' default is true. Set it false to force anywave to also add bad channels to processing input.<br/>
 +
'''--create_montage <bipolar_ieeg|none>''' create a montage from data file and use it as input for processing. ''bipolar_ieeg'' means seeg alike bipolar. ''none'' will force AnyWave to ignore .mtg file that may be present along with the data file.<br/>
 +
'''--use_markers "markers"''' specify the markers to use for processing. sets --use_markers all_data to force AnyWave to use a global marker for the whole data as input.<br/>
 +
'''--skip_markers "markers"''' specify the markers to avoid while processing. Can be used with use_markers. if --use_markers all_data is set, this option is ignored.<br/>
 
<br/>
 
<br/>
===Setup parameters and run a processing plugin===
+
'''--log_dir <directory>''' set the output log directory. Every log files generated by the command line will be placed in that directory. The directory must exist.<br/>
Processing a file relies on a specific plugin which need to be setup using specific parameters.<br/>
+
'''--run <plugin name>''' start processing data using a plugin. This will required to specify plugin related options.<br/>
There are several ways to setup plugin parameters and run it:<br/>
+
1. use a json file to describe all the parameters.<br/>
+
2. use a json string to describe all the parameters.<br/>
+
3. use a plugin which declares its parameters.<br/>
+
 
<br/>
 
<br/>
'''Examples''':<br/>
+
Example:<br/>
Suppose we want to run a processing using a plugin named ''ProcessPlugin''.<br/>
+
Running h² computation on a seeg data file:<br/>
This ''ProcessPlugin'' requires two parameters, a time window in (s) and a threshold value.<br/>
+
<syntaxhighlight lang="bash">
The expected parameters are :  time_window, threshold.<br/>
+
anywave --run h2 --time_window 4 --step 1 --max_lag 0.1 --hp 1 --lp 45 --input_file d:\data\seeg\data.vhdr
If the plugin publishes its required arguments to AnyWave when loading, it's ok, you can do :<br/>
+
<syntaxhighlight lang='bash'>
+
anywave --run ProcessPlugin --input_file d:\data\my_file.eeg --time_window 4 --threshold 0.3
+
</syntaxhighlight>
+
Note the input_file common keyword that set the data file to be processed by the plugin.<br/>
+
If the command fails, you'd probably need to use the json way:<br/>
+
Create a parameters.json file as follow:<br/>
+
<syntaxhighlight lang='java'>
+
{
+
"plugin" : "ProcessPlugin",
+
"time_window" : 4,
+
"threshold" : 0.3
+
}
+
</syntaxhighlight>
+
and use the command line:<br/>
+
<syntaxhighlight lang='bash'>
+
anywave --run parameters.json --input_file d:\data\my_file.eeg
+
</syntaxhighlight>
+
This way AnyWave will reads the parameters from the json and setup the plugin accordingly.<br/>
+
Note the you can also use the common keyword inside your json file:<br/>
+
<syntaxhighlight lang='java'>
+
{
+
"plugin" : "ProcessPlugin",
+
"input_file" : "d:\\data\\my_file.eeg",
+
"time_window" : 4,
+
"threshold" : 0.3
+
}
+
Although it does not make sense there, you can do it.
+
You can also write down the json string on te command line after the --run keyword:<br/>
+
<syntaxhighlight lang='bash'>
+
anywave --run "{ """plugin""" : """ProcessPlugin""", """time_window""" : 4, """threshold""" : 0.3 }" --input_file d:\data\my_file.eeg
+
 
</syntaxhighlight>
 
</syntaxhighlight>

Latest revision as of 15:27, 15 October 2020

Command Line Operations
convert a file to BIDS Run a plugin

AnyWave allows the user to process data using the command line.
Passing arguments to anywave can be done using the double dash syntax:

anywave --arg1 <value> --arg2 <value> --arg3

An argument may have a value.
There is a list of common arguments that can be used anytime for every command line operation:
--input_file <file> set the file to process.
--input_dir <dir> sets the input directory to use.
--marker_file <file> sets the marker file (.mrk) to use. (path must be absolute)
--montage_file <file> sets the montage file (.mtg) to use. (path must be absolute)
--input_dir <dir> sets the input directory to use.
--output_dir <dir> sets the output directory. The location where the plugin should generate its results.
--output_file <file> sets the name of the processing output file.
--output_prefix <string> sets the prefix of the output file.
--hp <value> sets the high pass filter value to use.
--lp <value> sets the low pass filter value to use.
--notch <value> sets the notch filter value to use.
--skip_bad_chanels <true|false|yes|no> default is true. Set it false to force anywave to also add bad channels to processing input.
--create_montage <bipolar_ieeg|none> create a montage from data file and use it as input for processing. bipolar_ieeg means seeg alike bipolar. none will force AnyWave to ignore .mtg file that may be present along with the data file.
--use_markers "markers" specify the markers to use for processing. sets --use_markers all_data to force AnyWave to use a global marker for the whole data as input.
--skip_markers "markers" specify the markers to avoid while processing. Can be used with use_markers. if --use_markers all_data is set, this option is ignored.

--log_dir <directory> set the output log directory. Every log files generated by the command line will be placed in that directory. The directory must exist.
--run <plugin name> start processing data using a plugin. This will required to specify plugin related options.

Example:
Running h² computation on a seeg data file:

anywave --run h2 --time_window 4 --step 1 --max_lag 0.1 --hp 1 --lp 45 --input_file d:\data\seeg\data.vhdr