Rename min_peak_amplitude -> min_peak_height (to drop reference to amplitude)

Author: TomDonoghue

README.md

@@ -114,12 +114,12 @@ FOOOF.report() fits the model, plots the original power spectrum with the associ
 FOOOF also accepts parameters for fine-tuning the fit. For example:
 
 ```python
-fm = FOOOF(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_amplitude=0.1, peak_threshold=2.0)
+fm = FOOOF(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_height=0.1, peak_threshold=2.0)
 ```
 
 * `peak_width_limits` sets the possible lower- and upper-bounds for the fitted peak widths.
 * `max_n_peaks` sets the maximum number of peaks to fit.
-* `min_peak_amp` sets an absolute limit on the minimum amplitude (above aperiodic) for any extracted peak.
+* `min_peak_height` sets an absolute limit on the minimum amplitude (above aperiodic) for any extracted peak.
 * `peak_threshold`, also sets a threshold above which a peak amplitude must cross to be included in the model. This parameter is in terms of standard deviation above the noise of the flattened spectrum.
 
 FOOOF also has convenience methods for running the FOOOF model across matrices of multiple power spectra, as well as functionality for saving and loading results, creating reports from FOOOF outputs, and utilities to further analize FOOOF results.

fooof/core/info.py

@@ -13,7 +13,7 @@ def get_obj_desc():
                                'r_squared_', 'error_',
                                '_gaussian_params'],
                   'settings' : ['peak_width_limits', 'max_n_peaks',
-                                'min_peak_amplitude', 'peak_threshold',
+                                'min_peak_height', 'peak_threshold',
                                 'aperiodic_mode'],
                   'data' : ['power_spectrum', 'freq_range', 'freq_res'],
                   'data_info' : ['freq_range', 'freq_res'],

fooof/core/strings.py

@@ -59,7 +59,7 @@ def gen_settings_str(f_obj, description=False, concise=False):
     # Parameter descriptions to print out, if requested
     desc = {'peak_width_limits'     : 'Enforced limits for peak widths, in Hz.',
             'max_n_peaks'           : 'The maximum number of peaks that can be extracted.',
-            'min_peak_amplitude'    : 'Minimum absolute amplitude of a peak, above aperiodic component.',
+            'min_peak_height'    : 'Minimum absolute amplitude of a peak, above aperiodic component.',
             'peak_threshold'        : 'Threshold at which to stop searching for peaks.',
             'aperiodic_mode'        : 'The aproach taken to fitting the aperiodic component.'}
 
@@ -81,8 +81,8 @@ def gen_settings_str(f_obj, description=False, concise=False):
                         '{}'.format(desc['peak_width_limits']),
                         'Max Number of Peaks : {}'.format(f_obj.max_n_peaks),
                         '{}'.format(desc['max_n_peaks']),
-                        'Minimum Amplitude : {}'.format(f_obj.min_peak_amplitude),
-                        '{}'.format(desc['min_peak_amplitude']),
+                        'Minimum Amplitude : {}'.format(f_obj.min_peak_height),
+                        '{}'.format(desc['min_peak_height']),
                         'Amplitude Threshold: {}'.format(f_obj.peak_threshold),
                         '{}'.format(desc['peak_threshold']),
                         'Aperiodic Mode : {}'.format(f_obj.aperiodic_mode),

fooof/data.py

@@ -6,7 +6,7 @@
 ###################################################################################################
 
 FOOOFSettings = namedtuple('FOOOFSettings', ['peak_width_limits', 'max_n_peaks',
-                                             'min_peak_amplitude', 'peak_threshold',
+                                             'min_peak_height', 'peak_threshold',
                                              'aperiodic_mode'])
 FOOOFSettings.__doc__ = """\
 The user defined settings for a FOOOF object.
@@ -17,7 +17,7 @@
     Limits on possible peak width, as (lower_bound, upper_bound).
 max_n_peaks : int, optional, default: inf
     Maximum number of gaussians to be fit in a single spectrum.
-min_peak_amplitude : float, optional, default: 0
+min_peak_height : float, optional, default: 0
     Minimum amplitude threshold for a peak to be modeled.
 peak_threshold : float, optional, default: 2.0
     Threshold for detecting peaks, units of standard deviation.

fooof/fit.py

@@ -67,10 +67,10 @@ class FOOOF(object):
         Limits on possible peak width, as (lower_bound, upper_bound).
     max_n_peaks : int, optional, default: inf
         Maximum number of gaussians to be fit in a single spectrum.
-    min_peak_amplitude : float, optional, default: 0
-        Minimum amplitude threshold for a peak to be modeled.
+    min_peak_height : float, optional, default: 0
+        Minimum height threshold for a peak to be modeled, in units of the input data.
     peak_threshold : float, optional, default: 2.0
-        Threshold for detecting peaks, units of standard deviation.
+        Threshold for detecting peaks, in units of standard deviation of the input data.
     aperiodic_mode : {'fixed', 'knee'}
         Which approach to take for fitting the aperiodic component.
     verbose : boolean, optional, default: True
@@ -111,7 +111,7 @@ class FOOOF(object):
       get smoother power spectra, as this will give better FOOOF fits.
     """
 
-    def __init__(self, peak_width_limits=(0.5, 12.0), max_n_peaks=np.inf, min_peak_amplitude=0.0,
+    def __init__(self, peak_width_limits=(0.5, 12.0), max_n_peaks=np.inf, min_peak_height=0.0,
                  peak_threshold=2.0, aperiodic_mode='fixed', verbose=True):
         """Initialize FOOOF object with run parameters."""
 
@@ -124,7 +124,7 @@ def __init__(self, peak_width_limits=(0.5, 12.0), max_n_peaks=np.inf, min_peak_a
         # Set input parameters
         self.peak_width_limits = peak_width_limits
         self.max_n_peaks = max_n_peaks
-        self.min_peak_amplitude = min_peak_amplitude
+        self.min_peak_height = min_peak_height
         self.peak_threshold = peak_threshold
         self.aperiodic_mode = aperiodic_mode
         self.verbose = verbose
@@ -644,7 +644,7 @@ def _fit_peaks(self, flat_iter):
             guess_amp = max_amp
 
             # Halt fitting process if candidate peak drops below minimum amp size.
-            if not guess_amp > self.min_peak_amplitude:
+            if not guess_amp > self.min_peak_height:
                 break
 
             # Data-driven first guess BW

fooof/plts/fm.py

@@ -86,7 +86,7 @@ def plot_peak_iter(fm):
         plot_spectrum(fm.freqs, flatspec, linewidth=2.0, label='Flattened Spectrum', ax=ax)
         plot_spectrum(fm.freqs, [fm.peak_threshold * np.std(flatspec)]*len(fm.freqs),
                       color='orange', linestyle='dashed', label='Relative Threshold', ax=ax)
-        plot_spectrum(fm.freqs, [fm.min_peak_amplitude]*len(fm.freqs),
+        plot_spectrum(fm.freqs, [fm.min_peak_height]*len(fm.freqs),
                       color='red', linestyle='dashed', label='Absolute Threshold', ax=ax)
 
         maxi = np.argmax(flatspec)

tutorials/plot_03-FOOOFAlgorithm.py

@@ -54,7 +54,7 @@
 ###################################################################################################
 
 # Initialize a FOOOF object, with some settings
-fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6 , min_peak_amplitude=0.15)
+fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6 , min_peak_height=0.15)
 
 ###################################################################################################
 #

tutorials/plot_04-MoreFOOOF.py

@@ -75,7 +75,7 @@
 # Once a candidate peak drops below this threshold, the peak search is halted (without
 # including the most recent candidate).
 #
-# **min_peak_amplitude (units of power - same as the input spectrum)** default: 0
+# **min_peak_height (units of power - same as the input spectrum)** default: 0
 #
 # The minimum amplitude, above the aperiodic fit, that a peak must have to be extracted
 # in the initial fit stage. Once a candidate peak drops below this threshold, the peak
@@ -182,7 +182,7 @@
 ###################################################################################################
 
 # Initialize FOOOF model, with some specified settings
-fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_amplitude=0.15)
+fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_height=0.15)
 
 # Fit FOOOF
 fm.report(freqs, spectrum, freq_range)

tutorials/plot_06-FOOOFGroup.py

@@ -87,7 +87,7 @@
 ###################################################################################################
 
 # Initialize a FOOOFGroup object - it accepts all the same settings as FOOOF
-fg = FOOOFGroup(peak_width_limits=[1, 8], min_peak_amplitude=0.05, max_n_peaks=6)
+fg = FOOOFGroup(peak_width_limits=[1, 8], min_peak_height=0.05, max_n_peaks=6)
 
 ###################################################################################################
 

tutorials/plot_07-TroubleShooting.py

@@ -118,7 +118,7 @@
 # - Setting a maximum number of peaks that the algorithm may fit: `max_n_peaks`
 #
 #   - If set, the algorithm will fit (up to) the `max_n_peaks` highest power peaks.
-# - Setting a minimum absolute amplitude for peaks: `min_peak_amplitude`
+# - Setting a minimum absolute amplitude for peaks: `min_peak_height`
 #
 
 ###################################################################################################
@@ -157,7 +157,7 @@
 ###################################################################################################
 
 # Update settings to fit a more constrained FOOOF model, to reduce overfitting
-fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_amplitude=0.4)
+fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_height=0.4)
 fm.report(freqs, spectrum)
 
 ###################################################################################################
@@ -185,7 +185,7 @@
 # relative amplitude check (`min_peak_threshold`) is very liberal at keeping gaussian fits.
 #
 # If you expect, or know, you have power spectra without peaks in your data,
-# we therefore recommend making sure you set some value for `min_peak_amplitude`,
+# we therefore recommend making sure you set some value for `min_peak_height`,
 # as otherwise FOOOF is unlikely to appropriately fit power spectra as having
 # no peaks. Setting this value requires checking the scale of your power spectra,
 # allowing you to define an absolute threshold for extracting peaks.
@@ -197,7 +197,7 @@
 #
 # If you are finding that FOOOF is underfitting:
 #
-# - First check and perhaps loosen any restrictions from `max_n_peaks` and `min_peak_amplitude`
+# - First check and perhaps loosen any restrictions from `max_n_peaks` and `min_peak_height`
 # - Try updating `peak_threshold` to a lower value
 # - Bad fits may come from issues with aperiodic signal fitting
 #
@@ -219,7 +219,7 @@
 freqs, spectrum = gen_power_spectrum([1, 50], ap_params, gauss_params, nlv=nlv)
 
 # Update settings to make sure they are sensitive to smaller peaks in smoother power spectra
-fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_amplitude=0.2)
+fm = FOOOF(peak_width_limits=[1, 8], max_n_peaks=6, min_peak_height=0.2)
 fm.report(freqs, spectrum)
 
 ###################################################################################################