The BIDS units should be available

[captainnova]

Hi,

In a lab meeting today a lot of us were poring over some BIDS .jsons from dcm2niix, and it turned out that we have some disagreement over what the units should be. I don't know if a group of > 2 people will ever settle that issue, but it would be moot if there were some official statement saying what the units are.

I know the times are in s and the frequencies are in Hz, which agrees with https://bids-specification.readthedocs.io/en/stable/02-common-principles.html#units and has been previously documented (#281). But the distances are in mm, which is "normal" for MRI, but not SI like BIDS prefers. I'm fine with the distances staying in mm (it was the times in s that started the hullabaloo), but it's hard to end a philosophical dispute about units with "SI except mm".

Ideally BIDS would have made specifying units mandatory, e.g.

{
  "MagneticFieldStrength": {"value": 3, "unit": "T"}
}

but they didn't. More practically, dcm2niix is probably the source of most BIDS sidecars, so it probably isn't a good idea to make major changes to its format now. Unfortunately I couldn't find much documentation except for the times being in s. Could you please add a documentation file, and/or an option to also produce a ..._units.json? e.g.

{
   "MagneticFieldStrength": "T",
   "SliceThickness": "mm",
   "SpacingBetweenSlices": "mm",
   "EchoTime": "s",
   "RepetitionTime" : "s",
   ...
}

The latter would be more work for you, but easier to use by downstream processing scripts.

Looking at an MRI, the most ambiguous fields are:

{
  # More of a time zone than a unit issue, but still a peeve of mine. I realize the time zone isn't always available in the DICOM.
  "AcquisitionTime": "07:17:59.177500",

   "SAR": 0.217671,               # straight from DICOM?
  "FlipAngle": 180,        # Obviously degrees, would be less obvious for very small flip angles

    "ShimSetting": [       # straight from DICOM and arbitrary?
        -3141,
        -7171,
        3588,
        510,
        25,
        -150,
        52,
        0   ],

    "TxRefAmp": 247.531,   # straight from DICOM and arbitrary?
}

Thanks as always!

Rob

[mharms]

TxRefAmp is Volts, I believe.

As for ShimSetting, that's complicated. The first 3 values are related to the 1st order shims, and are taken from sGRADSPEC.lOffset{X,Y,Z}. The next 5 values are related to the 2nd order shims, and are taken from sGRADSPEC.alShimCurrent[0-4]. Here's what I've previously learned about the units of each, based on comparison to the "Options:Adjustments" tool on the scanner, as well as a discussion with a knowledgeable individual:

Header [DICOM] info is in mA for 2nd order terms, and DAC units for 1st order terms. Conversion to uT/m^2 and uT/m, respectively, require knowledge of the conversions/calibrations, which are not stored in the header information for 2nd order, but ARE stored in the header for 1st order (these are the so-called “gradient sensitivities”). To get the conversions for 2nd order, this is stored in measperm.

The 2nd order terms are not calibrated, so this remains fixed for a given scanner (shim coil) configuration. That will never change as long as you don’t change the shim hardware configuration. As for the 1st orders, these can change quite frequently, as they are recalibrated on PMs. Usually, the calibrations vary very little, but they can vary by as much as 3% since this is the service spec for them.

[drmclem]

Hi

I assume that the values in the previous comment are very manufacturer specific private tags or derived from elsewhere as I don't think the DICOM standard has places for these items - I would worry that you define a standard which can only apply to one vendor - For example I'm not sure we could reliably convert from how one vendor sets its shim or Rf Power into a meaningful value for which another does which could be used outside of the scanner operating system itself.

M

[neurolabusc]

The fields defined by the BIDS standard have defined units, for example MagneticFieldStrength is in Tesla, and EchoTime as well as other temporal values are in seconds.

However, dcm2niix often includes fields that are not defined in the BIDS standard. Since these fields have not been formally defined, the units are typically whatever the vendor uses. For example, since the NIfTI header can only store the distance between voxel centers, the fields SliceThickness and SpacingBetweenSlices are useful to determine if there was a gap between slices, and these values are stored in millimeters (matching the NIFTI_UNITS_MM from the NIfTI header xyzt_units. As you note, many of these additional fields are straight from the DICOM, and were suggested by users of other tools (HCP, FreeSurfer, FSL) to control for sequence variability. As you note, these are unlikely to be useful for analyses between vendors.

If you want to formalize these values, you should propose fields to be defined by a future version of the BIDS proposal. For example, one might define SliceGap to always be in meters. In brief, when a field is defined by BIDS, dcm2niix uses the BIDS definition. However, it includes some informal meta data that is not well defined (but potentially useful). @effigies may have thoughts on this.

[captainnova]

OK. When I searched for units in the BIDS standard it took me straight to Appendix V: Units, which has the general statement about preferring SI but being OK with other units if they are specified, but not a table of field: unit like I was hoping for. The section you linked to above is more like that, thanks.

I'm surprised that SliceGap/SliceThickness aren't already in the BIDS standard, but since I'm not eager to have them converted to m I probably won't bother lobbying for that.

I would, however, be happy to put some effort into making units available in a reasonably convenient way for both the official BIDS fields and the less formal but very useful other items that dcm2niix includes in the .json. Since it seems like a very large fraction of BIDS sidecars are coming from dcm2niix instead of an independent BIDS .json producer, those fields carry a lot of weight. It is also important to provide the units as dcm2niix is providing them - if the BIDS standard changes it could be out of sync with dcm2niix, or vice versa. If I submitted a BIDS.md document (to go in the top level directory along with README.md and BATCH.md etc?), would the people interested in this issue edit it?

I am thinking of including:

1. an explanation that the .json file is a BIDS sidecar + additional handy fields
2. a disclaimer that the BIDS standard and dcm2niix output are not necessarily in sync - either is free to independently make changes, but the fields that are in the BIDS standard are probably in agreement
3. a table of the fields with name, BIDS standard (y/n), description, and unit.
   • My reading of the BIDS standard is that "arbitrary" is a valid unit. I think we would have to use this for some fields where there is a unit, but it is unknown to us and/or too complicated.

Thank you for the information, @mharms, but I agree with @drmclem that we should not present items that are strongly vendor dependent as standards. So TxRefAmp in Volts is probably OK, but if we attempt to explain the units of ShimSetting we would have to make it clear that the info is just for Siemens, and possibly even only for the V series of software. But I'm fine with not covering everything in the first draft - if I understand correctly people mostly only look at ShimSetting to see if has changed from scan to scan.

Thanks,

Rob

[neurolabusc]

@captainnova I have created my proposal for a description here. You could add more types of Notes to describe which fields are part of BIDS (b), units (e.g. s for seconds), etc.

Since you have offered to put some time into this, feel free to expand my existing proposal or come up with your own independent proposal. I am probably ill-suited to fill in the details of this table, as I am unable to see this from the perspective of a new user.

While you may be correct that large fraction of BIDS sidecars currently come from dcm2niix, I think it is really important that we document the arbitrary names given to fields and be careful not to conflict with other existing tools (like dicm2nii) and upcoming converters. I think it is really important to have multiple tools, both for handling edge-case images but also because there is an inherent trade-off between speed and adaptability.

[captainnova]

Thanks @neurolabusc, that's a really great start. I am working on it, but will eventually need a correctness check.

[neurolabusc]

@captainnova I have extended your work. With the new organization, I suggest we remove the manufacturer column, as we describe vendor-specific fields in different tables.

[captainnova]

I suggest we remove the manufacturer column, as we describe vendor-specific fields in different tables.

Agreed and done.

[captainnova]

Thank you, @neurolabusc, I think this is ready.