Merge pull request #133 from fooof-tools/amp

Update reference to 'amp' & 'amplitude' -> 'height' or 'power'

Author: TomDonoghue

README.md

@@ -17,7 +17,7 @@ FOOOF conceives of a model of the power spectrum as a combination of two distinc
 
 This model driven approach can be used to measure periodic and aperiodic properties of electrophysiological data, including EEG, MEG, ECoG and LFP data.
 
-The benefit of using FOOOF for measuring putative oscillations, is that peaks in the power spectrum are characterized in terms of their specific center frequency, amplitude and bandwidth without requiring predefining specific bands of interest and controlling for the aperiodic component. FOOOF also gives you a measure of this aperiodic components of the signal, allowing for measuring and comparison of 1/f like components of the signal within and between subjects.
+The benefit of using FOOOF for measuring putative oscillations, is that peaks in the power spectrum are characterized in terms of their specific center frequency, power and bandwidth without requiring predefining specific bands of interest and controlling for the aperiodic component. FOOOF also gives you a measure of this aperiodic components of the signal, allowing for measuring and comparison of 1/f like components of the signal within and between subjects.
 
 ## Documentation
 
@@ -114,13 +114,13 @@ 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.
-* `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.
+* `min_peak_height` sets an absolute limit on the minimum height (above aperiodic) for any extracted peak.
+* `peak_threshold`, also sets a threshold above which a peak height 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.
 

doc/api.rst

@@ -52,7 +52,7 @@ Analysis Functions
 
     get_band_peak
     get_band_peak_group
-    get_highest_amp_peak
+    get_highest_peak
 
 Synth Code
 ----------

doc/faq.rst

@@ -129,7 +129,7 @@ symmetric function (gaussians) to what can be an asymetric peak power spectrum.
 
 Because of this, it is often useful to focus on the dominant (highest power) peak within a
 given frequency band from a FOOOF analysis, as this peak will offer the best estimate of
-the putative oscillations center frequency and amplitude. If analyzing bandwidth of extracted peaks,
+the putative oscillations center frequency and power. If analyzing bandwidth of extracted peaks,
 than overlapping peaks should always be considered. FOOOF is not currently optimized for inferring
 whether multiple peaks within a frequency band likely reflect distinct oscillations or not.
 

examples/plot_synthetic_power_spectra.py

@@ -57,7 +57,7 @@
 # the example below, this is interpreted as [offset, knee, exponent] for a 'knee' spectrum.
 #
 # Power spectra can also be simulated with any number of peaks. Peaks can be listed in a flat
-# list with [center frequency, amplitude, bandwidth] listed for as many peaks as you would
+# list with [center frequency, height, bandwidth] listed for as many peaks as you would
 # like to add, or as a list of lists containing the same information.
 #
 # The following example shows simulating a different power spectrum with some different

fooof/analysis.py

@@ -65,7 +65,7 @@ def get_band_peaks_group(peak_params, band, n_fits):
     Returns
     -------
     band_peaks : 2d array
-        Peak data. Each row is a peak, as [CF, Amp, BW].
+        Peak data. Each row is a peak, as [CF, PW, BW].
 
     Notes
     -----
@@ -104,12 +104,12 @@ def get_band_peak(peak_params, band, ret_one=True):
         Defines the band of interest, as (lower_frequency_bound, upper_frequency_bound).
     ret_one : bool, optional, default: True
         Whether to return single peak (if True) or all peaks within the range found (if False).
-        If True, returns the highest power peak within the search range.
+        If True, returns the highest peak within the search range.
 
     Returns
     -------
     band_peaks : 1d or 2d array
-        Peak data. Each row is a peak, as [CF, Amp, BW]
+        Peak data. Each row is a peak, as [CF, PW, BW]
     """
 
     # Return nan array if empty input
@@ -127,17 +127,17 @@ def get_band_peak(peak_params, band, ret_one=True):
 
     band_peaks = peak_params[peak_inds, :]
 
-    # If results > 1 and ret_one, then we return the highest power peak
+    # If results > 1 and ret_one, then we return the highest peak
     #    Call a sub-function to select highest power peak in band
     if n_peaks > 1 and ret_one:
-        band_peaks = get_highest_amp_peak(band_peaks)
+        band_peaks = get_highest_peak(band_peaks)
 
     # If results == 1, return single peak
     return np.squeeze(band_peaks)
 
 
-def get_highest_amp_peak(band_peaks):
-    """Searches for the highest amplitude peak.
+def get_highest_peak(band_peaks):
+    """Searches for the highest peak.
 
     Parameters
     ----------
@@ -147,7 +147,7 @@ def get_highest_amp_peak(band_peaks):
     Returns
     -------
     1d array
-        Seleced peak data. Row is a peak, as [CF, Amp, BW].
+        Peak data. Each row is a peak, as [CF, PW, BW].
     """
 
     # Catch & return NaN if empty

fooof/core/funcs.py

@@ -32,9 +32,9 @@ def gaussian_function(xs, *params):
 
     for ii in range(0, len(params), 3):
 
-        ctr, amp, wid = params[ii:ii+3]
+        ctr, hgt, wid = params[ii:ii+3]
 
-        ys = ys + amp * np.exp(-(xs-ctr)**2 / (2*wid**2))
+        ys = ys + hgt * np.exp(-(xs-ctr)**2 / (2*wid**2))
 
     return ys
 

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'],
@@ -40,12 +40,12 @@ def get_data_indices(aperiodic_mode):
     """
 
     indices = {
-        'CF'  : 0,
-        'Amp' : 1,
-        'BW'  : 2,
+        'CF' : 0,
+        'PW' : 1,
+        'BW' : 2,
         'offset' : 0,
-        'knee'      : 1 if aperiodic_mode == 'knee' else None,
-        'exponent'  : 1 if aperiodic_mode == 'fixed' else 2
+        'knee' : 1 if aperiodic_mode == 'knee' else None,
+        'exponent' : 1 if aperiodic_mode == 'fixed' else 2
     }
 
     return indices

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 height of a peak, above the aperiodic component.',
             'peak_threshold'        : 'Threshold at which to stop searching for peaks.',
             'aperiodic_mode'        : 'The aproach taken to fitting the aperiodic component.'}
 
@@ -81,9 +81,9 @@ 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']),
-                        'Amplitude Threshold: {}'.format(f_obj.peak_threshold),
+                        'Minimum Peak Height : {}'.format(f_obj.min_peak_height),
+                        '{}'.format(desc['min_peak_height']),
+                        'Peak Threshold: {}'.format(f_obj.peak_threshold),
                         '{}'.format(desc['peak_threshold']),
                         'Aperiodic Mode : {}'.format(f_obj.aperiodic_mode),
                         '{}'.format(desc['aperiodic_mode'])] if el != ''],
@@ -143,7 +143,7 @@ def gen_results_str_fm(fm, concise=False):
         # Peak parameters
         '{} peaks were found:'.format(
             len(fm.peak_params_)),
-        *['CF: {:6.2f}, Amp: {:6.3f}, BW: {:5.2f}'.format(op[0], op[1], op[2]) \
+        *['CF: {:6.2f}, PW: {:6.3f}, BW: {:5.2f}'.format(op[0], op[1], op[2]) \
           for op in fm.peak_params_],
         '',
 

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,10 +17,10 @@
     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
+    Absolute threshold for detecting peaks, in units of the input data.
 peak_threshold : float, optional, default: 2.0
-    Threshold for detecting peaks, units of standard deviation.
+    Relative 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.
 """
@@ -51,13 +51,14 @@
     Parameters that define the aperiodic fit. As [Offset, (Knee), Exponent].
     The knee parameter is only included if aperiodic is fit with knee.
 peak_params : 2d array
-    Fitted parameter values for the peaks. Each row is a peak, as [CF, Amp, BW].
+    Fitted parameter values for the peaks. Each row is a peak, as [CF, PW, BW].
 r_squared : float
     R-squared of the fit between the input power spectrum and the full model fit.
 error : float
     Root mean squared error of the full model fit.
 gaussian_params : 2d array
-    Parameters that define the gaussian fit(s). Each row is a gaussian, as [mean, amp, std].
+    Parameters that define the gaussian fit(s).
+    Each row is a gaussian, as [mean, height, standard deviation].
 """
 
 
@@ -70,9 +71,10 @@
 ----------
 aperiodic_params : list, len 2 or 3
     Parameters that define the aperiodic fit. As [Offset, (Knee), Exponent].
-        The knee parameter is only included if aperiodic is fit with knee. Otherwise, length is 2.
+    The knee parameter is only included if aperiodic is fit with knee. Otherwise, length is 2.
 gaussian_params : list or list of lists
-    Fitted parameter values for the peaks. Each list is a peak, as [CF, Amp, BW].
+    Fitted parameter values for the peaks.
+    Each list is a peak, with a gaussian definition of [mean, height, standard deviation].
 nlv : float
     Noise level added to the generated power spectrum.
 """