From 7d22046b5cbe36ec5f4d624773a4c32169e96b28 Mon Sep 17 00:00:00 2001 From: Jacques Chester Date: Wed, 14 Aug 2024 14:31:30 -0400 Subject: [PATCH] Add doc comments for cusum_rules() [#6] --- sql/03-spc-reports-schema.sql | 40 +++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/sql/03-spc-reports-schema.sql b/sql/03-spc-reports-schema.sql index ea2b797..3075b26 100644 --- a/sql/03-spc-reports-schema.sql +++ b/sql/03-spc-reports-schema.sql @@ -394,7 +394,41 @@ $$; -- Cumulative Sum aka Cusum --- Asymmetric form of cusum_rules() +-- cusum_rules() provides the entrypoint for Cusum calculations of net (Cₙ), positive (C⁺) and negative (C⁻) deviations +-- from a mean. This is the asymmetric function that implements the bulk of the logic for Cusum reports. "Asymmetry" +-- here simply means that you can choose different values for upper and lower allowances or decision intervals. +-- +-- Parameters: +-- +-- * `p_upper_allowance` is the "allowance" for C⁺, known also in literature as K. The allowance should be set to a +-- value which represents half of the difference from the mean that is acceptable or normal. So for example, if you +-- want to detect shifts of 10 units, set `p_upper_allowance` to 5. +-- * `p_upper_decision_interval` is the "decision interval" for C⁺, known also in literature as H. The decision interval +-- represents the limits of deviation at which C⁺ is considered to have grown large enough that it's considered to be +-- out-of-control. The units are standard deviations, not the underlying measurement units. Typically set to 4 or 5, +-- depending on sensitivity requirements. See Montgomery §9.1.3 for a discussion of selecting K and H based on the +-- desired Average Run Length (how long, on average, between false alarms). +-- * `p_lower_allowance`. Same as `p_upper_allowance`, but for C⁻. +-- * `p_lower_decision_interval`. Same as `p_upper_decision_interval`, but for C⁻. +-- * `p_target_mean` represents a fixed, known value for the mean of the process. If not provided this will be derived +-- from the limit establishment window. +-- +-- Note that the function will not focus its calculations on a particular window, instrument etc unless you include a +-- `where window_id = 999` or similar in your query. Leaving off such a where clause will cause the calculation to run +-- over all samples from all windows, instruments etc. Slow and basically useless. +-- +-- Returns: +-- * `sample_id`, `window_id` and `instrument_id`. For filtering by these values. It is recommended to use +-- `where window_id = ` when using this function. +-- * `measured_value`. As the name suggests. +-- * `deviation`. The net amount by which the measured value differs from the mean. +-- * `deviation_plus`. The amount by which the measured value differs from the mean + the upper allowance. +-- * `deviation_minus`. The amount by which the measured value differs from the mean - the lower allowance. +-- * `C_n`. The calculated Cₙ value for this measurement. +-- * `C_plus`. The calculated C⁺ for this measurement. +-- * `C_minus`. The calculated C⁻ for this measurement. +-- * `upper_decision_interval`. Signals whether C⁺ has gone above the upper decision interval. +-- * `lower_decision_interval`. Signals whether C⁻ has gone below the lower decision interval. create function spc_reports.cusum_rules( p_upper_allowance decimal , p_upper_decision_interval decimal @@ -445,7 +479,9 @@ from spc_data.measurements m window window_sample as (partition by w.id order by m.sample_id); $$; --- Symmetric form of cusum_rules() +-- This is the symmetric form of cusum_rules(), provided for convenience. That is, it only takes a single value for +-- allowance and decision interval and applies these for both upper and lower calculations. It delegates to the fully +-- asymmetric version of cusum_rules(); see that function for a discussion of parameters and returned values. create function spc_reports.cusum_rules( p_allowance decimal , p_decision_interval decimal