[sfmig]

Description

What is this PR?

• Bug fix
• Addition of a new feature
• Other

Why is this PR needed?
Currently, the zarr store that collects the crab tracks across the full set of videos has a sparse time axis. This means that for a given clip, the time dimension has coordinates only for the frames with data. This is because the VIA tracks file only records detections, and therefore only logs frames with data.

When concatenating the data across clips of the same video, the time dimension becomes less sparse (as it will become the union of all 'coordinates' per clip), but there is no guarantee that it will be dense for any video.

Importantly, because the data per clip was loaded with use_frame_numbers_from_file=False, the frame numbers are mapped to ordinal numbers 0,1,2,... If there are frames with no detections in the clip, this can be confusing and lead to error (e.g. this would make the current definition of the escape_state array wrong).

What does this PR do?
It makes the time axis on the zarr dataset dense. Specificallu:

• It loads the clip tracked data with use_frame_numbers_from_file=True, to retain the frame numbers from the VIA tracks file (which for the crabs case, are 0-based clip indices)
  • After movement PR 1103, using the default use_frame_numbers_from_file=False would give the same result in this case.
• It gets the frame range from the clip metadata and reindexes the dataset.
  • We first ensure there are no frames in the dataset outside the range specified in the metadata, since in that case the reindexing operation would drop those values silently.

It also updates the script to generate output videos, so that the ds loaded from an input VIA tracks file has a dense axis that matches the frame in the video (it includes a check like the above to avoid silently dropping data out of range).

References

• movement PR 1103
• The plan provided to Claude to develop this feature is included in this PR's history here

How has this PR been tested?

Past and added tests pass locally and in CI

Does this PR require an update to the documentation?

It includes an update to the guide to generate a zarr dataset from tracks (guides/CreateZarrDatasetForTracks.md)

Checklist:

• The code has been tested locally
• Tests have been added to cover all new functionality
• The documentation has been updated to reflect any changes
• The code has been formatted with pre-commit

[sfmig]

Suggested change

	By default the file holds boxes for a sparse set of frames of a
	101-frame clip, which is the case the dense `time` axis is about.
	Pass `frame_indices` to write boxes for a different set of frames.
	By default the file holds boxes for a sparse set of frames within a
	101-frame clip. Pass `frame_indices` to write boxes for a different
	set of frames.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 50.89%. Comparing base (77ae44d) to head (d8289a9).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #291      +/-   ##
==========================================
+ Coverage   50.53%   50.89%   +0.35%     
==========================================
  Files          26       26              
  Lines        1670     1682      +12     
==========================================
+ Hits          844      856      +12     
  Misses        826      826              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.