DOC: Updates & clean ups

TomDonoghue · TomDonoghue · commit ec5f59d2f4ab · 2019-04-06T20:29:32.000-07:00
diff --git a/fooof_mat/fooof.m b/fooof_mat/fooof.m
@@ -1,7 +1,7 @@
 % fooof() - Fit the FOOOF model on a neural power spectrum.
 %
 % Usage:
-%   >> fooof_results = fooof(freqs, power_spectrum, f_range, settings);
+%   >> fooof_results = fooof(freqs, power_spectrum, f_range, settings, return_model);
 %
 % Inputs:
 %   freqs           = row vector of frequency values
@@ -14,7 +14,7 @@
 %       settings.peak_threshold
 %       settings.background_mode
 %       settings.verbose
-%   return_model    = boolean of whether to return actual model, optional 
+%   return_model    = boolean of whether to return the FOOOF model fit, optional
 %
 % Outputs:
 %   fooof_results   = fooof model ouputs, in a struct, including:
@@ -30,9 +30,9 @@
 %            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. 
+%   Not all settings need to be defined by the user.
+%     Any settings that are not provided are set to default values.
+%     To run with all defaults, input settings as an empty struct.
 
 function fooof_results = fooof(freqs, power_spectrum, f_range, settings, return_model)
 
@@ -43,32 +43,32 @@
     freqs = py.numpy.array(freqs);
     power_spectrum = py.numpy.array(power_spectrum);
     f_range = py.list(f_range);
-    
+
     % Initialize FOOOF object
     fm = py.fooof.FOOOF(settings.peak_width_limits, ...
                         settings.max_n_peaks, ...
                         settings.min_peak_amplitude, ...
                         settings.peak_threshold, ...
                         settings.background_mode, ...
                         settings.verbose);
-    
+
     % Run FOOOF fit
     fm.fit(freqs, power_spectrum, f_range)
 
     % Extract outputs
     fooof_results = fm.get_results();
     fooof_results = fooof_unpack_results(fooof_results);
-    
+
     % Also return the actual model fit, if requested
     %   This will default to not return model, if variable not set
     if exist('return_model', 'var') && return_model
-        
-        % Get the model, and add outputs to foof_results
+
+        % Get the model, and add outputs to fooof_results
         model_out = fooof_get_model(fm);
         for field = fieldnames(model_out)'
             fooof_results.(field{1}) = model_out.(field{1});
         end
-        
+
     end
-    
+
 end
diff --git a/fooof_mat/fooof_check_settings.m b/fooof_mat/fooof_check_settings.m
@@ -12,17 +12,17 @@
 %       settings.background_mode
 %       settings.verbose
 %
-% Returns:
+% Outputs:
 %   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. 
+%   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)
@@ -35,8 +35,8 @@
         'peak_threshold', 2.0, ...
         'background_mode', 'fixed', ...
         'verbose', true);
-    
-    % Overwrite any non-existent of nan settings with defaults
+
+    % Overwrite any non-existent or nan settings with defaults
     for field = fieldnames(defaults)'
         if ~isfield(settings, field) || all(isnan(settings.(field{1})))
             settings.(field{1}) = defaults.(field{1});
diff --git a/fooof_mat/fooof_get_model.m b/fooof_mat/fooof_get_model.m
@@ -14,15 +14,13 @@
 %       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. 
+%   This function is mostly an internal function.
+%     It 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_fit = fooof_get_model(fm)
 
     model_fit = struct();
-    
+
     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_));
diff --git a/fooof_mat/fooof_plot.m b/fooof_mat/fooof_plot.m
@@ -13,47 +13,49 @@
 function fooof_plot(fooof_results, log_freqs)
 
     %% Data Checking
+
     if ~isfield(fooof_results, 'freqs')
        error('FOOOF results struct does not contain model output.')
     end
 
     %% Set Up
+
     if exist('log_freqs', 'var') && log_freqs
         plt_freqs = log10(fooof_results.freqs);
     else
         plt_freqs = fooof_results.freqs;
     end
-    
+
     % Plot settings
     lw = 2.5;
-    
-    %% Create the Plots
-    
+
+    %% Create the plots
+
     figure()
     hold on
+
     % Plot the original data
     data = plot(plt_freqs, fooof_results.power_spectrum, 'black');
-    
+
     % Plot the full model fit
     model = plot(plt_freqs, fooof_results.fooofed_spectrum, 'red');
 
-    
     % Plot the background fit
     bg_fit = plot(plt_freqs, fooof_results.bg_fit, 'b--');
-    
-    %% Plot Settings
-    
+
+    %% Plot settings
+
     % Apply general plot settings
     for plt = [data, model, bg_fit]
         set(plt, 'LineWidth', lw);
-        
+
     % Set alpha value for model - in a wonky way, because Matlab
-    %   Note: the '4' is magical and mysterious. No idea. 
+    %   Note: the '4' is magical and mysterious. No idea.
     model.Color(4) = 0.5;
-    
+
     grid on
     legend('Original Spectrum', 'Full Model Fit', 'Aperiodic Fit')
-    
+
     hold off
 
 end
diff --git a/fooof_mat/fooof_unpack_results.m b/fooof_mat/fooof_unpack_results.m
@@ -1,10 +1,11 @@
 % fooof_unpack_results() - Extract model fit results from FOOOFResults.
 %
 % Usage:
-%   >> results_out = fooof_unpack_results(fooof_results);
+%   >> results_out = fooof_unpack_results(results_in);
 %
 % Inputs:
 %   fooof_results   = FOOOFResults object
+%
 % Outputs:
 %   results_out     = fooof model results, in a struct, including:
 %       results_out.background_params
@@ -13,34 +14,34 @@
 %       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. 
+% Notes
+%   This function is mostly an internal function.
+%     It can be called directly by the user if you are interacting with FOOOF objects directly.
 
 function results_out = fooof_unpack_results(results_in)
 
     results_out = struct();
 
     results_out.background_params = ...
         double(py.array.array('d', results_in.background_params));
-    
+
     temp = double(py.array.array('d', results_in.peak_params.ravel));
     results_out.peak_params = ...
         transpose(reshape(temp, 3, length(temp) / 3));
-    
+
     temp = double(py.array.array('d', results_in.gaussian_params.ravel));
     results_out.gaussian_params = ...
         transpose(reshape(temp, 3, length(temp) / 3));
-    
+
     results_out.error = ...
         double(py.array.array('d', py.numpy.nditer(results_in.error)));
-    
-    % Note: r_squared seems to come out as float
-    %   It's not clear why this value is different, but doesn't seem
-    %   to require the type casting like other (code commented below)
+
     results_out.r_squared = results_in.r_squared;
+
+    % Note: r_squared seems to come out as float, and does not need type casting
+    %   It is not clear why this value is different
+    %   Just in case, the code for type casting is commented out below:
     %results_out.r_squared = ...
     %    double(py.array.array('d', py.numpy.nditer(results_in.r_squared)));
-    
+
 end
diff --git a/fooof_mat/fooof_version.m b/fooof_mat/fooof_version.m
@@ -1,19 +1,23 @@
-% fooof_version() - Get FOOOF version information, of both Python & Wrapper.
+% fooof_version() - Get FOOOF version information.
 %
 % Usage:
 %   >> fooof_version()
+%
+% Notes
+%   This function returns versions of both the installed FOOOF in Python, and of this Matlab wrapper.
+%     The version number of the Matlab FOOOF wrapper is defined in this function.
 
 function fooof_version()
 
     % Get the version of the Python implementation of FOOOf being used
     fooof_py_version = string(py.pkg_resources.get_distribution('fooof').version);
 
     % Set the version number of the matlab wrapper
-    %   Note: this is where version is defined for this wrapper 
+    %   Note: this is where version is defined for this wrapper
     fooof_wrapper_version = "0.1.0";
 
     % Display versions
     disp('Current version of FOOOF:     ' + fooof_py_version)
     disp('Current version of Wrapper:   ' + fooof_wrapper_version)
-    
+
 end
