Handling run entity label for 4D sequences

[Dan Levitas]

Currently, ezBIDS applies a run entity to sequences in a scan session that contain the same series group ID, meaning they have the same values for the SeriesDescription, ImageType, EchoTime, and RepetitionTime metadata fields. When users reach the Dataset Review page, ezBIDS performs a volume threshold check on all 4D sequences (most commonly, func/bold). This is for instances where a func/bold sequence may not have run to completion, either due to a stimulus presentation software issue, participant asked to stop early, MRI technician needed to restart the sequence, etc. As such, the researcher is unlikely to use this data because it is too truncated be of value and likely re-runs the sequence. ezBIDS uses a simple heuristic for volume threshold (60/TR), the expected number of volumes collected in a 60-sec duration given the TR.

Here's how the run entity labels are generated, given an instance where a func/bold sequence doesn't reach the threshold:
Case 1
func/bold (task-bart_run-1)
func/bold (task-bart_run-2) [excluded, only 10 volumes]
func/bold (task-bart_run-3)
func/bold (task-bart_run-4)
func/bold (task-bart_run-5)

As we can see, run 2 was restarted, yet ezBIDS increases the run entity value. I feel the expected behavior should be:
Case 2
func/bold (task-bart_run-1)
func/bold (task-bart_run-2) [excluded, only 10 volumes]
func/bold (task-bart_run-2)
func/bold (task-bart_run-3)
func/bold (task-bart_run-4)

This way, the final run numbers for the func/bold sequences in this scan are [1,2,3,4] rather an [1,3,4,5]. The latter appears odd from a data sharing perspective. Furthermore, if users upload timing files to be converted to events.tsv, proper mapping necessitates correct matching of the run entity label.

For what it's worth, the bids-validator doesn't complain if the run labels are disjointed in (e.g, run-1, run-3), so this is mainly an issue of data organization.

@anibalsolon and @bhatiadheeraj, do you have any thoughts/comments on this?

[Dan Levitas]

Alternatively, users may prefer Case 1 in situations where they explicitly don't want a specific run and want to denote that (e.g., we anticipated running 5 func/bold sequences but the 2nd run had poor motion but we still conducted runs 3,4,5).

[Dan Levitas]

I've pushed a commit (88d25d2) that will have ezBIDS adhere to Case 2, as in my experience this is the most common way files would be ordered. This thus follows the 80/20 rule.