Merge pull request #207 from AUS-DOH-Safety-and-Quality/init-limit-do…

…ctests

Begin adding doc and unit testing for control limits

src/Limit Calculations/c.ts

@@ -1,6 +1,22 @@
 import { truncate, rep, mean } from "../Functions";
 import { type controlLimitsObject, type controlLimitsArgs } from "../Classes";
 
+/**
+ * Calculates the control limits for an SPC C Chart.
+ *
+ * The control limits are calculated using:
+ * - Center Line (CL): mean(numerators)
+ * - Sigma (σ): sqrt(CL)
+ * - Lower Control Limit (LCL): max(CL - 3*σ, 0)
+ * - Upper Control Limit (UCL): CL + 3*σ
+ *
+ * Note: The control limits are truncated to 0 if they fall below 0.
+ *
+ * @param {controlLimitsArgs} args - The arguments for calculating control limits.
+ * It includes keys (categories), and numerators (values for each category).
+ * @returns {controlLimitsObject} An object containing the keys, values, targets (center line),
+ * and the lower and upper control limits for both 95% and 99% confidence intervals.
+ */
 export default function cLimits(args: controlLimitsArgs): controlLimitsObject {
   const cl: number = mean(args.numerators);
   const sigma: number = Math.sqrt(cl);

src/Limit Calculations/g.ts

@@ -1,6 +1,25 @@
 import { sqrt, rep, mean, median } from "../Functions";
 import { type controlLimitsObject, type controlLimitsArgs } from "../Classes";
 
+/**
+ * Calculates the control limits for an SPC G Chart.
+ *
+ * The control limits for a G Chart are calculated using:
+ * - Center Line (CL): mean(numerators)
+ * - Sigma (σ): sqrt(CL * (CL + 1))
+ * - Lower Control Limit (LCL): 0 (G Charts do not have a lower control limit)
+ * - Upper Control Limit (UCL): CL + 3*σ
+ *
+ * Note:
+ *  - While the control limits are calculated using the mean of the numerators,
+ *      the median is used as the target to reduce the impact of skewed data.
+ *  - The control limits are truncated to 0 if they fall below 0.
+ *
+ * @param {controlLimitsArgs} args - The arguments for calculating control limits.
+ * It includes keys (categories), and numerators (values for each category).
+ * @returns {controlLimitsObject} An object containing the keys, values, targets (center line),
+ * and the lower and upper control limits for both 95% and 99% confidence intervals.
+ */
 export default function gLimits(args: controlLimitsArgs): controlLimitsObject {
   const cl: number = mean(args.numerators);
   const sigma: number = sqrt(cl * (cl + 1));

test/Limit Calculations/c.test.ts

@@ -0,0 +1,17 @@
+import { test } from 'vitest'
+import { c } from '../../src/Limit Calculations'
+import { rep } from '../../src/Functions'
+
+// Test values calculated using the 'qicharts2' R package
+test('cLimits function', ({ expect }) => {
+  const keys = [{ x: 5, id: 1, label: 'a' }, { x: 7, id: 2, label: 'b' }, { x: 9, id: 3, label: 'c' }];
+  const result = c({ keys: keys, numerators: [5, 7, 9] })
+
+  expect(result.keys).toEqual(keys)
+  expect(result.values).toEqual([5, 7, 9])
+  expect(result.targets).toEqual([7, 7, 7]) // assuming mean of [5, 7, 9] is 7
+  expect(result.ll99).toEqual([0, 0, 0])
+  expect(result.ll95).toEqual(rep(1.7084973778708186, 3))
+  expect(result.ul95).toEqual(rep(12.291502622129181, 3))
+  expect(result.ul99).toEqual(rep(14.937253933193773, 3))
+})

test/Limit Calculations/g.test.ts

@@ -0,0 +1,17 @@
+import { test } from 'vitest'
+import { g } from '../../src/Limit Calculations'
+import { rep } from '../../src/Functions'
+
+// Test values calculated using the 'qicharts2' R package
+test('gLimits function', ({ expect }) => {
+  const keys = [{ x: 5, id: 1, label: 'a' }, { x: 7, id: 2, label: 'b' }, { x: 9, id: 3, label: 'c' }];
+  const result = g({ keys: keys, numerators: [0, 10, 4] })
+
+  expect(result.keys).toEqual(keys)
+  expect(result.values).toEqual([0, 10, 4])
+  expect(result.targets).toEqual(rep(4, 3))
+  expect(result.ll99).toEqual(rep(0, 3))
+  expect(result.ll95).toEqual(rep(0, 3))
+  expect(result.ul95).toEqual(rep(14.95149908036101, 3))
+  expect(result.ul99).toEqual(rep(20.09391528720818, 3))
+})