Scrub reference to amplitude (replace by height or power) in docs & tutorials

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
 
@@ -119,8 +119,8 @@ fm = FOOOF(peak_width_limits=[1.0, 8.0], max_n_peaks=6, min_peak_height=0.1, pea
 
 * `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_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.
+* `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/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

tutorials/plot_01-ModelDescription.py

@@ -75,7 +75,7 @@
 #
 # Each peak is defined in terms of parameters `a`, `c` and `w`, where:
 #
-# - `a` is the amplitude of the peak, over and above the aperiodic signal
+# - `a` is the height of the peak, over and above the aperiodic signal
 # - `c` is the center frequency of the peak
 # - `w` is the width of the peak
 # - `F` is the vector of input frequencies

tutorials/plot_02-FOOOF.py

@@ -112,20 +112,27 @@
 # Notes on Interpreting Peak Parameters
 # -------------------------------------
 #
+# Peak parameters are labelled as:
+#
+# - CF: center frequency of the extracted peak
+# - PW: power of the peak, over and above the aperiodic background
+# - BW: bandwidth of the extracted peak
+#
 # Note that the peak parameters that are returned are not exactly the same as the
 # parameters of the Gaussians used internally to fit the peaks.
 #
 # Specifically:
 #
-# - CF is the mean parameter of the Gaussian (same as the Gaussian)
-# - Amp is the amplitude of the model fit above the aperiodic signal fit [1],
-#   which is not necessarily the same as the Gaussian amplitude
+# - CF is the exact same as mean parameter of the Gaussian
+# - PW is the height of the model fit above the aperiodic signal fit [1],
+#   which is not necessarily the same as the Gaussian height
 # - BW is 2 * the standard deviation of the Gaussian [2]
 #
 # [1] Since the Gaussians are fit together, if any Gaussians overlap,
 # than the actual height of the fit at a given point can only be assessed
-# when considering all Gaussians. To be better able to interpret amplitudes
-# for single peak fits, we re-define the peak amplitude as above.
+# when considering all Gaussians. To be better able to interpret heights
+# for single peak fits, we re-define the peak height as above, and label
+# it as 'power', as the units of the input data as expected to be power.
 #
 # [2] Standard deviation is '1 sided', where as the returned BW is '2 sided'.
 #

tutorials/plot_03-FOOOFAlgorithm.py

@@ -113,7 +113,7 @@
 #
 # - The maximum point of the flattened spectrum is found.
 #
-#   - If this point fails to pass the relative or absolute amplitude threshold,
+#   - If this point fails to pass the relative or absolute height threshold,
 #     the procedure halts.
 # - A Gaussian is fit around this maximum point
 # - This 'guess' Gaussian is then subtracted from the flatted spectrum

tutorials/plot_04-MoreFOOOF.py

@@ -58,14 +58,14 @@
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
 # An iterative procedures searches for candidate peaks in the flattened spectrum. Candidate
-# peaks are extracted in order of decreasing amplitude, until some stopping criterion is met,
+# peaks are extracted in order of decreasing height, until some stopping criterion is met,
 # which is controlled by the following parameters:
 #
 # **max_n_peaks (int)** default: infinite
 #
 # The maximum number of peaks that can be extracted from a given power spectrum. FOOOF will
 # halt searching for new peaks when this number is reached. Note that FOOOF extracts peaks
-# iteratively by amplitude (over and above the aperiodic signal), and so this approach will
+# iteratively by height (over and above the aperiodic signal), and so this approach will
 # extract (up to) the *n* largest peaks.
 #
 # **peak_threshold (in units of standard deviation)** default: 2.0
@@ -77,13 +77,13 @@
 #
 # **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
+# The minimum height, 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
 # search is halted (without including the most recent candidate). Note that because
 # this constraint is enforced during peak search, and prior to final peak fit, returned
-# peaks are not guaranteed to surpass this value in amplitude.
+# peaks are not guaranteed to surpass this value in height.
 #
-# Note: there are two different amplitude-related halting conditions for the peak searching.
+# Note: there are two different height-related halting conditions for the peak searching.
 # By default, the relative (standard-deviation based) threshold is defined, whereas the
 # absolute threshold is set to zero (this default is because there is no general way to
 # set this value without knowing the scale of the data). If both are defined, both are

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_height`
+# - Setting a minimum absolute peak height: `min_peak_height`
 #
 
 ###################################################################################################
@@ -182,7 +182,7 @@
 #
 # A known case in which FOOOF can overfit is in power spectra in which no peaks
 # are present. In this case, the standard deviation can be very low, and so the
-# relative amplitude check (`min_peak_threshold`) is very liberal at keeping gaussian fits.
+# relative peak height 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_height`,

tutorials/plot_08-FurtherAnalysis.py

@@ -68,7 +68,7 @@
 ###################################################################################################
 
 # Set up indexes for accessing data, for convenience
-cf_ind, amp_ind, bw_ind = 0, 1, 2
+cf_ind, pw_ind, bw_ind = 0, 1, 2
 
 # Define frequency bands of interest
 theta_band = [4, 8]
@@ -144,7 +144,7 @@
 
 # Check descriptive statistics of oscillation data
 print('Alpha CF : ', np.nanmean(alphas[:, cf_ind]))
-print('Alpha Amp: ', np.nanmean(alphas[:, amp_ind]))
+print('Alpha PW : ', np.nanmean(alphas[:, pw_ind]))
 print('Alpha BW : ', np.nanmean(alphas[:, bw_ind]))
 
 ###################################################################################################