> ## 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.

# Group Runs into a Family

> Create a named group of related Runs to use as a comparison baseline, statistical reference, and automated detection source.

After completing this topic, you can create a Family, add members, and configure the alignment that makes cross-Run comparison meaningful.

<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 you have a set of related Runs that represent a known-good or representative baseline and want to:

* Compare new Runs against the historical spread visually in Explore
* Compute aggregate statistics across the group (mean, standard deviation, min/max)
* Build Rules that automatically flag when a new Run deviates from the group's statistical envelope

A Family is the starting point for all of these workflows.

## Before you begin

* You have at least two Runs ingested into Sift.
* Your Sift account has the Editor role on the organization containing those Runs. See [Manage user access](/documentation/manage/manage-user-access).

## Complete the workflow

### Step 1: Create a Family

1. Select **Families** in the navigation.
2. Click **Create Family**.

### Step 2: Enter basic information

Fill in the following:

* **Family name**: A human-readable identifier; for example, `Engine 5 Nominal Acceptance Tests`.
* **Description** (optional): What the Family represents and when to use it.
* **Client key** (optional): A unique identifier for use in external systems or APIs. This cannot be changed after it is set.
* **Metadata** (optional): Key-value pairs for tagging the Family with additional context, such as vehicle ID, test campaign, or configuration version. Metadata is searchable and filterable.

### Step 3: Add members

In the **Membership** step, search for and add the Runs that represent your baseline.

To add Runs individually:

1. Use the search field to find Runs by name or Asset.
2. Click **+** on each Run to include it, or select multiple Runs and use **Bulk Actions > Include in Family**.

To exclude a Run from analysis while keeping it in the Family for reference:

1. Select the Run.
2. Click **−** or use **Bulk Actions > Exclude from Family**.
3. Optionally enter a rationale. The Run appears in the **Excluded** tab and is not counted in aggregate calculations.

#### Use a candidate query to find members automatically

A candidate query is a CEL expression evaluated against each Run. Runs that match appear in the **Candidates** tab, where you can bulk include or exclude them.

1. In the **Membership** step, click the **Candidates** tab.

2. Click **Add candidate query**.

3. Enter a CEL expression. For example, to match Runs whose name contains `flight` for a specific Asset:

   ```cel theme={null}
   name.contains('flight') && asset_name == 'rover-1'
   ```

   Click **Show CEL documentation** in the editor for an inline syntax reference. To start from another Family's query, click **Import from existing Family** and select the source Family; Sift populates the editor with that Family's candidate query expression, which you can then modify.

4. Click **Run Query** to preview matching Runs.

5. Select the Runs and apply **Include** or **Exclude** from **Bulk Actions**.

The query is saved with the Family. Any future Run that matches the query but has not been explicitly included or excluded surfaces as a candidate on the Family overview page. This is the mechanism that keeps a Family current over time without manual checking. See [Manage Families](/documentation/analyze/families/keep-a-family-current).

### Step 4: Configure alignments

Alignments define how Runs are time-synchronized for comparison. Without an alignment, each Run's time axis starts at its own absolute start time, making cross-Run comparison meaningless.

Configure at least one alignment:

* **Run Start**: T-0 is set to the beginning of each Run. Use this for Runs with a consistent structure.
* **Run End**: T-0 is set to the end of each Run.
* **Timestamp**: T-0 is a fixed absolute time; use this when all Runs pass through a known moment.
* **Annotation**: T-0 is set when a named event occurs in each Run, such as engine ignition or valve opening. Use this when the event of interest happens at different absolute times across Runs.

You can define multiple alignments and switch between them in Explore or when configuring a Rule. Alignment names must be unique within the Family.

<Tip>
  **Phase Annotations for Annotation alignments**: An Annotation alignment resolves T-0 to the timestamp of a matching [Phase Annotation](/documentation/reference/annotations-reference#phase-annotations) on each Run. Mark the event you want to align on, such as flight computer startup, with a Phase Annotation of the same name on every Run in the Family before configuring the alignment.
</Tip>

When you choose **Annotation** and click **Change**, the **Select Default Annotation** setting lists the Annotations found across your Runs. Select the Annotation that corresponds to the event you want to align on. For example, for a startup alignment, select the Phase Annotation that marks startup on each Run.

### Step 5: Save the Family

Click **Save**. Sift creates the Family and records the initial state in version history.

## Verify the result

After saving:

* The Family appears under **Families** in the navigation with a member count and the alignments you configured.
* Included members are listed under **Family Members**; excluded Runs appear under **Excluded**.
* If you set a candidate query, the **Candidates** tab shows Runs that currently match.

## Next steps

* To overlay all members in Explore on a shared time axis, see [Compare Runs visually against a Family baseline](/documentation/analyze/families/compare-runs-visually-against-a-family-baseline).
* To compute aggregate statistics and write Rules that flag deviations, see [Detect statistical deviations using Family Rules](/documentation/analyze/families/detect-deviations-from-a-historical-baseline).
* To add new Runs to the Family as they are ingested, see [Manage Families](/documentation/analyze/families/keep-a-family-current).