Buf stats

doc/BufStats.rst

@@ -1,71 +1,81 @@
-:digest: Computing Statistics on Buffers as Series.
+:digest: Statistically summarise a time series in a Buffer
 :species: buffer-proc
 :sc-categories: Libraries>FluidDecomposition, UGens>Buffer
 :sc-related: Guides/FluidCorpusManipulationToolkit
 :see-also: BufLoudness, BufPitch, BufMelBands, BufMFCC, BufSpectralShape
 :description: Statistical analysis on buffer channels.
 :discussion: 
-   Typically, a buffer would hold various time series (i.e. descriptors over time), and BufStats allows this series to be described statistically.
 
-   The process returns a buffer where each channel of the source buffer has been reduced to 7 statistics: mean, standard deviation, skewness, kurtosis, followed by 3 percentiles, by default the minimum value, the median, and the maximum value. Moreover, it is possible to request the same 7 stats to be applied to derivative of the input. These are useful to describe statistically the rate of change of the time series. The stats buffer will grow accordingly, yielding the seven same statistical description of the n requested derivatives. Therefore, the stats buffer will have as many channel as the input buffer, and as many frames as 7 times the requested numDerivs (stats of derivatives).
+  :fluid-obj:`BufStats` statistically summarises a time-series (or any values) that is in a buffer, returning seven statistics for each channel: the buffer channel's mean, standard deviation, skewness, kurtosis, low, middle, and high values. See the ``low``, ``middle`` and ``high`` parameters below for more description on these values.
+
+  For a detailed explanation of :fluid-obj:`BufStats` features visit http://learn.flucoma.org/reference/bufstats.
+
+  The ``stats`` output buffer of :fluid-obj:`BufStats` will have the same number of channels as the input buffer, each one containing the statistics of its corresponding channel in the input buffer. Because the dimension of time is summarised statistically, the frames in the ``stats`` buffer do not represent time as they normally would. The first seven frames in every channel of the ``stats`` buffer will have the seven statistics computed on the input buffer channel. After these first seven frames, there will be seven more frames for each derivative requested, each containing the seven statistical summaries for the corresponding derivative.
+
+  For example if the input to :fluid-obj:`BufStats` is a three-channel buffer and ``numDerivs`` = 1 the output ``stats`` buffer would contain:
+
+   ========= ============ ============= ============= ======== =========== ======== ================= ==================== ===================== ===================== ================ =================== ================
+   ch 0 mean ch 0 std dev ch 0 skewness ch 0 kurtosis ch 0 min ch 0 median ch 0 max ch 0 deriv 1 mean ch 0 deriv 1 std dev ch 0 deriv 1 skewness ch 0 deriv 1 kurtosis ch 0 deriv 1 min ch 0 deriv 1 median ch 0 deriv 1 max
+   ch 1 mean ch 1 std dev ch 1 skewness ch 1 kurtosis ch 1 min ch 1 median ch 1 max ch 1 deriv 1 mean ch 1 deriv 1 std dev ch 1 deriv 1 skewness ch 1 deriv 1 kurtosis ch 1 deriv 1 min ch 1 deriv 1 median ch 1 deriv 1 max
+   ch 2 mean ch 2 std dev ch 2 skewness ch 2 kurtosis ch 2 min ch 2 median ch 2 max ch 2 deriv 1 mean ch 2 deriv 1 std dev ch 2 deriv 1 skewness ch 2 deriv 1 kurtosis ch 2 deriv 1 min ch 2 deriv 1 median ch 2 deriv 1 max
+   ========= ============ ============= ============= ======== =========== ======== ================= ==================== ===================== ===================== ================ =================== ================    
 
-:process: This is the method that calls for the slicing to be calculated on a given source buffer.
-:output: Nothing, as the destination buffer is declared in the function call.
+:process: This is the method that calls for the statistical analysis to be calculated on ``source``.
 
+:output: Nothing, as the ``stats`` buffer is declared in the function call.
 
 :control source:
 
-   The index of the buffer to use as the source material to be processed. The different channels of multichannel buffers will be considered independently as time series.
+   The buffer to statistically summarise. Each channel of multichannel buffers will be computed independently.
 
 :control startFrame:
 
-   The starting point (in samples) from which to copy in the source buffer.
+   The position (in frames) to begin the statistical analysis. :fluid-obj:`BufStats` is unaware of what kind of time-series is in ``source`` and what the sample rate might be (whether it is audio samples or audio descriptors). It will begin analysis at the indicated frame index in ``source``. The default is 0.
 
 :control numFrames:
 
-   The duration (in samples) to copy from the source buffer. The default (-1) copies the full lenght of the buffer.
+   The number of frames to use in the statistical analysis. The default of -1 indicates to use all the frames from ``startFrame`` through the end of the ``source`` buffer.
 
 :control startChan:
 
-   The first channel from which to copy in the source buffer.
+   The channel from which to begin computing statistics for. The default is 0.
 
 :control numChans:
 
-   The number of channels from which to copy in the source buffer. This parameter will wrap around the number of channels in the source buffer. The default (-1) copies all of the buffer's channel.
+   The number of channels to compute statistics for. The default of -1 indicates to compute statistics through the last channel in the ``source`` buffer.
 
 :control stats:
 
-   The index of the buffer to write the statistics to. Each channel is the fruit of the statistical computations on the same channel number of the source buffer.
+   The buffer to write the statistical summary into.
 
 :control numDerivs:
 
-   The number of derivatives of the original time series for the statistic to be computed on. By default, none are computed. This will influence the number of frames the stats buffer will have.
+   The number of derivatives of the original time-series to compute statistics on. The default of 0 will compute statistics on no derivates, only the original time-series itself. Setting this parameter > 0 (maximum of 2) will return the same seven statistics computed on consecutive derivatives of the channel's time-series. (``numDerivs`` = 1 will return the channel's statistics and the statistics of the first derivative, ``numDerivs`` = 2 will return the channel's statistics and the statistics of the first and second derivatives.) The derivative statistics are useful to describe the rate of change of the time series.
 
 :control low:
 
-   The components requested for the first percentile value. By default, it is percentile 0.0, which is the minimum of the given channel of the source buffer.
+   The value at this percentile (indicated as 0.0-100.0) will be written into frame 4 (zero-counting). By default, it is percentile 0.0, which is the minimum value of the channel.
 
 :control middle:
 
-   The components requested for the second percentile value. By default, it is percentile 50.0, which is the median of the given channel of the source buffer.
+  The value at this percentile (indicated as 0.0-100.0) will be written into frame 5 (zero-counting). By default, it is percentile 50.0, which is the median value of the channel.
 
 :control high:
 
-   The components requested for the third percentile value. By default, it is percentile 100.0, which is the maximum of the given channel of the source buffer.
+  The value at this percentile (indicated as 0.0-100.0) will be written into frame 6 (zero-counting). By default, it is percentile 100.0, which is the maximum value of the channel.
 
 :control outliersCutoff:
 
-   A ratio of the inter quantile range (IQR) that defines a range outside of which data will be rejected. It is run on each channel independently and a single channel being flagged as outlier removes the whole frame (on all channels). The default (-1) bypasses this function, keeping all frames in the statistical measurements. For more information on this statistical process, please refer to the concept of IQR and how the whiskers of a box plot are computed here (https://en.wikipedia.org/wiki/Box_plot)
+   A ratio of the inter quantile range (IQR) that defines a range from the median, outside of which data will be considered an outlier and not used to compute the statistical summary. For each frame, if a single value in any channel of that frame is considered an outlier (when compared to the rest of the values in it's channel), the whole frame (on all channels) will not be used for statistical calculations. The default of -1 bypasses this function, keeping all frames in the statistical measurements.
 
 :control weights:
 
-   A buffer to provide relative weighting of the source material. Not providing one will not apply weighting and consider all frames equally. The provided buffer has to satisfy all of the following conditions:
+   A buffer to provide relative weighting of each frame in the ``source`` buffer when computing the statistics. Not providing a ``weights`` buffer will cause all the frames to be considered equally. This may be useful for weighting certain descriptors by the value of other descriptors (such as the loudness or pitch confidence of the sound). The provided buffer has to satisfy all of the following conditions:
 
-   * a single-channel, that will be applied to all channels of source;
-   * exactly the same amount of frames as ‘source’;
-   * weights must be positive (anything lower than 0 will be rejected).
+   * a single-channel
+   * exactly the same amount of frames as ``source``
+   * all values must be positive (anything lower than 0 will be rejected)
 
 :control action:
 
-   A Function to be evaluated once the offline process has finished and indices instance variables have been updated on the client side. The function will be passed stats as an argument.
-
+   A Function to be evaluated once the offline process has finished and all the |buffer| variables have been updated on the client side. The function will be passed ``stats`` as an argument.