improve doc of IndexSeries

core/nwb.image.yaml

@@ -177,13 +177,20 @@ groups:
 
 - neurodata_type_def: IndexSeries
   neurodata_type_inc: TimeSeries
-  doc: Stores indices to image frames stored in an ImageSeries. The purpose of the
-    IndexSeries is to allow a static image stack to be stored in an Images
-    object, and the images in the stack to be referenced out-of-order. This can be for
-    the display of individual images, or of movie segments (as a movie is simply a
-    series of images). The data field stores the index of the frame in the referenced
-    Images object, and the timestamps array indicates when that image
-    was displayed.
+  doc: Stores indices that reference images defined in other containers. The primary purpose
+    of the IndexSeries is to allow images stored in an Images container to be referenced in a 
+    specific sequence through the 'indexed_images' link. This approach avoids duplicating image data
+    when the same image needs to be presented multiple times or when images need to be shown in a
+    different order than they are stored. Since images in an Images container do not have an inherent 
+    order, the Images container needs to include an 'order_of_images' dataset (of type 
+    ImageReferences) when being referenced by an IndexSeries. This dataset establishes the ordered 
+    sequence that the indices in IndexSeries refer to. The 'data' field stores the index into this 
+    ordered sequence, and the 'timestamps' array indicates the precise presentation time of each 
+    indexed image during an experiment. This can be used for displaying individual images or creating 
+    movie segments by referencing a sequence of images with the appropriate timestamps. While 
+    IndexSeries can also reference frames from an ImageSeries through the 'indexed_timeseries' link, 
+    this usage is discouraged and will be deprecated in favor of using Images containers with 
+    'order_of_images'.
   datasets:
   - name: data
     dtype: uint32

docs/format/source/format_release_notes.rst

@@ -21,13 +21,14 @@ Major changes
 - Changed ``DecompositionSeries.bands`` from a generic ``DynamicTable`` with added columns to a new ``FrequencyBandsTable``
   neurodata type that extends ``DynamicTable`` with added columns. (#610)
 - Made ``SpikeEventSeries.timestamps`` explicitly required as described in the documentation. (#629)
-- Allowed `EventDetection` to have shape (num_events, 2) to store the channel index of the detected event. (#620)
+- Allowed ``EventDetection`` to have shape (num_events, 2) to store the channel index of the detected event. (#620)
 
 Minor changes
 ^^^^^^^^^^^^^
 - Made group quantities consistent ("1 or more") across data interfaces / wrapper types (#613)
 - Fixed typo and removed HTML tag from doc of behavioral neurodata types. (#600)
-- Made `EventDetection.times` optional. (#620)
+- Improved the documentation of ``IndexSeries``. (#614)
+- Made ``EventDetection.times`` optional. (#620)
 
 2.8.0 (November 24, 2024)
 -------------------------