> For the complete documentation index, see [llms.txt](https://docs.unitlab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.unitlab.ai/documentation/data/data-groups-and-layouts.md).

# Data Groups and layouts

Data Groups change the unit of work from one file to a related set of files. A custom layout then determines how those members are presented together in the Workbench.

### Before you make the change

* Define the real-world unit that must remain together.
* Identify the filename or metadata key that reliably joins members.
* Specify required, optional, duplicate, incomplete, and ambiguous group behavior.

### Follow the interface

#### Start Auto-Groups from the Asset library

![Assets page with Add Auto-Groups in the New Folder menu](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FkaZggvW6dujbqKfqeO9r%2Fdata-space-create-menu.png?alt=media\&token=f486bf59-dc3b-4e26-8758-7b82c4ccd03d)

*Open Data Space › Assets or an eligible folder, open New Folder, then choose Add Auto-Groups. This starts a non-destructive grouping flow from the selected source scope.*

#### Configure grouping keys and tile match rules

![Auto-Groups Configure step with source folder, grouping keys, group name, and tile rules](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FZ9rF9ti8Np2g8rHevUq5%2Fauto-groups-configure.png?alt=media\&token=0e1bdbb3-a54b-40e8-8ca0-2ff1c047fdee)

*Configure defines the source folder, grouping key, group-name template, expected tiles, match patterns, and optional exclusions. Auto-detect can propose a configuration from filenames.*

Treat every proposed regular expression as production logic. Inspect representative matches, naming collisions, missing members, and unexpected suffixes before advancing.

#### Set completeness rules and inspect the estimate

![Auto-Groups Rules step with required tiles and estimated valid groups](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2FiEh3xf25jpXH2RkDyBna%2Fauto-groups-rules.png?alt=media\&token=42188cca-3c09-42b0-bdbb-b5404ec13d32)

*Rules controls the minimum matched tiles, required members, and incomplete-group behavior. The estimate and example outcomes show whether the policy produces valid groups before anything is created.*

#### Build the saved Workbench layout

![Auto-Groups Layout step with Grid, List, and Custom options and a three-panel custom builder](https://292810646-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGjVLUz4wthGkGlRKM6rM%2Fuploads%2F8eyEMKLe8RbL8q4uIsNW%2Fauto-groups-custom-layout.png?alt=media\&token=810552ad-bdf3-44b8-b959-3f3afe77847d)

*Layout offers Grid, List, and Custom. In Custom, each expected tile becomes a draggable and resizable panel; Builder and JSON edit the same percentage-based layout.*

The saved layout follows the Data Group into dataset versions, project attachment, the grouped Workbench, and release context. Overlap is invalid and must be resolved before review.

### Understand the product behavior

Unitlab can automatically group related files into multiview or multimodal units using filename patterns. The current UI shows a four-step wizard:

1. **Configure**
2. **Rules**
3. **Layout**
4. **Review**

Available layout options are:

* **Grid** — related files arranged as a balanced grid;
* **List** — a primary tile with remaining files listed below;
* **Custom** — a draggable, resizable workspace for specialized arrangements.

A custom layout can place video, document, and audio tiles in one workspace. Layout determines what information an annotator can compare without leaving the task.

The SDK can:

* suggest a filename grouping pattern;
* estimate the outcome before creating groups;
* create groups from an explicit configuration;
* compile a literal filename template such as `{patient_id}_{view}`;
* map expected tile values such as `L_CC`, `R_CC`, `L_MLO`, and `R_MLO`.

### Auto-Grouping user flow

1. The user opens **Add auto-groups** from Assets or a folder.
2. **Configure:** choose the source folder. Unitlab analyzes filenames and can propose grouping keys, group-name template, and tiles; **Auto-detect** reruns the suggestion.
3. **Rules:** define the minimum matched tiles, required tiles, and incomplete-group handling. A live estimate shows valid, skipped, and conflicting examples. The user cannot continue without at least one valid estimated group.
4. **Layout:** arrange a panel per tile using Grid, List, or Custom/free-form placement. Panels can be dragged, resized, nudged, enlarged, or minimized. Overlap is highlighted and blocks continuation. An optional JSON view edits the same layout.
5. **Review:** inspect the final rules and static layout preview.
6. **Create:** Unitlab creates a new sibling `<source>_grouped` folder and leaves the source folder unchanged.

Every grouping run is non-destructive and creates a new grouped folder, even when the same configuration is run again. The saved percentage-based layout becomes the single layout used by preview, published dataset version, attached project group, and grouped Workbench.

For folders above 5,000 files or estimates above 1,000 groups, Unitlab starts an asynchronous grouping job and reports that it has begun. The SDK applies a stricter guard and may advise splitting the source before retrying.

### From Custom Layout to multimodal annotation

The layout is part of the Data Group, not a temporary preference inside the annotation screen. It moves with the group through the complete data lifecycle:

```
Source files
    ↓ Auto-group by filename rules
Data Group + saved tile layout
    ↓ Add to dataset and publish
Immutable dataset version with grouped tiles
    ↓ Attach to project
One grouped project work item
    ↓ Open in Workbench
Multimodal annotation in the saved layout
    ↓ Release
Grouped annotation context preserved in UUEF
```

Each configured tile retains its own data family and native viewer. A single layout can therefore combine video playback, PDF pages, audio waveforms, images, or medical views while the surrounding project supplies one ontology, workflow state, assignee, comment history, and review route for the grouped case.

The grouped Workbench follows the saved Grid, List, or Custom arrangement. Annotators activate one tile at a time for editing; the other tiles remain visible as read-only context. Previous/next navigation treats the complete group as one work item, and group members do not appear again as unrelated loose tasks.

Custom-layout UX is designed to prevent invalid arrangements before creation:

* each expected tile has one panel;
* panels can be dragged, resized, nudged, enlarged, or minimized;
* panel coordinates and dimensions are percentage-based so the layout scales with the Workbench;
* overlap is highlighted and blocks continuation;
* the visual editor and optional JSON view edit the same layout;
* Review shows the final rules and a static layout preview before groups are created.

### Create and qualify groups

{% stepper %}
{% step %}

#### 1. Open Add Auto-Groups

Start from Data Space › Assets or the intended source folder. Auto-Groups never rewrites the source folder.
{% endstep %}

{% step %}

#### 2. Configure

Choose the source folder, accept or correct suggested grouping keys, group naming, tile names, match rules, and exclusions.
{% endstep %}

{% step %}

#### 3. Rules

Set the minimum matched tiles, required tiles, and incomplete-group policy; continue only when the estimate contains valid, explainable groups.
{% endstep %}

{% step %}

#### 4. Layout

Choose Grid, List, or Custom. In Custom, place one panel per expected tile, resize or nudge panels, and clear all overlap errors.
{% endstep %}

{% step %}

#### 5. Review and create

Inspect the final rules and static layout preview. Creation writes a new sibling grouped folder and preserves the original source.
{% endstep %}

{% step %}

#### 6. Test in a pilot project

Publish grouped membership, attach it to a pilot, and verify the saved tile roles, active editor, navigation, workflow state, and release output.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision         | Production guidance                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------ |
| Grouping key     | Prefer stable identifiers or metadata over fragile positional assumptions.                 |
| Missing member   | Decide whether the group remains usable, becomes invalid, or routes to exception handling. |
| Layout order     | Make the order meaningful and stable across users and releases.                            |
| Release contract | Confirm the downstream consumer can preserve or reconstruct group context.                 |

### Continue the operating flow

* Publish grouped membership as a dataset version.
* Configure the Grouped Workbench project flow.
* Train annotators on active versus passive panels.