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

# Detect statistical deviations using Family Rules

> Automatically flag when new data falls outside the expected range of your historical reference.

After completing this topic, you can configure Family statistics, write a Rule that uses those statistics as dynamic thresholds, and view flagged deviations in a Report.

<Note>
  New to Families? Read the [Overview](/documentation/analyze/families/overview) to understand how members, alignments, statistics, and Rules work together before proceeding.
</Note>

## When to use this workflow

Use this workflow when a fixed threshold is not the right approach for your telemetry. Instead of checking whether a channel exceeds a hardcoded limit, a Family Rule checks whether a new Run falls outside the statistical envelope of your reference Runs. For example, more than 2 standard deviations from the mean of all known-good acceptance tests.

Common use cases:

* **Acceptance testing**: flag Runs that fall outside mean ± Nσ of a known-good baseline
* **Regression detection**: flag simulation builds whose output diverges from a reference signal shape

## Before you begin

* A Family with at least two included members and at least one alignment configured. See [Group Runs into a Family](/documentation/analyze/families/group-runs-into-a-family).
* Permission to create Rules (Admin or Editor role).

## Complete the workflow

### Step 1: Configure Family statistics

Family statistics compute aggregate time series across all included members. You need at least one statistic before you can write a Family Rule.

**How computation works**: Sift produces each statistic through a fixed pipeline:

1. First, each Run is normalized to a common time axis using the alignment you configured.
2. Then a dynamic window scopes the comparison to the phase of interest. Bucketing normalizes all occurrences to a single value per bucket regardless of underlying sample rate, so each Run contributes equally.
3. Finally, the selected aggregation is computed per bucket across all contributing occurrences.

The **output rate** controls bucket width: a lower rate smooths noise before aggregation, and a higher rate preserves temporal detail.

**Data ranges** scope the computation to a specific test phase rather than the full Run duration. For a full explanation, see [Families reference](/documentation/reference/families-reference).

From the Family overview page, click **Create Family Stat** in the **Family Analysis** section and fill in the following fields.

**Aggregate Channel Group**: Select the channel to aggregate. Sift searches all included members for a channel matching that name. If some Runs use a different name for the same measurement, click **Customize** to define fallback channel names that are tried in order. Runs with no match across the primary name and all fallbacks are excluded from that statistic.

**Aggregation type**: How to aggregate across Runs at each time step. For a sigma-band Rule, create two statistics on the same channel: one `Average` and one `Standard Deviation`. For an envelope Rule, create `Minimum` and `Maximum`.

**Output data rate**: The sample rate of the output in Hz. The default is 1 Hz.

**Data ranges** (optional): The time window within each Run used for the computation. By default, the full Run is used. To scope the computation to a specific phase of the test, click **Add range** and define a dynamic window:

1. Set the **T-0 alignment** that anchors the window.
2. Set **window start** and **window end** as offsets from T-0; for example, `-10s` to `+30s` captures a 40-second window centered on the event.

Click **Preview** to verify the aggregate looks correct before saving, then click **Save**.

Repeat for each statistic you need. A sigma-band Rule requires both an `avg` and a `stdev` stat on the same channel.

<Info>
  To view, edit, duplicate, or delete existing statistics, see [Manage Families](/documentation/analyze/families/keep-a-family-current#step-4-manage-statistics).
</Info>

### Step 2: Create the Rule

1. On the Family overview page, click **Create Rule** in the **Family Analysis** section. This prepopulates the Family in the Rule editor.
   Alternatively, go to the **Rules** tab and click **New Rule**, then configure the Family manually.
2. Choose one or more Assets to which the Rule applies.
3. In **Input Channels**, toggle **Aggregate Comparison**.
4. In **Aggregate Source**, select the Family.
5. In **Aggregate Channel Group Input**, select the statistics you created. For a sigma-band Rule, select both the `avg` and `stdev` statistics. When you select multiple statistics from the same Family, Sift uses the union of their alignment and dynamic window configurations for evaluation.
6. In **T-0 Alignment**, choose the alignment configuration defined on the Family.
7. Optionally select a **dynamic window** to scope the evaluation to a specific phase of the Run. You can create a new dynamic window without leaving the Rule editor by clicking **New window** in the dynamic window selector.

### Step 3: Write the Rule expression

Reference the Channel under test with `$1` and the Family statistics with the variable placeholders assigned in the editor (for example, `$A` for avg, `$B` for stdev).

**Sigma-band example**: flag when the channel falls outside mean ± 2 standard deviations:

```
($1 < ($A - 2 * $B)) || ($1 > ($A + 2 * $B))
```

**Envelope example**: flag when the channel falls outside the Family min/max:

```
$1 < $A || $1 > $B
```

Where `$A` is the min statistic and `$B` is the max statistic.

For full syntax reference, see [Expression syntax](/documentation/reference/expression-syntax).

### Step 4: Preview the Rule

1. In **Rule Preview**, click **Select Run** and choose a sample Run.
2. Sift prompts you to resolve the alignment: map the Run's available alignment configurations to the Family's T-0 so the comparison is time-synchronized correctly.
3. Sift evaluates the Rule and plots the result. The Family statistic time series appears as a reference overlay alongside the Run's channel data in relative time. Annotations mark where the Rule condition is met.

Review the output to confirm the expression fires when and only when you expect it to.

### Step 5: Save the Rule

Click **Save**. Family Rules cannot be set to evaluate live; they run retrospectively when you generate a Report.

<Info>
  To see all Rules that reference a given statistic, use the **Rule references** tab on the Family overview page. Rules are grouped by statistic, so you can identify downstream impact before editing or deleting a statistic.
</Info>

### Step 6: Run the Rule in a Report

1. Open the Run you want to evaluate.
2. Click **Create report**.
3. Select the Family Rule and click **Evaluate**.
4. Sift prompts you to resolve the alignment for the Run before the Report generates. The alignment configuration used for the evaluation is recorded in the Report header.
5. The Report opens with the Family statistic overlay, the Run's channel data in relative time, and Annotations at each deviation. Each Annotation detail panel shows the absolute timestamp alongside the relative time offset from T-0.

<Info>
  Add the Family Rule to a Report Template so you do not need to select it manually each time. See [Set up a repeatable review checklist](/documentation/review/set-up-a-repeatable-review-checklist).
</Info>

## Verify the result

After completing this workflow:

* The Family statistics appear in the **Family Analysis** section of the Family overview page.
* The Rule appears in the **Rules** tab with the Family and Asset configured.
* The Report shows the Family statistic overlay, the Run's channel data in relative time, and Annotations at each point where the Rule fired.

## Next steps

* To triage the Annotations generated by the Rule, see [Triage and close out flagged issues](/documentation/review/triage-and-close-out-flagged-issues).
* To keep the Family current as new Runs arrive, see [Manage Families](/documentation/analyze/families/keep-a-family-current).
* To understand how alignment, bucketing, and aggregation interact in detail, see [Families reference](/documentation/reference/families-reference).

## Reference

* [Expression syntax](/documentation/reference/expression-syntax)
* [Annotations reference](/documentation/reference/annotations-reference)


## Related topics

- [Detect deviations automatically using Rules](/documentation/review/detect-deviations-automatically-using-rules.md)
- [Manage Families](/documentation/analyze/families/keep-a-family-current.md)
- [Group Runs into a Family](/documentation/analyze/families/group-runs-into-a-family.md)