From beac27cd8c90963c29a30cd8680f25d51a6a857a Mon Sep 17 00:00:00 2001
From: pollfly <75068813+pollfly@users.noreply.github.com>
Date: Thu, 2 Feb 2023 08:00:31 +0200
Subject: [PATCH] Add frame `context_id` description (#464)

---
 docs/hyperdatasets/single_frames.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/hyperdatasets/single_frames.md b/docs/hyperdatasets/single_frames.md
index c73211db..a2b8b9ba 100644
--- a/docs/hyperdatasets/single_frames.md
+++ b/docs/hyperdatasets/single_frames.md
@@ -14,6 +14,7 @@ A `SingleFrame` contains the following components:
 * [Masks](#masks)
 * [Previews](#previews)
 * [Metadata](#metadata)
+* [Context ID](#context-id)
 
 ### Sources
 Every `SingleFrame` includes a [`sources`](sources.md) dictionary, which contains attributes of the raw data, including:
@@ -52,6 +53,18 @@ For more information, see [Previews](previews.md).
 
 For more information, see [Custom Metadata](custom_metadata.md).
 
+### Context ID
+Frames' `context_id` property facilitates grouping SingleFrames and FrameGroups. When a `context_id` is not explicitly 
+defined, the frame's source URI is used instead.
+
+When you query the server for frames (e.g. with the [`DataView.get_iterator`](../references/hyperdataset/dataview.md#get_iterator) 
+method), the returned frames are grouped together according to their `context_id`, and within their context group are 
+ordered according to their `timestamp`. 
+
+Use the WebApp's dataset version frame browser "Group by URL" option to display a single preview for all frames with the 
+same context ID. Click the preview to view the context group's frames in the frame viewer in order of their timestamps. 
+This is useful when working with a video. You can give all the video frames the same context ID, and then view them in order.
+
 ## Frame Structure
 
 The panel below describes the details contained within a `frame`:
@@ -218,7 +231,7 @@ There are also options to populate the instance with:
 * A dictionary of annotation objects - `annotations`
 * A URI link to a mask file for the frame - `mask_source`
 
-For more information, see the `SingleFrame` class description.
+For more information, see the [`SingleFrame`](../references/hyperdataset/singleframe.md) class description.
 
 ### Adding SingleFrames to a Dataset Version