Package: d2b-nth-of-type
d2b-nth-of-typePlugin for the d2b package to deterministically uniquify different acquisition runsIntallationpipinstalld2b-nth-of-typeGetting StartedThis plugin will inject properties into each JSON sidecar which distinguish different runs from one another, which can subsequently be used incriteriaspecifications in d2b config files.Specifically, this plugin will inject a property,__nth_of_type__, into each JSON sidecar. The value of this property is a 0-indexed integer.This plugin groups acquisitions and gives each run in the group a unique (0-indexed) label, incrementing in the specified order.By default, acquisitions are grouped bySeriesDescriptionand are ordered bySeriesNumber(inascendingorder).For example, if a subject has a session in which 3 fieldmaps are acquired, and say, for example, the 3 sidecars (truncated) are of the form:fieldmap 1:{"SeriesDescription":"my_fmap","SeriesNumber":3}fieldmap 2:{"SeriesDescription":"my_fmap","SeriesNumber":16}fieldmap 3:{"SeriesDescription":"my_fmap","SeriesNumber":24}Then, when runningd2b runwith this plugin installed, this plugin will inject__nth_of_type__into each sidecar, resulting in sidecars (truncated) which look like:fieldmap 1:{"SeriesDescription":"my_fmap","SeriesNumber":3,"__nth_of_type__":0}fieldmap 2:{"SeriesDescription":"my_fmap","SeriesNumber":16,"__nth_of_type__":1}fieldmap 3:{"SeriesDescription":"my_fmap","SeriesNumber":24,"__nth_of_type__":2}The utility is that these values will be invariant under changes toSeriesNumber.So, if the "first" fmap is intended for a BOLD acquisition, and the "second" fmap is intended for a PCASL acquisition, we can safely pick-out each fmap using the__nth_of_type__field.For example, we could have a d2b configuration file of the following form (NOTE:d2b-yamlplugin required for yaml config files, and you probably also want thed2b-aslplugin for ASL data):descriptions:# BOLD Resting State-id:my-bold-rsdataType:funcmodalityLabel:boldcustomLabels:task-restcriteria:# ...# PCASL-id:my-pcasldataType:perfmodalityLabel:aslcustomLabels:acq:pcaslcriteria:# ...aslContext:# ...# FIRST FMAP - for BOLD - phase encoding = AP-dataType:fmapmodalityLabel:epicustomLabels:dir:APIntendedFor:-my-bold-rscriteria:ManufacturersModelName:Prisma_fitSidecarFilename:"*SpinEchoFieldMap_AP*"__nth_of_type__:0# <-- HERE# FIRST FMAP - for BOLD - phase encoding = PA-dataType:fmapmodalityLabel:epicustomLabels:dir:PAIntendedFor:-my-bold-rscriteria:ManufacturersModelName:Prisma_fitSidecarFilename:"*SpinEchoFieldMap_PA*"__nth_of_type__:0# <-- HERE# SECOND FMAP - for PCASL - phase encoding = AP-dataType:fmapmodalityLabel:epicustomLabels:dir:APIntendedFor:-my-pcaslcriteria:ManufacturersModelName:Prisma_fitSidecarFilename:"*SpinEchoFieldMap_AP*"__nth_of_type__:1# <-- HERE# SECOND FMAP - for PCASL - phase encoding = PA-dataType:fmapmodalityLabel:epicustomLabels:dir:PAIntendedFor:-my-pcaslcriteria:ManufacturersModelName:Prisma_fitSidecarFilename:"*SpinEchoFieldMap_PA*"__nth_of_type__:1# <-- HEREConfigurationThis plugin can be configured by via options to thed2b runcommand or via the environment:--nth-of-type-enabled | --nth-of-type-disabledEnable or disable this plugin. (default: enabled)Can also be configured via theD2B_NTH_OF_TYPE_ENABLEDenvironment variable. The command line argument takes precedence over the environment variable.--nth-of-type-sort-by <string>Which sidecar field to sort the acquisitions by (default:SeriesNumber:asc).To sort in descending order append:desconto the fieldname, ex:SeriesNumber:desc. If no direction/ordering suffix (:asc/:desc) is present then the acquisitions are sorted in ascending order.Can also be configured via theD2B_NTH_OF_TYPE_SORT_BYenvironment variable. The command line argument takes precedence over the environment variable.--nth-of-type-group-by <string>Which sidecar field(s) to group acquisitions by (default:SeriesDescription).To group by more then one field pass a comma separated list, ex:SeriesDescription,RepetitionTimeCan also be configured via theD2B_NTH_OF_TYPE_GROUP_BYenvironment variable. The command line argument takes precedence over the environment variable.ContributingHave or install a recent version ofpoetry(version >= 1.1)Fork the repoSetup a virtual environment (however you prefer)Runpoetry installRunpre-commit installAdd your changes (adding/updating tests is always nice too)Commit your changes + push to your forkOpen a PR