@m2c2kit/assessment-color-shapes 0.8.32 → 0.8.34

package/dist/index.js

@@ -11,6 +11,72 @@ class M2Error extends Error {
     }
   }
 }
+const CHAIN_REGISTRY = /* @__PURE__ */ new Map();
+let CHAIN_COUNTER = 0;
+function getChainOps(id) {
+  return CHAIN_REGISTRY.get(id);
+}
+function clearChainOps(id) {
+  CHAIN_REGISTRY.delete(id);
+}
+function makeChainFn() {
+  const fn = ((dataCalc) => {
+    if (!dataCalc) return void 0;
+    let current = dataCalc;
+    for (const op of fn.ops) {
+      const method = current[op.name];
+      if (typeof method !== "function") {
+        throw new M2Error(
+          `chain: method ${op.name} does not exist on DataCalc`
+        );
+      }
+      const res = method.apply(current, op.args);
+      if (res instanceof DataCalc) {
+        current = res;
+        continue;
+      }
+      return res;
+    }
+    return void 0;
+  });
+  fn.ops = [];
+  const record = (name, args) => {
+    fn.ops.push({ name, args });
+    return fn;
+  };
+  fn.arrange = (...variables) => record("arrange", variables);
+  fn.slice = (start, end) => record("slice", [start, end]);
+  fn.pull = (variable) => record("pull", [variable]);
+  fn.filter = (predicate) => record("filter", [predicate]);
+  fn.mutate = (mutations) => record("mutate", [mutations]);
+  fn.select = (...variables) => record("select", variables);
+  fn.groupBy = (...groups) => record("groupBy", groups);
+  fn.ungroup = () => record("ungroup", []);
+  fn.rename = (renames) => record("rename", [renames]);
+  fn.distinct = () => record("distinct", []);
+  Object.defineProperty(fn, "length", {
+    configurable: true,
+    get: function() {
+      try {
+        const id = `c${++CHAIN_COUNTER}`;
+        CHAIN_REGISTRY.set(
+          id,
+          (fn.ops || []).map((o) => ({ ...o }))
+        );
+        return `__CHAIN_EXPR__[${id}]`;
+      } catch (err) {
+        return void 0;
+      }
+    }
+  });
+  return fn;
+}
+function arrange(...variables) {
+  return makeChainFn().arrange(...variables);
+}
+function filter(predicate) {
+  return makeChainFn().filter(predicate);
+}
 class DataCalc {
   /**
    * A class for transformation and calculation of m2c2kit data.
@@ -34,6 +100,7 @@ class DataCalc {
    */
   constructor(data, options) {
     this._groups = new Array();
+    this._warnings = false;
     if (!Array.isArray(data)) {
       throw new M2Error(
         "DataCalc constructor expects an array of observations as first argument"
@@ -63,6 +130,9 @@ class DataCalc {
     if (options?.groups) {
       this._groups = Array.from(options.groups);
     }
+    if (options?.warnings) {
+      this._warnings = true;
+    }
   }
   /**
    * Returns the groups in the data.
@@ -89,7 +159,8 @@ class DataCalc {
    * Returns a single variable from the data.
    *
    * @remarks If the variable length is 1, the value is returned. If the
-   * variable has length > 1, an array of values is returned.
+   * variable has length > 1, an array of values is returned. If an empty
+   * dataset is provided, `null` is returned and a warning is logged.
    *
    * @param variable - Name of variable to pull from the data
    * @returns the value of the variable
@@ -105,9 +176,11 @@ class DataCalc {
    */
   pull(variable) {
     if (this._observations.length === 0) {
-      console.warn(
-        `DataCalc.pull(): No observations available to pull variable "${variable}" from. Returning null.`
-      );
+      if (this._warnings) {
+        console.warn(
+          `DataCalc.pull(): No observations available to pull variable "${variable}" from. Returning null.`
+        );
+      }
       return null;
     }
     this.verifyObservationsContainVariable(variable);
@@ -167,7 +240,7 @@ class DataCalc {
       this._observations.filter(
         predicate
       ),
-      { groups: this._groups }
+      { groups: this._groups, warnings: this._warnings }
     );
   }
   /**
@@ -176,7 +249,8 @@ class DataCalc {
    * @remarks This is used with the `summarize()` method to calculate summaries
    * by group.
    *
-   * @param groups - variable names to group by
+   * @param groups - variable names to group by. Grouping variables must be
+   * primitive values (string, number, boolean).
    * @returns A new `DataCalc` object with the observations grouped by one or
    * more variables
    *
@@ -197,6 +271,16 @@ class DataCalc {
   groupBy(...groups) {
     groups.forEach((group) => {
       this.verifyObservationsContainVariable(group);
+      for (let i = 0; i < this._observations.length; i++) {
+        const val = this._observations[i][group];
+        if (val === null) continue;
+        const t = typeof val;
+        if (t !== "number" && t !== "string" && t !== "boolean") {
+          throw new M2Error(
+            `groupBy(): variable "${group}" contains non-primitive value at index ${i} (type=${t}). Only number, string, boolean, or null are allowed for grouping.`
+          );
+        }
+      }
     });
     return new DataCalc(this._observations, { groups });
   }
@@ -250,7 +334,10 @@ class DataCalc {
       }
       return newObservation;
     });
-    return new DataCalc(newObservations, { groups: this._groups });
+    return new DataCalc(newObservations, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Calculates summaries of the data.
@@ -287,6 +374,31 @@ class DataCalc {
    * );
    * // [ { filteredTotalC: 10 } ]
    * ```
+   *
+   * @remarks Within a `summarize()` call, regular arithmetic operations
+   * (+, -, *, /, etc.) must not be used directly on `DataCalc` objects
+   * or summary functions. This is not allowed:
+   *
+   * @example
+   * ```js
+   * dc.summarize({
+   *   meanA: mean("a"),
+   *   // The below will cause an error because it attempts to add a number
+   *   // to a DataCalc object, which is not supported
+   *   totalBPlus5: sum("b") + 5
+   * })
+   * ```
+   *
+   * Instead, use the `DataCalc` helper functions such as `add` to perform
+   * calculations within summary results. For example, to add 5 to the sum
+   * of "b", you can do:
+   * @example
+   * ```js
+   * dc.summarize({
+   *   meanA: mean("a"),
+   *   totalBPlus5: sum("b").add(5)
+   * })
+   * ```
    */
   summarize(summarizations) {
     if (this._groups.length === 0) {
@@ -299,20 +411,103 @@ class DataCalc {
             summarizeOperation.parameters,
             summarizeOperation.options
           );
+        } else if (typeof value === "function") {
+          try {
+            const res = value(this);
+            if (typeof res === "function") {
+              throw new M2Error(
+                `summarize(): lazy callback for ${newVariable} returned a function; expected a value or array of values.`
+              );
+            }
+            if (res instanceof DataCalc) {
+              throw new M2Error(
+                `summarize(): lazy callback for ${newVariable} returned a DataCalc; expected a value or array of values.`
+              );
+            }
+            obs[newVariable] = res;
+          } catch (err) {
+            throw new M2Error(
+              `summarize(): lazy callback for ${newVariable} threw an error: ${err && err.message ? err.message : String(err)}`
+            );
+          }
         } else {
+          if (typeof value === "string") {
+            const re = /__CHAIN_EXPR__\[(.*?)\]/g;
+            const matches = Array.from(value.matchAll(re));
+            if (matches.length > 0) {
+              let sum2 = 0;
+              for (const m of matches) {
+                const payload = m[1];
+                let ops = getChainOps(payload);
+                if (!ops) {
+                  try {
+                    ops = JSON.parse(decodeURIComponent(payload));
+                  } catch (err) {
+                    throw new M2Error(
+                      `summarize(): failed to parse chain payload for ${newVariable}`
+                    );
+                  }
+                }
+                let current = this;
+                let evaluated = void 0;
+                if (!ops) {
+                  throw new M2Error(
+                    `summarize(): empty chain ops for ${newVariable}`
+                  );
+                }
+                for (const op of ops) {
+                  const method = current[op.name];
+                  if (typeof method !== "function") {
+                    throw new M2Error(
+                      `summarize(): chain method ${op.name} does not exist on DataCalc`
+                    );
+                  }
+                  const res = method.apply(current, op.args);
+                  if (res instanceof DataCalc) {
+                    current = res;
+                    continue;
+                  }
+                  if (Array.isArray(res)) {
+                    evaluated = res.length;
+                    break;
+                  }
+                  if (typeof res === "boolean") {
+                    evaluated = res ? 1 : 0;
+                    break;
+                  }
+                  evaluated = typeof res === "number" ? res : Number(res);
+                  break;
+                }
+                if (evaluated === void 0) {
+                  evaluated = current instanceof DataCalc ? current.length : 0;
+                }
+                sum2 += evaluated;
+              }
+              let leftover = value;
+              for (const m of matches) leftover = leftover.replace(m[0], "");
+              const leftoverNum = Number(leftover);
+              if (!Number.isNaN(leftoverNum)) sum2 += leftoverNum;
+              obs[newVariable] = sum2;
+              for (const m of matches) {
+                clearChainOps(m[1]);
+              }
+              continue;
+            }
+          }
           obs[newVariable] = value;
         }
       }
-      return new DataCalc([obs], { groups: this._groups });
+      return new DataCalc([obs], {
+        groups: this._groups,
+        warnings: this._warnings
+      });
     }
     return this.summarizeByGroups(summarizations);
   }
   summarizeByGroups(summarizations) {
     const groupMap = /* @__PURE__ */ new Map();
     this._observations.forEach((obs) => {
-      const groupKey = this._groups.map(
-        (g) => typeof obs[g] === "object" ? JSON.stringify(obs[g]) : obs[g]
-      ).join("|");
+      const groupKey = this._groups.map((g) => String(obs[g])).join("|");
       if (!groupMap.has(groupKey)) {
         groupMap.set(groupKey, []);
       }
@@ -330,21 +525,17 @@ class DataCalc {
       const summaryObj = {};
       this._groups.forEach((group, i) => {
         const valueStr = groupValues[i];
-        const originalType = typeof firstObs[group];
-        if (originalType === "number") {
-          summaryObj[group] = Number(valueStr);
-        } else if (originalType === "boolean") {
-          summaryObj[group] = valueStr === "true";
-        } else if (valueStr.startsWith("{") || valueStr.startsWith("[")) {
-          try {
-            summaryObj[group] = JSON.parse(valueStr);
-          } catch {
-            throw new M2Error(
-              `Failed to parse group value ${valueStr} as JSON for group ${group}`
-            );
-          }
+        if (firstObs[group] === null) {
+          summaryObj[group] = null;
         } else {
-          summaryObj[group] = valueStr;
+          const originalType = typeof firstObs[group];
+          if (originalType === "number") {
+            summaryObj[group] = Number(valueStr);
+          } else if (originalType === "boolean") {
+            summaryObj[group] = valueStr === "true";
+          } else {
+            summaryObj[group] = valueStr;
+          }
         }
       });
       const groupDataCalc = new DataCalc(groupObs);
@@ -356,13 +547,98 @@ class DataCalc {
             summarizeOperation.parameters,
             summarizeOperation.options
           );
+        } else if (typeof value === "function") {
+          try {
+            const res = value(groupDataCalc);
+            if (typeof res === "function") {
+              throw new M2Error(
+                `summarize(): lazy callback for ${newVariable} returned a function; expected a value or array of values.`
+              );
+            }
+            if (res instanceof DataCalc) {
+              throw new M2Error(
+                `summarize(): lazy callback for ${newVariable} returned a DataCalc; expected a value or array of values.`
+              );
+            }
+            summaryObj[newVariable] = res;
+          } catch (err) {
+            throw new M2Error(
+              `summarize(): lazy callback for ${newVariable} threw an error: ${err && err.message ? err.message : String(err)}`
+            );
+          }
         } else {
+          if (typeof value === "string") {
+            const re = /__CHAIN_EXPR__\[(.*?)\]/g;
+            const matches = Array.from(value.matchAll(re));
+            if (matches.length > 0) {
+              let sum2 = 0;
+              for (const m of matches) {
+                const payload = m[1];
+                let ops = getChainOps(payload);
+                if (!ops) {
+                  try {
+                    ops = JSON.parse(decodeURIComponent(payload));
+                  } catch (err) {
+                    throw new M2Error(
+                      `summarize(): failed to parse chain payload for ${newVariable}`
+                    );
+                  }
+                }
+                let current = groupDataCalc;
+                let evaluated = void 0;
+                if (!ops) {
+                  throw new M2Error(
+                    `summarize(): empty chain ops for ${newVariable}`
+                  );
+                }
+                for (const op of ops) {
+                  const method = current[op.name];
+                  if (typeof method !== "function") {
+                    throw new M2Error(
+                      `summarize(): chain method ${op.name} does not exist on DataCalc`
+                    );
+                  }
+                  const res = method.apply(current, op.args);
+                  if (res instanceof DataCalc) {
+                    current = res;
+                    continue;
+                  }
+                  if (Array.isArray(res)) {
+                    evaluated = res.length;
+                    break;
+                  }
+                  if (typeof res === "boolean") {
+                    evaluated = res ? 1 : 0;
+                    break;
+                  }
+                  evaluated = typeof res === "number" ? res : Number(res);
+                  break;
+                }
+                if (evaluated === void 0) {
+                  evaluated = current instanceof DataCalc ? current.length : 0;
+                }
+                sum2 += evaluated;
+              }
+              let leftover = value;
+              for (const m of matches) leftover = leftover.replace(m[0], "");
+              const leftoverNum = Number(leftover);
+              if (!Number.isNaN(leftoverNum)) sum2 += leftoverNum;
+              summaryObj[newVariable] = sum2;
+              for (const m of matches) {
+                clearChainOps(m[1]);
+              }
+              continue;
+            }
+          }
           summaryObj[newVariable] = value;
         }
       }
       summarizedObservations.push(summaryObj);
     });
-    return new DataCalc(summarizedObservations, { groups: this._groups });
+    return new DataCalc(summarizedObservations, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Selects specific variables to keep in the dataset.
@@ -415,7 +691,10 @@ class DataCalc {
       }
       return newObservation;
     });
-    return new DataCalc(newObservations, { groups: this._groups });
+    return new DataCalc(newObservations, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Arranges (sorts) the observations based on one or more variables.
@@ -467,7 +746,10 @@ class DataCalc {
       }
       return 0;
     });
-    return new DataCalc(sortedObservations, { groups: this._groups });
+    return new DataCalc(sortedObservations, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Keeps only unique/distinct observations.
@@ -496,11 +778,19 @@ class DataCalc {
       seen.add(key);
       return true;
     });
-    return new DataCalc(uniqueObs, { groups: this._groups });
+    return new DataCalc(uniqueObs, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Renames variables in the observations.
    *
+   * @remarks If a target name in `renames` already exists in the dataset (and is not
+   * simply the source name being renamed), the rename will overwrite the existing
+   * variable. When warnings are enabled, a warning will be logged to make users aware
+   * of the potential overwrite.
+   *
    * @param renames - Object mapping new variable names to old variable names
    * @returns A new DataCalc object with renamed variables
    *
@@ -522,21 +812,37 @@ class DataCalc {
     Object.values(renames).forEach((oldName) => {
       this.verifyObservationsContainVariable(oldName);
     });
+    if (this._observations.length > 0) {
+      const existingKeys = new Set(Object.keys(this._observations[0]));
+      const oldNames = new Set(Object.values(renames));
+      const collisions = Object.keys(renames).filter(
+        (n2) => existingKeys.has(n2) && !oldNames.has(n2)
+      );
+      if (collisions.length > 0 && this._warnings) {
+        console.warn(
+          `DataCalc.rename(): renaming will overwrite existing variables: ${collisions.join(", ")}`
+        );
+      }
+    }
     const newObservations = this._observations.map((observation) => {
       const newObservation = {};
+      const newNames = new Set(Object.keys(renames));
       for (const [key, value] of Object.entries(observation)) {
         const newKey = Object.entries(renames).find(
           ([, old]) => old === key
         )?.[0];
         if (newKey) {
           newObservation[newKey] = value;
-        } else if (!Object.values(renames).includes(key)) {
+        } else if (!newNames.has(key)) {
           newObservation[key] = value;
         }
       }
       return newObservation;
     });
-    return new DataCalc(newObservations, { groups: this._groups });
+    return new DataCalc(newObservations, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Performs an inner join with another DataCalc object.
@@ -876,7 +1182,10 @@ class DataCalc {
     }
     let sliced;
     if (start >= this._observations.length) {
-      return new DataCalc([], { groups: this._groups });
+      return new DataCalc([], {
+        groups: this._groups,
+        warnings: this._warnings
+      });
     }
     if (end === void 0) {
       const index = start < 0 ? this._observations.length + start : start;
@@ -884,7 +1193,10 @@ class DataCalc {
     } else {
       sliced = this._observations.slice(start, end);
     }
-    return new DataCalc(sliced, { groups: this._groups });
+    return new DataCalc(sliced, {
+      groups: this._groups,
+      warnings: this._warnings
+    });
   }
   /**
    * Combines observations from two DataCalc objects by rows.
@@ -1046,6 +1358,26 @@ class DataCalc {
    * @returns a deep copy of the object
    */
   deepCopy(source, map = /* @__PURE__ */ new WeakMap()) {
+    const sClone = globalThis.structuredClone;
+    if (typeof sClone === "function") {
+      try {
+        const proto = source && typeof source === "object" ? Object.getPrototypeOf(source) : null;
+        const isPlain = Array.isArray(source) || proto === Object.prototype || proto === null;
+        if (isPlain) {
+          const descriptors = Object.getOwnPropertyDescriptors(
+            source
+          );
+          const hasAccessors = Object.values(descriptors).some(
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            (d) => typeof d.get === "function" || typeof d.set === "function"
+          );
+          if (!hasAccessors) {
+            return sClone(source);
+          }
+        }
+      } catch {
+      }
+    }
     if (source === null || typeof source !== "object") {
       return source;
     }
@@ -1064,8 +1396,9 @@ class DataCalc {
         key
       );
       if (descriptor) {
+        const { get, set, ...descWithoutAccessors } = descriptor;
         Object.defineProperty(copy, key, {
-          ...descriptor,
+          ...descWithoutAccessors,
           // eslint-disable-next-line @typescript-eslint/no-explicit-any
           value: this.deepCopy(source[key], map)
         });
@@ -1085,7 +1418,613 @@ class DataCalc {
     return keys.some((key) => obs[key] === null || obs[key] === void 0);
   }
 }
-console.log("\u26AA @m2c2kit/data-calc version 0.8.5 (d289d12c)");
+const PRECEDENCE = {
+  "+": 1,
+  "-": 1,
+  "*": 2,
+  "/": 2,
+  "^": 3
+};
+class SummarizeOperation {
+  constructor(leafFn, parameters, options, tokens) {
+    this.leafFn = leafFn;
+    this.parameters = parameters;
+    this.options = options;
+    if (tokens && tokens.length > 0) {
+      this.tokens = tokens.slice();
+    } else if (leafFn) {
+      this.tokens = [{ t: "operand", v: this }];
+    } else {
+      this.tokens = [];
+    }
+    this.summarizeFunction = (dc) => {
+      return this.evaluateAsValue(dc);
+    };
+  }
+  // Factory for creating a leaf SummarizeOperation (use in helpers)
+  static leaf(leafFn, parameters, options) {
+    return new SummarizeOperation(leafFn, parameters, options);
+  }
+  // clone with new token stream (immutable-ish)
+  cloneWithTokens(newTokens) {
+    return new SummarizeOperation(void 0, void 0, void 0, newTokens);
+  }
+  // append operator + operand (operand can be number or SummarizeOperation)
+  appendOp(op, operand) {
+    const newTokens = this.tokens.slice();
+    newTokens.push({ t: "op", v: op });
+    newTokens.push({ t: "operand", v: operand });
+    return this.cloneWithTokens(newTokens);
+  }
+  /**
+   * Append addition to this expression.
+   *
+   * @param x - A numeric literal or another `SummarizeOperation` to add to this expression
+   * @returns A new `SummarizeOperation` representing `(this + x)`
+   *
+   * @example
+   * ```js
+   * const d = [
+   *   { a: 1, b: 2, c: 3 },
+   *   { a: 0, b: 8, c: 3 },
+   *   { a: 9, b: 4, c: 7 },
+   * ];
+   * const dc = new DataCalc(d);
+   * console.log(
+   *   dc.summarize({
+   *     result: mean("a").add(10),
+   *   }).observations
+   * );
+   * // [ { result: 13.33333 } ]
+   * ```
+   */
+  add(x) {
+    return this.appendOp("+", x);
+  }
+  /**
+   * Append subtraction to this expression.
+   *
+   * @param x - A numeric literal or another `SummarizeOperation` to subtract from this expression
+   * @returns A new `SummarizeOperation` representing `(this - x)`
+   *
+   * @example
+   * ```js
+   * const d = [
+   *   { a: 1, b: 2, c: 3 },
+   *   { a: 0, b: 8, c: 3 },
+   *   { a: 9, b: 4, c: 7 },
+   * ];
+   * const dc = new DataCalc(d);
+   * console.log(
+   *   dc.summarize({
+   *     result: mean("a").sub(10),
+   *   }).observations
+   * );
+   * // [ { result: -6.6667 } ]
+   * ```
+   */
+  sub(x) {
+    return this.appendOp("-", x);
+  }
+  /**
+   * Append multiplication to this expression. Multiplication has higher
+   * precedence than addition/subtraction.
+   *
+   * @param x - A numeric literal or another `SummarizeOperation` to multiply with this expression
+   * @returns A new `SummarizeOperation` representing `(this * x)`
+   *
+   * @example
+   * ```js
+   * const d = [
+   *   { a: 1, b: 2, c: 3 },
+   *   { a: 0, b: 8, c: 3 },
+   *   { a: 9, b: 4, c: 7 },
+   * ];
+   * const dc = new DataCalc(d);
+   * console.log(
+   *   dc.summarize({
+   *     result: mean("a").mul(10),
+   *   }).observations
+   * );
+   * // [ { result: 33.3333 } ]
+   * ```
+   */
+  mul(x) {
+    return this.appendOp("*", x);
+  }
+  /**
+   * Append division to this expression.
+   *
+   * @param x - A numeric literal or another `SummarizeOperation` to divide this expression by
+   * @returns A new `SummarizeOperation` representing `(this / x)`
+   *
+   * @example
+   * ```js
+   * const d = [
+   *   { a: 1, b: 2, c: 3 },
+   *   { a: 0, b: 8, c: 3 },
+   *   { a: 9, b: 4, c: 7 },
+   * ];
+   * const dc = new DataCalc(d);
+   * console.log(
+   *   dc.summarize({
+   *     result: mean("a").div(10),
+   *   }).observations
+   * );
+   * // [ { result: .3333 } ]
+   * ```
+   */
+  div(x) {
+    return this.appendOp("/", x);
+  }
+  /**
+   * Append exponentiation (power) to this expression.
+   *
+   * Note: exponentiation uses right-associative semantics (a ^ b ^ c -> a ^ (b ^ c)).
+   *
+   * @param x - A numeric literal or another `SummarizeOperation` used as the exponent
+   * @returns A new `SummarizeOperation` representing `(this ^ x)`
+   *
+   * @example
+   * ```js
+   * const d = [
+   *   { a: 1, b: 2, c: 3 },
+   *   { a: 0, b: 8, c: 3 },
+   *   { a: 9, b: 4, c: 7 },
+   * ];
+   * const dc = new DataCalc(d);
+   * console.log(
+   *   dc.summarize({
+   *     result: mean("a").pow(2),
+   *   }).observations
+   * );
+   * // [ { result: 11.1111 } ]
+   * ```
+   */
+  pow(x) {
+    return this.appendOp("^", x);
+  }
+  // Evaluate an operand token to a number (returns NaN for non-numeric)
+  evaluateOperandToNumber(opd, dc) {
+    if (!this._usedChainIds) this._usedChainIds = /* @__PURE__ */ new Set();
+    if (typeof opd === "number") return opd;
+    if (typeof opd === "string") {
+      const re = /^__CHAIN_EXPR__\[(.*?)\]$/;
+      const m = re.exec(opd);
+      if (m) {
+        const payload = m[1];
+        let ops = getChainOps(payload);
+        if (ops) this._usedChainIds?.add(payload);
+        if (!ops) {
+          try {
+            ops = JSON.parse(decodeURIComponent(payload));
+          } catch {
+            ops = void 0;
+          }
+        }
+        if (!ops) return NaN;
+        let current = dc;
+        let evaluated = void 0;
+        for (const op of ops) {
+          const method = current[op.name];
+          if (typeof method !== "function") return NaN;
+          const res = method.apply(current, op.args);
+          if (res instanceof DataCalc) {
+            current = res;
+            continue;
+          }
+          if (Array.isArray(res)) {
+            evaluated = res.length;
+            break;
+          }
+          if (typeof res === "boolean") {
+            const coerce = this.options && typeof this.options.coerceBooleans === "boolean" ? this.options.coerceBooleans : true;
+            if (coerce) {
+              evaluated = res ? 1 : 0;
+              break;
+            } else {
+              return NaN;
+            }
+          }
+          evaluated = typeof res === "number" ? res : Number(res);
+          break;
+        }
+        if (evaluated === void 0)
+          evaluated = current instanceof DataCalc ? current.length : NaN;
+        return typeof evaluated === "number" && !isNaN(evaluated) ? evaluated : NaN;
+      }
+    }
+    const params = Array.isArray(opd.parameters) ? opd.parameters : opd.parameters === void 0 ? void 0 : [opd.parameters];
+    const raw = opd.leafFn ? opd.leafFn(dc, params, opd.options) : opd.evaluateAsValue(dc);
+    if (raw === null || raw === void 0) return NaN;
+    const num = Number(raw);
+    return typeof num === "number" && !isNaN(num) ? num : NaN;
+  }
+  // Evaluate a flat token stream (no nested handling required here; nested SummarizeOperation
+  // operands will evaluate themselves recursively)
+  evaluateFlatTokens(tokens, dc) {
+    const operands = [];
+    const ops = [];
+    for (const tk of tokens) {
+      if (tk.t === "operand") operands.push(tk.v);
+      else ops.push(tk.v);
+    }
+    if (operands.length === 0) return NaN;
+    while (ops.length > 0) {
+      let bestIdx = 0;
+      let bestPrec = PRECEDENCE[ops[0]] ?? 0;
+      for (let i = 1; i < ops.length; i++) {
+        const p = PRECEDENCE[ops[i]] ?? 0;
+        if (p > bestPrec || p === bestPrec && ops[i] === "^") {
+          bestPrec = p;
+          bestIdx = i;
+        }
+      }
+      const op = ops.splice(bestIdx, 1)[0];
+      const left = operands.splice(bestIdx, 1)[0];
+      const right = operands.splice(bestIdx, 1)[0];
+      const a = this.evaluateOperandToNumber(left, dc);
+      const b = this.evaluateOperandToNumber(right, dc);
+      let res2 = NaN;
+      if (op === "+") res2 = a + b;
+      else if (op === "-") res2 = a - b;
+      else if (op === "*") res2 = a * b;
+      else if (op === "/") res2 = b === 0 ? NaN : a / b;
+      else if (op === "^") res2 = Math.pow(a, b);
+      operands.splice(bestIdx, 0, res2);
+    }
+    const final = operands[0];
+    if (typeof final === "number") {
+      if (this._usedChainIds) {
+        for (const id of this._usedChainIds) clearChainOps(id);
+        this._usedChainIds = void 0;
+      }
+      return final;
+    }
+    const res = this.evaluateOperandToNumber(final, dc);
+    if (this._usedChainIds) {
+      for (const id of this._usedChainIds) clearChainOps(id);
+      this._usedChainIds = void 0;
+    }
+    return res;
+  }
+  /**
+   * Instance helper: return a grouped version of this operation so it becomes
+   * a single operand in outer expressions. Equivalent to parens(this).
+   */
+  parens() {
+    return parens(this);
+  }
+  // Top-level evaluation: handles the case where this instance is a leaf (leafFn present)
+  // or an expression token stream.
+  evaluateAsValue(dc) {
+    if (this.leafFn) {
+      const params = Array.isArray(this.parameters) ? this.parameters : this.parameters === void 0 ? void 0 : [this.parameters];
+      const res = this.leafFn(dc, params, this.options);
+      if (typeof res === "number" && Number.isNaN(res)) return null;
+      return res;
+    }
+    if (!this.tokens || this.tokens.length === 0) return NaN;
+    const val = this.evaluateFlatTokens(this.tokens, dc);
+    if (typeof val === "number" && Number.isNaN(val)) return null;
+    return val;
+  }
+}
+function parens(op) {
+  const tokens = [{ t: "operand", v: op }];
+  return new SummarizeOperation(void 0, void 0, void 0, tokens);
+}
+const DEFAULT_SUMMARIZE_OPTIONS = {
+  coerceBooleans: true,
+  skipMissing: false
+};
+function applyDefaultOptions(options) {
+  return { ...DEFAULT_SUMMARIZE_OPTIONS, ...options };
+}
+function resolveLazy(param, dataCalc, opName) {
+  if (typeof param !== "function") {
+    return param;
+  }
+  try {
+    const res = param(dataCalc);
+    if (typeof res === "function") {
+      throw new M2Error(
+        `${opName || "summarize()"}: lazy callback returned a function; expected a value or array of values.`
+      );
+    }
+    if (res instanceof DataCalc) {
+      throw new M2Error(
+        `${opName || "summarize()"}: lazy callback returned a DataCalc instance; expected a value or array of values.`
+      );
+    }
+    return res;
+  } catch (err) {
+    throw new M2Error(
+      `${"summarize()"}: lazy callback threw an error: ${err && err.message ? err.message : String(err)}`
+    );
+  }
+}
+function processNumericValues(dataCalc, variable, options, collector, errorPrefix, initialState) {
+  const mergedOptions = applyDefaultOptions(options);
+  dataCalc.verifyObservationsContainVariable(variable);
+  let count = 0;
+  let state = initialState;
+  let containsMissing = false;
+  dataCalc.observations.forEach((o) => {
+    if (dataCalc.isNonMissingNumeric(o[variable])) {
+      state = collector(o[variable], state);
+      count++;
+      return;
+    }
+    if (typeof o[variable] === "boolean" && mergedOptions.coerceBooleans) {
+      state = collector(o[variable] ? 1 : 0, state);
+      count++;
+      return;
+    }
+    if (dataCalc.isMissingNumeric(o[variable])) {
+      containsMissing = true;
+      return;
+    }
+    throw new M2Error(
+      `${errorPrefix}: variable ${variable} has non-numeric value ${o[variable]} in this observation: ${JSON.stringify(o)}`
+    );
+  });
+  return { state, count, containsMissing };
+}
+function processSingleValue(value, options, errorPrefix) {
+  const mergedOptions = applyDefaultOptions(options);
+  if (typeof value === "number" && !isNaN(value) && isFinite(value)) {
+    return { value, isMissing: false };
+  } else if (typeof value === "boolean" && mergedOptions.coerceBooleans) {
+    return { value: value ? 1 : 0, isMissing: false };
+  } else if (value === null || value === void 0 || typeof value === "number" && (isNaN(value) || !isFinite(value))) {
+    return { value: 0, isMissing: true };
+  } else {
+    throw new M2Error(`${errorPrefix}: has non-numeric value ${value}`);
+  }
+}
+const varianceInternal = (dataCalc, params, options) => {
+  let variableOrValues = params ? params[0] : void 0;
+  variableOrValues = resolveLazy(variableOrValues, dataCalc);
+  const mergedOptions = applyDefaultOptions(options);
+  if (typeof variableOrValues === "string") {
+    if (!dataCalc.variableExists(variableOrValues)) {
+      return null;
+    }
+    const variable = variableOrValues;
+    const meanResult = processNumericValues(
+      dataCalc,
+      variable,
+      options,
+      (value, sum2) => sum2 + value,
+      "variance()",
+      0
+    );
+    if (meanResult.containsMissing && !mergedOptions.skipMissing) {
+      return null;
+    }
+    if (meanResult.count <= 1) {
+      return null;
+    }
+    const meanValue = meanResult.state / meanResult.count;
+    const varianceResult = processNumericValues(
+      dataCalc,
+      variable,
+      options,
+      (value, sum2) => {
+        const actualValue = typeof value === "boolean" && mergedOptions.coerceBooleans ? value ? 1 : 0 : value;
+        return sum2 + Math.pow(actualValue - meanValue, 2);
+      },
+      "variance()",
+      0
+    );
+    return varianceResult.state / (meanResult.count - 1);
+  } else if (Array.isArray(variableOrValues)) {
+    const validValues = [];
+    let containsMissing = false;
+    for (const value of variableOrValues) {
+      if (typeof value === "number" && !isNaN(value) && isFinite(value)) {
+        validValues.push(value);
+      } else if (typeof value === "boolean" && mergedOptions.coerceBooleans) {
+        validValues.push(value ? 1 : 0);
+      } else if (value === null || value === void 0 || typeof value === "number" && (isNaN(value) || !isFinite(value))) {
+        containsMissing = true;
+      } else {
+        throw new M2Error(`variance(): has non-numeric value ${value}`);
+      }
+    }
+    if (containsMissing && !mergedOptions.skipMissing) {
+      return null;
+    }
+    if (validValues.length <= 1) {
+      return null;
+    }
+    const sum2 = validValues.reduce((acc, val) => acc + val, 0);
+    const mean2 = sum2 / validValues.length;
+    const sumSquaredDiffs = validValues.reduce(
+      (acc, val) => acc + Math.pow(val - mean2, 2),
+      0
+    );
+    return sumSquaredDiffs / (validValues.length - 1);
+  } else {
+    return null;
+  }
+};
+const medianInternal = (dataCalc, params, options) => {
+  let variableOrValues = params ? params[0] : void 0;
+  variableOrValues = resolveLazy(variableOrValues, dataCalc);
+  const mergedOptions = applyDefaultOptions(options);
+  if (typeof variableOrValues === "string") {
+    if (!dataCalc.variableExists(variableOrValues)) {
+      return null;
+    }
+    const variable = variableOrValues;
+    dataCalc.verifyObservationsContainVariable(variable);
+    const values = [];
+    let containsMissing = false;
+    dataCalc.observations.forEach((o) => {
+      if (dataCalc.isNonMissingNumeric(o[variable])) {
+        values.push(o[variable]);
+      } else if (typeof o[variable] === "boolean" && mergedOptions.coerceBooleans) {
+        values.push(o[variable] ? 1 : 0);
+      } else if (dataCalc.isMissingNumeric(o[variable])) {
+        containsMissing = true;
+      } else {
+        throw new M2Error(
+          `median(): variable ${variable} has non-numeric value ${o[variable]} in this observation: ${JSON.stringify(o)}`
+        );
+      }
+    });
+    if (containsMissing && !mergedOptions.skipMissing) {
+      return null;
+    }
+    if (values.length === 0) {
+      return null;
+    }
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    if (values.length % 2 === 0) {
+      return (values[mid - 1] + values[mid]) / 2;
+    } else {
+      return values[mid];
+    }
+  } else if (Array.isArray(variableOrValues)) {
+    const values = [];
+    let containsMissing = false;
+    for (const value of variableOrValues) {
+      if (typeof value === "number" && !isNaN(value) && isFinite(value)) {
+        values.push(value);
+      } else if (typeof value === "boolean" && mergedOptions.coerceBooleans) {
+        values.push(value ? 1 : 0);
+      } else if (value === null || value === void 0 || typeof value === "number" && (isNaN(value) || !isFinite(value))) {
+        containsMissing = true;
+      } else {
+        throw new M2Error(`median(): has non-numeric value ${value}`);
+      }
+    }
+    if (containsMissing && !mergedOptions.skipMissing) {
+      return null;
+    }
+    if (values.length === 0) {
+      return null;
+    }
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    if (values.length % 2 === 0) {
+      return (values[mid - 1] + values[mid]) / 2;
+    } else {
+      return values[mid];
+    }
+  } else {
+    const result = processSingleValue(variableOrValues, options, "median()");
+    if (result.isMissing && !mergedOptions.skipMissing) {
+      return null;
+    }
+    return result.isMissing ? null : result.value;
+  }
+};
+function median(variableOrValues, options) {
+  return SummarizeOperation.leaf(medianInternal, [variableOrValues], options);
+}
+const sdInternal = (dataCalc, params, options) => {
+  let variableOrValues = params ? params[0] : void 0;
+  variableOrValues = resolveLazy(variableOrValues, dataCalc);
+  if (typeof variableOrValues === "string") {
+    if (!dataCalc.variableExists(variableOrValues)) {
+      return null;
+    }
+    const varianceValue = varianceInternal(dataCalc, params, options);
+    if (varianceValue === null) {
+      return null;
+    }
+    return Math.sqrt(varianceValue);
+  } else if (Array.isArray(variableOrValues)) {
+    const newParams = params ? [...params] : [variableOrValues];
+    const varianceValue = varianceInternal(dataCalc, newParams, options);
+    if (varianceValue === null) {
+      return null;
+    }
+    return Math.sqrt(varianceValue);
+  } else {
+    return null;
+  }
+};
+function sd(variableOrValues, options) {
+  return SummarizeOperation.leaf(sdInternal, [variableOrValues], options);
+}
+const scalarInternal = (_dataCalc, params, options) => {
+  let v = params ? params[0] : void 0;
+  if (typeof v === "function") v = v(_dataCalc);
+  if (typeof v === "string") {
+    const re = /^__CHAIN_EXPR__\[(.*?)\]$/;
+    const m = re.exec(v);
+    if (m) {
+      const payload = m[1];
+      let ops = getChainOps(payload);
+      if (!ops) {
+        try {
+          ops = JSON.parse(decodeURIComponent(payload));
+        } catch {
+          ops = void 0;
+        }
+      }
+      if (ops) {
+        let current = _dataCalc;
+        let evaluated = void 0;
+        for (const op of ops) {
+          const method = current[op.name];
+          if (typeof method !== "function") {
+            evaluated = NaN;
+            break;
+          }
+          const res = method.apply(current, op.args);
+          if (res instanceof DataCalc) {
+            current = res;
+            continue;
+          }
+          if (Array.isArray(res)) {
+            evaluated = res.length;
+            break;
+          }
+          if (typeof res === "boolean") {
+            evaluated = res;
+            break;
+          }
+          evaluated = typeof res === "number" ? res : Number(res);
+          break;
+        }
+        if (evaluated === void 0)
+          evaluated = current instanceof DataCalc ? current.length : NaN;
+        if (!Number.isNaN(evaluated)) v = evaluated;
+        else v = null;
+        try {
+          clearChainOps(payload);
+        } catch {
+        }
+      }
+    }
+  }
+  if (typeof v === "object" && v !== null && "summarizeFunction" in v) {
+    try {
+      const op = v;
+      const paramsForOp = Array.isArray(op.parameters) ? op.parameters : op.parameters === void 0 ? void 0 : [op.parameters];
+      const raw = op.summarizeFunction(
+        _dataCalc,
+        paramsForOp,
+        op.options
+      );
+      v = raw;
+    } catch {
+      v = null;
+    }
+  }
+  const result = processSingleValue(v, options, "scalar()");
+  return result.isMissing ? null : result.value;
+};
+function scalar(value) {
+  return SummarizeOperation.leaf(scalarInternal, [value], void 0);
+}
+console.log("\u26AA @m2c2kit/data-calc version 0.8.7 (38a5862e)");
 
 class ColorShapes extends Game {
   constructor() {
@@ -1198,6 +2137,14 @@ class ColorShapes extends Game {
         type: "boolean",
         default: false,
         description: "Should scoring data be generated? Default is false."
+      },
+      scoring_filter_response_time_duration_ms: {
+        type: "array",
+        items: {
+          type: "number"
+        },
+        default: [100, 1e4],
+        description: "When scoring, values of response_time_duration_ms less than the lower bound or greater than the upper bound are discarded. This array contains two numbers, the lower and upper bounds."
       }
     };
     const colorShapesTrialSchema = {
@@ -1330,6 +2277,14 @@ class ColorShapes extends Game {
         format: "date-time",
         description: "ISO 8601 timestamp at the end of the last trial. Null if no trials were completed."
       },
+      response_time_filter_lower_bound: {
+        type: "number",
+        description: "Response times less than this lower bound were discarded when calculating filtered response times."
+      },
+      response_time_filter_upper_bound: {
+        type: "number",
+        description: "Response times greater than this upper bound were discarded when calculating filtered response times."
+      },
       n_trials: {
         type: "integer",
         description: "Number of trials completed."
@@ -1349,6 +2304,158 @@ class ColorShapes extends Game {
       participant_score: {
         type: ["number", "null"],
         description: "Participant-facing score, calculated as (number of correct trials / number of trials attempted) * 100. This is a simple metric to provide feedback to the participant. Null if no trials attempted."
+      },
+      flag_trials_lt_expected: {
+        type: "number",
+        description: "Is the number of completed trials fewer than expected? 1 = true, 0 = false."
+      },
+      flag_trials_gt_expected: {
+        type: "number",
+        description: "Is the number of completed trials greater than expected? 1 = true, 0 = false."
+      },
+      n_trials_HIT: {
+        type: "number",
+        description: "Number of HIT trials (correctly identified a 'different' trial)"
+      },
+      n_trials_MISS: {
+        type: "number",
+        description: "Number of MISS trials (failed to detect a 'different' trial, responded 'same')"
+      },
+      n_trials_FA: {
+        type: "number",
+        description: "Number of False Alarm trials (incorrectly responded 'different' on a 'same' trial)"
+      },
+      n_trials_CR: {
+        type: "number",
+        description: "Number of Correct Rejection trials (correctly responded 'same' on a 'same' trial)"
+      },
+      n_trials_type_same: {
+        type: "number",
+        description: "Number of trials where the true signal type was 'SAME' (presented and response shapes were identical)"
+      },
+      n_trials_type_different: {
+        type: "number",
+        description: "Number of trials where the true signal type was 'DIFFERENT' (response shapes differed from presented)"
+      },
+      HIT_rate: {
+        type: ["number", "null"],
+        description: "Proportion of 'different' trials correctly identified as different. Calculated as n_trials_HIT / n_trials_type_different"
+      },
+      MISS_rate: {
+        type: ["number", "null"],
+        description: "Proportion of 'different' trials incorrectly identified as same. Calculated as 1 - HIT_rate"
+      },
+      FA_rate: {
+        type: ["number", "null"],
+        description: "Proportion of 'same' trials incorrectly identified as different. Calculated as n_trials_FA / n_trials_type_same"
+      },
+      CR_rate: {
+        type: ["number", "null"],
+        description: "Proportion of 'same' trials correctly identified as same. Calculated as 1 - FA_rate"
+      },
+      n_trials_rt_invalid: {
+        type: "number",
+        description: "Number of trials with null or non-positive response times (excluded from RT calculations)"
+      },
+      median_rt_overall_valid: {
+        type: ["number", "null"],
+        description: "Median response time (ms) across all trials with valid (non-null, positive) response times. No outlier filtering applied"
+      },
+      sd_rt_overall_valid: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) across all trials with valid response times. No outlier filtering applied"
+      },
+      median_rt_HIT_valid: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for HIT trials with valid response times. No outlier filtering"
+      },
+      sd_rt_HIT_valid: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for HIT trials with valid response times. No outlier filtering"
+      },
+      median_rt_MISS_valid: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for MISS trials with valid response times. No outlier filtering"
+      },
+      sd_rt_MISS_valid: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for MISS trials with valid response times. No outlier filtering"
+      },
+      median_rt_FA_valid: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for False Alarm trials with valid response times. No outlier filtering"
+      },
+      sd_rt_FA_valid: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for False Alarm trials with valid response times. No outlier filtering"
+      },
+      median_rt_CR_valid: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for Correct Rejection trials with valid response times. No outlier filtering"
+      },
+      sd_rt_CR_valid: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for Correct Rejection trials with valid response times. No outlier filtering"
+      },
+      median_rt_overall_valid_filtered: {
+        type: ["number", "null"],
+        description: "Median response time (ms) across all valid trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      sd_rt_overall_valid_filtered: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) across all valid trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      n_outliers_rt_overall_valid: {
+        type: "number",
+        description: "Number of valid trials removed as RT outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      median_rt_HIT_valid_filtered: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for HIT trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      sd_rt_HIT_valid_filtered: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for HIT trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      n_outliers_rt_HIT_valid: {
+        type: "number",
+        description: "Number of HIT trials removed as RT outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      median_rt_MISS_valid_filtered: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for MISS trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      sd_rt_MISS_valid_filtered: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for MISS trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      n_outliers_rt_MISS_valid: {
+        type: "number",
+        description: "Number of MISS trials removed as RT outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      median_rt_FA_valid_filtered: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for False Alarm trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      sd_rt_FA_valid_filtered: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for False Alarm trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      n_outliers_rt_FA_valid: {
+        type: "number",
+        description: "Number of False Alarm trials removed as RT outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      median_rt_CR_valid_filtered: {
+        type: ["number", "null"],
+        description: "Median response time (ms) for Correct Rejection trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      sd_rt_CR_valid_filtered: {
+        type: ["number", "null"],
+        description: "Standard deviation of response time (ms) for Correct Rejection trials after removing outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
+      },
+      n_outliers_rt_CR_valid: {
+        type: ["number", "null"],
+        description: "Number of Correct Rejection trials removed as RT outliers, as specified in response_time_filter_lower_bound and response_time_filter_upper_bound."
       }
     };
     const translation = {
@@ -1415,8 +2522,8 @@ class ColorShapes extends Game {
        */
       id: "color-shapes",
       publishUuid: "394cb010-2ccf-4a87-9d23-cda7fb07a960",
-      version: "0.8.32 (d289d12c)",
-      moduleMetadata: { "name": "@m2c2kit/assessment-color-shapes", "version": "0.8.32", "dependencies": { "@m2c2kit/addons": "0.3.33", "@m2c2kit/core": "0.3.34" } },
+      version: "0.8.34 (38a5862e)",
+      moduleMetadata: { "name": "@m2c2kit/assessment-color-shapes", "version": "0.8.34", "dependencies": { "@m2c2kit/addons": "0.3.35", "@m2c2kit/core": "0.3.36", "@m2c2kit/data-calc": "0.8.7" } },
       translation,
       shortDescription: "Color Shapes is a visual array change detection task, measuring intra-item feature binding, where participants determine if shapes change color across two sequential presentations of shape stimuli.",
       longDescription: `Color Shapes is a change detection paradigm used to measure visual short-term memory binding (Parra et al., 2009). Participants are asked to memorize the shapes and colors of three different polygons for 3 seconds. The three polygons are then removed from the screen and re-displayed at different locations, either having the same or different colors. Participants are then asked to decide whether the combination of colors and shapes are the "Same" or "Different" between the study and test phases.`,
@@ -1494,6 +2601,12 @@ class ColorShapes extends Game {
         game.trialComplete();
         if (game.getParameter("scoring")) {
           const scores = game.calculateScores([], {
+            rtLowerBound: game.getParameter(
+              "scoring_filter_response_time_duration_ms"
+            )[0],
+            rtUpperBound: game.getParameter(
+              "scoring_filter_response_time_duration_ms"
+            )[1],
             numberOfTrials: game.getParameter("number_of_trials")
           });
           game.addScoringData(scores);
@@ -1916,6 +3029,12 @@ class ColorShapes extends Game {
       } else {
         if (game.getParameter("scoring")) {
           const scores = game.calculateScores(game.data.trials, {
+            rtLowerBound: game.getParameter(
+              "scoring_filter_response_time_duration_ms"
+            )[0],
+            rtUpperBound: game.getParameter(
+              "scoring_filter_response_time_duration_ms"
+            )[1],
             numberOfTrials: game.getParameter("number_of_trials")
           });
           game.addScoringData(scores);
@@ -1959,18 +3078,198 @@ class ColorShapes extends Game {
   }
   calculateScores(data, extras) {
     const dc = new DataCalc(data);
-    const scores = dc.summarize({
+    const n_trials = dc.filter((o) => o.quit_button_pressed === false).length;
+    const scores = dc.mutate({
+      metric_accuracy: (obs) => {
+        const ur = obs.user_response;
+        const uc = obs.user_response_correct;
+        if (ur === "same" && uc === true) return "CR";
+        if (ur === "same" && uc === false) return "MISS";
+        if (ur === "different" && uc === true) return "HIT";
+        if (ur === "different" && uc === false) return "FA";
+        return null;
+      },
+      metric_trial_type: (obs) => {
+        const ur = obs.user_response;
+        const uc = obs.user_response_correct;
+        if (ur === "same" && uc === true) return "SAME";
+        if (ur === "same" && uc === false) return "DIFFERENT";
+        if (ur === "different" && uc === true) return "DIFFERENT";
+        if (ur === "different" && uc === false) return "SAME";
+        return null;
+      },
+      is_valid: (obs) => typeof obs.response_time_duration_ms === "number" && obs.response_time_duration_ms > 0
+    }).summarize({
       activity_begin_iso8601_timestamp: this.beginIso8601Timestamp,
-      first_trial_begin_iso8601_timestamp: dc.arrange("trial_begin_iso8601_timestamp").slice(0).pull("trial_begin_iso8601_timestamp"),
-      last_trial_end_iso8601_timestamp: dc.arrange("-trial_end_iso8601_timestamp").slice(0).pull("trial_end_iso8601_timestamp"),
-      n_trials: dc.length,
-      flag_trials_match_expected: dc.length === extras.numberOfTrials ? 1 : 0,
-      n_trials_correct: dc.filter((obs) => obs.user_response_correct === true).length,
-      n_trials_incorrect: dc.filter(
-        (obs) => obs.user_response_correct === false
-      ).length
-    }).mutate({
-      participant_score: (obs) => obs.n_trials > 0 ? obs.n_trials_correct / obs.n_trials * 100 : null
+      first_trial_begin_iso8601_timestamp: arrange(
+        "trial_begin_iso8601_timestamp"
+      ).slice(0).pull("trial_begin_iso8601_timestamp"),
+      last_trial_end_iso8601_timestamp: arrange(
+        "-trial_end_iso8601_timestamp"
+      ).slice(0).pull("trial_end_iso8601_timestamp"),
+      n_trials,
+      flag_trials_match_expected: n_trials === extras.numberOfTrials ? 1 : 0,
+      flag_trials_lt_expected: n_trials < extras.numberOfTrials ? 1 : 0,
+      flag_trials_gt_expected: n_trials > extras.numberOfTrials ? 1 : 0,
+      // counts by accuracy
+      n_trials_HIT: filter((o) => o.metric_accuracy === "HIT").length,
+      n_trials_MISS: filter((o) => o.metric_accuracy === "MISS").length,
+      n_trials_FA: filter((o) => o.metric_accuracy === "FA").length,
+      n_trials_CR: filter((o) => o.metric_accuracy === "CR").length,
+      // trial types
+      n_trials_type_same: filter((o) => o.metric_trial_type === "SAME").length,
+      n_trials_type_different: filter(
+        (o) => o.metric_trial_type === "DIFFERENT"
+      ).length,
+      // Note: When the summarize operation is a custom function,
+      // () => value, rather than a built in function like sum or mean,
+      // we must provide the DataCalc object as an argument to the
+      // function, and do the filtering and pulling of values on that
+      // object within the function. Specifically below, we must do:
+      //   const denom = d.filter(...).length
+      // NOT
+      //   const denom = filter(...).length
+      // rates
+      HIT_rate: (d) => {
+        const denom = d.filter(
+          (o) => o.metric_trial_type === "DIFFERENT"
+        ).length;
+        return denom > 0 ? d.filter((o) => o.metric_accuracy === "HIT").length / denom : null;
+      },
+      MISS_rate: (d) => {
+        const denom = d.filter(
+          (o) => o.metric_trial_type === "DIFFERENT"
+        ).length;
+        return denom > 0 ? 1 - d.filter((o) => o.metric_accuracy === "HIT").length / denom : null;
+      },
+      FA_rate: (d) => {
+        const denom = d.filter((o) => o.metric_trial_type === "SAME").length;
+        return denom > 0 ? d.filter((o) => o.metric_accuracy === "FA").length / denom : null;
+      },
+      CR_rate: (d) => {
+        const denom = d.filter((o) => o.metric_trial_type === "SAME").length;
+        return denom > 0 ? 1 - d.filter((o) => o.metric_accuracy === "FA").length / denom : null;
+      },
+      // response time summaries
+      // overall valid RTs (>0)
+      median_rt_overall_valid: median(
+        filter((o) => o.is_valid).pull("response_time_duration_ms")
+      ),
+      sd_rt_overall_valid: sd(
+        filter((o) => o.is_valid).pull("response_time_duration_ms")
+      ),
+      // filtered overall RTs
+      median_rt_overall_valid_filtered: median(
+        filter((o) => o.is_valid).filter(
+          (o) => o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      sd_rt_overall_valid_filtered: sd(
+        filter((o) => o.is_valid).filter(
+          (o) => o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      // counts of invalid/outliers
+      n_trials_rt_invalid: filter((o) => !o.is_valid).length,
+      n_outliers_rt_overall_valid: filter((o) => o.is_valid).filter(
+        (o) => o.response_time_duration_ms < extras.rtLowerBound || o.response_time_duration_ms > extras.rtUpperBound
+      ).length,
+      response_time_filter_lower_bound: extras.rtLowerBound,
+      response_time_filter_upper_bound: extras.rtUpperBound,
+      // per-metric RT summaries
+      median_rt_HIT_valid: median(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "HIT").pull("response_time_duration_ms")
+      ),
+      sd_rt_HIT_valid: sd(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "HIT").pull("response_time_duration_ms")
+      ),
+      median_rt_HIT_valid_filtered: median(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "HIT" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      sd_rt_HIT_valid_filtered: sd(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "HIT" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      n_outliers_rt_HIT_valid: filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "HIT").filter(
+        (o) => o.response_time_duration_ms < extras.rtLowerBound || o.response_time_duration_ms > extras.rtUpperBound
+      ).length,
+      median_rt_MISS_valid: median(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "MISS").pull("response_time_duration_ms")
+      ),
+      sd_rt_MISS_valid: sd(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "MISS").pull("response_time_duration_ms")
+      ),
+      median_rt_MISS_valid_filtered: median(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "MISS" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      sd_rt_MISS_valid_filtered: sd(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "MISS" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      n_outliers_rt_MISS_valid: filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "MISS").filter(
+        (o) => o.response_time_duration_ms < extras.rtLowerBound || o.response_time_duration_ms > extras.rtUpperBound
+      ).length,
+      median_rt_FA_valid: median(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "FA").pull("response_time_duration_ms")
+      ),
+      sd_rt_FA_valid: sd(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "FA").pull("response_time_duration_ms")
+      ),
+      median_rt_FA_valid_filtered: median(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "FA" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      sd_rt_FA_valid_filtered: sd(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "FA" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      n_outliers_rt_FA_valid: filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "FA").filter(
+        (o) => o.response_time_duration_ms < extras.rtLowerBound || o.response_time_duration_ms > extras.rtUpperBound
+      ).length,
+      median_rt_CR_valid: median(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "CR").pull("response_time_duration_ms")
+      ),
+      sd_rt_CR_valid: sd(
+        filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "CR").pull("response_time_duration_ms")
+      ),
+      median_rt_CR_valid_filtered: median(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "CR" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      sd_rt_CR_valid_filtered: sd(
+        filter((o) => o.is_valid).filter(
+          (o) => o.metric_accuracy === "CR" && o.response_time_duration_ms >= extras.rtLowerBound && o.response_time_duration_ms <= extras.rtUpperBound
+        ).pull("response_time_duration_ms")
+      ),
+      n_outliers_rt_CR_valid: filter((o) => o.is_valid).filter((o) => o.metric_accuracy === "CR").filter(
+        (o) => o.response_time_duration_ms < extras.rtLowerBound || o.response_time_duration_ms > extras.rtUpperBound
+      ).length,
+      n_trials_correct: filter(
+        (o) => o.metric_accuracy === "HIT" || o.metric_accuracy === "CR"
+      ).length,
+      n_trials_incorrect: filter(
+        (o) => o.metric_accuracy === "MISS" || o.metric_accuracy === "FA"
+      ).length,
+      participant_score: (d) => {
+        const total = d.length;
+        if (total === 0) return null;
+        return d.summarize({
+          correct: parens(
+            scalar(d.filter((o) => o.metric_accuracy === "HIT").length).add(
+              scalar(d.filter((o) => o.metric_accuracy === "CR").length)
+            )
+          ).div(scalar(total)).mul(scalar(100))
+        }).pull("correct");
+      }
     });
     return scores.observations;
   }