Skip to main content

system.kanoa.quality.spc.spcCheck(values, chartType, ruleSet, subgroupSize, usl, lsl, sampleSizes, [ucl], [lcl], [center])

Computes SPC control limits, zone-based rule violations (Western Electric / Nelson), and - where applicable - process capability/performance indices, for one of the following chart types:

  • individuals - Individuals (I-MR) chart. Default. Paired with a Moving Range secondary chart.
  • xbar - X-bar/R chart (subgroup mean + range). Requires subgroupSize 2-10. Paired with a Range secondary chart.
  • xbar_s - X-bar/S chart (subgroup mean + sample std dev). Any subgroup size >= 2, unlike xbar (R-based), which is limited to the tabulated range n=2-10. Paired with an S secondary chart.
  • p - Percent defective chart, variable subgroup size.
  • np - Number defective chart, constant subgroup size.
  • c - Number of defects chart, constant area of opportunity.
  • u - Defects-per-unit chart, variable area of opportunity.
  • pre_control - Pre-Control zones. Spec-limit based - no control limits, no Western Electric/Nelson rules, no capability indices; uses its own run/stop signal instead.

p/np/c/u have no secondary chart and no capability indices - there is no subgroup-internal spread statistic to chart, and no within-subgroup sigma to build Cp/Cpk from (attribute-chart limits come directly from the binomial/Poisson variance formula, not from an estimated range/std dev).

Capability is only returned for individuals/xbar/xbar_s, and only when usl and/or lsl was given: {cp, cpk, cpu, cpl, pp, ppk, ppu, ppl, mean, sigmaWithin, sigmaOverall}. cp/pp are None unless BOTH usl and lsl are given; cpk/ppk are the min() of whichever one-sided indices exist. cp/cpk use sigmaWithin (short-term, from the same R-bar/d2 or S-bar/c4 estimate the control limits are built from); pp/ppk use sigmaOverall (long-term, the plain sample std dev of every individual reading around the grand mean, ignoring subgrouping). With no spread (sigma 0), the indices are None.

pre_control returns a materially different shape (zones/pairSignals/qualifyRunIndex/greenLow/greenHigh/yellowLow/yellowHigh in place of uclPoints/lclPoints/violations/violationPoints/secondary/capability).

By default the control limits are computed from values. That only makes sense when they are a stable baseline (20-25 points or more): limits computed from a short run of readings, a minute of one-second samples say, are so tight that nearly every rule fires. To judge the values against limits you already have (a measure's configured UCL/LCL, for example), pass ucl and lcl, and optionally center. A chart with constant limits (every type but p, u and pre_control) then uses them: the center line is center (midway between the limits when None), sigma for the zones is (ucl - lcl) / 6, and mean/sigma/ucl/lcl in the result are the given ones. Capability is still computed from the values.

The rules use zones 1, 2 and 3 sigma either side of the mean. A point exactly on the mean is on neither side: it breaks a run of points on one side, and counts as within 1 sigma. Nelson rule 8 (eight points in a row with none within 1 sigma) also needs points on both sides of the mean. With ruleSet None, no rules are run. violations gives where each violating run starts; violationPoints gives every point in the runs, to highlight them on a chart.


Parameters​

values List of Float values: raw measurements for individuals/xbar/xbar_s/pre_control (flat list, subgrouped internally for xbar/xbar_s); defect/defective count per subgroup for p/u; defect/defective count per subgroup (constant sample size/area) for np/c.
chartType String: 'individuals', 'xbar', 'xbar_s', 'p', 'np', 'c', 'u', 'pre_control'. Can be None (defaults to 'individuals').
ruleSet String: 'both', 'western_electric', 'nelson'. Can be None: no rules are run, and violations is empty. Ignored for pre_control.
subgroupSize Integer: required for xbar (2-10), xbar_s (>= 2), and np (constant n). Can be None otherwise.
usl Float: upper spec limit. Required for pre_control, optional elsewhere - if given (with or without lsl) for individuals/xbar/xbar_s, one-sided capability indices (cpu/cpk, ppu/ppk) are computed. Can be None.
lsl Float: lower spec limit. Same rules as usl, mirrored. Can be None.
sampleSizes List of Integers: required for p/u - one entry per subgroup, parallel to values. Can be None otherwise.
ucl Float: optional. An upper control limit to judge the values against instead of one computed from them; used only together with lcl, and not for p, u or pre_control. Can be None or left out.
lcl Float: optional. The lower control limit to use with ucl. Can be None or left out.
center Float: optional. The center line with ucl and lcl (a target, say); midway between them when None or left out.


Returns​

results Dictionary
outOfControl Boolean
chartType String
ruleSet String
mean Float
sigma Float: only when control limits are constant across points (None for p/u, where they vary by sample size - use uclPoints/lclPoints instead)
ucl / lcl Float: same constant-limit caveat as sigma
uclPoints / lclPoints List of Float values: per-point limit lists, always populated (repeated scalar for constant-limit chart types; genuinely varying point by point for p/u)
usl / lsl Float: pass-through of the input spec limits
aboveUCL / belowLCL / aboveUSL / belowLSL List of Integers: violating point indices
violations Dictionary: rule name -> the index of the first point of each violating run (for a control or spec limit, the point itself)
violationPoints Dictionary: rule name -> the indices of every point in its violating runs, for highlighting them on a chart. Not returned on an error.
points List of Float values
secondary Dictionary: (individuals/xbar/xbar_s only) the paired Moving-Range/Range/S chart - {label, centerLine, ucl, lcl, points}
capability Dictionary: see above
error String: None when the chart was computed. Otherwise why it couldn't be, for example Unknown chartType 'x', Zero dispersion - all values identical, ucl must be greater than lcl or center must be between lcl and ucl; the limit and violation fields are then empty.

Violation keys​

violations and violationPoints use these keys. A key is only present when its rule found at least one violation. getRuleInfo() gives each one a readable label, a description and a kind, for showing them to people.

KeyRule setViolation
aboveUCL / belowLCLanyA point above the upper or below the lower control limit
aboveUSL / belowLSLany, when usl / lsl is givenA point above the upper or below the lower spec limit
WE1_beyond_3sigmawestern_electric, bothOne point beyond 3 sigma
WE2_2of3_beyond_2sigmawestern_electric, both2 of 3 points in a row beyond 2 sigma, on the same side
WE3_4of5_beyond_1sigmawestern_electric, both4 of 5 points in a row beyond 1 sigma, on the same side
WE4_8_same_sidewestern_electric, both8 points in a row on the same side of the mean
WE5_6_trendingwestern_electric, both6 points in a row all increasing or all decreasing
WE6_15_within_1sigmawestern_electric, both15 points in a row within 1 sigma
N1_beyond_3sigmanelsonOne point beyond 3 sigma
N2_9_same_sidenelson, both9 points in a row on the same side of the mean
N3_6_trendingnelson6 points in a row all increasing or all decreasing
N4_14_alternatingnelson, both14 points in a row alternating up and down
N5_2of3_beyond_2sigmanelson2 of 3 points in a row beyond 2 sigma, on the same side
N6_4of5_beyond_1sigmanelson4 of 5 points in a row beyond 1 sigma, on the same side
N7_15_within_1sigmanelson15 points in a row within 1 sigma
N8_8_none_within_1sigmanelson, both8 points in a row, none within 1 sigma, on both sides of the mean

With both, the Nelson rules that a Western Electric rule already covers (1, 3, 5, 6 and 7) aren't repeated. The removed rule1() to rule8() functions are Nelson rules 1 to 8: run spcCheck() with the nelson rule set and read N1_beyond_3sigma to N8_8_none_within_1sigma.


Examples​

The shape of result changes noticeably by chartType - constant vs. per-point control limits, whether secondary/capability are populated, and (for pre_control) an entirely different set of fields. Each example below shows the actual computed values so you can see exactly what differs.

individuals against given limits​

A measure's configured limits (UCL 24, LCL 20, target 22). The readings sit inside them but all above the target, so only the run rules fire.

values = [22.6, 22.7, 22.9, 23.1, 23.3, 23.4, 23.5, 23.4, 23.2]
result = system.kanoa.quality.spc.spcCheck(values, "individuals", "both", None, 26.0, 18.0, None, 24.0, 20.0, 22.0)

# result["ucl"], result["lcl"], result["mean"] = 24.0, 20.0, 22.0 (the given limits)
# result["sigma"] = 0.667 ((24 - 20) / 6)
# result["violations"]: WE2_2of3_beyond_2sigma, WE3_4of5_beyond_1sigma, WE4_8_same_side, WE5_6_trending and N2_9_same_side
# (every point is above the target, and rising); no aboveUCL / belowLCL / WE1_beyond_3sigma

individuals​

One reading per point, no subgrouping. sigma/ucl/lcl are single constant values; secondary is the paired Moving Range chart.

values = [100.4, 98.6, 100.2, 96.0, 109.8, 102.1, 103.2]
result = system.kanoa.quality.spc.spcCheck(values, "individuals", None, None, None, None, None)

# result["points"] = [100.4, 98.6, 100.2, 96.0, 109.8, 102.1, 103.2] (unchanged - one point per reading)
# result["mean"] = 101.471
# result["sigma"] = 4.462
# result["ucl"] = 114.858
# result["lcl"] = 88.085
# result["secondary"] = {"label": "Moving Range", "centerLine": 5.033, "ucl": 16.444, "lcl": 0.0, "points": [1.8, 1.6, 4.2, 13.8, 7.7, 1.1]}

xbar (X-bar/R, subgroup size 4)​

Readings are grouped into subgroups; points become subgroup averages, not raw readings. secondary is the paired Range chart instead of Moving Range.

values = [100.4, 98.6, 100.2, 96.0, 109.8, 102.1, 103.2, 97.5, 101.0, 99.8, 100.5, 98.9]
subgroupSize = 4
result = system.kanoa.quality.spc.spcCheck(values, "xbar", None, subgroupSize, None, None, None)

# subgroups formed = [[100.4, 98.6, 100.2, 96.0], [109.8, 102.1, 103.2, 97.5], [101.0, 99.8, 100.5, 98.9]]
# result["points"] = [98.8, 103.15, 100.05] (subgroup means, not raw values)
# result["mean"] = 100.667
# result["ucl"] = 105.235
# result["lcl"] = 96.098
# result["secondary"] = {"label": "Range", "centerLine": 6.267, "ucl": 14.301, "lcl": 0.0, "points": [4.4, 12.3, 2.1]}

xbar_s (X-bar/S, subgroup size 5)​

Same idea as xbar, but any subgroup size >= 2 (not capped at 10) since it uses the sample standard deviation instead of range.

values = [100.4, 98.6, 100.2, 96.0, 109.8, 102.1, 103.2, 97.5, 101.0, 99.8]
subgroupSize = 5
result = system.kanoa.quality.spc.spcCheck(values, "xbar_s", None, subgroupSize, None, None, None)

# result["points"] = [101.0, 100.72] (subgroup means)
# result["mean"] = 100.860
# result["ucl"] = 106.158
# result["lcl"] = 95.562
# result["secondary"] = {"label": "S", "centerLine": 3.712, "ucl": 7.755, "lcl": 0.0, "points": [5.253, 2.170]}

p (percent defective, sample size varies)​

Attribute chart - no secondary, no capability. uclPoints/lclPoints genuinely vary per point since sampleSizes isn't constant.

values = [3, 5, 2, 8, 4] # defective counts per subgroup
sampleSizes = [50, 60, 45, 55, 50]
result = system.kanoa.quality.spc.spcCheck(values, "p", None, None, None, None, sampleSizes)

# result["points"] = [0.06, 0.083, 0.044, 0.145, 0.08] (proportion defective per subgroup)
# result["mean"] = 0.0846
# result["uclPoints"] = [0.203, 0.192, 0.209, 0.197, 0.203] (different per point - sample size varies)
# result["lclPoints"] = [0.0, 0.0, 0.0, 0.0, 0.0]

np (number defective, constant sample size)​

subgroupSize is the constant sample size here, not a grouping count - points stays as the raw defective counts, and control limits are constant (a single ucl/lcl, same as individuals/xbar).

values = [3, 5, 2, 8, 4] # defective counts, each out of a subgroup of 50
subgroupSize = 50
result = system.kanoa.quality.spc.spcCheck(values, "np", None, subgroupSize, None, None, None)

# result["points"] = [3, 5, 2, 8, 4] (raw counts, unchanged)
# result["mean"] = 4.4
# result["sigma"] = 2.003
# result["ucl"] = 10.410
# result["lcl"] = 0.0

c (number of defects, constant area of opportunity)​

values = [3, 5, 2, 8, 4, 6] # defect counts, one inspection unit each
result = system.kanoa.quality.spc.spcCheck(values, "c", None, None, None, None, None)

# result["points"] = [3, 5, 2, 8, 4, 6]
# result["mean"] = 4.667
# result["sigma"] = 2.160
# result["ucl"] = 11.147
# result["lcl"] = 0.0

u (defects per unit, area of opportunity varies)​

Same as c, but sampleSizes carries the varying area/unit count, so points becomes a rate and the limits vary per point.

values = [3, 5, 2, 8, 4] # defect counts
areas = [10, 12, 9, 11, 10] # units inspected per subgroup
result = system.kanoa.quality.spc.spcCheck(values, "u", None, None, None, None, areas)

# result["points"] = [0.3, 0.417, 0.222, 0.727, 0.4] (defects per unit)
# result["mean"] = 0.4231
# result["uclPoints"] = [1.04, 0.986, 1.074, 1.011, 1.04]
# result["lclPoints"] = [0.0, 0.0, 0.0, 0.0, 0.0]

pre_control​

A materially different return shape - zones/pairSignals/qualifyRunIndex/greenLow/greenHigh/yellowLow/yellowHigh in place of uclPoints/lclPoints/violations/secondary/capability. Requires both usl and lsl.

values = [99, 101, 98, 102, 100, 106, 107]
usl, lsl = 110.0, 90.0
result = system.kanoa.quality.spc.spcCheck(values, "pre_control", None, None, usl, lsl, None)

# result["greenLow"] = 95.0 (middle 50% of the 90-110 tolerance)
# result["greenHigh"] = 105.0
# result["zones"] = ["green", "green", "green", "green", "green", "yellow-high", "yellow-high"]
# the first five points qualify the process (5 consecutive green); the last two
# both landing in yellow-high is what pairSignals flags as a shift, not a random blip