Back to the main page.

Bug 1656 - input variable name should be consistent with the data type

Status NEW
Reported 2012-08-16 09:53:00 +0200
Modified 2014-03-26 12:57:56 +0100
Product: FieldTrip
Component: core
Version: unspecified
Hardware: PC
Operating System: Mac OS
Importance: P3 normal
Assigned to:
URL:
Tags:
Depends on:
Blocks:
See also: http://bugzilla.fcdonders.nl/show_bug.cgi?id=2513

Robert Oostenveld - 2012-08-16 09:53:59 +0200

I noticed that sourceplot uses function [cfg] = ft_sourceplot(cfg, data) and also in its documentation % To facilitate data-handling and distributed computing with the peer-to-peer % module, this function has the following option: % 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. It makes more sense to have it use either "source", "mri", "volume" or "segment" as input variable, as those are documented as output variables for the preceding functions. It would be good to review this issue on input and output variable naming and add it to the code guidelines at http://fieldtrip.fcdonders.nl/code_guidelines I suggest something like: ===== Variable names ==== If you write a new function, please use input and output variable names that are consistent with their use in other fieldtrip code and documentation. Especially the reference documentation (i.e. "help functionname") should be consistent w.r.t. variable naming. * data * source * mri * segment * freq * timelock See ft_datatype and the ft_datatype_xxx functions for the most commonly used names.


Roemer van der Meij - 2012-08-16 11:10:47 +0200

This will be difficult to do for single/multi/topoplotER, as freq and timelock are very common inputs. Shall we skip these for the time being? We wanted to change the interface to those anyways by restructuring/slightly-redoing them. Also see http://fieldtrip.fcdonders.nl/development/restructure_and_rework_all_visualization_functions


Robert Oostenveld - 2012-08-16 11:30:01 +0200

(In reply to comment #1) There are more functions that allow multiple inputs. My suggestion is that the code should at least reflect one of them. The bug as I see it is that ft_sourceplot uses "data" as input, whereas data usually refers to the output of ft_preprocessing. The input variable source makes most sense if you ask me. Rather than the present Use as ft_sourceplot(cfg, data) where the input data can contain an anatomical MRI, functional source reconstruction results and statistical data, which all have to be interpolated on the same 3-d grid. we can document it as % Use as % ft_sourceplot(cfg, source) % where the input can contain a source reconstruction, statistical results % and/or an anatomical MRI, which all have to be interpolated on the same 3-d grid. Alternatively we can elaborate like this % Use as % ft_sourceplot(cfg, mri) % ft_sourceplot(cfg, source) % ft_sourceplot(cfg, stat) % ft_sourceplot(cfg, segment) % where ... The second style would provide a better relation to the "see also" section. This is already being used for example in % Use as % [interp] = ft_sourceinterpolate(cfg, source, anatomy) % [interp] = ft_sourceinterpolate(cfg, stat, anatomy) % where % source is the output of FT_SOURCEANALYSIS % stat is the output of FT_SOURCESTATISTICS % anatomy is the output of FT_READ_MRI or one of the FT_VOLUMExxx functions, % a cortical sheet that was read with FT_READ_HEADSHAPE, or a regular % 3D grid created with FT_PREPARE_SOURCEMODEL. % and cfg is a structure with any of the following fields Note that I do also think that it won't be possible everywhere. But going over the ref/help documentation once to clean it up as much as possible should be doable.


Robert Oostenveld - 2012-08-16 11:46:59 +0200

I used the following linux command line code for file in ft_*.m ; do awk 'BEGIN{ p=0 }; /Use as/ {p=1} ; /%$/ {p=0} ; {if (p==1) print $0 };' $file | head -10 >> out.txt; echo "" >> out.txt; echo "----------------------------------------------" >> out.txt; echo "" >> out.txt; done to try and get the relevant section from all FT main functions (see below). I suggest we discuss it and decide on the best style in the next meeting. ---------------------------------------------- % Use as % ft_analysisprotocol(cfg, data) ---------------------------------------------- % Use as % data = ft_appenddata(cfg, data1, data2, data3, ...) % where the configuration can be empty. ---------------------------------------------- % Use as % combined = ft_appendfreq(cfg, freq1, freq2, ...) ---------------------------------------------- % Use as % combined = ft_appendsource(cfg, source1, source2, ...) ---------------------------------------------- % Use as % [spike] = ft_appendspike(cfg, spike1, spike2, spike3, ...) % where the input structures come from FT_READ_SPIKE, or as % [data] = ft_appendspike(cfg, data, spike1, spike2, ...) % where the first data structure is the result of FT_PREPROCESSING % and the subsequent ones come from FT_READ_SPIKE. ---------------------------------------------- % Use as % combined = ft_appendtimelock(cfg, timelock1, timelock2, ...) ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_clip(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_ecg(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_eog(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_jump(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_muscle(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_threshold(cfg) % with the configuration options % cfg.dataset % cfg.headerfile % cfg.datafile ---------------------------------------------- % Use as % [cfg, artifact] = ft_artifact_zvalue(cfg) % or % [cfg, artifact] = ft_artifact_zvalue(cfg, data) ---------------------------------------------- ---------------------------------------------- % Use as % [dataout] = ft_channelnormalise(cfg, data) ---------------------------------------------- % Use as % [interp] = ft_channelrepair(cfg, data) ---------------------------------------------- % Use as: % channel = ft_channelselection(desired, datachannel) ---------------------------------------------- % Use as % ft_clusterplot(cfg, stat) ---------------------------------------------- % Use as % [data] = ft_combineplanar(cfg, data) % where data contains an averaged planar gradient (either ERF or TFR). ---------------------------------------------- % Use as % list = add_mex_source(list, directory, relName, includePlatform, excludePlatform, extras) % Use as % compile_mex_list(L, baseDir) ---------------------------------------------- % Use as % [comp] = ft_componentanalysis(cfg, data) ---------------------------------------------- % Use as % outdata = ft_componentclassification(cfg, comp) % where comp is the output of FT_COMPONENTANALYSIS and cfg is a % configuration structure that should contain ---------------------------------------------- % Use as % [stat] = ft_conjunctionanalysis(cfg, stat1, stat2, .., statN) ---------------------------------------------- % Use as % stat = ft_connectivityanalysis(cfg, data) % stat = ft_connectivityanalysis(cfg, timelock) % stat = ft_connectivityanalysis(cfg, freq) % stat = ft_connectivityanalysis(cfg, source) % where the first input argument is a configuration structure (see % below) and the second argument is the output of FT_PREPROCESSING, % FT_TIMELOCKANLAYSIS, FT_FREQANALYSIS, FT_MVARANALYSIS, % FT_SOURCEANALYSIS. The different connectivity % metrics are supported only for specific datatypes (see below). ---------------------------------------------- % Use as % ft_connectivityplot(cfg, data) ---------------------------------------------- % Use as % [data] = ft_connectivitysimulation(cfg) ---------------------------------------------- % Use as % cfg = ft_databrowser(cfg) % where the configuration structure contains the reference to the dataset % on your hard disk (see below), or use as % cfg = ft_databrowser(cfg, data) % where the input data is a structure as obtained from FT_PREPROCESSING or % from FT_COMPONENTANALYSIS. ---------------------------------------------- ---------------------------------------------- % Use as % [cfg] = ft_definetrial(cfg) % where the configuration structure should contain either % cfg.trialdef = structure with details of trial definition, see below % cfg.trialfun = function name, see below (default = 'ft_trialfun_general') % and also % cfg.dataset = pathname to dataset from which to read the events % % A call to FT_DEFINETRIAL results in the trial definition "trl" being % added to the output configuration structure. The trials are defined ---------------------------------------------- % Use as % [dataout] = ft_denoise_pca(cfg, data) % or % [dataout] = ft_denoise_pca(cfg, data, refdata) ---------------------------------------------- % Use as % [data] = ft_denoise_synthetic(cfg, data); ---------------------------------------------- % Use as outdata = ft_recompile(cfg, indata) where indata is <<describe % the type of data or where it comes from>> and cfg is a configuratioun % structure that should contain: ---------------------------------------------- % Use as % [source] = ft_dipolefitting(cfg, data) ---------------------------------------------- % Use as % data = ft_dipolesimulation(cfg) ---------------------------------------------- ---------------------------------------------- ---------------------------------------------- % Use as % [elec] = ft_electroderealign(cfg) ---------------------------------------------- % Use as % outdata = ft_examplefunction(cfg, indata) % where indata is <> % and cfg is a configuratioun structure that should contain ---------------------------------------------- % Use as % [freq] = ft_freqanalysis(cfg, data) ---------------------------------------------- % Use as % [freq] = ft_freqanalysis(cfg, data), with cfg.method = 'mvar' ---------------------------------------------- % Use as % [freq] = ft_freqbaseline(cfg, freq) % where the freq data comes from FT_FREQANALYSIS and the configuration % should contain % cfg.baseline = [begin end] (default = 'no') % cfg.baselinetype = 'absolute', 'relchange' or 'relative' (default = 'absolute') % cfg.parameter = field for which to apply baseline normalization, or % cell array of strings to specify multiple fields to normalize % (default = 'powspctrm') ---------------------------------------------- % Use as % [freq] = ft_freqcomparison(cfg, dataset1, dataset2); ---------------------------------------------- % Use as % [freq] = ft_freqdescriptives(cfg, freq) % [freq] = ft_freqdescriptives(cfg, freqmvar) ---------------------------------------------- % Use as % [grandavg] = ft_freqgrandaverage(cfg, freq1, freq2, freq3...) ---------------------------------------------- % Use as % freq = ft_freqinterpolate(cfg, freq) % where freq is the output of FT_FREQANALYSIS or FT_FREQDESCRIPTIVES and the % configuration may contain % cfg.method = 'nan', 'linear' (default = 'nan') % cfg.foilim = Nx2 matrix with begin and end of each interval to be % interpolated (default = [49 51; 99 101; 149 151]) ---------------------------------------------- % Use as % [data] = ft_freqsimulation(cfg) ---------------------------------------------- % Use as % [stat] = ft_freqstatistics(cfg, freq1, freq2, ...) % where the input data is the result from FT_FREQANALYSIS, FT_FREQDESCRIPTIVES % or from FT_FREQGRANDAVERAGE. ---------------------------------------------- % Use as % grad = ft_headmovement(cfg) % where the configuration should contain % cfg.dataset = string with the filename % cfg.trl = Nx3 matrix with the trial definition, see FT_DEFINETRIAL % cfg.numclusters = number of segments with constant headposition in which to split the data (default = 12) ---------------------------------------------- % Use as % [cfg] = ft_interactiverealign(cfg) ---------------------------------------------- % Use as % [lrp] = ft_lateralizedpotential(cfg, avgL, avgR) ---------------------------------------------- % Use as % ft_layoutplot(cfg, data) ---------------------------------------------- % Use as % [interp] = ft_megplanar(cfg, data) ---------------------------------------------- % Use as % [interp] = ft_megrealign(cfg, data) ---------------------------------------------- % Use as % ft_movieplotER(cfg, timelock) % where the input data is from FT_TIMELOCKANALYSIS and the configuration % can contain % cfg.parameter = string, parameter that is color coded (default = 'avg') % cfg.xlim = 'maxmin' or [xmin xmax] (default = 'maxmin') % cfg.zlim = 'maxmin', 'maxabs' or [zmin zmax] (default = 'maxmin') % cfg.samperframe = number, samples per fram (default = 1) % cfg.framespersec = number, frames per second (default = 5) % cfg.framesfile = [], no file saved, or 'string', filename of saved frames.mat (default = []); ---------------------------------------------- % Use as % ft_movieplotTFR(cfg, data) % where the input data comes from FT_FREQANALYSIS or FT_FREQDESCRIPTIVES and the % configuration is a structure that can contain % cfg.parameter = string, parameter that is color coded (default = 'avg') % cfg.xlim = selection boundaries over first dimension in data (e.g., time) % 'maxmin' or [xmin xmax] (default = 'maxmin') % cfg.ylim = selection boundaries over second dimension in data (e.g., freq) % 'maxmin' or [xmin xmax] (default = 'maxmin') % cfg.zlim = plotting limits for color dimension, 'maxmin', ---------------------------------------------- % Use as % ft_multiplotCC(cfg, data) ---------------------------------------------- % Use as % ft_multiplotER(cfg, data) % or % ft_multiplotER(cfg, data, data2, ..., dataN) ---------------------------------------------- % Use as % ft_multiplotTFR(cfg, data) ---------------------------------------------- % Use as % [mvardata] = ft_mvaranalysis(cfg, data) ---------------------------------------------- % Use as % ft_neighbourplot(cfg) % or as % ft_neighbourplot(cfg, data) ---------------------------------------------- % Use as % stat = ft_networkanalysis(cfg, data) ---------------------------------------------- % Use as % [atlas] = ft_prepare_atlas(cfg) ---------------------------------------------- % Use as % [vol] = ft_prepare_bemmodel(cfg, mri), or % [vol] = ft_prepare_bemmodel(cfg, seg), or % [vol] = ft_prepare_bemmodel(cfg, vol), or % [vol] = ft_prepare_bemmodel(cfg) ---------------------------------------------- % Use as % vol = ft_prepare_concentricspheres(cfg) ---------------------------------------------- % Use as % vol = ft_prepare_headmodel(cfg) or % vol = ft_prepare_headmodel(cfg, bnd) with the output of FT_PREPARE_MESH % vol = ft_prepare_headmodel(cfg, seg) with the output of FT_VOLUMESEGMENT % vol = ft_prepare_headmodel(cfg, elec) with the output of FT_READ_SENS % vol = ft_prepare_headmodel(cfg, vol) with the output of FT_READ_VOL % Use as % [pnt, tri] = msphere(M) % Use as % [pnt, tri] = remove_double_vertices(pnt, tri) ---------------------------------------------- % Use as % lay = ft_prepare_layout(cfg, data) ---------------------------------------------- % Use as % [grid] = ft_prepare_leadfield(cfg, data); ---------------------------------------------- % Use as % vol = ft_prepare_localspheres(cfg, seg), or % vol = ft_prepare_localspheres(cfg, mri), or % vol = ft_prepare_localspheres(cfg) ---------------------------------------------- % Use as % bnd = ft_prepare_mesh(cfg, mri) ---------------------------------------------- % Use as % bnd = ft_prepare_mesh(cfg, data) ---------------------------------------------- % Use as % neighbours = ft_prepare_neighbours(cfg, data) ---------------------------------------------- % Use as % vol = ft_prepare_singleshell(cfg, seg), or % vol = ft_prepare_singleshell(cfg, mri), or % vol = ft_prepare_singleshell(cfg) ---------------------------------------------- % Use as % grid = prepare_prepare_sourcemodel(cfg) ---------------------------------------------- % Use as % [data] = ft_preprocessing(cfg) % or % [data] = ft_preprocessing(cfg, data) ---------------------------------------------- % Use as % [info, timelock, freq, summary, headpos] = ft_qualitycheck(cfg) % where info contains the dataset properties, timelock the timelocked data, % freq the powerspectra, summary the mean descriptives, and headpos the % headpositions throughout the recording ---------------------------------------------- % Use as % [ev] = ft_recodeevent(cfg, data) % where cfg is a structure with configuration settings and data contains the % (nested) configuration that describes the original trial definition and % event structure. ---------------------------------------------- % Use as % data = ft_redefinetrial(cfg, data) % where the input data should correspond to the output of FT_PREPROCESSING and % the configuration should be specified as explained below. Note that some % options are mutually exclusive, and require two calls to this function to % avoid confucion about the order in which they are applied. ---------------------------------------------- % Use as % timelock = ft_regressconfound(cfg, timelock) % or as % freq = ft_regressconfound(cfg, freq) % or as % source = ft_regressconfound(cfg, source) ---------------------------------------------- % Use as % cfg = ft_rejectartifact(cfg) % with the cfg as obtained from FT_DEFINETRIAL, or as % data = ft_rejectartifact(cfg, data) % with the data as obtained from FT_PREPROCESSING ---------------------------------------------- % Use as % [data] = ft_rejectcomponent(cfg, comp) % or as % [data] = ft_rejectcomponent(cfg, comp, data) ---------------------------------------------- % Use as % [data] = ft_rejectvisual(cfg, data) ---------------------------------------------- % Use as % [data] = ft_resampledata(cfg, data) ---------------------------------------------- % Use as % [data] = ft_scalpcurrentdensity(cfg, data) % or % [timelock] = ft_scalpcurrentdensity(cfg, timelock) % where the input data is obtained from FT_PREPROCESSING or from % FT_TIMELOCKANALYSIS. The output data has the same format as the input % and can be used in combination with most other FieldTrip functions % such as FT_FREQNALYSIS or FT_TOPOPLOTER. ---------------------------------------------- % Use as % [sensor] = ft_sensorrealign(cfg) or % [sensor] = ft_sensorrealign(cfg, sensor) % where you specify the electrodes or gradiometers in the configuration % structure (see below) or as the second input argument. ---------------------------------------------- % Use as % ft_singleplotER(cfg, data) % or % ft_singleplotER(cfg, data1, data2, ..., datan) ---------------------------------------------- % Use as % ft_singleplotTFR(cfg,data) ---------------------------------------------- % Use as % ft_sliceinterp(cfg, interp) % or % [rgbimage] = ft_sliceinterp(cfg, interp), rgbimage is the monatage image ---------------------------------------------- % Use as either % [source] = ft_sourceanalysis(cfg, freq) % [source] = ft_sourceanalysis(cfg, timelock) ---------------------------------------------- % Use as % [source] = ft_sourcedescriptives(cfg, source) ---------------------------------------------- % Use as % [grandavg] = ft_sourcegrandaverage(cfg, source1, source2, ...) ---------------------------------------------- % Use as % [interp] = ft_sourceinterpolate(cfg, source, anatomy) % [interp] = ft_sourceinterpolate(cfg, stat, anatomy) % where % source is the output of FT_SOURCEANALYSIS % stat is the output of FT_SOURCESTATISTICS % anatomy is the output of FT_READ_MRI or one of the FT_VOLUMExxx functions, % a cortical sheet that was read with FT_READ_HEADSHAPE, or a regular % 3D grid created with FT_PREPARE_SOURCEMODEL. % and cfg is a structure with any of the following fields ---------------------------------------------- % Use as % ft_sourcemovie(cfg, source) % where the input source data is obtained from FT_SOURCEANALYSIS and cfg is % a configuratioun structure that should contain ---------------------------------------------- % Use as % ft_sourceplot(cfg, data) % where the input data can contain an anatomical MRI, functional source % reconstruction results and/or statistical data. If both anatomical and % functional/statistical data is provided as input, they should be % represented or interpolated on the same same 3-D grid, e.g. using % FT_SOURCEINTERPOLATE. ---------------------------------------------- % Use as % [stat] = ft_sourcestatistics(cfg, source1, source2, ...) % where the input data is the result from FT_SOURCEANALYSIS, FT_SOURCEDESCRIPTIVES % or FT_SOURCEGRANDAVERAGE. The source structures should be spatially alligned % to each other and should have the same positions for the source grid. ---------------------------------------------- % Use as % ft_sourcewrite(cfg, source) % where source is a source structure obtained after FT_SOURCEANALYSIS and % cfg is a configuratioun structure that should contain ---------------------------------------------- % Use as % stat = ft_timelockstatistics(cfg, data1, data2, data3, ...) % stat = ft_freqstatistics (cfg, data1, data2, data3, ...) % stat = ft_sourcestatistics (cfg, data1, data2, data3, ...) % where the data is obtained from FT_TIMELOCKANALYSIS, FT_FREQANALYSIS % or FT_SOURCEANALYSIS respectively, or from FT_TIMELOCKGRANDAVERAGE, % FT_FREQGRANDAVERAGE or FT_SOURCEGRANDAVERAGE respectively. ---------------------------------------------- % Use as % stat = ft_timelockstatistics(cfg, data1, data2, data3, ...) % stat = ft_freqstatistics (cfg, data1, data2, data3, ...) % stat = ft_sourcestatistics (cfg, data1, data2, data3, ...) ---------------------------------------------- % Use as % stat = ft_timelockstatistics(cfg, data1, data2, data3, ...) % stat = ft_freqstatistics (cfg, data1, data2, data3, ...) % stat = ft_sourcestatistics (cfg, data1, data2, data3, ...) ---------------------------------------------- % Use as % stat = ft_timelockstatistics(cfg, data1, data2, data3, ...) % stat = ft_freqstatistics (cfg, data1, data2, data3, ...) % stat = ft_sourcestatistics (cfg, data1, data2, data3, ...) ---------------------------------------------- % Use as % [output] = ft_stratify(cfg, input1, input2, ...), or % [output, binaxis] = ft_stratify(cfg, input1, input2, ...) ---------------------------------------------- ---------------------------------------------- % Use as % [timelock] = ft_timelockbaseline(cfg, timelock) % where the timelock data comes from FT_TIMELOCKANALYSIS and the % configuration should contain % cfg.baseline = [begin end] (default = 'no') % cfg.channel = cell-array, see FT_CHANNELSELECTION % cfg.parameter = field for which to apply baseline normalization, or % cell array of strings to specify multiple fields to normalize % (default = 'avg') % To facilitate data-handling and distributed computing with the peer-to-peer ---------------------------------------------- % Use as % [grandavg] = ft_timelockgrandaverage(cfg, avg1, avg2, avg3, ...) ---------------------------------------------- % Use as % [stat] = ft_timelockstatistics(cfg, timelock1, timelock2, ...) % where the input data is the result from either FT_TIMELOCKANALYSIS or % FT_TIMELOCKGRANDAVERAGE. ---------------------------------------------- % Use as % ft_topoplotCC(cfg, freq) ---------------------------------------------- % Use as % ft_topoplotER(cfg, timelock) % or % ft_topoplotER(cfg, freq) ---------------------------------------------- % Use as % ft_topoplotIC(cfg, comp) % where the input comp structure should be obtained from FT_COMPONENTANALYSIS. ---------------------------------------------- % Use as % ft_topoplotTFR(cfg, freq) ---------------------------------------------- ---------------------------------------------- % Use as % [volume] = ft_volumedownsample(cfg, mri) % where the input mri should be a single anatomical volume that was % for example read with FT_READ_MRI or should be a volumetric source % reconstruction resulting from FT_SOURCEANALYSIS or FT_SOURCEINTERPOLATE. % % The configuration can contain % cfg.downsample = integer number (default = 1, i.e. no downsampling) % cfg.smooth = 'no' or the FWHM of the gaussian kernel in voxels (default = 'no') ---------------------------------------------- ---------------------------------------------- % Use as % [mri] = ft_volumenormalise(cfg, mri) % where the input mri should be a single anatomical volume that was for % example read with FT_READ_MRI. ---------------------------------------------- % Use as % [mri] = ft_volumerealign(cfg, mri) % where the input mri should be a single anatomical or functional MRI % volume that was for example read with FT_READ_MRI. ---------------------------------------------- % Use as % mri = ft_volumereslice(cfg, mri) % where the input mri should be a single anatomical or functional MRI % volume that was for example read with FT_READ_MRI. ---------------------------------------------- % Use as % segment = ft_volumesegment(cfg, mri) % where the input mri should be a single anatomical volume that was for % example read with FT_READ_MRI. You can also provide an already segmented % volume as input for the purpose of creating a binary mask. ---------------------------------------------- % Use as % ft_volumewrite(cfg, volume) % where the input volume structure should represent an anatomical MRI % that was for example obtained from FT_READ_MRI, the source % reconstruction results from FT_SOURCEANALYSIS, the statistical % results from FT_SOURCESTATISTICS or an otherwise processed anatomical % or functional volume. ---------------------------------------------- % Use as % ft_wizard scriptname % or % ft_wizard('scriptname') </p>

Robert Oostenveld - 2012-09-19 22:27:07 +0200

*** Bug 1077 has been marked as a duplicate of this bug. ***