Skip to content

Commit

Permalink
put comma after e.g.
Browse files Browse the repository at this point in the history
  • Loading branch information
robertoostenveld committed Mar 1, 2024
1 parent f2a2396 commit fff8c54
Show file tree
Hide file tree
Showing 11 changed files with 18 additions and 19 deletions.
2 changes: 1 addition & 1 deletion example/common_filters_in_beamforming.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ FIXME Code for reconstruction of single trial data is incomplete
In the following, scripts for both approaches are presented.
Let's say we have data for two conditions, condition A and B, and we assume that the same sources are active in both, but to a different extent.

We have the preprocessed data for both conditions (_dataA_ and _dataB_) and we precomputed the sourcemodel and the volume conduction model (_sourcemodel_ and _headmodel_). For more information on how to do this, have a look at the [beamformer tutorial](/tutorial/beamformer) and the FieldTrip functions **[ft_prepare_leadfield](/reference/ft_prepare_leadfield)** and **[ft_prepare_headmodel](/reference/ft_prepare_headmodel)** with method='singleshell'. In order to have some data to begin with, we could use the [beamformer tutorial](/tutorial/beamformer) data, e.g. rename the _dataPre_ and _dataPost_ variables into _dataA_ and _dataB_ respectively, and use the _headmodel_ and _sourcemodel_ that have been created in that tutorial.
We have the preprocessed data for both conditions (_dataA_ and _dataB_) and we precomputed the sourcemodel and the volume conduction model (_sourcemodel_ and _headmodel_). For more information on how to do this, have a look at the [beamformer tutorial](/tutorial/beamformer) and the FieldTrip functions **[ft_prepare_leadfield](/reference/ft_prepare_leadfield)** and **[ft_prepare_headmodel](/reference/ft_prepare_headmodel)** with method='singleshell'. In order to have some data to begin with, we could use the [beamformer tutorial](/tutorial/beamformer) data, e.g., rename the _dataPre_ and _dataPost_ variables into _dataA_ and _dataB_ respectively, and use the _headmodel_ and _sourcemodel_ that have been created in that tutorial.

### PCC

Expand Down
2 changes: 1 addition & 1 deletion example/meg_eyelink.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ tags: [example, artifact, preprocessing, eyelink, eog]

## Description

This example demonstrates how you can combine detailed information from Eyelink eyetracker data with the MEG data to mark eye movement events. The Eyelink eyetracker data contains timing information about blinks, fixations and saccades, which can inform the MEG data analysis, for artifact identification/rejection purposes, or for experimental reasons. Upon data acquisition, the Eyelink can be set up (or is set up by default), to mark saccades and blinks in the output file. This identification scheme is based on certain heuristics (e.g. velocity thresholding of the eye position traces to identify saccades), and may be configured by the researcher. Under the assumption that the parameters have been judiciously specified, it may be useful to use this timing information in the downstream analysis. This could replace an ad-hoc analysis of the eyetracker data that has been recorded along with the MEG data.
This example demonstrates how you can combine detailed information from Eyelink eyetracker data with the MEG data to mark eye movement events. The Eyelink eyetracker data contains timing information about blinks, fixations and saccades, which can inform the MEG data analysis, for artifact identification/rejection purposes, or for experimental reasons. Upon data acquisition, the Eyelink can be set up (or is set up by default), to mark saccades and blinks in the output file. This identification scheme is based on certain heuristics (e.g., velocity thresholding of the eye position traces to identify saccades), and may be configured by the researcher. Under the assumption that the parameters have been judiciously specified, it may be useful to use this timing information in the downstream analysis. This could replace an ad-hoc analysis of the eyetracker data that has been recorded along with the MEG data.

### Why use information from the Eyelink and not use the eyetracker traces from the MEG data?

Expand Down
2 changes: 1 addition & 1 deletion example/reproducescript.md
Original file line number Diff line number Diff line change
Expand Up @@ -160,7 +160,7 @@ The reproducescript functionality copies the input data to a function and the ou
figure;
ft_topoplotER(cfg);

Note that the fields from the cfg input to **[ft_definetrial](/reference/ft_definetrial)** are repeated as input to **[ft_preprocessing](/reference/ft_preprocessing)** because the configuration in the original script was not emptied. There are also additional fields created by **[ft_definetrial](/reference/ft_definetrial)**. If these fields exceed a certain printed size, which would make them unwieldy to include inline in a script (e.g. `cfg.trl`, which normally consists of a [Ntrials x 3] matrix specifying the relevant sections of the data on disk), these too are saved on disk instead of being printed in the standardized script. One last thing that should stand out is the comment “a new input variable is entering the pipeline here ...”. This points to the mat-file subsequently specified in cfg.inputfile to **[ft_topoplotER](/reference/ft_topoplotER)**. The data structure in this file was not originally created by a FieldTrip function but comes from another source: in this case it consists of the data in which originates from the T to fT unit conversion step (see the original code at the top of the page). Thus, this comment puts an emphasis on the fact that a data structure with unknown provenance enters the pipeline. See the section below on [Note on using functions outside of the FieldTrip ecosystem](/example/reproducescript/#note-on-using-functions-outside-of-the-fieldtrip-ecosystem) for how to work with _reproducescript_ and non-FieldTrip code.
Note that the fields from the cfg input to **[ft_definetrial](/reference/ft_definetrial)** are repeated as input to **[ft_preprocessing](/reference/ft_preprocessing)** because the configuration in the original script was not emptied. There are also additional fields created by **[ft_definetrial](/reference/ft_definetrial)**. If these fields exceed a certain printed size, which would make them unwieldy to include inline in a script (e.g., `cfg.trl`, which normally consists of a [Ntrials x 3] matrix specifying the relevant sections of the data on disk), these too are saved on disk instead of being printed in the standardized script. One last thing that should stand out is the comment “a new input variable is entering the pipeline here ...”. This points to the mat-file subsequently specified in cfg.inputfile to **[ft_topoplotER](/reference/ft_topoplotER)**. The data structure in this file was not originally created by a FieldTrip function but comes from another source: in this case it consists of the data in which originates from the T to fT unit conversion step (see the original code at the top of the page). Thus, this comment puts an emphasis on the fact that a data structure with unknown provenance enters the pipeline. See the section below on [Note on using functions outside of the FieldTrip ecosystem](/example/reproducescript/#note-on-using-functions-outside-of-the-fieldtrip-ecosystem) for how to work with _reproducescript_ and non-FieldTrip code.

Finally, the reproduce folder contains a file named `hashes.mat`. This is a file containing MD5 hashes for bookkeeping all input and output files. It allows reproducescript to match the output files of any one step to the input files of any subsequent step. For example, the output from **[ft_preprocessing](/reference/ft_preprocessing)** is used as input to **[ft_timelockanalysis](/reference/ft_preprocessing)**, which means that the data structure only needs to be stored once and `xxx_ft_timelockanalysis_input_timelock.mat` does not have to be additionally saved to disk. If the output data from one function and the input data to the next function are slightly different, they are both saved under different file names. This happens when the researcher modified the data using custom code (as in the example when converting channel units). The `hashes.mat` file furthermore allows any researcher to check the integrity of all the intermediate and final result files of the pipeline.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ date: 2023-05-12
# Should I use t or F values for cluster-based permutation tests?

Both t and F distributions are interchangeable for a two-sample setting. In this setting, the F value is simply the t value to the power of two: ```F = t^2```.
Cluster-based permutation tests have originally been used with a t-test statistic (Maris & Oostenveld, 2007, in J. of Neurosci. Methods) but their implementation in fieldtrip allows to use any other statistic function in addition to the common [ft_statfun_depsamplesT](/reference/statfun/ft_statfun_depsamplesT) and [ft_statfun_indepsamplesT](/reference/statfun/ft_statfun_indepsamplesT), such as e.g. [ft_statfun_depsamplesFunivariate](/reference/statfun/ft_statfun_depsamplesFunivariate) and [ft_statfun_indepsamplesF](/reference/statfun/ft_statfun_indepsamplesF). Using F values instead of t values for cluster-based permutation tests looks like a good opportunity to test for interaction effects and one might think that the results are equivalent to their t-test version. This is, however, not the case as will be explained below and it will finally be recommended to use the t statistic wherever possible in order to maintain the statistical properties of the test (in terms of power).
Cluster-based permutation tests have originally been used with a t-test statistic (Maris & Oostenveld, 2007, in J. of Neurosci. Methods) but their implementation in fieldtrip allows to use any other statistic function in addition to the common [ft_statfun_depsamplesT](/reference/statfun/ft_statfun_depsamplesT) and [ft_statfun_indepsamplesT](/reference/statfun/ft_statfun_indepsamplesT), such as [ft_statfun_depsamplesFunivariate](/reference/statfun/ft_statfun_depsamplesFunivariate) and [ft_statfun_indepsamplesF](/reference/statfun/ft_statfun_indepsamplesF). Using F values instead of t values for cluster-based permutation tests looks like a good opportunity to test for interaction effects and one might think that the results are equivalent to their t-test version. This is, however, not the case as will be explained below and it will finally be recommended to use the t statistic wherever possible in order to maintain the statistical properties of the test (in terms of power).


## The decisive step in cluster-based permutation testing: computing the cluster mass
Expand Down
2 changes: 1 addition & 1 deletion faq/why_largest_peak_spectrum.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ tags: [faq, mtmfft, freq, demean]

# Why is the largest peak in the spectrum at the frequency which is 1/segment length?

If you use 'mtmfft' as a method for frequency analysis it could happen that apparently the largest peak in the spectrum is invariably at the first non-zero frequency bin. In addition, when changing the epoch length, e.g. by cutting a long data segment into 1-second snippets, rather than into 1-second segments, it seems that this peak is shifting from 0.5 to 1 Hz.
If you use 'mtmfft' as a method for frequency analysis it could happen that apparently the largest peak in the spectrum is invariably at the first non-zero frequency bin. In addition, when changing the epoch length, e.g., by cutting a long data segment into 1-second snippets, rather than into 1-second segments, it seems that this peak is shifting from 0.5 to 1 Hz.

This phenomenon is caused by the discrete nature of the spectral transformation, and by one of the default algorithmic details of the spectral decomposition in FieldTrip. Specifically, FieldTrip removes the DC-component (signal mean) by default, prior to spectral transformation. This brings down the 0 Hz component to have a power of ~0. Next, if there's a 1/f power profile in the underlying data, the first non-zero frequency bin will show the highest power in the spectrum of the DC-corrected signal. The location of this first non-zero bin depends on the spectral resolution, which is determined by the segments' length.

Expand Down
15 changes: 7 additions & 8 deletions getting_started/mne.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,17 @@ MNE-python is an interactive python toolbox for processing EEG, MEG and other el

## How does FieldTrip use MNE-python?

FieldTrip relies on the m-files in fieldtrip/external/mne, which are copied over from the MNE-matlab toolbox, which is a companion repository to the MNE-python code on [github](https://github.com/mne-tools). FieldTrip data structures can be exported to fif-files, using the **[fieldtrip2fiff](/reference/fieldtrip2fiff)** function. Besides writing the time series into a fif-file, this function makes an attempt to also write some of the metadata in a format the MNE-python can work with.
FieldTrip relies on the m-files in fieldtrip/external/mne, which are copied over from the MNE-matlab toolbox, which is a companion repository to the MNE-python code on [github](https://github.com/mne-tools). FieldTrip data structures can be exported to fif-files, using the **[fieldtrip2fiff](/reference/fieldtrip2fiff)** function. Besides writing the time series into a fif-file, this function makes an attempt to also write some of the metadata in a format the MNE-python can work with.

## How does MNE-python use FieldTrip?

MNE-python has functionality to extract channel time series from FieldTrip structures, by operating on matfiles that contain a supported data structure, **[Raw](https://mne.tools/stable/generated/mne.read_raw_fieldtrip.html)** data containing a single trial, **[Epoched](https://mne.tools/stable/generated/mne.read_epochs_fieldtrip.html)** data containing multiple trials, or **[Evoked](https://mne.tools/stable/generated/mne.read_evoked_fieldtrip.html)** data. This functionality does not allow for the extraction of the relevant metadata from the FieldTrip structures, such as channel position information or events. In many occasions, using this route to import data from FieldTrip, access to the original dataset's header information would be needed (or some metadata needs to be creatively hand-crafted).
MNE-python has functionality to extract channel time series from FieldTrip structures, by operating on matfiles that contain a supported data structure, **[Raw](https://mne.tools/stable/generated/mne.read_raw_fieldtrip.html)** data containing a single trial, **[Epoched](https://mne.tools/stable/generated/mne.read_epochs_fieldtrip.html)** data containing multiple trials, or **[Evoked](https://mne.tools/stable/generated/mne.read_evoked_fieldtrip.html)** data. This functionality does not allow for the extraction of the relevant metadata from the FieldTrip structures, such as channel position information or events. In many occasions, using this route to import data from FieldTrip, access to the original dataset's header information would be needed (or some metadata needs to be creatively hand-crafted).

## Complementary use of both toolboxes

Both toolboxes share a lot of functionality with respect to time series processing and forward/inverse modelling. FieldTrip's historical perspective is based on CTF MEG data, advanced spectral analysis and beamformers for source reconstruction. MNE-python's historical perspective is based in Elekta/neuromag MEG data, evoked-field analysis, and minimum norm estimation for source reconstruction. These days, however, both toolboxes have moved ahead substantially.
Both toolboxes share a lot of functionality with respect to time series processing and forward/inverse modelling. FieldTrip's historical perspective is based on CTF MEG data, advanced spectral analysis and beamformers for source reconstruction. MNE-python's historical perspective is based in Elekta/neuromag MEG data, evoked-field analysis, and minimum norm estimation for source reconstruction. These days, however, both toolboxes have moved ahead substantially.

## Practical issues
## Practical issues

FieldTrip and MNE-Python have conceptually similar but not identical processing pipelines and data representations. A common pipeline in FieldTrip is to create trials by reading the data directly from disk (in order to have a **[ft_datatype_raw](/reference/utilities/ft_datatype_raw)**) and then use this preprocessed data to create ERP (**[ft_datatype_timelock](/reference/utilities/ft_datatype_timelock)**). In MNE-Python, the whole continuous recording is imported (with the **[Raw](https://mne.tools/stable/generated/mne.read_raw_fieldtrip.html)** class), then trials are extracted with the **[Epoched](https://mne.tools/stable/generated/mne.read_epochs_fieldtrip.html)** class and finally trials are averaged into the **[Evoked](https://mne.tools/stable/generated/mne.read_evoked_fieldtrip.html)** class. The below table shows the correspondence between datatypes in the two packages

Expand All @@ -35,9 +35,9 @@ In order to import data from MNE-python into FieldTrip, it is most straightforwa

Below are some practical examples that demonstrate how to export FieldTrip data to a fif-file. For this we use the example data of [dataset 10](/faq/datasets#meg-tactile_dipole_fitting). If you want to try this out yourself, please download [SubjectBraille.zip](https://download.fieldtriptoolbox.org/tutorial/SubjectBraille.zip) and extract the `.ds` folder in a convenient location.

### example: export raw - single trial - data structure
### example: export raw - single trial - data structure

As a first example, we read the data as a continuous chunk. Note that the example dataset used has actually been acquired in 'trial'-mode, which means that it consists of discontinuous segments of data.
As a first example, we read the data as a continuous chunk. Note that the example dataset used has actually been acquired in 'trial'-mode, which means that it consists of discontinuous segments of data.

datadir = <path-to-data>;
dataset = fullfile(datadir, 'SubjectBraille.ds');
Expand All @@ -58,7 +58,7 @@ We can now export the data to a fiff file, pretending as if it's raw data. Note
fieldtrip2fiff(fiff_file, data, 'headshape', hs);
save(fullfile(datadir, 'ctf-raw.mat'), 'data'); % for comparison

Including the headshape information as an extra input argument will result in the fif-file to also contain the information about the location of the HPI-coils. This might be relevant for a smooth experience in MNE-python, e.g. if one wishes to apply tSSS to the data.
Including the headshape information as an extra input argument will result in the fif-file to also contain the information about the location of the HPI-coils. This might be relevant for a smooth experience in MNE-python, e.g., if one wishes to apply tSSS to the data.

Also, **[fieldtrip2fiff](/reference/fieldtrip2fiff)** will attempt to create an event file (provided the data object has an event structure buried somewhere in the processing history, called `'ctf_raw-eve.fif'`. The events will be represented as numbers, in a Nx3 matrix, where the first column contains the sample index of the event, and the third column contains the value. As of April 2023, also an interpretative comment will be saved in the event file, that allows to map the numbered events in the event file back onto the FieldTrip-style event representation.

Expand Down Expand Up @@ -91,4 +91,3 @@ Timelocked data can be exported to an **Evoked** object representation:
fieldtrip2fiff(fiff_file, avg);
save(fullfile(datadir, 'ctf-ave.mat'), 'avg');


2 changes: 1 addition & 1 deletion template/layout.md
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,7 @@ Furthermore, this section from the **[ft_prepare_layout](/reference/ft_prepare_l
%
% For an ECoG grid the option cfg.layout='ordered' is useful to represent the
% channels in a grid array. In this case you can also specify the number of rows
% and/or columns and hwo the channels increment over the grid (e.g. first
% and/or columns and hwo the channels increment over the grid (e.g., first
% left-to-right, then top-to-bottom). You can check the channel order of your grid
% using FT_PLOT_LAYOUT.
% cfg.rows = number of rows (default is automatic)
Expand Down
Loading

0 comments on commit fff8c54

Please sign in to comment.