/** * Copyright (c) 2025 Elara AI Pty Ltd * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details. */ /** * Plain-language **guidance** for every explainable element of the Experiment * surface — so a domain expert (e.g. a marketer) can hover any heading, control * or result and understand it without a statistician's vocabulary. * * This is a **built-in glossary**: the *concepts* are universal across every * experiment, so they're authored once here, never per-experiment and never by * the developer who drops in ``. The only per-experiment part is the * **nouns** — `{treatment}` / `{outcome}` / `{feature}` are interpolated from the * (ran) config's column names (run through `columns` labels), and `{subject}` / * `{subjects}` is the neutral noun for a row (`record(s)` — the component is * generic over any causal-analytics dataset, so it never assumes customers / * batches / patients). Result *specifics* (the actual numbers) stay derived at * the call site; here we only explain what a thing *means*. * * Each entry is three tiers of depth, shown stacked in the hover card: * - `gist` — Tier 1: one jargon-free sentence (what it is). * - `detail` — Tier 2: why it matters / what to do with it. * - `jargon` — Tier 3: the technical name, muted, for trust + the curious. */ /** One glossary entry — three tiers of depth. */ export interface HelpEntry { /** The heading/term (the card title). */ term: string; /** Tier 1 — one plain sentence. */ gist: string; /** Tier 2 — why it matters / what to do. */ detail: string; /** Tier 3 — the technical name it maps to (for the curious). */ jargon?: string; } /** Substitute `{treatment}` / `{outcome}` / `{feature}` (and any extra) tokens. */ export declare function fillHelp(entry: HelpEntry, vars: Record): HelpEntry; /** The glossary, keyed by stable element id. */ export declare const HELP: { readonly guidance: { readonly term: "Guidance"; readonly gist: "Plain-language explainers for everything on this surface."; readonly detail: "While this is on, hover any heading, value or chart label to see what it means — in business terms, with the statistical name underneath. Click to turn it off."; }; readonly header: { readonly term: "The question"; readonly gist: "You’re asking whether {treatment} actually moved {outcome}."; readonly detail: "Pick the lever you changed and the result you cared about, then hit Run — the surface answers whether the change is real and trustworthy."; readonly jargon: "a binary-treatment causal effect"; }; readonly step_treatment: { readonly term: "What did you change?"; readonly gist: "The lever you’re testing — a yes/no flag on each {subject}."; readonly detail: "It splits {subjects} into a “did” group and a “didn’t” group; the whole experiment compares those two."; readonly jargon: "the treatment (binary)"; }; readonly step_outcome: { readonly term: "What did you want it to improve?"; readonly gist: "The result you’re hoping {treatment} moved."; readonly detail: "A number measured on each {subject} (revenue, a duration, a score, …). The effect is the change in this we can credit to the lever."; readonly jargon: "the outcome"; }; readonly step_confounders: { readonly term: "What else was different?"; readonly gist: "Things about the “did” group that could also explain the change."; readonly detail: "If the {subjects} you treated already differed on something that matters — bigger, older, higher-value — that, not the lever, could be moving the result. We level the playing field on each of these so the comparison is fair. Add the ones you suspect."; readonly jargon: "confounders / the backdoor adjustment set"; }; readonly step_population: { readonly term: "Which {subjects}?"; readonly gist: "Narrow the experiment to a slice of the {subjects}."; readonly detail: "Filter to a subset you care about — a region, a period, a category — before measuring, so the answer is about the {subjects} that matter."; readonly jargon: "population / cohort filter"; }; readonly adv_method: { readonly term: "How to compare"; readonly gist: "The maths used to make the like-for-like comparison."; readonly detail: "“Regression” fits a line through the confounders; “re-weighting” up-weights rare look-alikes. They usually agree — if they don’t, treat the result with care."; readonly jargon: "estimator: linear regression vs propensity-score weighting"; }; readonly adv_estimand: { readonly term: "Answer for"; readonly gist: "Who the effect is reported for."; readonly detail: "“All” averages over everyone; “only treated” asks what the lever did for the {subjects} you actually treated — useful when you’d only ever apply it to them."; readonly jargon: "estimand: ATE vs ATT"; }; readonly confounder_imbalance: { readonly term: "How lopsided this one was"; readonly gist: "How different the two groups were on this factor, before adjusting."; readonly detail: "A long bar means the treated and untreated {subjects} started far apart here — exactly the kind of gap the adjustment has to close."; readonly jargon: "standardised mean difference (SMD)"; }; readonly tab_answer: { readonly term: "Answer"; readonly gist: "The headline: did {treatment} move {outcome}, and by how much?"; readonly detail: "Shows the raw gap, the fair like-for-like estimate, and an honest verdict."; }; readonly tab_trust: { readonly term: "Can we trust it?"; readonly gist: "The stress tests we ran to try to break the answer."; readonly detail: "Each check probes a way the result could be a fluke; green means it held up."; }; readonly tab_dose: { readonly term: "How much?"; readonly gist: "How the result changes as a factor goes up or down."; readonly detail: "Not just yes/no — the shape of the response, so you can find the sweet spot."; }; readonly answer_effect: { readonly term: "Like-for-like effect"; readonly gist: "The change in {outcome} we can credit to {treatment}."; readonly detail: "It compares treated vs untreated {subjects} who were otherwise similar — so it strips out “who you targeted” and leaves the lever’s real impact."; readonly jargon: "the backdoor-adjusted average treatment effect"; }; readonly answer_ci: { readonly term: "95% range"; readonly gist: "Where the true effect most likely sits."; readonly detail: "If this range doesn’t cross 0, the effect is real, not noise. The wider it is, the less certain — usually because of fewer {subjects}."; readonly jargon: "95% confidence interval"; }; readonly answer_flip: { readonly term: "Raw and like-for-like disagree"; readonly gist: "The plain average points one way; the fair comparison points the other."; readonly detail: "This happens when the treated group differed sharply on a confounder. Trust the like-for-like number — the raw gap is misleading here."; readonly jargon: "confounding / Simpson’s-paradox sign flip"; }; readonly answer_cautious: { readonly term: "Treat this as provisional"; readonly gist: "We got a number, but a trust check failed."; readonly detail: "The estimate may still be driven by something we didn’t adjust for. See “Can we trust it?” before acting on it."; readonly jargon: "adjustment_insufficient verdict"; }; readonly forest_plot: { readonly term: "Raw average vs. like-for-like"; readonly gist: "The misleading number next to the fair one."; readonly detail: "Each bar is an estimate with its uncertainty range; the dashed line is “no effect”. A bar clear of that line is a real change."; readonly jargon: "a forest plot of naive vs adjusted estimates"; }; readonly forest_naive: { readonly term: "Raw average"; readonly gist: "The plain difference, with no adjusting."; readonly detail: "Just treated-minus-untreated. It mixes in who you targeted, so it can mislead — it’s here only as the “before” picture."; readonly jargon: "the unadjusted mean difference"; }; readonly forest_adjusted: { readonly term: "Like-for-like"; readonly gist: "The fair comparison after levelling the confounders."; readonly detail: "This is the number to act on — what {treatment} did among otherwise-similar {subjects}."; readonly jargon: "the adjusted effect"; }; readonly balance: { readonly term: "How unbalanced each one was"; readonly gist: "How far apart the two groups started on each factor."; readonly detail: "Big bars are the factors the adjustment had to work hardest to correct — and the ones most worth double-checking."; readonly jargon: "pre-adjustment covariate balance (SMD)"; }; readonly counts: { readonly term: "The {subject} counts"; readonly gist: "How many {subjects} went into the comparison."; readonly detail: "“Compared like-for-like” are the ones with a fair match on the other side; “no fair match” were set aside because nobody comparable existed."; readonly jargon: "n total / on-support / off-support"; }; readonly overlap_histogram: { readonly term: "Do the two groups overlap?"; readonly gist: "Whether treated and untreated {subjects} actually look alike anywhere."; readonly detail: "Each bar is how many {subjects} sit at a given “likelihood of being treated”. Where the two arms both have bars, a fair comparison exists; if they barely meet, there’s nothing to compare."; readonly jargon: "propensity-score overlap / common support"; }; readonly refusal_positivity: { readonly term: "No like-for-like comparison exists"; readonly gist: "The treated and untreated {subjects} are too different to compare."; readonly detail: "For almost every treated {subject} there’s no similar untreated one (or vice-versa), so there’s no fair “other side”. We refuse rather than extrapolate into thin air. Try fewer or different confounders."; readonly jargon: "positivity / overlap violation"; }; readonly refusal_not_estimable: { readonly term: "Can’t be estimated"; readonly gist: "Almost every {subject} is on one side of {treatment}, so there’s no comparison group."; readonly detail: "Measuring an effect needs a decent number of {subjects} who got the lever AND who didn’t. When one side is just a handful, we refuse to guess rather than read too much into a few people."; readonly jargon: "no treatment variation"; }; readonly trust_intro: { readonly term: "Can we trust it?"; readonly gist: "Before believing the answer, we tried to break it."; readonly detail: "Each row is a different way the result could be a fluke; colour shows whether it held up (pass) or wobbled (caution)."; }; readonly check_shuffle: { readonly term: "Shuffle test"; readonly gist: "We randomly re-label who got {treatment} and re-measure."; readonly detail: "On fake labels a genuine effect should collapse to nothing. If a “fake” effect still appears, the real one isn’t trustworthy."; readonly jargon: "placebo / permutation refuter"; }; readonly check_dropsome: { readonly term: "Drop-some test"; readonly gist: "We re-run on random slices of the {subjects}."; readonly detail: "A trustworthy effect barely moves when you drop some data; a jumpy one is resting on a few {subjects}."; readonly jargon: "data-subset refuter"; }; readonly check_decoy: { readonly term: "Decoy factor"; readonly gist: "We add a totally random extra factor and re-measure."; readonly detail: "A made-up factor shouldn’t change the answer. If it does, the model is over-reacting to noise."; readonly jargon: "random-common-cause refuter"; }; readonly check_hidden: { readonly term: "Hidden cause"; readonly gist: "How strong an unrecorded cause would have to be to overturn the result."; readonly detail: "Something you didn’t measure could drive both who got {treatment} and {outcome}. “Holds throughout” means only an implausibly strong hidden cause could flip it."; readonly jargon: "unobserved-confounding sensitivity / E-value"; }; readonly sensitivity: { readonly term: "Effect as a hidden cause gets stronger"; readonly gist: "What happens to the effect if an unrecorded cause is dialled up."; readonly detail: "The line is the estimate as a simulated hidden cause grows. The point where it crosses 0 is how much hidden bias it would take to erase the result."; readonly jargon: "sensitivity (tipping-point) curve"; }; readonly dose_curve: { readonly term: "{outcome} gained vs. {feature}"; readonly gist: "How {outcome} responds as {feature} goes up."; readonly detail: "The line is the average change in {outcome} at each level of {feature}, with its uncertainty band — the shape tells you where more pays off and where it flattens."; readonly jargon: "accumulated local effects (ALE) dose-response"; }; readonly dose_here: { readonly term: "You are here"; readonly gist: "Where most of your {subjects} currently sit on {feature}."; readonly detail: "The busiest level today — your starting point for deciding whether to push higher or lower."; readonly jargon: "the modal bin"; }; readonly dose_sweet: { readonly term: "Sweet spot"; readonly gist: "Where the gains are solid and start to flatten."; readonly detail: "Past here, pushing {feature} higher buys little extra {outcome} — a sensible target."; readonly jargon: "the diminishing-returns knee"; }; readonly dose_reco: { readonly term: "Recommended"; readonly gist: "The level of {feature} we’d aim for."; readonly detail: "The sweet-spot level and the {outcome} you’d expect there, with its range — and the trade-off of going one step further."; readonly jargon: "the recommended operating point"; }; readonly dose_marginal: { readonly term: "Extra {outcome} per step"; readonly gist: "What each additional step of {feature} buys you."; readonly detail: "Tall early bars then short ones is the classic diminishing-returns shape — spend effort where the bars are tall."; readonly jargon: "marginal / incremental effect per bin"; }; readonly verdict_causal: { readonly term: "Causal"; readonly gist: "A real change you can credit to {treatment} — and it held up."; readonly detail: "The like-for-like effect is clear, sizeable, and survived the trust checks. Safe to act on."; readonly jargon: "a robust, identified effect"; }; readonly verdict_modest: { readonly term: "Modest / unclear"; readonly gist: "There may be an effect, but it’s small or fuzzy."; readonly detail: "The fair comparison can’t cleanly separate it from no-effect (the range straddles 0, or it’s tiny). Don’t bet much on it."; readonly jargon: "effect CI spans zero / below materiality"; }; readonly verdict_adjustment_insufficient: { readonly term: "Not trustworthy yet"; readonly gist: "We got a number, but a trust check failed."; readonly detail: "Likely something we didn’t adjust for is still in play. Treat as provisional and look at “Can we trust it?”."; readonly jargon: "placebo / robustness failure"; }; readonly verdict_non_identifiable_positivity: { readonly term: "No fair comparison"; readonly gist: "Treated and untreated {subjects} don’t overlap enough to compare."; readonly detail: "There’s no like-for-like “other side”, so any number would be extrapolation. See the overlap chart."; readonly jargon: "positivity / overlap violation"; }; readonly verdict_not_estimable: { readonly term: "Can’t be estimated"; readonly gist: "Almost everyone is on one side of {treatment} — no comparison group."; readonly detail: "One arm is just a handful of {subjects}, so we won’t guess an effect from it."; readonly jargon: "no treatment variation"; }; readonly tab_validate: { readonly term: "Validate"; readonly gist: "The real experiment you’d run to prove this — for sure."; readonly detail: "This analysis adjusted for what it could measure. A controlled trial — assigning {treatment} at random — removes any leftover doubt. This tab sizes that trial."; }; readonly validate_size: { readonly term: "How many to run"; readonly gist: "The number of {subjects} the trial needs."; readonly detail: "Enough to spot a change this size if it’s real. A bigger or cleaner effect needs fewer; a small or noisy one needs many more."; readonly jargon: "required sample size at the target power"; }; readonly validate_split: { readonly term: "How to split them"; readonly gist: "How many get {treatment} versus are left alone."; readonly detail: "Assign at random — that’s what makes the two groups comparable with no adjusting. An even split is the most efficient; treating fewer needs a larger total."; readonly jargon: "randomised allocation between arms"; }; readonly validate_match: { readonly term: "Match the groups on"; readonly gist: "Keep both groups balanced on these — they were lopsided last time."; readonly detail: "Give each group the same mix of these factors when you split, so neither one starts ahead. These are the factors that muddied the original comparison most."; readonly jargon: "stratified / blocked randomisation on the high-imbalance covariates"; }; readonly validate_power: { readonly term: "Chance of detecting it"; readonly gist: "How likely the trial is to catch the effect, by size."; readonly detail: "More {subjects} means a better chance of a clear result. The marker shows where today’s data sits — usually well short of a confident answer."; readonly jargon: "statistical power vs sample size"; }; readonly validate_holdback: { readonly term: "Hold back a control"; readonly gist: "Keep a random group untreated to compare against."; readonly detail: "Right now almost everything got {treatment}, so there’s nothing to compare to. Next time, leave a random sample untreated — that group becomes the fair baseline."; readonly jargon: "a randomised control arm"; }; readonly journal: { readonly term: "Committed experiments"; readonly gist: "A log of the questions you’ve saved."; readonly detail: "Each row is a framing you committed — its verdict and headline effect — so the team can see what’s been tried and what held up."; readonly jargon: "the experiment journal"; }; }; /** Every valid help id. */ export type HelpId = keyof typeof HELP; //# sourceMappingURL=help.d.ts.map