forked from fieldtrip/fieldtrip
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ft_artifact_muscle.m
154 lines (138 loc) · 6.82 KB
/
ft_artifact_muscle.m
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
function [cfg, artifact] = ft_artifact_muscle(cfg, data)
% FT_ARTIFACT_MUSCLE reads the data segments of interest from file and
% identifies muscle artifacts.
%
% Use as
% [cfg, artifact] = ft_artifact_muscle(cfg)
% with the configuration options
% cfg.dataset = string with the filename
% or
% cfg.headerfile = string with the filename
% cfg.datafile = string with the filename
% and optionally
% cfg.headerformat
% cfg.dataformat
%
% Alternatively you can use it as
% [cfg, artifact] = ft_artifact_muscle(cfg, data)
% where the input data is a structure as obtained from FT_PREPROCESSING.
%
% In both cases the configuration should also contain
% cfg.trl = structure that defines the data segments of interest. See FT_DEFINETRIAL
% cfg.continuous = 'yes' or 'no' whether the file contains continuous data
%
% The data is preprocessed (again) with the following configuration parameters,
% which are optimal for identifying muscle artifacts.
% cfg.artfctdef.muscle.bpfilter = 'yes'
% cfg.artfctdef.muscle.bpfreq = [110 140]
% cfg.artfctdef.muscle.bpfiltord = 8
% cfg.artfctdef.muscle.bpfilttype = 'but'
% cfg.artfctdef.muscle.hilbert = 'yes'
% cfg.artfctdef.muscle.boxcar = 0.2
%
% Artifacts are identified by means of thresholding the z-transformed value
% of the preprocessed data.
% cfg.artfctdef.muscle.channel = Nx1 cell-array with selection of channels, see FT_CHANNELSELECTION for details
% cfg.artfctdef.muscle.cutoff = z-value at which to threshold (default = 4)
% cfg.artfctdef.muscle.trlpadding = 0.1
% cfg.artfctdef.muscle.fltpadding = 0.1
% cfg.artfctdef.muscle.artpadding = 0.1
%
% The output argument "artifact" is a Nx2 matrix comparable to the
% "trl" matrix of FT_DEFINETRIAL. The first column of which specifying the
% beginsamples of an artifact period, the second column contains the
% endsamples of the artifactperiods.
%
% To facilitate data-handling and distributed computing you can use
% cfg.inputfile = ...
% If you specify this option the input data will be read from a *.mat
% file on disk. This mat files should contain only a single variable named 'data',
% corresponding to the input structure.
%
% See also FT_REJECTARTIFACT, FT_ARTIFACT_CLIP, FT_ARTIFACT_ECG, FT_ARTIFACT_EOG,
% FT_ARTIFACT_JUMP, FT_ARTIFACT_MUSCLE, FT_ARTIFACT_THRESHOLD, FT_ARTIFACT_ZVALUE
% Undocumented local options:
% cfg.method
% Copyright (C) 2003-2011, Jan-Mathijs Schoffelen & Robert Oostenveld
%
% This file is part of FieldTrip, see http://www.fieldtriptoolbox.org
% for the documentation and details.
%
% FieldTrip is free software: you can redistribute it and/or modify
% it under the terms of the GNU General Public License as published by
% the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% FieldTrip is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
% GNU General Public License for more details.
%
% You should have received a copy of the GNU General Public License
% along with FieldTrip. If not, see <http://www.gnu.org/licenses/>.
%
% $Id$
% these are used by the ft_preamble/ft_postamble function and scripts
ft_revision = '$Id$';
ft_nargin = nargin;
ft_nargout = nargout;
% do the general setup of the function
ft_defaults
ft_preamble init
% ft_preamble provenance is not needed because just a call to ft_artifact_zvalue
% ft_preamble loadvar data is not needed because ft_artifact_zvalue will do this
% the ft_abort variable is set to true or false in ft_preamble_init
if ft_abort
return
end
% check if the input cfg is valid for this function
cfg = ft_checkconfig(cfg, 'renamed', {'datatype', 'continuous'});
cfg = ft_checkconfig(cfg, 'renamedval', {'continuous', 'continuous', 'yes'});
% set default rejection parameters
cfg.artfctdef = ft_getopt(cfg, 'artfctdef', []);
cfg.artfctdef.muscle = ft_getopt(cfg.artfctdef, 'muscle', []);
cfg.artfctdef.muscle.method = ft_getopt(cfg.artfctdef.muscle, 'method', 'zvalue');
if isfield(cfg.artfctdef.muscle, 'artifact')
fprintf('muscle artifact detection has already been done, retaining artifacts\n');
artifact = cfg.artfctdef.muscle.artifact;
return
end
if ~strcmp(cfg.artfctdef.muscle.method, 'zvalue')
ft_error('muscle artifact detection only works with cfg.method=''zvalue''');
end
% for backward compatibility
cfg.artfctdef.muscle = ft_checkconfig(cfg.artfctdef.muscle, 'renamed', {'sgn', 'channel'});
cfg.artfctdef.muscle = ft_checkconfig(cfg.artfctdef.muscle, 'renamed', {'passbnd', 'bpfreq'});
cfg.artfctdef.muscle = ft_checkconfig(cfg.artfctdef.muscle, 'renamed', {'padding', 'trlpadding'});
artpadding_oldstyle = max(ft_getopt(cfg.artfctdef.muscle, 'pretim', 0), ft_getopt(cfg.artfctdef.muscle, 'psttim', 0));
% settings for preprocessing
cfg.artfctdef.muscle.bpfilter = ft_getopt(cfg.artfctdef.muscle, 'bpfilter', 'yes');
cfg.artfctdef.muscle.bpfreq = ft_getopt(cfg.artfctdef.muscle, 'bpfreq', [110 140]);
cfg.artfctdef.muscle.bpfiltord = ft_getopt(cfg.artfctdef.muscle, 'bpfiltor', 8);
cfg.artfctdef.muscle.bpfilttype = ft_getopt(cfg.artfctdef.muscle, 'bpfilttype', 'but');
cfg.artfctdef.muscle.hilbert = ft_getopt(cfg.artfctdef.muscle, 'hilbert', 'yes');
cfg.artfctdef.muscle.boxcar = ft_getopt(cfg.artfctdef.muscle, 'boxcar', 0.2);
% settings for the zvalue subfunction
cfg.artfctdef.muscle.channel = ft_getopt(cfg.artfctdef.muscle, 'channel', 'MEG');
cfg.artfctdef.muscle.trlpadding = ft_getopt(cfg.artfctdef.muscle, 'trlpadding', 0.1);
cfg.artfctdef.muscle.fltpadding = ft_getopt(cfg.artfctdef.muscle, 'fltpadding', 0.1);
cfg.artfctdef.muscle.artpadding = max(ft_getopt(cfg.artfctdef.muscle, 'artpadding', 0.1), artpadding_oldstyle);
cfg.artfctdef.muscle.cutoff = ft_getopt(cfg.artfctdef.muscle, 'cutoff', 4);
% construct a temporary configuration that can be passed onto artifact_zvalue
tmpcfg = cfg;
tmpcfg.artfctdef.zvalue = cfg.artfctdef.muscle;
tmpcfg.artfctdef = rmfield(tmpcfg.artfctdef, 'muscle');
% call the zvalue artifact detection function, where the data is either passed
% into the function by the user or read from file with cfg.inputfile
hasdata = exist('data', 'var');
if ~hasdata
tmpcfg = ft_checkconfig(tmpcfg, 'dataset2files', 'yes');
tmpcfg = ft_checkconfig(tmpcfg, 'required', {'headerfile', 'datafile'});
[tmpcfg, artifact] = ft_artifact_zvalue(tmpcfg);
else
tmpcfg.artfctdef.zvalue.trlpadding = 0;
tmpcfg.artfctdef.zvalue.fltpadding = 0;
ft_warning('trlpadding and fltpadding are set to zero to avoid filter problems with NaN, see bug3193 for details');
[tmpcfg, artifact] = ft_artifact_zvalue(tmpcfg, data);
end
cfg.artfctdef.muscle = tmpcfg.artfctdef.zvalue;