Create unique series description (#275)

added unique SeriesDescription to outputs 4 ezBIDS

* Made use of the SeriesDescription field produced by dcm2niix
  to allow ezBIDS to differentiate between mulitple pet scans
  for the same subject/session even. The SeriesDescription field
  previously housed (observed at least) the reconstruction method.
  Now it gets some PET BIDS entities along with an MD5 hash of the
  TimeZero, InjectedMass, TracerName, ReconMethodName etc to ensure
  that a unique and human readable value is recorded in
  SeriesDescription field; added the same functionality and field
  to the ecat methods
* Sanitized date's from datetime fields injested by the spreadsheet
  reader when those fields should be Time objects. e.g. TimeZero,
  MolarActivityMeasureTime etc.
* bump version

Author: bendhouseart

pypet2bids/pypet2bids/dcm2niix4pet.py

@@ -521,6 +521,32 @@ def run_dcm2niix(self):
                     sidecar_json.update(self.spreadsheet_metadata.get('nifti_json', {}))
                     sidecar_json.update(self.additional_arguments)
 
+                    # this is mostly for ezBIDS, but it helps us to make better use of the series description that
+                    # dcm2niix generates by default for PET imaging
+                    collect_these_fields = {
+                        'SeriesDescription': '',
+                        'TracerName': 'trc',
+                        'InjectedRadioactivity': '',
+                        'InjectedRadioactivityUnits': '',
+                        'ReconMethodName': 'rec',
+                        'TimeZero': '',
+                    }
+                    collection_of_fields = {}
+                    for field, entity_string in collect_these_fields.items():
+                        if sidecar_json.get(field):
+                            # if there's a shortened entity string for the field use that
+                            if entity_string != '':
+                                collection_of_fields[entity_string] = sidecar_json.get(field)
+                            else:
+                                collection_of_fields[field] = sidecar_json.get(field)
+
+                    if self.session_id:
+                        collection_of_fields['ses'] = self.session_id
+
+                    hash_string = helper_functions.hash_fields(**collection_of_fields)
+
+                    sidecar_json.update({'SeriesDescription': hash_string})
+
                 # if there's a subject id rename the output file to use it
                 if self.subject_id:
                     if 'nii.gz' in created_path.name:

pypet2bids/pypet2bids/ecat.py

@@ -363,6 +363,32 @@ def show_sidecar(self, output_path=None):
         """
         self.prune_sidecar()
         self.sidecar_template = helper_functions.replace_nones(self.sidecar_template)
+
+        # this is mostly for ezBIDS, but it helps us to make better use of the series description that
+        # dcm2niix generates by default for PET imaging, here we mirror the dcm2niix output for ecats
+        collect_these_fields = {
+            'SeriesDescription': '',
+            'TracerName': 'trc',
+            'InjectedRadioactivity': '',
+            'InjectedRadioactivityUnits': '',
+            'ReconMethodName': 'rec',
+            'TimeZero': '',
+        }
+        collection_of_fields = {}
+        for field, entity_string in collect_these_fields.items():
+            if self.sidecar_template.get(field, None):
+                # if there's a shortened entity string for the field use that
+                if entity_string != '':
+                    collection_of_fields[entity_string] = self.sidecar_template.get(field)
+                else:
+                    collection_of_fields[field] = self.sidecar_template.get(field)
+
+        if helper_functions.collect_bids_part('ses', self.output_path) != '':
+            collection_of_fields['ses'] = helper_functions.collect_bids_part('ses', self.output_path)
+
+        hash_string = helper_functions.hash_fields(**collection_of_fields)
+        self.sidecar_template['SeriesDescription'] = hash_string
+
         if output_path:
             if not isinstance(output_path, pathlib.Path):
                 output_path = pathlib.Path(output_path)

pypet2bids/pypet2bids/helper_functions.py

@@ -20,6 +20,7 @@
 import shutil
 import typing
 import json
+import hashlib
 import warnings
 import logging
 import dotenv
@@ -979,3 +980,20 @@ def format(self, record):
         log_fmt = self.FORMATS.get(record.levelno)
         formatter = logging.Formatter(log_fmt)
         return formatter.format(record)
+
+
+def hash_fields(**fields):
+    hash_return_string = ""
+    hash_string = ""
+    keys_we_want = ['ses', 'rec', 'trc']
+    for key, value in fields.items():
+        # sanitize values
+        regex = r"[^a-zA-Z0-9]"
+        value = re.sub(regex, "", str(value))
+        hash_string += f"{key}-{value}_"
+        if key in keys_we_want:
+            hash_return_string += f"{key}-{value}_"
+
+    hash_hex = hashlib.md5(hash_string.encode('utf-8')).hexdigest()
+
+    return f"{hash_return_string}{hash_hex}"

pypet2bids/pypet2bids/update_json_pet_file.py

@@ -7,6 +7,7 @@
 from dateutil import parser
 import argparse
 import pydicom
+import datetime
 from typing import Union
 
 try:
@@ -584,6 +585,19 @@ def get_metadata_from_spreadsheet(metadata_path: Union[str, Path], image_folder,
             dicom_metadata=image_header_dict,
             **additional_arguments)
 
+    # remove any dates from the spreadsheet time values
+    for key, value in spreadsheet_values.items():
+        if 'time' in key.lower():
+            if isinstance(value, str):
+                # check to see if the value converts to a datetime object with a date
+                try:
+                    time_value = parser.parse(value).time().strftime("%H:%M:%S")
+                    spreadsheet_values[key] = time_value
+                except ValueError:
+                    pass
+            if isinstance(value, datetime.datetime):
+                spreadsheet_values[key] = value.time().strftime("%H:%M:%S")
+
     if Path(metadata_path).is_dir() or metadata_path == "":
         # we accept folder input as well as no input, in the
         # event of no input we search for spreadsheets in the
@@ -621,11 +635,18 @@ def get_metadata_from_spreadsheet(metadata_path: Union[str, Path], image_folder,
     # even out the values in the blood tsv columns if they're different lengths by appending zeros to the end
     # of each column/list
     # determine the longest column
-    longest_column = max([len(column) for column in spreadsheet_metadata['blood_tsv'].values()])
-    # iterate over each column, determine how many zeros to append to the end of each column
-    for column in spreadsheet_metadata['blood_tsv'].keys():
-        zeros_to_append = longest_column - len(spreadsheet_metadata['blood_tsv'][column])
-        spreadsheet_metadata['blood_tsv'][column] += [0] * zeros_to_append
+    column_lengths = [len(column) for column in spreadsheet_metadata['blood_tsv'].values()]
+
+    try:
+        longest_column = max(column_lengths)
+    except ValueError:
+        # columns are all the same length or there are no columns
+        longest_column = None
+    if longest_column:
+        # iterate over each column, determine how many zeros to append to the end of each column
+        for column in spreadsheet_metadata['blood_tsv'].keys():
+            zeros_to_append = longest_column - len(spreadsheet_metadata['blood_tsv'][column])
+            spreadsheet_metadata['blood_tsv'][column] += [0] * zeros_to_append
 
     # check for existing blood json values
     for column in blood_json_columns:

pypet2bids/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pypet2bids"
-version = "1.3.5"
+version = "1.3.6"
 description = "A python implementation of an ECAT to BIDS converter."
 authors = ["anthony galassi <[email protected]>"]
 license = "MIT"