> 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

Prepare and upload related local files, create Unitlab Data Groups with filename rules, and save Grid, List, or Custom layouts for multimodal annotation.

## Watch multimodal annotation in one workspace

See related video, documents, audio, and images together in Unitlab, with a saved layout and shared annotation workflow.

{% embed url="<https://cdn.prod.website-files.com/651fc1beafe23dfe4999151d/6a7610b174ee3346f6af02c1_unitlab-multimodal-data-platform-explainer-1080p.mp4>" %}

[Open the full-screen Unitlab AI explainer](https://cdn.prod.website-files.com/651fc1beafe23dfe4999151d/6a7610b174ee3346f6af02c1_unitlab-multimodal-data-platform-explainer-1080p.mp4).

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.

## Prepare and upload related local files

Group files by a real-world case, recording, patient, or inspection. Use a shared identifier and a consistent suffix for each view. For example:

```
inspection-images/
├── case_001_front.jpg
├── case_001_side.jpg
├── case_002_front.jpg
└── case_002_side.jpg
```

Here `case_001` is one group and `case_002` is another. Each group has a **Front** image and a **Side** image. The filename pattern should distinguish those views without relying on upload order.

Prepare all four files before uploading. The folder shown is on your computer; the next steps create Assets and logical Data Groups in Unitlab. For your own collection, substitute your folder name and keep the same consistent identifier-and-view pattern.

{% stepper %}
{% step %}

### Upload the source folder

Open **Data Space > Assets**. In the Folders view, choose **New Folder > Upload Data**, then **Local > Upload folder**. Select `inspection-images` and set **Target Folder** to the library folder that should hold the files. Select **Upload**.
{% endstep %}

{% step %}

### Check the source files

Wait for processing to finish. Confirm that the Unitlab source folder contains all four filenames shown above and that each case has both views. Correct duplicate names or inconsistent suffixes before grouping.
{% endstep %}

{% step %}

### Start Auto-Groups

From Assets or the source folder, open **New Folder > Add Auto-Groups**. In **Configure**, select that folder and review the suggested pattern. **Auto-detect** analyzes filenames again if needed.
{% endstep %}
{% endstepper %}

For the example above, a manual configuration can use:

| Setting               | Value                                   |
| --------------------- | --------------------------------------- |
| Grouping key          | `case_id`                               |
| Group name            | `{case_id}`                             |
| Front tile match rule | `^(?P<case_id>case_[0-9]+)_front\.jpg$` |
| Side tile match rule  | `^(?P<case_id>case_[0-9]+)_side\.jpg$`  |

The named capture `(?P<case_id>...)` extracts the same identifier for both files. The group-name template uses it to name the groups `case_001` and `case_002`. Add both tiles, then use **Rules** to require Front and Side and create only complete groups. Expect two valid groups from the four example files. A file matching multiple tiles, or multiple files matching one tile in the same case, is a conflict rather than a valid group.

{% hint style="info" %}
Uploading a folder and creating a Data Group are separate steps. Upload transfers the files. Auto-Groups matches assets already in a library folder and creates grouped output. A JSON file containing arbitrary file paths or group definitions is not a supported Local upload manifest.
{% endhint %}

See [Data upload](/documentation/data/data-upload.md) for supported media, upload progress, and format-specific configuration. Existing labels are handled by [Import local annotations](/documentation/data/import-local-annotations.md), a separate project workflow. The annotation importer cannot target grouped tasks and does not reconstruct groups from exported group metadata.

## Configure the group and layout

### Start Auto-Groups from the Asset library

![Assets page with Add Auto-Groups in the New Folder menu](https://storage.ghost.io/c/48/f4/48f4b614-5c29-430d-9cb3-e0b3f34395f3/content/images/2026/08/clean-data-space-create-menu.webp)

*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://storage.ghost.io/c/48/f4/48f4b614-5c29-430d-9cb3-e0b3f34395f3/content/images/2026/08/clean-auto-groups-configure.webp)

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

Check that the match rules select the intended files. Review duplicate matches, missing members, and unexpected filename suffixes before advancing.

### Set completeness rules and inspect the estimate

![Auto-Groups Rules step with required tiles and estimated valid groups](https://storage.ghost.io/c/48/f4/48f4b614-5c29-430d-9cb3-e0b3f34395f3/content/images/2026/08/clean-auto-groups-rules.webp)

*Rules controls the minimum matched tiles, required members, and incomplete-group behavior. Inspect the estimate and example outcomes before creating anything.*

Set the **Minimum matched tiles** and any **Required tiles**. Choose whether to allow incomplete groups or **Only create groups when all tiles are matched**. You need at least one valid estimated group to continue. Required tiles must be present even when incomplete groups are allowed.

### Build the saved Workbench layout

![Auto-Groups Layout step with Grid, List, and Custom options and a three-panel custom builder](https://storage.ghost.io/c/48/f4/48f4b614-5c29-430d-9cb3-e0b3f34395f3/content/images/2026/08/clean-auto-groups-custom-layout.webp)

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

Choose **Grid** for a balanced arrangement, **List** for one primary tile with the others below it, or **Custom** to place panels yourself. Drag, resize, or nudge the panels to make the views easy to compare.

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.

### Review, create, and verify

Continue to **Review** and inspect the final rules and static layout preview. Select **Create Auto-Groups**. Unitlab creates a new sibling `<source>_grouped` folder and leaves the source files unchanged. Running the same configuration again creates another grouped output folder.

For this example, the expected result is two groups with two tiles each:

```
Grouped result in Unitlab
├── case_001
│   ├── Front → case_001_front.jpg
│   └── Side  → case_001_side.jpg
└── case_002
    ├── Front → case_002_front.jpg
    └── Side  → case_002_side.jpg
```

This diagram shows group membership in Unitlab. It does not describe new local folders or duplicate image files.

Open the grouped folder and inspect several cases. Check that each tile contains the intended file, required views are present, and the group count matches your expectation. Then add the grouped output to a dataset, publish a version, and attach that version to a project. Open a group in the Workbench to confirm its layout and tile roles.

Keep each grouping run within 5,000 source files and 1,000 estimated groups. Split larger collections into smaller source folders and review the estimate for each folder before creating groups.

## What the layout JSON contains

The **Layout > JSON** tab edits the same panel arrangement as **Builder**. It does not upload files or identify which assets belong to a group; the tile match rules already determine membership.

For the example's two tiles, a side-by-side arrangement can be written as follows when their tile IDs are `Front` and `Side`:

```json
{
  "version": "1.0",
  "type": "custom",
  "panels": [
    {"id": "Front", "title": "Front", "x": 0, "y": 0, "width": 49, "height": 100},
    {"id": "Side", "title": "Side", "x": 51, "y": 0, "width": 49, "height": 100}
  ]
}
```

Use the tile IDs shown by the layout generated for your configuration. Each panel needs a unique known `id` and numeric `x`, `y`, `width`, and `height`. Coordinates and dimensions are percentages: panels must stay within the 0-to-100 canvas, each dimension must be at least 8%, and panels must not overlap. After editing, select **Format** to format valid JSON and inspect the visual arrangement before continuing.

The two panels above occupy the left and right halves with a 2% gap. Check the Builder preview shows **Front** on the left and **Side** on the right. Renaming a panel's title does not change which Asset its tile matches.

There are three different JSON roles:

| JSON                        | What it controls                                                            | Where it belongs                    |
| --------------------------- | --------------------------------------------------------------------------- | ----------------------------------- |
| Layout JSON                 | Panel placement for the configured tiles                                    | **Auto-Groups > Layout > JSON**     |
| Grouping configuration JSON | Filename rules, grouping keys, completeness, and layout for existing assets | SDK/CLI grouping operations         |
| Supported annotation JSON   | Labels that reference existing or simultaneously uploaded project media     | **Project > Data > Upload > Local** |

None of these is a generic list of remote media to download. For code-based grouping, upload the files first, estimate the rules against their Assets folder, and create the groups only after reviewing that estimate.

## Automate grouping with the SDK

See [Data Group automation](https://docs.unitlab.ai/api-sdk-cli/sdks/data-group-automation) for Python examples and [CLI Assets and folders](https://docs.unitlab.ai/api-sdk-cli/clis/cli-assets-and-folders#group-related-files) for terminal commands.

For repeatable workflows, the SDK can suggest a filename pattern, estimate groups, and create them from an explicit configuration. It can also compile a literal filename template such as `{patient_id}_{view}` and map expected view values such as `L_CC`, `R_CC`, `L_MLO`, and `R_MLO`.

Upload the source files into an Assets folder first. Review the grouping estimate before creating output, especially when filenames, required views, or completeness rules change.

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

## Continue the operating flow

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

***

> **Continue with Unitlab:** [cross-modal annotation workflows](https://unitlab.ai/en/multimodal-annotation) · [Unitlab’s data curation platform](https://unitlab.ai/en/data-curation)