Fix up docs, some naming things

fooof-tools · Sep 25, 2018 · 61911d0 · 61911d0
1 parent 484ea2e
commit 61911d0
Show file tree

Hide file tree

Showing 5 changed files with 87 additions and 14 deletions.
diff --git a/matlab_wrapper/fooof.m b/matlab_wrapper/fooof.m
@@ -1,11 +1,11 @@
-% fooof() - run the fooof model on a neural power spectrum
+% fooof() - Fit the FOOOF model on a neural power spectrum.
 %
 % Usage:
-%   >> fooof_results = fooof(freqs, psd, f_range, settings);
+%   >> fooof_results = fooof(freqs, power_spectrum, f_range, settings);
 %
 % Inputs:
 %   freqs           = row vector of frequency values
-%   psd             = row vector of power values
+%   power_spectrum  = row vector of power values
 %   f_range         = fitting range (Hz)
 %   settings        = fooof model settings, in a struct, including:
 %       settings.peak_width_limts
@@ -23,20 +23,25 @@
 %       fooof_results.gaussian_params
 %       fooof_results.error
 %       fooof_results.r_squared
+%       if return_model is true, it also includes:
+%            fooof_results.freqs
+%            fooof_results.power_spectrum
+%            fooof_results.fooofed_spectrum
+%            fooof_results.bg_fit
 %
 % Notes
 %   Not all settings need to be set. Any settings that are not 
 %     provided as set to default values. To run with all defaults, 
 %     input settings as an empty struct. 
 
-function fooof_results = fooof(freqs, psd, f_range, settings, return_model)
+function fooof_results = fooof(freqs, power_spectrum, f_range, settings, return_model)
 
     % Check settings - get defaults for those not provided
     settings = fooof_check_settings(settings);
 
     % Convert inputs
     freqs = py.numpy.array(freqs);
-    psd = py.numpy.array(psd);
+    power_spectrum = py.numpy.array(power_spectrum);
     f_range = py.list(f_range);
 
     % Initialize FOOOF object
@@ -48,7 +53,7 @@
                         settings.verbose);
 
     % Run FOOOF fit
-    fm.fit(freqs, psd, f_range)
+    fm.fit(freqs, power_spectrum, f_range)
 
     % Extract outputs
     fooof_results = fm.get_results();

diff --git a/matlab_wrapper/fooof_check_settings.m b/matlab_wrapper/fooof_check_settings.m
@@ -1,4 +1,28 @@
-% Check fooof settings, provided as a struct
+% fooof_check_settings() - Check a struct of settings for the FOOOF model.
+%
+% Usage:
+%  >> settings = fooof_check_settings(settings)
+%
+% Inputs:
+%   settings        = struct, can optionally include:
+%       settings.peak_width_limts
+%       settings.max_n_peaks
+%       settings.min_peak_amplitude
+%       settings.peak_threshold
+%       settings.background_mode
+%       settings.verbose
+%
+% Returns:
+%   settings        = struct, with all settings defined:
+%       settings.peak_width_limts
+%       settings.max_n_peaks
+%       settings.min_peak_amplitude
+%       settings.peak_threshold
+%       settings.background_mode
+%       settings.verbose
+
+% Notes:
+%   This is a helper function, probably not called directly by the user. 
 %   Any settings not specified are set to default values
 
 function settings = fooof_check_settings(settings)

diff --git a/matlab_wrapper/fooof_get_model.m b/matlab_wrapper/fooof_get_model.m
@@ -1,9 +1,29 @@
+% fooof_get_model() - Return the model fit values from a FOOOF object
+%
+% Usage:
+%   >> model_fit = fooof_get_model(fm)
+%
+% Inputs:
+%   fm              = FOOOF object
+%
+% Outputs:
+%   model_fit       = model results, in  a struct, including:
+%       model_fit.freqs
+%       model_fit.power_spectrum
+%       model_fit.fooofed_spectrum
+%       model_fit.bg_fit
+%
+% Notes
+%   This function is mostly an internal function, but can be called 
+%     directly by the user if you are interacting with FOOOF objects
+%     directly. 
+
 % Get the actual fit model from a FOOOF object
-function model_out = fooof_get_model(fm)
+function model_fit = fooof_get_model(fm)
 
-    model_out = struct();
+    model_fit = struct();
 
-    model_out.freqs = double(py.array.array('d',fm.freqs));
-    model_out.power_spectrum = double(py.array.array('d', fm.power_spectrum));
-    model_out.fooofed_spectrum = double(py.array.array('d', fm.fooofed_spectrum_));
-    model_out.bg_fit = double(py.array.array('d', py.getattr(fm, '_bg_fit')));
+    model_fit.freqs = double(py.array.array('d',fm.freqs));
+    model_fit.power_spectrum = double(py.array.array('d', fm.power_spectrum));
+    model_fit.fooofed_spectrum = double(py.array.array('d', fm.fooofed_spectrum_));
+    model_fit.bg_fit = double(py.array.array('d', py.getattr(fm, '_bg_fit')));
diff --git a/matlab_wrapper/fooof_unpack_results.m b/matlab_wrapper/fooof_unpack_results.m
@@ -1,4 +1,23 @@
-% Unpack fooof_results python object into matlab struct
+% fooof_unpack_results() - Extract model fit results from FOOOFResults.
+%
+% Usage:
+%   >> results_out = fooof_unpack_results(fooof_results);
+%
+% Inputs:
+%   fooof_results   = FOOOFResults object
+% Outputs:
+%   results_out     = fooof model results, in a struct, including:
+%       results_out.background_params
+%       results_out.peak_params
+%       results_out.gaussian_params
+%       results_out.error
+%       results_out.r_squared
+%
+% Notes:
+%   This function is mostly an internal function, and doesn't need to be
+%   called directly by the user - but can be if you are interacting
+%   directly with FOOOF objects. 
+
 function results_out = fooof_unpack_results(results_in)
 
     results_out = struct();

diff --git a/matlab_wrapper/fooof_version.m b/matlab_wrapper/fooof_version.m
@@ -1,3 +1,8 @@
+% fooof_version() - Get FOOOF version information, of both Python & Wrapper.
+%
+% Usage:
+%   >> fooof_version()
+
 function fooof_version()
 
     % Get the version of the Python implementation of FOOOf being used