{ "cells": [ { "cell_type": "markdown", "id": "b0099b87", "metadata": {}, "source": [ "(magnetic-resonance-imaging)=\n", "# Magnetic Resonance Imaging" ] }, { "cell_type": "code", "execution_count": 1, "id": "9482045f", "metadata": { "tags": [ "remove-cell" ] }, "outputs": [], "source": [ "from myst_nb import glue\n", "from IPython.display import display, Markdown, HTML\n", "from schemacode import render, schema, utils\n", "from markdown import markdown\n", "\n", "# Load the schema path\n", "schemapath = utils.get_schema_path()\n", "schema_obj = schema.load_schema(schemapath)" ] }, { "cell_type": "markdown", "id": "6289b1e8", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields)=\n", "## Common metadata fields\n", "\n", "MR Data described in the following sections share the following RECOMMENDED metadata\n", "fields (stored in sidecar JSON files).\n", "MRI acquisition parameters are divided into several categories based on\n", "\"A checklist for fMRI acquisition methods reporting in the literature\"\n", "([article](https://winnower-production.s3.amazonaws.com/papers/977/v4/pdf/977-a-checklist-for-fmri-acquisition-methods-reporting-in-the-literature.pdf),\n", "[checklist](https://winnower-production.s3.amazonaws.com/papers/977/assets/993e199d-6bc3-4418-be3a-f620af1188b7-Parameter_Reporting_V1p3.pdf))\n", "by Ben Inglis.\n", "\n", "(magnetic-resonance-imaging:common-metadata-fields:scanner-hardware)=\n", "### Scanner Hardware\n", "\n", "{term}`Manufacturer (metadata)`" ] }, { "cell_type": "code", "execution_count": 2, "id": "84a04936", "metadata": {}, "outputs": [ { "data": { "text/markdown": [ "{term}`Manufacturer (metadata)`" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(Markdown(\"{term}`Manufacturer (metadata)`\"))" ] }, { "cell_type": "code", "execution_count": 3, "id": "c7e32749", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/plain": [ "'{term}`Manufacturer (metadata)`'" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(\"{term}`Manufacturer (metadata)`\")" ] }, { "cell_type": "code", "execution_count": 4, "id": "c1f7341e", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}`Manufacturer (metadata)`RECOMMENDEDstringManufacturer of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 0070 Manufacturer.
{term}`ManufacturersModelName (metadata)`RECOMMENDEDstringManufacturer's model name of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 1090 Manufacturers Model Name.
{term}`DeviceSerialNumber (metadata)`RECOMMENDEDstringThe serial number of the equipment that produced the measurements. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset. Corresponds to DICOM Tag 0018, 1000 DeviceSerialNumber.
{term}`StationName (metadata)`RECOMMENDEDstringInstitution defined name of the machine that produced the measurements. Corresponds to DICOM Tag 0008, 1010 Station Name.
{term}`SoftwareVersions (metadata)`RECOMMENDEDstringManufacturer's designation of software version of the equipment that produced the measurements. Corresponds to DICOM Tag 0018, 1020 Software Versions.
{term}`HardcopyDeviceSoftwareVersion (metadata)`DEPRECATEDstringManufacturer's designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A Hardcopy Device Software Version.
{term}`MagneticFieldStrength (metadata)`RECOMMENDED, but REQUIRED for Arterial Spin LabelingnumberNominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018, 0087 Magnetic Field Strength.
{term}`ReceiveCoilName (metadata)`RECOMMENDEDstringInformation describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 Receive Coil Name, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field.
{term}`ReceiveCoilActiveElements (metadata)`RECOMMENDEDstringInformation describing the active/selected elements of the receiver coil. This does not correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. See an example below the table.
{term}`GradientSetType (metadata)`RECOMMENDEDstringIt should be possible to infer the gradient coil from the scanner model. If not, for example because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently.
{term}`MRTransmitCoilSequence (metadata)`RECOMMENDEDstringThis is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 MR Transmit Coil Sequence.
{term}`MatrixCoilMode (metadata)`RECOMMENDEDstring(If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (for example, \"GRAPPA\", \"SENSE\") imaging.
{term}`CoilCombinationMethod (metadata)`RECOMMENDEDstringAlmost all fMRI studies using phased-array coils use root-sum-of-squares (rSOS) combination, but other methods exist. The image reconstruction is changed by the coil combination method (as for the matrix coil mode above), so anything non-standard should be reported.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"Manufacturer\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 0070 `Manufacturer`.\"),\n", " \"ManufacturersModelName\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name`.\"),\n", " \"DeviceSerialNumber\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`.\"),\n", " \"StationName\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 1010 `Station Name`.\"),\n", " \"SoftwareVersions\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0018, 1020 `Software Versions`.\"),\n", " \"HardcopyDeviceSoftwareVersion\": \"DEPRECATED\",\n", " \"MagneticFieldStrength\": \"RECOMMENDED, but REQUIRED for Arterial Spin Labeling\",\n", " \"ReceiveCoilName\": \"RECOMMENDED\",\n", " \"ReceiveCoilActiveElements\": (\n", " \"RECOMMENDED\",\n", " \"See an example below the table.\",\n", " ),\n", " \"GradientSetType\": \"RECOMMENDED\",\n", " \"MRTransmitCoilSequence\": \"RECOMMENDED\",\n", " \"MatrixCoilMode\": \"RECOMMENDED\",\n", " \"CoilCombinationMethod\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(utils.fix(markdown(table.to_markdown(), extensions=['tables']))))" ] }, { "cell_type": "code", "execution_count": 5, "id": "df30c99e", "metadata": {}, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}Manufacturer (metadata)RECOMMENDEDstringManufacturer of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 0070 Manufacturer.
{term}ManufacturersModelName (metadata)RECOMMENDEDstringManufacturer's model name of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 1090 Manufacturers Model Name.
{term}DeviceSerialNumber (metadata)RECOMMENDEDstringThe serial number of the equipment that produced the measurements. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset. Corresponds to DICOM Tag 0018, 1000 DeviceSerialNumber.
{term}StationName (metadata)RECOMMENDEDstringInstitution defined name of the machine that produced the measurements. Corresponds to DICOM Tag 0008, 1010 Station Name.
{term}SoftwareVersions (metadata)RECOMMENDEDstringManufacturer's designation of software version of the equipment that produced the measurements. Corresponds to DICOM Tag 0018, 1020 Software Versions.
{term}HardcopyDeviceSoftwareVersion (metadata)DEPRECATEDstringManufacturer's designation of the software of the device that created this Hardcopy Image (the printer). Corresponds to DICOM Tag 0018, 101A Hardcopy Device Software Version.
{term}MagneticFieldStrength (metadata)RECOMMENDED, but REQUIRED for Arterial Spin LabelingnumberNominal field strength of MR magnet in Tesla. Corresponds to DICOM Tag 0018, 0087 Magnetic Field Strength.
{term}ReceiveCoilName (metadata)RECOMMENDEDstringInformation describing the receiver coil. Corresponds to DICOM Tag 0018, 1250 Receive Coil Name, although not all vendors populate that DICOM Tag, in which case this field can be derived from an appropriate private DICOM field.
{term}ReceiveCoilActiveElements (metadata)RECOMMENDEDstringInformation describing the active/selected elements of the receiver coil. This does not correspond to a tag in the DICOM ontology. The vendor-defined terminology for active coil elements can go in this field. See an example below the table.
{term}GradientSetType (metadata)RECOMMENDEDstringIt should be possible to infer the gradient coil from the scanner model. If not, for example because of a custom upgrade or use of a gradient insert set, then the specifications of the actual gradient coil should be reported independently.
{term}MRTransmitCoilSequence (metadata)RECOMMENDEDstringThis is a relevant field if a non-standard transmit coil is used. Corresponds to DICOM Tag 0018, 9049 MR Transmit Coil Sequence.
{term}MatrixCoilMode (metadata)RECOMMENDEDstring(If used) A method for reducing the number of independent channels by combining in analog the signals from multiple coil elements. There are typically different default modes when using un-accelerated or accelerated (for example, \"GRAPPA\", \"SENSE\") imaging.
{term}CoilCombinationMethod (metadata)RECOMMENDEDstringAlmost all fMRI studies using phased-array coils use root-sum-of-squares (rSOS) combination, but other methods exist. The image reconstruction is changed by the coil combination method (as for the matrix coil mode above), so anything non-standard should be reported.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "6f624e1e", "metadata": {}, "source": [ "Example for `ReceiveCoilActiveElements`:\n", "\n", "For Siemens, coil channels are typically not activated/selected individually,\n", "but rather in pre-defined selectable \"groups\" of individual channels,\n", "and the list of the \"groups\" of elements that are active/selected in any\n", "given scan populates the `Coil String` entry in Siemens' private DICOM fields\n", "(for example, `HEA;HEP` for the Siemens standard 32 ch coil\n", "when both the anterior and posterior groups are activated).\n", "This is a flexible field that can be used as most appropriate for a given\n", "vendor and coil to define the \"active\" coil elements.\n", "Since individual scans can sometimes not have the intended coil elements selected,\n", "it is preferable for this field to be populated directly from the DICOM\n", "for each individual scan, so that it can be used as a mechanism for checking\n", "that a given scan was collected with the intended coil elements selected\n", "\n", "(magnetic-resonance-imaging:common-metadata-fields:sequence-specifics)=\n", "### Sequence Specifics" ] }, { "cell_type": "code", "execution_count": 6, "id": "1a6222f3", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}PulseSequenceType (metadata)RECOMMENDEDstringA general description of the pulse sequence used for the scan (for example, \"MPRAGE\", \"Gradient Echo EPI\", \"Spin Echo EPI\", \"Multiband gradient echo EPI\").
{term}ScanningSequence (metadata)RECOMMENDEDstring or array of stringsDescription of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 Scanning Sequence.
{term}SequenceVariant (metadata)RECOMMENDEDstring or array of stringsVariant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 Sequence Variant.
{term}ScanOptions (metadata)RECOMMENDEDstring or array of stringsParameters of ScanningSequence. Corresponds to DICOM Tag 0018, 0022 Scan Options.
{term}SequenceName (metadata)RECOMMENDEDstringManufacturer's designation of the sequence name. Corresponds to DICOM Tag 0018, 0024 Sequence Name.
{term}PulseSequenceDetails (metadata)RECOMMENDEDstringInformation beyond pulse sequence type that identifies the specific pulse sequence used (for example, \"Standard Siemens Sequence distributed with the VB17 software\", \"Siemens WIP ### version #.##,\" or \"Sequence written by X using a version compiled on MM/DD/YYYY\").
{term}NonlinearGradientCorrection (metadata)RECOMMENDED, but REQUIRED if PET data are presentbooleanBoolean stating if the image saved has been corrected for gradient nonlinearities by the scanner sequence.

Must be one of: \"true\", \"false\".
{term}MRAcquisitionType (metadata)RECOMMENDED, but REQUIRED for Arterial Spin LabelingstringType of sequence readout. Corresponds to DICOM Tag 0018, 0023 MR Acquisition Type.

Must be one of: \"2D\", \"3D\".
{term}MTState (metadata)RECOMMENDEDbooleanBoolean stating whether the magnetization transfer pulse is applied. Corresponds to DICOM Tag 0018, 9020 Magnetization Transfer.

Must be one of: \"true\", \"false\".
{term}MTOffsetFrequency (metadata)RECOMMENDED if the MTstate is True.numberThe frequency offset of the magnetization transfer pulse with respect to the central H1 Larmor frequency in Hertz (Hz).
{term}MTPulseBandwidth (metadata)RECOMMENDED if the MTstate is True.numberThe excitation bandwidth of the magnetization transfer pulse in Hertz (Hz).
{term}MTNumberOfPulses (metadata)RECOMMENDED if the MTstate is True.numberThe number of magnetization transfer RF pulses applied before the readout.
{term}MTPulseShape (metadata)RECOMMENDED if the MTstate is True.stringShape of the magnetization transfer RF pulse waveform. The value \"GAUSSHANN\" refers to a Gaussian pulse with a Hanning window. The value \"SINCHANN\" refers to a sinc pulse with a Hanning window. The value \"SINCGAUSS\" refers to a sinc pulse with a Gaussian window.

Must be one of: \"HARD\", \"GAUSSIAN\", \"GAUSSHANN\", \"SINC\", \"SINCHANN\", \"SINCGAUSS\", \"FERMI\".
{term}MTPulseDuration (metadata)RECOMMENDED if the MTstate is True.numberDuration of the magnetization transfer RF pulse in seconds.
{term}SpoilingState (metadata)RECOMMENDEDbooleanBoolean stating whether the pulse sequence uses any type of spoiling strategy to suppress residual transverse magnetization.

Must be one of: \"true\", \"false\".
{term}SpoilingType (metadata)RECOMMENDED if the SpoilingState is True.stringSpecifies which spoiling method(s) are used by a spoiled sequence.

Must be one of: \"RF\", \"GRADIENT\", \"COMBINED\".
{term}SpoilingRFPhaseIncrement (metadata)RECOMMENDED if the SpoilingType is \"RF\" or \"COMBINED\".numberThe amount of incrementation described in degrees, which is applied to the phase of the excitation pulse at each TR period for achieving RF spoiling.
{term}SpoilingGradientMoment (metadata)RECOMMENDED if the SpoilingType is \"GRADIENT\" or \"COMBINED\".numberZeroth moment of the spoiler gradient lobe in millitesla times second per meter (mT.s/m).
{term}SpoilingGradientDuration (metadata)RECOMMENDED if the SpoilingType is \"GRADIENT\" or \"COMBINED\".numberThe duration of the spoiler gradient lobe in seconds. The duration of a trapezoidal lobe is defined as the summation of ramp-up and plateau times.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"PulseSequenceType\": \"RECOMMENDED\",\n", " \"ScanningSequence\": \"RECOMMENDED\",\n", " \"SequenceVariant\": \"RECOMMENDED\",\n", " \"ScanOptions\": \"RECOMMENDED\",\n", " \"SequenceName\": \"RECOMMENDED\",\n", " \"PulseSequenceDetails\": \"RECOMMENDED\",\n", " \"NonlinearGradientCorrection\": \"RECOMMENDED, but REQUIRED if [PET](./09-positron-emission-tomography.md) data are present\",\n", " \"MRAcquisitionType\": \"RECOMMENDED, but REQUIRED for Arterial Spin Labeling\",\n", " \"MTState\": \"RECOMMENDED\",\n", " \"MTOffsetFrequency\": \"RECOMMENDED if the MTstate is `True`.\",\n", " \"MTPulseBandwidth\": \"RECOMMENDED if the MTstate is `True`.\",\n", " \"MTNumberOfPulses\": \"RECOMMENDED if the MTstate is `True`.\",\n", " \"MTPulseShape\": \"RECOMMENDED if the MTstate is `True`.\",\n", " \"MTPulseDuration\": \"RECOMMENDED if the MTstate is `True`.\",\n", " \"SpoilingState\": \"RECOMMENDED\",\n", " \"SpoilingType\": \"RECOMMENDED if the SpoilingState is `True`.\",\n", " \"SpoilingRFPhaseIncrement\": 'RECOMMENDED if the SpoilingType is `\"RF\"` or `\"COMBINED\"`.',\n", " \"SpoilingGradientMoment\": 'RECOMMENDED if the SpoilingType is `\"GRADIENT\"` or `\"COMBINED\"`.',\n", " \"SpoilingGradientDuration\": 'RECOMMENDED if the SpoilingType is `\"GRADIENT\"` or `\"COMBINED\"`.',\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "fcc827ab", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:in-plane-spatial-encoding)=\n", "### In-Plane Spatial Encoding" ] }, { "cell_type": "code", "execution_count": 7, "id": "55c26c76", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}NumberShots (metadata)RECOMMENDEDnumber or array of numbersThe number of RF excitations needed to reconstruct a slice or volume (may be referred to as partition). Please mind that this is not the same as Echo Train Length which denotes the number of k-space lines collected after excitation in a multi-echo readout. The data type array is applicable for specifying this parameter before and after the k-space center is sampled. Please see \"NumberShots\" metadata field in the qMRI appendix for corresponding calculations.
{term}ParallelReductionFactorInPlane (metadata)RECOMMENDEDnumberThe parallel imaging (for instance, GRAPPA) factor. Use the denominator of the fraction of k-space encoded for each slice. For example, 2 means half of k-space is encoded. Corresponds to DICOM Tag 0018, 9069 Parallel Reduction Factor In-plane.
{term}ParallelAcquisitionTechnique (metadata)RECOMMENDEDstringThe type of parallel imaging used (for example \"GRAPPA\", \"SENSE\"). Corresponds to DICOM Tag 0018, 9078 Parallel Acquisition Technique.
{term}PartialFourier (metadata)RECOMMENDEDnumberThe fraction of partial Fourier information collected. Corresponds to DICOM Tag 0018, 9081 Partial Fourier.
{term}PartialFourierDirection (metadata)RECOMMENDEDstringThe direction where only partial Fourier information was collected. Corresponds to DICOM Tag 0018, 9036 Partial Fourier Direction.
{term}PhaseEncodingDirection (metadata)RECOMMENDEDstringThe letters i, j, k correspond to the first, second and third axis of the data in the NIFTI file. The polarity of the phase encoding is assumed to go from zero index to maximum index unless - sign is present (then the order is reversed - starting from the highest index instead of zero). PhaseEncodingDirection is defined as the direction along which phase is was modulated which may result in visible distortions. Note that this is not the same as the DICOM term InPlanePhaseEncodingDirection which can have ROW or COL values. This parameter is REQUIRED if corresponding fieldmap data is present or when using multiple runs with different phase encoding directions (which can be later used for field inhomogeneity correction).

Must be one of: \"i\", \"j\", \"k\", \"i-\", \"j-\", \"k-\".
{term}EffectiveEchoSpacing (metadata)RECOMMENDEDnumberThe \"effective\" sampling interval, specified in seconds, between lines in the phase-encoding direction, defined based on the size of the reconstructed image in the phase direction. It is frequently, but incorrectly, referred to as \"dwell time\" (see the \"DwellTime\" parameter for actual dwell time). It is required for unwarping distortions using field maps. Note that beyond just in-plane acceleration, a variety of other manipulations to the phase encoding need to be accounted for properly, including partial fourier, phase oversampling, phase resolution, phase field-of-view and interpolation. 2 This parameter is REQUIRED if corresponding fieldmap data is present.

Must be a number greater than 0.
{term}TotalReadoutTime (metadata)RECOMMENDEDnumberThis is actually the \"effective\" total readout time, defined as the readout duration, specified in seconds, that would have generated data with the given level of distortion. It is NOT the actual, physical duration of the readout train. If \"EffectiveEchoSpacing\" has been properly computed, it is just EffectiveEchoSpacing * (ReconMatrixPE - 1). 3 This parameter is REQUIRED if corresponding 'field/distortion' maps acquired with opposing phase encoding directions are present (see Case 4: Multiple phase encoded directions).
{term}MixingTime (metadata)RECOMMENDEDnumberIn the context of a stimulated- and spin-echo 3D EPI sequence for B1+ mapping, corresponds to the interval between spin- and stimulated-echo pulses. In the context of a diffusion-weighted double spin-echo sequence, corresponds to the interval between two successive diffusion sensitizing gradients, specified in seconds.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"NumberShots\": \"RECOMMENDED\",\n", " \"ParallelReductionFactorInPlane\": \"RECOMMENDED\",\n", " \"ParallelAcquisitionTechnique\": \"RECOMMENDED\",\n", " \"PartialFourier\": \"RECOMMENDED\",\n", " \"PartialFourierDirection\": \"RECOMMENDED\",\n", " \"PhaseEncodingDirection\": (\n", " \"RECOMMENDED\",\n", " \"This parameter is REQUIRED if corresponding fieldmap data is present \"\n", " \"or when using multiple runs with different phase encoding directions \"\n", " \"(which can be later used for field inhomogeneity correction).\",\n", " ),\n", " \"EffectiveEchoSpacing\": (\n", " \"RECOMMENDED\",\n", " \"2 This parameter is REQUIRED if corresponding fieldmap data is present.\",\n", " ),\n", " \"TotalReadoutTime\": (\n", " \"RECOMMENDED\",\n", " \"3 This parameter is REQUIRED if corresponding 'field/distortion' maps \"\n", " \"acquired with opposing phase encoding directions are present \"\n", " \"(see [Case 4: Multiple phase encoded \"\n", " \"directions](#case-4-multiple-phase-encoded-directions-pepolar)).\",\n", " ),\n", " \"MixingTime\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "39a17c8f", "metadata": {}, "source": [ "2Conveniently, for Siemens data, this value is easily obtained as\n", "`1 / (BWPPPE * ReconMatrixPE)`, where BWPPPE is the\n", "\"BandwidthPerPixelPhaseEncode\" in DICOM Tag 0019, 1028 and ReconMatrixPE is\n", "the size of the actual reconstructed data in the phase direction (which is NOT\n", "reflected in a single DICOM Tag for all possible aforementioned scan\n", "manipulations). See [here](https://lcni.uoregon.edu/kb-articles/kb-0003) and\n", "[here](https://github.com/neurolabusc/dcm_qa/tree/master/In/TotalReadoutTime)\n", "\n", "3We use the time between the center of the first \"effective\" echo\n", "and the center of the last \"effective\" echo, sometimes called the \"FSL definition\".\n", "\n", "(magnetic-resonance-imaging:common-metadata-fields:timing-parameters)=\n", "### Timing Parameters" ] }, { "cell_type": "code", "execution_count": 8, "id": "6be75997", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}EchoTime (metadata)RECOMMENDED, but REQUIRED if corresponding fieldmap data is present, or the data comes from a multi echo sequence or Arterial Spin Labelingnumber or array of numbersThe echo time (TE) for the acquisition, specified in seconds. Corresponds to DICOM Tag 0018, 0081 Echo Time (please note that the DICOM term is in milliseconds not seconds). The data type number may apply to files from any MRI modality concerned with a single value for this field, or to the files in a file collection where the value of this field is iterated using the echo entity. The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in ASL or variable echo time fMRI sequences.
{term}InversionTime (metadata)RECOMMENDEDnumberThe inversion time (TI) for the acquisition, specified in seconds. Inversion time is the time after the middle of inverting RF pulse to middle of excitation pulse to detect the amount of longitudinal magnetization. Corresponds to DICOM Tag 0018, 0082 Inversion Time (please note that the DICOM term is in milliseconds not seconds).

Must be a number greater than 0.
{term}SliceTiming (metadata)RECOMMENDED, but REQUIRED for sparse sequences that do not have the DelayTime field set, and Arterial Spin Labeling with MRAcquisitionType set on 2D.array of numbersThe time at which each slice was acquired within each volume (frame) of the acquisition. Slice timing is not slice order -- rather, it is a list of times containing the time (in seconds) of each slice acquisition in relation to the beginning of volume acquisition. The list goes through the slices along the slice axis in the slice encoding dimension (see below). Note that to ensure the proper interpretation of the \"SliceTiming\" field, it is important to check if the OPTIONAL SliceEncodingDirection exists. In particular, if \"SliceEncodingDirection\" is negative, the entries in \"SliceTiming\" are defined in reverse order with respect to the slice axis, such that the final entry in the \"SliceTiming\" list is the time of acquisition of slice 0. Without this parameter slice time correction will not be possible.
{term}SliceEncodingDirection (metadata)RECOMMENDEDstringThe axis of the NIfTI data along which slices were acquired, and the direction in which \"SliceTiming\" is defined with respect to. i, j, k identifiers correspond to the first, second and third axis of the data in the NIfTI file. A - sign indicates that the contents of \"SliceTiming\" are defined in reverse order - that is, the first entry corresponds to the slice with the largest index, and the final entry corresponds to slice index zero. When present, the axis defined by \"SliceEncodingDirection\" needs to be consistent with the slice_dim field in the NIfTI header. When absent, the entries in \"SliceTiming\" must be in the order of increasing slice index as defined by the NIfTI header.

Must be one of: \"i\", \"j\", \"k\", \"i-\", \"j-\", \"k-\".
{term}DwellTime (metadata)RECOMMENDEDnumberActual dwell time (in seconds) of the receiver per point in the readout direction, including any oversampling. For Siemens, this corresponds to DICOM field 0019, 1018 (in ns). This value is necessary for the optional readout distortion correction of anatomicals in the HCP Pipelines. It also usefully provides a handle on the readout bandwidth, which isn't captured in the other metadata tags. Not to be confused with \"EffectiveEchoSpacing\", and the frequent mislabeling of echo spacing (which is spacing in the phase encoding direction) as \"dwell time\" (which is spacing in the readout direction).
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"EchoTime\": \"RECOMMENDED, but REQUIRED if corresponding fieldmap data is present, or the data comes from a multi echo sequence or Arterial Spin Labeling\",\n", " \"InversionTime\": \"RECOMMENDED\",\n", " \"SliceTiming\": \"RECOMMENDED, but REQUIRED for sparse sequences that do not have the `DelayTime` field set, and Arterial Spin Labeling with `MRAcquisitionType` set on `2D`.\",\n", " \"SliceEncodingDirection\": \"RECOMMENDED\",\n", " \"DwellTime\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "05979490", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:rf-&-contrast)=\n", "### RF & Contrast" ] }, { "cell_type": "code", "execution_count": 9, "id": "25b425fe", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}FlipAngle (metadata)RECOMMENDED, but REQUIRED if LookLocker is set truenumber or array of numbersFlip angle (FA) for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 Flip Angle. The data type number may apply to files from any MRI modality concerned with a single value for this field, or to the files in a file collection where the value of this field is iterated using the flip entity. The data type array provides a value for each volume in a 4D dataset and should only be used when the volume timing is critical for interpretation of the data, such as in ASL or variable flip angle fMRI sequences.
{term}NegativeContrast (metadata)OPTIONALbooleantrue or false value specifying whether increasing voxel intensity (within sample voxels) denotes a decreased value with respect to the contrast suffix. This is commonly the case when Cerebral Blood Volume is estimated via usage of a contrast agent in conjunction with a T2* weighted acquisition protocol.

Must be one of: \"true\", \"false\".
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"FlipAngle\": \"RECOMMENDED, but REQUIRED if `LookLocker` is set `true`\",\n", " \"NegativeContrast\": \"OPTIONAL\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "8ff05e80", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:slice-acceleration)=\n", "### Slice Acceleration" ] }, { "cell_type": "code", "execution_count": 10, "id": "919b5048", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}MultibandAccelerationFactor (metadata)RECOMMENDEDnumberThe multiband factor, for multiband acquisitions.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"MultibandAccelerationFactor\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "7c722800", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:anatomical-landmarks)=\n", "### Anatomical landmarks\n", "\n", "Useful for multimodal co-registration with MEG, (S)EEG, TMS, and so on." ] }, { "cell_type": "code", "execution_count": 11, "id": "147f51a8", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}AnatomicalLandmarkCoordinates (metadata)RECOMMENDEDobject of arraysKey:value pairs of any number of additional anatomical landmarks and their coordinates in voxel units (where first voxel has index 0,0,0) relative to the associated anatomical MRI (for example, {\"AC\": [127,119,149], \"PC\": [128,93,141], \"IH\": [131,114,206]}, or {\"NAS\": [127,213,139], \"LPA\": [52,113,96], \"RPA\": [202,113,91]}). Each array MUST contain three numeric values corresponding to x, y, and z axis of the coordinate system in that exact order.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"AnatomicalLandmarkCoordinates__mri\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "8076cd56", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:echo-planar-imaging-and-b0-mapping)=\n", "### Echo-Planar Imaging and *B0* mapping\n", "\n", "Echo-Planar Imaging (EPI) schemes typically used in the acquisition of\n", "diffusion and functional MRI may also be *intended for* estimating the\n", "*B0* field nonuniformity inside the scanner (in other words,\n", "*mapping the field*) without the acquisition of additional MRI schemes\n", "such as gradient-recalled echo (GRE) sequences that are stored under the\n", "`fmap/` directory of the BIDS structure.\n", "\n", "The modality labels `dwi` (under `dwi/`), `bold` (under `func/`),\n", "`asl` (under `perf/`), `sbref` (under `dwi/`, `func/` or `perf/`), and\n", "any modality under `fmap/` are allowed to encode the MR protocol intent for\n", "fieldmap estimation using the following metadata:" ] }, { "cell_type": "code", "execution_count": 12, "id": "fdf56475", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}B0FieldIdentifier (metadata)RECOMMENDEDstring or array of stringsThe presence of this key states that this particular 3D or 4D image MAY be used for fieldmap estimation purposes. Each \"B0FieldIdentifier\" MUST be a unique string within one participant's tree, shared only by the images meant to be used as inputs for the estimation of a particular instance of the B0 field estimation. It is RECOMMENDED to derive this identifier from DICOM Tags, for example, DICOM tag 0018, 1030 Protocol Name, or DICOM tag 0018, 0024 Sequence Name when the former is not defined (for example, in GE devices.)
{term}B0FieldSource (metadata)RECOMMENDEDstring or array of stringsAt least one existing \"B0FieldIdentifier\" defined by images in the participant's tree. This field states the B0 field estimation designated by the \"B0FieldIdentifier\" that may be used to correct the dataset for distortions caused by B0 inhomogeneities. \"B0FieldSource\" and \"B0FieldIdentifier\" MAY both be present for images that are used to estimate their own B0 field, for example, in \"pepolar\" acquisitions.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"B0FieldIdentifier\": \"RECOMMENDED\",\n", " \"B0FieldSource\": \"RECOMMENDED\",\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "ecd779e2", "metadata": {}, "source": [ "(magnetic-resonance-imaging:common-metadata-fields:institution-information)=\n", "### Institution information" ] }, { "cell_type": "code", "execution_count": 13, "id": "b2e2f226", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/html": [ "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
Key nameRequirement LevelData typeDescription
{term}InstitutionName (metadata)RECOMMENDEDstringThe name of the institution in charge of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 0080 InstitutionName.
{term}InstitutionAddress (metadata)RECOMMENDEDstringThe address of the institution in charge of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 0081 InstitutionAddress.
{term}InstitutionalDepartmentName (metadata)RECOMMENDEDstringThe department in the institution in charge of the equipment that produced the measurements. Corresponds to DICOM Tag 0008, 1040 Institutional Department Name.
" ], "text/plain": [ "" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "field_info = {\n", " \"InstitutionName\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 0080 `InstitutionName`.\"),\n", " \"InstitutionAddress\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 0081 `InstitutionAddress`.\"),\n", " \"InstitutionalDepartmentName\": (\"RECOMMENDED\", \"Corresponds to DICOM Tag 0008, 1040 `Institutional Department Name`.\")\n", "}\n", "\n", "table = render.make_metadata_table(schema_obj, field_info)\n", "display(HTML(markdown(table.to_markdown(), extensions=['tables'])))" ] }, { "cell_type": "markdown", "id": "51df2653", "metadata": {}, "source": [ "When adding additional metadata please use the CamelCase version of\n", "[DICOM ontology terms](https://scicrunch.org/scicrunch/interlex/dashboard)\n", "whenever possible. See also\n", "[recommendations on JSON files](../02-common-principles.md#keyvalue-files-dictionaries).\n", "\n", "(magnetic-resonance-imaging:anatomy-imaging-data)=\n", "## Anatomy imaging data" ] }, { "cell_type": "code", "execution_count": 14, "id": "ac2a8c56", "metadata": { "tags": [ "remove-input" ] }, "outputs": [ { "data": { "text/markdown": [ "Template:\n", "```Text\n", "sub-