sort_by_acquisition_order

bidsaid.path_utils.sort_by_acquisition_order(filenames, return_filenames_only=True)

Sort filenames based on acquisition sequence.

Sorts numerically based on the acquisition order implied by the filename and lexicographically based on parent filename and full basename.

For instance:

filenames = ["101_10_2.nii", "101_10_1.nii", "101_3_1.nii"]
sorted_filenames = ["101_3_1.nii", "101_10_1.nii", "101_10_2.nii"]

Note, numerical sorting depends on the acquisition order in the filename since the regex pattern used for sorting is “(?<=_)(d+)(?:_(d+))?(?=.)”. This is used to create a tuple (capture_group_2, capture_group_1, filename), which consist of the last capture group, the first capture group, and the filename. Thus, the sorting can result in:

filenames = [“101_10_2.nii”, “101_10_1.nii”, “101_3_1.nii”, “102_2_1.nii”, “102_1_1.nii”] sorted_filenames = [“102_1_1.nii”, “102_2_1.nii”, “101_3_1.nii”, “101_10_1.nii”, “101_10_2.nii”]

Parameters

filenameslist[str] or list[Path]

A list of paths.

return_filenames_onlybool, default=True

If True, returns a list of sorted filenames.

Returns

list[Path] or list[tuple[int, int, Path]]

A list of paths sorted based on acquisition order if return_filenames_only is True else returns a list of sorted tuples where each tuple has the form (capture_group_2, capture_group_1, filename).