@elaraai/e3-ui 1.0.11 → 1.0.12

package/dist/src/experiment/index.js

@@ -0,0 +1,148 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * `Experiment` component — an interactive causal-experiment surface.
+ *
+ * @remarks
+ * `Experiment` lets a domain expert ask *"did X change Y?"* against a dataset
+ * and trust the answer, without meeting a statistician's vocabulary. It is a
+ * registered extension component (architecturally like {@link Ontology}): the
+ * author writes one tag, `Experiment.Root({ … })`; the React renderer lives in
+ * `@elaraai/e3-ui-components` and is wired via
+ * `implementUIComponent(Experiment.Component, EastChakraExperiment)`.
+ *
+ * **Generic over the input row, like `Table`.** The author binds the input
+ * dataset (`data: BoundValue<ArrayType<Row>>`); the renderer introspects its
+ * row struct to drive the treatment / outcome / confounder pickers, so the
+ * **end user** re-frames the experiment from the dataset's own columns.
+ *
+ * **The user adjusts → results go stale → Run re-computes.** Editing a picker
+ * stages a new {@link ExperimentSpecType} and marks the result stale; **Run**
+ * calls the author-supplied estimator functions ({@link Func.bind} handles) and
+ * the answer arrives reactively; **Commit** appends to the journal. The causal
+ * compute (DoWhy / EconML) lives entirely in those function bodies, so `e3-ui`
+ * never imports `east-py-datascience`.
+ *
+ * **Visual-first and derived.** Because the user frames an arbitrary
+ * experiment, nothing on the result side is hand-authored — every word is a
+ * column name the user picked, a number an estimator returned, or a status
+ * derived by rule (interval clears zero → HIGHER / LOWER; spans zero → NO CLEAR
+ * EFFECT; raw and adjusted disagree in sign → the "misleading" banner). The
+ * contract types ({@link ExperimentSpecType}, {@link ExperimentResultType}, …)
+ * live in {@link "./experiment/types"} and are reached via `Experiment.Types.*`.
+ *
+ * @packageDocumentation
+ */
+import { East, NullType, BooleanType, StringType, ArrayType, StructType, VariantType, OptionType, none, some, variant, } from '@elaraai/east';
+import { EastUI } from '@elaraai/east-ui';
+import { DiffBindingType } from '../data.js';
+import { FuncBindingType } from '../func.js';
+import { ExperimentSpecType, ExperimentResultType, RefuteResultType, DoseResultType, JournalType, ColumnMetaType, } from './types.js';
+// Re-export the contract types so consumers can reach them from the component
+// module too (the canonical home is `./types`).
+export { WeightingSchemeType, EstimatorType, TargetUnitsType, TrimType, ExperimentSpecType, CiType, BalanceRowType, ExperimentResultType, RefuteKindType, RefuteCheckType, RefuteResultType, DoseSegmentType, DoseResultType, JournalRowType, JournalType, ColumnMetaType, } from './types.js';
+// ============================================================================
+// Component payload — descriptors only (binding handles + options).
+// ============================================================================
+/** Initial result tab variant — `answer` (default), `trust`, or `dose`. */
+export const ExperimentTabType = VariantType({ answer: NullType, trust: NullType, dose: NullType });
+/**
+ * The `Experiment` component payload — binding descriptors + options. Renderers
+ * decode this and resolve each binding to a live, reactive value / call handle.
+ *
+ * @property data - {@link DiffBindingType} for the input dataset — the renderer
+ *   introspects its row struct for the pickers and passes it to the functions.
+ * @property spec - {@link DiffBindingType} for the staged {@link ExperimentSpecType}.
+ * @property estimate - {@link FuncBindingType} for the `estimate` function.
+ * @property refute - Optional {@link FuncBindingType} for the `refute` function.
+ * @property dose - Optional {@link FuncBindingType} for the `dose` function.
+ * @property journal - Optional {@link DiffBindingType} for the committed-experiment journal.
+ * @property columnMeta - Optional per-column display metadata.
+ * @property readonly - Render without the Run / Commit / edit affordances.
+ * @property defaultTab - Initial result tab ({@link ExperimentTabType}).
+ */
+export const ExperimentPayloadType = StructType({
+    data: DiffBindingType,
+    spec: DiffBindingType,
+    estimate: FuncBindingType,
+    refute: OptionType(FuncBindingType),
+    dose: OptionType(FuncBindingType),
+    journal: OptionType(DiffBindingType),
+    columnMeta: OptionType(ColumnMetaType),
+    readonly: OptionType(BooleanType),
+    defaultTab: OptionType(ExperimentTabType),
+});
+/**
+ * Internal {@link EastUI.component} carrier. The React renderer registers
+ * against this in `@elaraai/e3-ui-components`.
+ */
+export const ExperimentComponent = EastUI.component('Experiment', ExperimentPayloadType, { optional: true });
+/**
+ * Build an Experiment surface bound to an input dataset + estimator functions.
+ *
+ * @typeParam Row - The input dataset's row struct, inferred from `data`.
+ * @param options - {@link ExperimentOptions}. `data`, `spec` and `estimate` are
+ *   required; the rest are optional.
+ * @returns An East expression of {@link UIComponentType}.
+ */
+function createExperiment(options) {
+    const defaultTab = options.defaultTab === undefined
+        ? none
+        : some(East.value(variant(options.defaultTab, null), ExperimentTabType));
+    const columnMeta = options.columns === undefined
+        ? none
+        : some(East.value(new Map(Object.entries(options.columns).map(([k, c]) => [k, {
+                label: c?.label !== undefined ? some(c.label) : none,
+                unit: c?.unit !== undefined ? some(c.unit) : none,
+                higherIsBetter: c?.higherIsBetter !== undefined ? some(c.higherIsBetter) : none,
+            }])), ColumnMetaType));
+    return ExperimentComponent.Root({
+        data: options.data.binding,
+        spec: options.spec.binding,
+        estimate: options.estimate.binding,
+        refute: options.refute !== undefined ? some(options.refute.binding) : none,
+        dose: options.dose !== undefined ? some(options.dose.binding) : none,
+        journal: options.journal !== undefined ? some(options.journal.binding) : none,
+        columnMeta,
+        readonly: options.readonly ?? none,
+        defaultTab,
+    });
+}
+/**
+ * The Experiment component namespace. Surfaces an interactive causal-experiment
+ * over a bound input dataset + estimator functions, generic over the row struct
+ * (the `Table` pattern), with the staged-binding machinery the rest of e3-ui
+ * uses.
+ *
+ * @remarks
+ * Use `Experiment.Root({ data, spec, estimate, refute, dose, journal })` inside
+ * a `Reactive` block. The `Component` property is the {@link EastUI.component}
+ * carrier the renderer registers against; `Types` exposes the render-contract
+ * value types (`Spec`, `Result`, `Refute`, `Dose`, `Journal`, …).
+ */
+export const Experiment = {
+    Root: createExperiment,
+    /** The internal {@link EastUI.component} carrier renderers register against. */
+    Component: ExperimentComponent,
+    Types: {
+        /** Rendered payload struct (bindings + options). */
+        Payload: ExperimentPayloadType,
+        /** The experiment-spec value type (what the pickers stage). */
+        Spec: ExperimentSpecType,
+        /** The estimator answer value type. */
+        Result: ExperimentResultType,
+        /** The robustness-battery value type. */
+        Refute: RefuteResultType,
+        /** The dose-response value type. */
+        Dose: DoseResultType,
+        /** The committed-experiment journal value type. */
+        Journal: JournalType,
+        /** Optional per-column display metadata. */
+        ColumnMeta: ColumnMetaType,
+        /** Initial result tab variant. */
+        Tab: ExperimentTabType,
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/src/experiment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/experiment/index.ts"],"names":[],"mappings":"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"}