diff --git a/.circleci/config.yml b/.circleci/config.yml index 4b6ba5382c..d458c32b1d 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -43,6 +43,22 @@ jobs: # failures for local file:/// -- yoh found no better way, linkchecker -t 1 --check-extern --ignore-url 'file:///.*' --ignore-url https://fonts.gstatic.com ~/build/site/*html ~/build/site/*/*.html + build_docs_pdf: + working_directory: ~/bids-specification/pdf_build_src + docker: + - image: danteev/texlive:TL2017 + steps: + - checkout: + path: ~/bids-specification + - run: + name: generate pdf version docs + command: sh build_pdf.sh + - store_artifacts: + path: bids-spec.pdf + - run: + name: remove pdf version from repo + command: rm bids-spec.pdf + # Auto changelog collector github-changelog-generator: working_directory: ~/build @@ -144,6 +160,7 @@ workflows: search_build: jobs: - build_docs + - build_docs_pdf - linkchecker: requires: - build_docs diff --git a/.gitignore b/.gitignore index ccbfadbd88..aa7b6b684b 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ -site/ \ No newline at end of file +site/ +.DS_Store +src/.DS_Store +src/04-modality-specific-files/.DS_Store \ No newline at end of file diff --git a/pdf_build_src/README.md b/pdf_build_src/README.md new file mode 100644 index 0000000000..0568002caf --- /dev/null +++ b/pdf_build_src/README.md @@ -0,0 +1,41 @@ +# pdf-version of BIDS specification + +The `pdf_build_src` directory contains the scripts and tex files required to build a pdf document of the BIDS specification from multiple markdown files using the pandoc library. + +Pandoc is command line tool which is also a Haskell library that converts files from one markup format to another. More here: https://pandoc.org/index.html + +## Requirements + +For the pdf build to be successful, the following need to be installed: + +- Python 3.x +- pandoc +- Latest version of LaTeX: By default, Pandoc creates PDFs using LaTeX. Because a full MacTeX installation uses four gigabytes of disk space, pandoc recommends BasicTeX or TinyTeX and using the tlmgr tool to install additional packages as needed. + +Installation instructions for both pandoc and LaTeX: https://pandoc.org/installing.html + +## Building pdf document + +Run the `build_pdf.sh` from the `pdf_build_src` with the command `sh build_pdf.sh` from the command line terminal + +List of warnings are for missing characters like emojis while converting from markdown to pdf. Except for losing those characters in the final document, it doesn't affect the formatting or contents and therefore, can be ignored. + +## Technical Overview + +Pandoc comes with a plethora of options to format the resulting document. For building a pdf from multiple markdowns, a consolidated intermediate tex file is first built, which is then converted to a pdf document. To achieve the desired formatting in the final pdf, additional tex files are used with options offered by pandoc. + +### Formatting files + +`listings_setup.tex` - Listings is a LaTeX package used for typestting programming code in TeX. This file sets up the listings package to suit our needs and is used with the `--listings` option. + +`cover.tex` - BIDS Logo is used as a cover page for the document. `cover.tex` is used with the option `--include-before-body` + +`header.tex` - Header tex file that's updated with the latest version number and date when `build_pdf.sh` is run. Used with the `-H` header option. + +### Scripts + +`process_markdowns.py` - Script that processes markdown files in the `src` directory that are duplicated and modified for the needs of the pdf. + +`pandoc_script.py` - Prepares and runs the final pandoc command through the `build_pdf.sh` script + +`build_pdf.sh` - Shell script that organizes the directory structure and runs the above two python scripts diff --git a/pdf_build_src/build_pdf.sh b/pdf_build_src/build_pdf.sh new file mode 100644 index 0000000000..b1ba744b83 --- /dev/null +++ b/pdf_build_src/build_pdf.sh @@ -0,0 +1,16 @@ +# Shell script that runs process_markdowns.py and pandoc_script.py in sequence to build the pdf document + +# prepare the copied src directory +python3 process_markdowns.py + +# copy pandoc_script into the temp src_copy directory +cp pandoc_script.py header.tex cover.tex listings_setup.tex src_copy/src + +# run pandoc_script from src_copy directory +cd src_copy/src +python3 pandoc_script.py +mv bids-spec.pdf ../.. +cd ../.. + +# delete the duplicated src directory +rm -rf src_copy diff --git a/pdf_build_src/cover.tex b/pdf_build_src/cover.tex new file mode 100644 index 0000000000..a69c1261da --- /dev/null +++ b/pdf_build_src/cover.tex @@ -0,0 +1,27 @@ +% adds the bids logo as the cover page of the pdf +\begin{titlepage} + +\newcommand{\HRule}{\rule{\linewidth}{0.5mm}} % Defines a new command for the horizontal lines, change thickness here + +\center % Center everything on the page + + + +%---------------------------------------------------------------------------------------- +% LOGO SECTION +%---------------------------------------------------------------------------------------- + +\includegraphics[width=0.6\textwidth]{images/BIDS_logo.jpg}\\[1cm] + +%---------------------------------------------------------------------------------------- +% TITLE SECTION +%---------------------------------------------------------------------------------------- + +\HRule \\[0.4cm] +{ \huge \bfseries Brain Imaging Data Structure Specification}\\[0.4cm] % Title of your document +\HRule \\[1.5cm] + +% \textsc{\large v1.2.1}\\[0.5cm]{\large 2019-08-14}\\[2cm] + +% \vfill % Fill the rest of the page with whitespace +\textsc{\large v1.2.1}\\[0.5cm]{\large 2019-08-14}\\[2cm]\vfill\end{titlepage} \ No newline at end of file diff --git a/pdf_build_src/header.tex b/pdf_build_src/header.tex new file mode 100644 index 0000000000..4d6b5a679b --- /dev/null +++ b/pdf_build_src/header.tex @@ -0,0 +1,6 @@ +% header file +\usepackage{fancyhdr} +\pagestyle{fancy} +\fancyhf{} +\chead{Brain Imaging Data Structure v1.2.1 2019-08-14} +\fancyfoot[LE,RO]{\thepage} diff --git a/pdf_build_src/listings_setup.tex b/pdf_build_src/listings_setup.tex new file mode 100644 index 0000000000..97ddd7d09f --- /dev/null +++ b/pdf_build_src/listings_setup.tex @@ -0,0 +1,25 @@ +% Contents of listings-setup.tex +\usepackage{xcolor} +\usepackage{graphicx} + +\lstset{ + basicstyle=\ttfamily, + numbers=left, + keywordstyle=\color[rgb]{0.13,0.29,0.53}\bfseries, + stringstyle=\color[rgb]{0.31,0.60,0.02}, + commentstyle=\color[rgb]{0.56,0.35,0.01}\itshape, + numberstyle=\footnotesize, + stepnumber=1, + numbersep=5pt, + backgroundcolor=\color[RGB]{248,248,248}, + showspaces=false, + showstringspaces=false, + showtabs=false, + tabsize=2, + captionpos=b, + breaklines=true, + breakautoindent=true, + escapeinside={\%*}{*)}, + linewidth=\textwidth, + basewidth=0.5em +} \ No newline at end of file diff --git a/pdf_build_src/pandoc_script.py b/pdf_build_src/pandoc_script.py new file mode 100644 index 0000000000..1e3d18061c --- /dev/null +++ b/pdf_build_src/pandoc_script.py @@ -0,0 +1,43 @@ +"""Use the pandoc library as a final step to build the pdf. + +This is done once the duplicate src directory is processed. +""" +import os +import subprocess + + +def build_pdf(filename): + """Construct command with required pandoc flags and run using subprocess. + + Parameters + ---------- + filename : str + Name of the output file. + + """ + markdown_list = [] + for root, dirs, files in os.walk('.'): + for file in files: + if file.endswith(".md") and file != 'index.md': + markdown_list.append(os.path.join(root, file)) + elif file == 'index.md': + index_page = os.path.join(root, file) + + default_pandoc_cmd = "pandoc " + + # creates string of file paths in the order we'd like them to be appear + # ordering is taken care of by the inherent file naming + files_string = index_page + " " + " ".join(sorted(markdown_list)) + + flags = (" -f markdown_github --include-before-body cover.tex --toc " + "-V documentclass=report --listings -H listings_setup.tex " + "-H header.tex -V linkcolor:blue -V geometry:a4paper " + "-V geometry:margin=2cm --pdf-engine=xelatex -o ") + output_filename = filename + + cmd = default_pandoc_cmd + files_string + flags + output_filename + subprocess.run(cmd.split()) + + +if __name__ == "__main__": + build_pdf('bids-spec.pdf') \ No newline at end of file diff --git a/pdf_build_src/process_markdowns.py b/pdf_build_src/process_markdowns.py new file mode 100644 index 0000000000..23c9dd84f7 --- /dev/null +++ b/pdf_build_src/process_markdowns.py @@ -0,0 +1,191 @@ +"""Process the markdown files. +The purpose of the script is to create a duplicate src directory within which +all of the markdown files are processed to match the specifications of building +a pdf from multiple markdown files using the pandoc library (***add link to +pandoc library documentation***) with pdf specific text rendering in mind as +well. +""" + +import os +import subprocess +import re +from datetime import datetime + + +def run_shell_cmd(command): + """Run shell/bash commands passed as a string using subprocess module.""" + process = subprocess.Popen(command.split(), stdout=subprocess.PIPE, + stderr=subprocess.PIPE) + output = process.stdout.read() + + return output.decode('utf-8') + + +def copy_src(): + """Duplicate src directory to a new but temp directory named 'src_copy'.""" + # source and target directories + src_path = "../src/" + target_path = "src_copy" + + # make new directory + mkdir_cmd = "mkdir "+target_path + run_shell_cmd(mkdir_cmd) + + # copy contents of src directory + copy_cmd = "cp -R "+src_path+" "+target_path + run_shell_cmd(copy_cmd) + + +def copy_bids_logo(): + """Copy BIDS_logo.jpg from the BIDS_logo dir in the root of the repo.""" + run_shell_cmd("cp ../BIDS_logo/BIDS_logo.jpg src_copy/src/images/") + + +def copy_images(root_path): + """Copy images. + Will be done from images directory of subdirectories to images directory + in the src directory + """ + subdir_list = [] + + # walk through the src directory to find subdirectories named 'images' + # and copy contents to the 'images' directory in the duplicate src + # directory + for root, dirs, files in os.walk(root_path): + if 'images' in dirs: + subdir_list.append(root) + + for each in subdir_list: + if each != root_path: + run_shell_cmd("cp -R "+each+"/images"+" "+root_path+"/images/") + + +def extract_header_string(): + """Extract the latest release's version number and date from CHANGES.md.""" + released_versions = [] + run_shell_cmd("cp ../mkdocs.yml src_copy/") + + with open(os.path.join(os.path.dirname(__file__), 'src_copy/mkdocs.yml'), 'r') as file: + data = file.readlines() + + header_string = data[0].split(": ")[1] + + title = " ".join(header_string.split()[0:4]) + version_number = header_string.split()[-1] + build_date = datetime.today().strftime('%Y-%m-%d') + + return title, version_number, build_date + + +def add_header(): + """Add the header string extracted from changelog to header.tex file.""" + title, version_number, build_date = extract_header_string() + header = " ".join([title, version_number, build_date]) + + # creating a header string with latest version number and date + header_string = ("\chead{ " + header + " }") + + with open('header.tex', 'r') as file: + data = file.readlines() + + # now change the last but 2nd line, note that you have to add a newline + data[-2] = header_string+'\n' + + # re-write header.tex file with new header string + with open('header.tex', 'w') as file: + file.writelines(data) + + +def remove_internal_links(root_path, link_type): + """Find and replace all cross and same markdown internal links. + The links will be replaced with plain text associated with it. + """ + if link_type == 'cross': + # regex that matches cross markdown links within a file + # TODO: add more documentation explaining regex + primary_pattern = re.compile(r'\[((?!http).[\w\s.\(\)`*/–]+)\]\(((?!http).+(\.md|\.yml|\.md#[\w\-\w]+))\)') # noqa: E501 + elif link_type == 'same': + # regex that matches references sections within the same markdown + primary_pattern = re.compile(r'\[([\w\s.\(\)`*/–]+)\]\(([#\w\-._\w]+)\)') + + for root, dirs, files in os.walk(root_path): + for file in files: + if file.endswith(".md"): + with open(os.path.join(root, file), 'r') as markdown: + data = markdown.readlines() + + for ind, line in enumerate(data): + match = primary_pattern.search(line) + + if match: + line = re.sub(primary_pattern, + match.group().split('](')[0][1:], line) + + data[ind] = line + + with open(os.path.join(root, file), 'w') as markdown: + markdown.writelines(data) + + +def modify_changelog(): + """Change first line of the changelog to markdown Heading 1. + This modification makes sure that in the pdf build, changelog is a new + chapter. + """ + with open('src_copy/src/CHANGES.md', 'r') as file: + data = file.readlines() + + data[0] = "# Changelog" + + with open('src_copy/src/CHANGES.md', 'w') as file: + file.writelines(data) + + +def edit_titlepage(): + """Add title and version number of the specification to the titlepage.""" + title, version_number, build_date = extract_header_string() + + with open('cover.tex', 'r') as file: + data = file.readlines() + + data[-1] = ("\\textsc{\large "+version_number+"}" + + "\\\\[0.5cm]" + + "{\large " + + build_date + + "}" + + "\\\\[2cm]" + + "\\vfill" + + "\\end{titlepage}") + + with open('cover.tex', 'w') as file: + data = file.writelines(data) + + +if __name__ == '__main__': + + duplicated_src_dir_path = 'src_copy/src' + + # Step 1: make a copy of the src directory in the current directory + copy_src() + + # Step 2: copy BIDS_logo to images directory of the src_copy directory + copy_bids_logo() + + # Step 3: copy images from subdirectories of src_copy directory + copy_images(duplicated_src_dir_path) + subprocess.call("mv src_copy/src/images/images/* src_copy/src/images/", + shell=True) + + # Step 4: extract the latest version number, date and title + extract_header_string() + add_header() + + edit_titlepage() + + # Step 5: modify changelog to be a level 1 heading to facilitate section + # separation + modify_changelog() + + # Step 6: remove all internal links + remove_internal_links(duplicated_src_dir_path, 'cross') + remove_internal_links(duplicated_src_dir_path, 'same') \ No newline at end of file diff --git a/src/02-common-principles.md b/src/02-common-principles.md index 51140f00e3..3acfa2a5de 100644 --- a/src/02-common-principles.md +++ b/src/02-common-principles.md @@ -298,9 +298,9 @@ If a data dictionary is provided, it MAY contain one or more fields describing the columns found in the TSV file (in addition to any other metadata one wishes to include that describe the file as a whole). Note that if a field name included in the data -dictionary matches a column name in the TSV file, then that field MUST contain -a description of the corresponding column, using an object containing the -following fields: +dictionary matches a column name in the TSV file, then that field MUST contain a +description of the corresponding column, using an object containing the following +fields: | Field name | Definition | | :---------- | :--------------------------------------------------------------------------------------------------------------------- | diff --git a/src/03-modality-agnostic-files.md b/src/03-modality-agnostic-files.md index dcc5d2af69..c98c6348fc 100644 --- a/src/03-modality-agnostic-files.md +++ b/src/03-modality-agnostic-files.md @@ -10,7 +10,7 @@ The file dataset_description.json is a JSON file describing the dataset. Every dataset MUST include this file with the following fields: | Field name | Definition | -| :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ------------------------------------------------------------------------------| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | REQUIRED. Name of the dataset. | | BIDSVersion | REQUIRED. The version of the BIDS standard that was used. | | License | RECOMMENDED. What license is this dataset distributed under? The use of license name abbreviations is suggested for specifying a license. A list of common licenses with suggested abbreviations can be found in Appendix II. | @@ -18,7 +18,7 @@ dataset MUST include this file with the following fields: | Acknowledgements | OPTIONAL. Text acknowledging contributions of individuals or institutions beyond those listed in Authors or Funding. | | HowToAcknowledge | OPTIONAL. Text containing instructions on how researchers using this dataset should acknowledge the original authors. This field can also be used to define a publication that should be cited in publications that use the dataset. | | Funding | OPTIONAL. List of sources of funding (grant numbers). | -| EthicsApprovals | OPTIONAL. List of ethics committee approvals of the research protocols and/or protocol identifiers. | +| EthicsApprovals | OPTIONAL. List of ethics committee approvals of the research protocols and/or protocol identifiers. | | | ReferencesAndLinks | OPTIONAL. List of references to publication that contain information on the dataset, or links. | | DatasetDOI | OPTIONAL. The Document Object Identifier of the dataset (not the corresponding paper). | diff --git a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md index a210cb69c2..5e652f866b 100644 --- a/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md +++ b/src/04-modality-specific-files/01-magnetic-resonance-imaging-data.md @@ -11,7 +11,7 @@ by Ben Inglis: ### Scanner Hardware | Field name | Definition | -| :---------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Manufacturer | RECOMMENDED. Manufacturer of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0070 `Manufacturer` | | ManufacturersModelName | RECOMMENDED. Manufacturer's model name of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1090 `Manufacturers Model Name` | | DeviceSerialNumber | RECOMMENDED. The serial number of the equipment that produced the composite instances. Corresponds to DICOM Tag 0018, 1000 `DeviceSerialNumber`. A pseudonym can also be used to prevent the equipment from being identifiable, so long as each pseudonym is unique within the dataset | @@ -29,7 +29,7 @@ by Ben Inglis: #### Sequence Specifics | Field name | Definition | -| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | PulseSequenceType | RECOMMENDED. A general description of the pulse sequence used for the scan (i.e. MPRAGE, Gradient Echo EPI, Spin Echo EPI, Multiband gradient echo EPI). | | ScanningSequence | RECOMMENDED. Description of the type of data acquired. Corresponds to DICOM Tag 0018, 0020 `Scanning Sequence`. | | SequenceVariant | RECOMMENDED. Variant of the ScanningSequence. Corresponds to DICOM Tag 0018, 0021 `Sequence Variant`. | @@ -41,7 +41,7 @@ by Ben Inglis: #### In-Plane Spatial Encoding | Field name | Definition | -| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NumberShots | RECOMMENDED. The number of RF excitations need to reconstruct a slice or volume. Please mind that this is not the same as Echo Train Length which denotes the number of lines of k-space collected after an excitation. | | ParallelReductionFactorInPlane | RECOMMENDED. The parallel imaging (e.g, 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`. | | ParallelAcquisitionTechnique | RECOMMENDED. The type of parallel imaging used (e.g. GRAPPA, SENSE). Corresponds to DICOM Tag 0018, 9078 `Parallel Acquisition Technique`. | @@ -64,39 +64,40 @@ first "effective" echo and the center of the last "effective" echo. #### Timing Parameters -| Field name | Definition | -| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| EchoTime | RECOMMENDED. The echo time (TE) for the acquisition, specified in seconds. This parameter is REQUIRED if corresponding fieldmap data is present or the data comes from a multi echo sequence. Corresponds to DICOM Tag 0018, 0081 `Echo Time` (please note that the DICOM term is in milliseconds not seconds). | -| InversionTime | RECOMMENDED. The 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). | -| SliceTiming | RECOMMENDED. The 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 (in JSON format) 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 (i.e., the final entry in the `SliceTiming` list is the time of acquisition of slice 0). This parameter is REQUIRED for sparse sequences that do not have the `DelayTime` field set. In addition without this parameter slice time correction will not be possible. | -| SliceEncodingDirection | RECOMMENDED. Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-` (the 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. | -| DwellTime | RECOMMENDED. Actual 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). | +| Field name | Definition | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| EchoTime | RECOMMENDED. The echo time (TE) for the acquisition, specified in seconds. This parameter is REQUIRED if corresponding fieldmap data is present or the data comes from a multi echo sequence. Corresponds to DICOM Tag 0018, 0081 `Echo Time` (please note that the DICOM term is in milliseconds not seconds). | +| InversionTime | RECOMMENDED. The 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). | +| SliceTiming | RECOMMENDED. The 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 (in JSON format) 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 (i.e., the final entry in the `SliceTiming` list is the time of acquisition of slice 0). This parameter is REQUIRED for sparse sequences that do not have the `DelayTime` field set. In addition without this parameter slice time correction will not be possible. | +| SliceEncodingDirection | RECOMMENDED. Possible values: `i`, `j`, `k`, `i-`, `j-`, `k-` (the 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. | +| DwellTime | RECOMMENDED. Actual 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). | #### RF & Contrast -| Field name | Definition | -| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| FlipAngle | RECOMMENDED. Flip angle for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. | -| MultibandAccelerationFactor | RECOMMENDED. The multiband factor, for multiband acquisitions. | -| NegativeContrast | OPTIONAL. Boolean (`true` 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. | +| Field name | Definition | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| FlipAngle | RECOMMENDED. Flip angle for the acquisition, specified in degrees. Corresponds to: DICOM Tag 0018, 1314 `Flip Angle`. | +| MultibandAccelerationFactor | RECOMMENDED. The multiband factor, for multiband acquisitions. | +| NegativeContrast | OPTIONAL. Boolean (`true` 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. | #### Slice Acceleration | Field name | Definition | -| :-------------------------- | :------------------------------------------------------------- | +| ---------------------------- | ------------------------------------------------------------- | | MultibandAccelerationFactor | RECOMMENDED. The multiband factor, for multiband acquisitions. | #### Anatomical landmarks + Useful for multimodal co-registration with MEG, (S)EEG, TMS, etc. | Field name | Definition | -| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |------------------------------------------------------------------------------- | | AnatomicalLandmarkCoordinates | RECOMMENDED. Key: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, (e.g. `{"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]}`). | #### Institution information | Field name | Definition | -| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| -------------------------------------------------------------------------------------------------------------------------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | InstitutionName | RECOMMENDED. The name of the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0080 `InstitutionName`. | | InstitutionAddress | RECOMMENDED. The address of the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 0081 `InstitutionAddress`. | | InstitutionalDepartmentName | RECOMMENDED. The department in the institution in charge of the equipment that produced the composite instances. Corresponds to DICOM Tag 0008, 1040 `Institutional Department Name`. | @@ -119,22 +120,22 @@ sub-