@iyulab/u-doe 0.6.2 → 0.8.0

package/README.md

@@ -106,7 +106,7 @@ println!("Required replicates: {n}");
 | Design | Function | Use Case |
 |--------|----------|----------|
 | Full Factorial | `full_factorial(k)` | k = 2..7, all factor combinations |
-| Fractional Factorial | `fractional_factorial(k, p)` | Screening, k=3..7, p=1..3 |
+| Fractional Factorial | `fractional_factorial(k, p)` | Screening, k=4..7, p=1..3 |
 | Plackett-Burman | `plackett_burman(k)` | Screening, k ≤ 19, N = 8/12/16/20 |
 | CCD | `ccd(k, alpha, n_center)` | RSM, k = 2..6 |
 | Box-Behnken | `box_behnken(k, n_center)` | RSM, k = 3/4/5 |
@@ -157,6 +157,21 @@ Generate a 2^k full factorial design (k = 1..7).
 
 Generate a 2^(k-p) fractional factorial design (k = 4..7, p = 1..3).
 
+#### `fractional_factorial_info(k, p) -> FractionalInfo`
+
+Metadata for the fraction `fractional_factorial(k, p)` emits: resolution, defining relation, and generator equations. Use it to derive the alias structure of the design you actually received instead of pairing the matrix with an external published table.
+
+**Output:**
+```json
+{
+  "k": 7,
+  "p": 3,
+  "resolution": "IV",
+  "defining_relation": "I=ABCE=BCDF=ACDG=ADEF=BDEG=ABFG=CEFG",
+  "generators": ["E=ABC", "F=BCD", "G=ACD"]
+}
+```
+
 #### `plackett_burman(k) -> DesignMatrix`
 
 Generate a Plackett-Burman screening design (k = 1..19).
@@ -204,11 +219,14 @@ Estimate main effects and interactions for a 2-level factorial design.
     { "name": "A",   "columns": [0],    "estimate": 21.6,  "sum_of_squares": 1870.6, "percent_contribution": 45.2 },
     { "name": "A:C", "columns": [0, 2], "estimate": -18.1, "sum_of_squares": 1314.1, "percent_contribution": 31.7 }
   ],
-  "half_normal": [[18.1, 0.57], [21.6, 1.15]] }
+  "half_normal": [{ "term_index": 1, "abs_effect": 18.1, "quantile": 0.57 },
+                  { "term_index": 0, "abs_effect": 21.6, "quantile": 1.15 }] }
 ```
 
 Interaction names join factor names with `":"` (since 0.5.0; previously bare concatenation `"AC"`). `columns` holds the design-matrix column indices of the term's factors — use it for display formatting (e.g. `"A × C"`) instead of parsing `name`.
 
+Each `half_normal` point carries `term_index` — an index into `effects` — so a point can be labelled directly (e.g. `effects[point.term_index].name`). The points are sorted by `|effect|`, a **different order** from `effects` (model-term order), so pairing them positionally (`effects[i]` ↔ `half_normal[i]`) mislabels every point; always use `term_index`.
+
 #### `fit_rsm(design, responses, factor_names) -> RsmModel`
 
 Fit a second-order Response Surface Model via OLS.
@@ -231,13 +249,17 @@ Compute the steepest ascent path from a fitted RSM model.
 
 Compute Derringer-Suich desirability for multiple responses.
 
-**Input:** `specs`: `[{ "goal": "Maximize"|"Minimize"|"Target", "lower": 0, "target": 100, "upper": 100, "s1": 1, "s2": 1 }]`, `responses`: `Float64Array`
+**Input:** `specs`: `[{ "goal": "Maximize"|"Minimize"|"Target", "lower": 0, "target": 100, "upper": 100, "s1": 1, "s2": 1, "importance": 1 }]`, `responses`: `Float64Array`
+
+`s1`/`s2` are curve-shape exponents (`s = 1` linear, `> 1` convex/stricter, `< 1` concave). `importance` (optional, default `1`) is the Derringer-Suich response weight rᵢ — it is **distinct from** the shape exponents: raise `importance` to make a response count more in the aggregate, not to reshape its curve.
 
 **Output:**
 ```json
 { "individual": [0.8, 0.6], "overall": 0.69 }
 ```
 
+`overall` is the importance-weighted geometric mean D = (∏ dᵢ^rᵢ)^(1/Σrᵢ); with all weights at the default `1` this is the plain geometric mean.
+
 #### `two_level_factorial_power(k, p, n_replicates, effect_size, sigma, alpha) -> f64`
 
 Compute statistical power of a 2^(k-p) factorial design. Returns power in [0, 1].

package/node/u_doe.cjs

@@ -73,10 +73,13 @@ exports.definitive_screening = definitive_screening;
  * Compute Derringer-Suich desirability for multiple responses.
  *
  * `specs`: native array of response specification objects, each:
- *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2 }`
+ *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2, importance? }`
+ *   where `s1`/`s2` are curve-shape exponents and the optional `importance`
+ *   (default 1.0) is the Derringer-Suich weight rᵢ for the overall aggregation.
  * `responses`: flat array of observed response values (one per spec).
  *
- * Returns `{ individual: [f64], overall: f64 }`.
+ * Returns `{ individual: [f64], overall: f64 }` where `overall` is the
+ * importance-weighted geometric mean (∏ dᵢ^rᵢ)^(1/Σrᵢ).
  *
  * # Errors
  * Returns an error string if `specs` has the wrong shape (native JS values,
@@ -138,7 +141,10 @@ exports.doe_anova = doe_anova;
  * `max_order`: maximum interaction order (1 = main effects only, 2 = + 2FI, 3 = + 3FI).
  *
  * Returns `{ effects: [{ name, columns, estimate, sum_of_squares, percent_contribution }],
- *            half_normal: [[abs_effect, quantile]] }`.
+ *            half_normal: [{ term_index, abs_effect, quantile }] }`.
+ * Each `half_normal` point carries `term_index` (an index into `effects`) so the
+ * point can be labelled directly — the points are sorted by `|effect|`, a
+ * different order from `effects`, so positional pairing would mislabel them.
  *
  * # Errors
  * Returns an error string if dimensions do not match or an argument has the
@@ -213,6 +219,33 @@ function fractional_factorial(k, p) {
 }
 exports.fractional_factorial = fractional_factorial;
 
+/**
+ * Metadata for a 2^(k-p) fractional factorial design: resolution, defining
+ * relation, and generator equations of the fraction `fractional_factorial(k, p)`
+ * actually emits — lets consumers derive the alias structure without pairing
+ * the design with an external published table.
+ *
+ * Returns `{ k: usize, p: usize, resolution: "III"|"IV"|"V",
+ * defining_relation: str, generators: [str] }` —
+ * e.g. `{ k: 7, p: 3, resolution: "IV",
+ * defining_relation: "I=ABCE=BCDF=ACDG=ADEF=BDEG=ABFG=CEFG",
+ * generators: ["E=ABC", "F=BCD", "G=ACD"] }`.
+ *
+ * # Errors
+ * Returns an error string if the (k, p) combination is not in the standard table.
+ * @param {number} k
+ * @param {number} p
+ * @returns {any}
+ */
+function fractional_factorial_info(k, p) {
+    const ret = wasm.fractional_factorial_info(k, p);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+exports.fractional_factorial_info = fractional_factorial_info;
+
 /**
  * Generate a 2^k full factorial design.
  *

package/node/u_doe.d.cts

@@ -42,10 +42,13 @@ export function definitive_screening(k: number): any;
  * Compute Derringer-Suich desirability for multiple responses.
  *
  * `specs`: native array of response specification objects, each:
- *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2 }`
+ *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2, importance? }`
+ *   where `s1`/`s2` are curve-shape exponents and the optional `importance`
+ *   (default 1.0) is the Derringer-Suich weight rᵢ for the overall aggregation.
  * `responses`: flat array of observed response values (one per spec).
  *
- * Returns `{ individual: [f64], overall: f64 }`.
+ * Returns `{ individual: [f64], overall: f64 }` where `overall` is the
+ * importance-weighted geometric mean (∏ dᵢ^rᵢ)^(1/Σrᵢ).
  *
  * # Errors
  * Returns an error string if `specs` has the wrong shape (native JS values,
@@ -81,7 +84,10 @@ export function doe_anova(design: any, responses: Float64Array, factor_names: an
  * `max_order`: maximum interaction order (1 = main effects only, 2 = + 2FI, 3 = + 3FI).
  *
  * Returns `{ effects: [{ name, columns, estimate, sum_of_squares, percent_contribution }],
- *            half_normal: [[abs_effect, quantile]] }`.
+ *            half_normal: [{ term_index, abs_effect, quantile }] }`.
+ * Each `half_normal` point carries `term_index` (an index into `effects`) so the
+ * point can be labelled directly — the points are sorted by `|effect|`, a
+ * different order from `effects`, so positional pairing would mislabel them.
  *
  * # Errors
  * Returns an error string if dimensions do not match or an argument has the
@@ -119,6 +125,23 @@ export function fit_rsm(design: any, responses: Float64Array, factor_names: any)
  */
 export function fractional_factorial(k: number, p: number): any;
 
+/**
+ * Metadata for a 2^(k-p) fractional factorial design: resolution, defining
+ * relation, and generator equations of the fraction `fractional_factorial(k, p)`
+ * actually emits — lets consumers derive the alias structure without pairing
+ * the design with an external published table.
+ *
+ * Returns `{ k: usize, p: usize, resolution: "III"|"IV"|"V",
+ * defining_relation: str, generators: [str] }` —
+ * e.g. `{ k: 7, p: 3, resolution: "IV",
+ * defining_relation: "I=ABCE=BCDF=ACDG=ADEF=BDEG=ABFG=CEFG",
+ * generators: ["E=ABC", "F=BCD", "G=ACD"] }`.
+ *
+ * # Errors
+ * Returns an error string if the (k, p) combination is not in the standard table.
+ */
+export function fractional_factorial_info(k: number, p: number): any;
+
 /**
  * Generate a 2^k full factorial design.
  *

package/package.json

@@ -5,7 +5,7 @@
     "iyulab"
   ],
   "description": "Design of Experiments (DOE) framework: factorial, Plackett-Burman, CCD, Box-Behnken, Taguchi, effects analysis, RSM, and desirability optimization.",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/u_doe.d.ts

@@ -42,10 +42,13 @@ export function definitive_screening(k: number): any;
  * Compute Derringer-Suich desirability for multiple responses.
  *
  * `specs`: native array of response specification objects, each:
- *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2 }`
+ *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2, importance? }`
+ *   where `s1`/`s2` are curve-shape exponents and the optional `importance`
+ *   (default 1.0) is the Derringer-Suich weight rᵢ for the overall aggregation.
  * `responses`: flat array of observed response values (one per spec).
  *
- * Returns `{ individual: [f64], overall: f64 }`.
+ * Returns `{ individual: [f64], overall: f64 }` where `overall` is the
+ * importance-weighted geometric mean (∏ dᵢ^rᵢ)^(1/Σrᵢ).
  *
  * # Errors
  * Returns an error string if `specs` has the wrong shape (native JS values,
@@ -81,7 +84,10 @@ export function doe_anova(design: any, responses: Float64Array, factor_names: an
  * `max_order`: maximum interaction order (1 = main effects only, 2 = + 2FI, 3 = + 3FI).
  *
  * Returns `{ effects: [{ name, columns, estimate, sum_of_squares, percent_contribution }],
- *            half_normal: [[abs_effect, quantile]] }`.
+ *            half_normal: [{ term_index, abs_effect, quantile }] }`.
+ * Each `half_normal` point carries `term_index` (an index into `effects`) so the
+ * point can be labelled directly — the points are sorted by `|effect|`, a
+ * different order from `effects`, so positional pairing would mislabel them.
  *
  * # Errors
  * Returns an error string if dimensions do not match or an argument has the
@@ -119,6 +125,23 @@ export function fit_rsm(design: any, responses: Float64Array, factor_names: any)
  */
 export function fractional_factorial(k: number, p: number): any;
 
+/**
+ * Metadata for a 2^(k-p) fractional factorial design: resolution, defining
+ * relation, and generator equations of the fraction `fractional_factorial(k, p)`
+ * actually emits — lets consumers derive the alias structure without pairing
+ * the design with an external published table.
+ *
+ * Returns `{ k: usize, p: usize, resolution: "III"|"IV"|"V",
+ * defining_relation: str, generators: [str] }` —
+ * e.g. `{ k: 7, p: 3, resolution: "IV",
+ * defining_relation: "I=ABCE=BCDF=ACDG=ADEF=BDEG=ABFG=CEFG",
+ * generators: ["E=ABC", "F=BCD", "G=ACD"] }`.
+ *
+ * # Errors
+ * Returns an error string if the (k, p) combination is not in the standard table.
+ */
+export function fractional_factorial_info(k: number, p: number): any;
+
 /**
  * Generate a 2^k full factorial design.
  *

package/u_doe.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./u_doe_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    box_behnken, ccd, definitive_screening, desirability, doe_anova, estimate_effects, fit_rsm, fractional_factorial, full_factorial, plackett_burman, signal_to_noise, simplex_centroid, simplex_lattice, steepest_ascent, taguchi_array, two_level_factorial_power
+    box_behnken, ccd, definitive_screening, desirability, doe_anova, estimate_effects, fit_rsm, fractional_factorial, fractional_factorial_info, full_factorial, plackett_burman, signal_to_noise, simplex_centroid, simplex_lattice, steepest_ascent, taguchi_array, two_level_factorial_power
 } from "./u_doe_bg.js";

package/u_doe_bg.js

@@ -68,10 +68,13 @@ export function definitive_screening(k) {
  * Compute Derringer-Suich desirability for multiple responses.
  *
  * `specs`: native array of response specification objects, each:
- *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2 }`
+ *   `{ goal: "Maximize"|"Minimize"|"Target", lower, target, upper, s1, s2, importance? }`
+ *   where `s1`/`s2` are curve-shape exponents and the optional `importance`
+ *   (default 1.0) is the Derringer-Suich weight rᵢ for the overall aggregation.
  * `responses`: flat array of observed response values (one per spec).
  *
- * Returns `{ individual: [f64], overall: f64 }`.
+ * Returns `{ individual: [f64], overall: f64 }` where `overall` is the
+ * importance-weighted geometric mean (∏ dᵢ^rᵢ)^(1/Σrᵢ).
  *
  * # Errors
  * Returns an error string if `specs` has the wrong shape (native JS values,
@@ -131,7 +134,10 @@ export function doe_anova(design, responses, factor_names, effect_names) {
  * `max_order`: maximum interaction order (1 = main effects only, 2 = + 2FI, 3 = + 3FI).
  *
  * Returns `{ effects: [{ name, columns, estimate, sum_of_squares, percent_contribution }],
- *            half_normal: [[abs_effect, quantile]] }`.
+ *            half_normal: [{ term_index, abs_effect, quantile }] }`.
+ * Each `half_normal` point carries `term_index` (an index into `effects`) so the
+ * point can be labelled directly — the points are sorted by `|effect|`, a
+ * different order from `effects`, so positional pairing would mislabel them.
  *
  * # Errors
  * Returns an error string if dimensions do not match or an argument has the
@@ -203,6 +209,32 @@ export function fractional_factorial(k, p) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Metadata for a 2^(k-p) fractional factorial design: resolution, defining
+ * relation, and generator equations of the fraction `fractional_factorial(k, p)`
+ * actually emits — lets consumers derive the alias structure without pairing
+ * the design with an external published table.
+ *
+ * Returns `{ k: usize, p: usize, resolution: "III"|"IV"|"V",
+ * defining_relation: str, generators: [str] }` —
+ * e.g. `{ k: 7, p: 3, resolution: "IV",
+ * defining_relation: "I=ABCE=BCDF=ACDG=ADEF=BDEG=ABFG=CEFG",
+ * generators: ["E=ABC", "F=BCD", "G=ACD"] }`.
+ *
+ * # Errors
+ * Returns an error string if the (k, p) combination is not in the standard table.
+ * @param {number} k
+ * @param {number} p
+ * @returns {any}
+ */
+export function fractional_factorial_info(k, p) {
+    const ret = wasm.fractional_factorial_info(k, p);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Generate a 2^k full factorial design.
  *