> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summand.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up an experiment

> Schedule analytical components — predictors, surprise finding, column stats — to run on a dataset or view, on cron.

Experiments are how recurring analysis happens in Summand. Once configured, the experiment fires on its schedule, runs the components you picked, writes versioned outputs, and surfaces results back to chat and the global Surprises page.

<Steps>
  <Step title="Open the Experiments page">
    Click **Experiments** in the sidebar, then **+ New experiment**.
  </Step>

  <Step title="Pick a source">
    Choose either a **dataset** or a **view**. Datasets are the simplest; views let you target a pre-aggregated or filtered subset (e.g. *enterprise customers only*) without the components having to filter each run.

    The source picker lists the datasets and views you own.
  </Step>

  <Step title="Pick components">
    From the component catalog, select one or more components to run:

    * **Column stats** — distributions, missingness, cardinality. Cheap; usually first.
    * **Predictors** — fits an EBM and writes feature importance. Requires a target column input.
    * **Surprise finding** — flags rows the predictor disagrees with. Chains automatically when both are in the same experiment.
    * **UMAP embedding** — 2-D projection for cluster visualization.

    See [Components](/concepts/components) for the full catalog.
  </Step>

  <Step title="Fill in component inputs">
    Each component declares typed inputs that the editor renders as form fields. For Predictors, you'll see:

    * **Target column** — dropdown of the source's columns. The thing the model should predict.
    * **Feature exclusions** — optional, columns to skip.

    Inputs are validated client-side before save. Required inputs are marked.
  </Step>

  <Step title="Pick a schedule">
    Choose a preset:

    * **Daily at 3:00 AM** or **Daily at 6:00 AM**
    * **Every 6 hours** or **Every 12 hours**
    * **Weekly Monday 3:00 AM** or **Weekly Sunday 3:00 AM**

    Or write a custom AWS EventBridge cron / rate expression:

    ```text theme={null}
    cron(*/15 * * * ? *)        — every 15 minutes
    cron(0 9 ? * MON-FRI *)     — every weekday at 9 AM
    rate(2 hours)               — every two hours
    ```

    EventBridge cron uses **six fields**, not the standard five. The editor renders a human-readable description (*"At minute 0, every 6 hours"*) so you can sanity-check.
  </Step>

  <Step title="Name and save">
    Give the experiment a name and an optional description. Save. The first run fires on the next schedule tick — or hit **Run now** to test immediately.
  </Step>
</Steps>

## After it's running

The experiment detail page shows:

* **Recent runs** — status, duration, error message on failure.
* **Run history** — older runs paginated back.
* **Manual trigger** — *Run now* fires outside the schedule; the next scheduled run goes as normal.
* **Pause** — stop scheduled runs without deleting the experiment.
* **Edit** — update components, inputs, or schedule. Changes apply on the next tick.

## Reading the output

Experiment outputs land in three places:

* **Chat with Summand** — *"What did the last predictor run say about churn?"* Summand reads the latest semantic-layer version and answers.
* **Global Surprises page** — surprise-finding outputs across all your experiments, ranked.
* **Downstream views** — write a SQL view that pulls component outputs and join them with other data.

There isn't a "results" tab on the experiment itself today — the model is "outputs are first-class data, queryable like any other".

## Patterns

### One component per experiment

Simplest case. Predictor on dataset X, daily at 3 AM. One row in your experiments list per analysis.

### Chained components in a single experiment

If you put **Predictors** and **Surprise finding** in the same experiment, Surprise finding chains to the predictor's output automatically — no input wiring needed. This is the canonical setup for "find rows that don't match the model's expectations."

### Different schedules for different cohorts

Define a view per cohort (*enterprise customers*, *trial users*, *newly-onboarded*), then set up one experiment per view. Each runs on its own cadence. All three reuse the same component definitions.

### Running on demand only

For experiments you only want to fire manually, set the schedule to a far-future cron (`cron(0 0 1 1 ? 2099)` works) and use **Run now** when needed. A first-class "manual only" mode is on the roadmap.

## Failures

Failed runs are kept in history with the error message. Common causes:

* **Source unavailable** — the underlying database connection failed or the view's SQL no longer compiles.
* **Input validation** — the target column was renamed or removed in the source.
* **Component error** — usually a data-shape issue (e.g. predictor target is all null on the latest snapshot).

Summand doesn't auto-retry failed runs. Edit the configuration to fix the underlying issue, or pause the experiment if the upstream is broken longer than you want failure noise.

## Limits

* **Number of components per experiment** — no hard cap, but cost and duration scale linearly.
* **Schedule frequency** — minimum is whatever EventBridge allows (1 minute), though most analytical components don't need that level of frequency.
* **Concurrent runs** — at most one run per experiment at a time. If a tick fires while the previous run is still in progress, the new tick is skipped (it's not queued).