Difference between revisions of "AnyWave:Faq"

From WikiMEG
Jump to: navigation, search
(→‎Configure AnyWave for MATLAB compiled plugins)
 
(77 intermediate revisions by one user not shown)
Line 1: Line 1:
 
'''Frequently asked questions (FAQ)''' about '''AnyWave'''. If you don't have an answer to your question reading the Documentation, you may find useful information here.
 
'''Frequently asked questions (FAQ)''' about '''AnyWave'''. If you don't have an answer to your question reading the Documentation, you may find useful information here.
 +
=File formats=
 +
AnyWave can read and/or write to different file formats depending on the available plug-ins.<br/>
 +
==Read==
 +
{| class="wikitable"
 +
|-
 +
! Manufacturer !! modality !! file extension
 +
|-
 +
| AnyWave|| all modalities || *.ades
 +
|-
 +
| Micromed || EEG/SEEG || *.trc
 +
|-
 +
| EDF+ || EEG/SEEG || *.edf
 +
|-
 +
| BrainProducts || EEG/SEEG || *.vhdr
 +
|-
 +
| ANT EEProbe || EEG/SEEG || *.cnt
 +
|-
 +
| SPM|| all modalities || *.mat
 +
|-
 +
| EEGLAB|| all modalities || *.set
 +
|-
 +
| EGI || EEG/SEEG || *.mff
 +
|-
 +
| 4D neuroimaging|| MEG/EEG || No extension
 +
|-
 +
| Elekta|| MEG/EEG || *.fif
 +
|-
 +
| CTF|| MEG/EEG || *.ds
 +
|}
 +
==Export==
 +
AnyWave can export to the following formats:<br/>
 +
{| class="wikitable"
 +
|-
 +
! Manufacturer !! modality !! file extension
 +
|-
 +
| AnyWave|| all modalities || *.ades
 +
|-
 +
| EDF+ || EEG/SEEG || *.edf
 +
|-
 +
| BrainProducts || EEG/SEEG || *.vhdr
 +
|-
 +
| Elekta|| MEG/EEG || *.fif
 +
|-
 +
| MATLAB|| all modalities || *.mat (see documentation below)
 +
|}
  
−
=[[AnyWave:versions|What are the available versions?]]=
+
==ADES format==
−
=[[AnyWave::install|How to install AnyWave]]=
+
This is a simple file format used mostly to exchange data between different software. <br />
−
=[[AnyWave:documentation|Where to get the documentation]]=
+
Here is a complete documentation of the [[AnyWave:ADES|ADES file format]]
−
 
+
  
 +
==MATLAB format==
 +
A new plugin allows AnyWave to export data into a MATLAB file.<br />
 +
[[AnyWave:MATLAB|Here is a complete documentation about what you will find inside the MATLAB file when exporting data.]]
 
=Plug-ins=
 
=Plug-ins=
−
==What is a plug-in?==
+
The application is designed to be modular by using plug-ins.<br/>
−
'''AnyWave''' uses external modules called plug-ins, that are loaded at startup and extend the functionalities of the application.<br/>
+
Some plugins are provided with the application when installing:<br/>
−
Depending on the platform, plug-ins are files with different extensions.<br/>
+
- File read/export plugins.<br/>
−
On Windows systems plug-ins are '''.dll''' files where on Mac OS X systems the extension is '''.dylib'''. Linux version of AnyWave will use plugin with '''.so''' extension.<br/>
+
- Data Processing plugins like h²/r² correlations, Time/Frequency using wavelet, markers tools.<br/>
 +
AnyWave also supports MATLAB/Python plugins.<br/>
 +
==How to install a plug-in==
 +
The user may add custom plug-ins to AnyWave. Depending on the plug-in type (MATLAB, Python or Native) the location where to put the plug-in may vary.<br />
 +
We strongly recommend '''NOT''' to add plug-ins in the Application directory, as it may require administrative privileges and it also make the plug-ins available to all users on the computer.<br />
 
<br/>
 
<br/>
−
There are several types of plug-ins used by '''AnyWave''':<br/>
+
Place native plugins (*.dll *.so *.dylib) on the following folder depending of your platform:<br/>
−
- '''Reader''' plug-ins are responsible of reading data file formats.<br/>
+
- Windows: the folder is created in '''Documents\AnyWave\Plugins'''.<br/>
−
- '''Writer''' plug-ins are responsible of writing data to a data file format.<br/>
+
- Mac: the folder is created in '''/Users/johndoe/AnyWave/Plugins'''.<br/>
−
- '''Signal processing''' plug-ins will run some processing on data and present or not the results in '''AnyWave'''.<br/>
+
- Linux: the folder if created in '''/home/johndoe/AnyWave/Plugins'''.<br/>
−
- '''Display''' plug-ins are responsible of displaying specific data type. Typically, the results computed by signal processing plug-ins.<br/>
+
<br/>
 +
Place MATLAB plugins on the following folder depending of your platform:<br/>
 +
- Windows : the folder is created in '''Documents\AnyWave\Plugins\MATLAB'''.<br/>
 +
- Mac: the folder is created in '''/Users/johndoe/AnyWave/Plugins/MATLAB'''.<br/>
 +
- Linux: the folder if created in '''/home/johndoe/AnyWave/Plugins/MATLAB'''.<br/>
 +
<br/>
 +
Place Python plugins on the following folder depending of your platform:<br/>
 +
- Windows: the folder is created in '''Documents\AnyWave\Plugins\Python '''.<br/>
 +
- Mac: the folder is created in '''/Users/johndoe/AnyWave/Plugins/Python '''.<br/>
 +
- Linux: the folder if created in '''/home/johndoe/AnyWave/Plugins/Python '''.<br/>
 
<br/>
 
<br/>
  
−
==How to install a plug-in==
+
===Configure AnyWave for MATLAB compiled plugins===
−
When installing '''AnyWave''' some plug-ins are also installed, allowing to read file formats and allowing to do processing on data.<br/>
+
The last releases of MATLAB compiled plugins require the '''MATLAB 2018b''' runtime on Windows and '''MATLAB 2020a''' runtime on Mac.<br/>
−
Those plug-ins are located in a Plugin folder:
+
- Install the required MATLAB runtime for you platform (See the mathworks website to download and install the runtime)<br/>
−
* On Windows and Linux systems the folder is called ''Plugins'' and is located in the AnyWave folder.
+
- Configure AnyWave to use the correct version of the runtime (Mac and Linux only) :<br/>
−
* On Mac systems, the folder is called ''Anywave_Plugins'' and is installed in the '''/Applications''' folder.
+
The path on Mac should be something close to '''/Applications/MATLAB_Runtime/v98'''<br/>
 +
The path on Linux should be something close to '''/usr/local/MATLAB/MATLAB_Runtime/v95'''<br/>
 +
<br/>
 +
Set the path to the MATLAB runtime in the AnyWave preferences UI then restart AnyWave.
 +
<br/>
  
−
Adding a plug-in is done by copying the plug-in file in that folder. However, that will required administrator privileges.
+
===Configure AnyWave for MATLAB scripted plugins===
 +
MATLAB plug-ins can be distributed as MATLAB .m files and thus require that MATLAB is available on the computer.<br />
 +
AnyWave will call the MATLAB execution engine to run those files.<br />
 +
<br />
  
−
===How to install user plug-ins===
+
== Batch processing ==
−
One other way to install plug-ins is to copy them into the user's home directory.  
+
Some processes can be executed in batch mode, using the command line.<br/>
 +
See this section [[AnyWave::CLI|Command Line Options]] for more details.<br/>
 +
List of process that can be executed in batch mode:<br>
 +
* [[AnyWave:ICA|ICA (extracts independent components)]].
 +
* [[AnyWave:H2| H2 (computes connectivity)]].
  
−
Indeed, AnyWave will create a AnyWave folder in the user's home directory:
 
−
* On Windows that will be someting like: "My Documents\AnyWave" or "Documents\AnyWave".
 
−
* On Linux it can be at /home/user/AnyWave
 
−
* on Mac systems it will be located at /Users/user/AnyWave
 
  
−
This AnyWave folder will contain several other folders. The one usefull here is called Plugins.
 
  
−
Copy user plug-ins file in that directory and AnyWave will load them the next time the user launches it.
+
=Command line options=
 +
AnyWave can also be launched using the command line. This will prevent any GUI to pop up on the screen.<br/>
 +
In this mode, you will be able to batch some operations, like converting files to another format or BIDSify some file.<br/>
 +
See this section [[AnyWave::CLI|Command Line Options]]
  
−
==MATLAB plug-in==
+
=BIDS support=
−
'''AnyWave''' offers the possibility to run signal processing plug-ins written with the '''MATLAB''' programming language.<br/>
+
The BIDS support is under development, but there is a command line feature that can be used to launch AnyWave without any GUI and<br />
−
There are two ways to run MATLAB code as plug-ins:
+
ask it to convert a SEEG file into a BIDS compatible format and place it to a specified folder.<br />
−
* You may have a MATLAB Compiled code as a standalone application.
+
options:<br />
−
* You may have a MATLAB scripted plug-in which is simply MATLAB code.
+
--toBIDS indicates we want to convert a file to BIDS.<br />
 +
--bids_modality <ieeg|meg> specify what the file to convert contains (ieeg, meg).'''REQUIRED'''<br />
 +
--bids_sub <subject> BIDS subject  '''REQUIRED'''<br />
 +
--bids_task <task> BIDS task  '''REQUIRED'''<br />
 +
--bids_run <run> BIDS run index (optional)<br />
 +
--bids_acq <acq> BIDS acquisition (optional)<br />
 +
--bids_proc <proc> process (optional)<br />
 +
--bids_output <sidecars|all>  (sidecars : only generates .json and .tsv files. all: full conversion)<br />
 +
--bids_ses <session> BIDS session (optional)<br />
 +
--bids_format <edf | vhdr> (optional)<br />
 +
'''Note''':<br/>
 +
When converting MEG data, user input_folder not input_file option.<br/>
 +
Some MEG formats consists of several files in a folder, so the BIDS conversion will produce also a folder.<br/>
 +
==Example==
 +
Convert a file data.eeg containing SEEG recordings to BIDS for subject JohnDoe.<br />
 +
<syntaxhighlight lang='bash'>
 +
anywave --toBIDS --bids_modality ieeg --input_file d:\data\data.eeg --output_dir d:\data\BIDS --bids_format vhdr --bids_sub johndoe --bids_task rest
 +
</syntaxhighlight>
 +
Convert a MEG data file (4DNI) to BIDS for subject JohnDoe.<br />
 +
The run number must be specified.<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>
  
−
===MATLAB Compiled Plugin===
+
= Log files =
−
A MATLAB Compiled plugin is a standalone application that AnyWave could launch and communicate with.<br />
+
Every time an operation is launched, a log file is created by AnyWave.<br />
−
To build that application the MATLAB Compiler is required as well as a C++ Compiler.<br />
+
This is also the case for command line execution.<br />
−
Follow the instructions on the developer's corner page to see how to write a MATLAB plugin for AnyWave.<br />
+
Depending on your platform, the log files are located in the following folder:<br/>
−
 
+
- Windows: '''\Documents\AnyWave\Log'''<br/>
−
===MATLAB Scripted Plugin===
+
- Mac: '''/Users/johndoe/AnyWave/Log'''<br/>
−
If you are a mighty MATLAB programmer and thus have MATLAB installed on your computer, you may use and develop a MATLAB Scripted plugin.<br/>
+
- Linux: '''/home/johndoe/AnyWave/Log'''<br/>
−
A MATLAB Scripted plugin is a MATLAB function that will be called by AnyWave.<br/>
+
−
It is possible to use a MATLAB Scripted plugin written by someone else just by installing it in AnyWave.<br/>
+
−
 
+
−
===How to install a MATLAB Plugin===
+
−
There are two locations where AnyWave will look for MATLAB plug-ins during startup:<br />
+
−
First, AnyWave will look for plugins into the Plugins (Anywave_plugins on Mac OS X) folder. <br />
+
−
As this folder is installed along with AnyWave in the system default application path, it is not advised to add user plug-ins into that folder.<br />
+
−
The easier way to add user plug-ins is to use the User folder created by AnyWave at first launch.<br />
+
−
 
+
−
====Find the user plugins directory====
+
−
Look at the use home directory of your operating system and you should see a folder called AnyWave.<br />
+
−
Within that folder, some other folders should be present. The Plugins directory holds the different C++ plug-ins you want to add to AnyWave.<br />
+
−
For MATLAB plugins, you may have to create a subfolder named MATLAB into Plugins. Thus, on Unices system the path to MATLAB plugin should be like:<br />
+
−
''/home/user/AnyWave/Plugins/MATLAB''<br />
+
−
where on Windows the path should be:<br />
+
−
''My Documents\AnyWave\Plugins\MATLAB''
+
−
 
+
−
Copy your MATLAB plugins into the right directory and launch AnyWave.<br />
+
−
A MATLAB plugin is a directory containing several files. For more detail see the section [[AnyWave:WriteMatlabScripted|How to write a MATLAB plug-in]]
+
−
 
+
−
==Python plug-ins==
+
−
This feature is under complete re-development. Please, subscribe to the google group to keep in touch.
+
−
 
+
−
=File formats=
+
−
AnyWave can read and/or write to different file formats depending on the available plug-ins.
+
−
 
+
−
For EEG data the following formats are supported for reading:
+
−
* Neuroscan (.cnt)
+
−
* Micromed (.trc)
+
−
* Electrode Array (.eab)
+
−
* EDF/BDF (.eeg)
+
−
* Brainvision Analyser (.vhdr)
+
−
* ADES (.ades) AnyWave simple format.
+
−
 
+
−
For MEG data the following formats are supported for reading:
+
−
* 4DNI
+
−
* CTF
+
−
* ADES (.ades) AnyWave simple format.
+
−
 
+
−
It is also possible to export to the following formats:
+
−
* Brainvision Analyser (.vhdr)
+
−
* ADES (.ades) AnyWave simple format.
+
−
 
+
−
==ADES format==
+
−
This is a simple file format used mostly to exchange data between different software.
+
−
This is '''NOT''' the official AnyWave format but just a media used for exchanging between software.
+
−
 
+
−
Here is a complete documentation of the [[AnyWave:ADES|ADES file format]]
+

Latest revision as of 09:46, 7 September 2020

Frequently asked questions (FAQ) about AnyWave. If you don't have an answer to your question reading the Documentation, you may find useful information here.

File formats

AnyWave can read and/or write to different file formats depending on the available plug-ins.

Read

Manufacturer modality file extension
AnyWave all modalities *.ades
Micromed EEG/SEEG *.trc
EDF+ EEG/SEEG *.edf
BrainProducts EEG/SEEG *.vhdr
ANT EEProbe EEG/SEEG *.cnt
SPM all modalities *.mat
EEGLAB all modalities *.set
EGI EEG/SEEG *.mff
4D neuroimaging MEG/EEG No extension
Elekta MEG/EEG *.fif
CTF MEG/EEG *.ds

Export

AnyWave can export to the following formats:

Manufacturer modality file extension
AnyWave all modalities *.ades
EDF+ EEG/SEEG *.edf
BrainProducts EEG/SEEG *.vhdr
Elekta MEG/EEG *.fif
MATLAB all modalities *.mat (see documentation below)

ADES format

This is a simple file format used mostly to exchange data between different software.
Here is a complete documentation of the ADES file format

MATLAB format

A new plugin allows AnyWave to export data into a MATLAB file.
Here is a complete documentation about what you will find inside the MATLAB file when exporting data.

Plug-ins

The application is designed to be modular by using plug-ins.
Some plugins are provided with the application when installing:
- File read/export plugins.
- Data Processing plugins like h²/r² correlations, Time/Frequency using wavelet, markers tools.
AnyWave also supports MATLAB/Python plugins.

How to install a plug-in

The user may add custom plug-ins to AnyWave. Depending on the plug-in type (MATLAB, Python or Native) the location where to put the plug-in may vary.
We strongly recommend NOT to add plug-ins in the Application directory, as it may require administrative privileges and it also make the plug-ins available to all users on the computer.

Place native plugins (*.dll *.so *.dylib) on the following folder depending of your platform:
- Windows: the folder is created in Documents\AnyWave\Plugins.
- Mac: the folder is created in /Users/johndoe/AnyWave/Plugins.
- Linux: the folder if created in /home/johndoe/AnyWave/Plugins.

Place MATLAB plugins on the following folder depending of your platform:
- Windows : the folder is created in Documents\AnyWave\Plugins\MATLAB.
- Mac: the folder is created in /Users/johndoe/AnyWave/Plugins/MATLAB.
- Linux: the folder if created in /home/johndoe/AnyWave/Plugins/MATLAB.

Place Python plugins on the following folder depending of your platform:
- Windows: the folder is created in Documents\AnyWave\Plugins\Python .
- Mac: the folder is created in /Users/johndoe/AnyWave/Plugins/Python .
- Linux: the folder if created in /home/johndoe/AnyWave/Plugins/Python .

Configure AnyWave for MATLAB compiled plugins

The last releases of MATLAB compiled plugins require the MATLAB 2018b runtime on Windows and MATLAB 2020a runtime on Mac.
- Install the required MATLAB runtime for you platform (See the mathworks website to download and install the runtime)
- Configure AnyWave to use the correct version of the runtime (Mac and Linux only) :
The path on Mac should be something close to /Applications/MATLAB_Runtime/v98
The path on Linux should be something close to /usr/local/MATLAB/MATLAB_Runtime/v95

Set the path to the MATLAB runtime in the AnyWave preferences UI then restart AnyWave.

Configure AnyWave for MATLAB scripted plugins

MATLAB plug-ins can be distributed as MATLAB .m files and thus require that MATLAB is available on the computer.
AnyWave will call the MATLAB execution engine to run those files.

Batch processing

Some processes can be executed in batch mode, using the command line.
See this section Command Line Options for more details.
List of process that can be executed in batch mode:


Command line options

AnyWave can also be launched using the command line. This will prevent any GUI to pop up on the screen.
In this mode, you will be able to batch some operations, like converting files to another format or BIDSify some file.
See this section Command Line Options

BIDS support

The BIDS support is under development, but there is a command line feature that can be used to launch AnyWave without any GUI and
ask it to convert a SEEG file into a BIDS compatible format and place it to a specified folder.
options:
--toBIDS indicates we want to convert a file to BIDS.
--bids_modality <ieeg|meg> specify what the file to convert contains (ieeg, meg).REQUIRED
--bids_sub <subject> BIDS subject REQUIRED
--bids_task <task> BIDS task REQUIRED
--bids_run <run> BIDS run index (optional)
--bids_acq <acq> BIDS acquisition (optional)
--bids_proc <proc> process (optional)
--bids_output <sidecars|all> (sidecars : only generates .json and .tsv files. all: full conversion)
--bids_ses <session> BIDS session (optional)
--bids_format <edf | vhdr> (optional)
Note:
When converting MEG data, user input_folder not input_file option.
Some MEG formats consists of several files in a folder, so the BIDS conversion will produce also a folder.

Example

Convert a file data.eeg containing SEEG recordings to BIDS for subject JohnDoe.

anywave --toBIDS --bids_modality ieeg --input_file d:\data\data.eeg --output_dir d:\data\BIDS --bids_format vhdr --bids_sub johndoe --bids_task rest

Convert a MEG data file (4DNI) to BIDS for subject JohnDoe.
The run number must be specified.

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

Convert a MEG data file (Elekta) to BIDS for subject JohnDoe.
As everything is stored in one file (.fif), no need here to specify a run number (but you can).
However, the input is still a folder, so specifiy the folder in which the fif file is located.

anywave --toBIDS --bids_modality meg --input_dir d:\data\MEG --output_dir d:\data\BIDS --bids_sub johndoe --bids_task rest

Log files

Every time an operation is launched, a log file is created by AnyWave.
This is also the case for command line execution.
Depending on your platform, the log files are located in the following folder:
- Windows: \Documents\AnyWave\Log
- Mac: /Users/johndoe/AnyWave/Log
- Linux: /home/johndoe/AnyWave/Log

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