Add phase encoding direction and echo number to files and MRI QC tabl…

…es (#8152) Phase encoding and echo number are now required to uniquely identify scans for some protocols.
aces · Aug 18, 2022 · c9873ed · c9873ed
1 parent e7b6a97
commit c9873ed
Show file tree

Hide file tree

Showing 6 changed files with 86 additions and 11 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,12 @@ core section.***
 - ***When possible please provide the number of the pull request(s) containing the 
 changes in the following format: PR #1234***
 
+### Core
+#### Updates and Improvements
+- Addition of `PhaseEncodingDirection` and `EchoNumber` columns to the `files`, `files_qcstatus`
+  and `feedback_mri_comments` tables to ensure uniqueness keys for specific GE sequences for
+  which the `SeriesUID/EchoTime` combination is not enough (PR #8152).
+
 ## LORIS 24.0 (Release Date: 2022-03-24)
 ### Core
 #### Features

diff --git a/SQL/0000-00-00-schema.sql b/SQL/0000-00-00-schema.sql
@@ -553,6 +553,8 @@ CREATE TABLE `files` (
   `File` varchar(255) NOT NULL default '',
   `SeriesUID` varchar(64) DEFAULT NULL,
   `EchoTime` double DEFAULT NULL,
+  `PhaseEncodingDirection` VARCHAR(3) DEFAULT NULL,
+  `EchoNumber` VARCHAR(20) DEFAULT NULL,
   `CoordinateSpace` varchar(255) default NULL,
   `OutputType` varchar(255) NOT NULL default '',
   `AcquisitionProtocolID` int(10) unsigned default NULL,
@@ -605,6 +607,8 @@ CREATE TABLE `files_qcstatus` (
     `FileID` int(10) UNSIGNED UNIQUE NULL,
     `SeriesUID` varchar(64) DEFAULT NULL,
     `EchoTime` double DEFAULT NULL,
+    `PhaseEncodingDirection` VARCHAR(3) DEFAULT NULL,
+    `EchoNumber` VARCHAR(20) DEFAULT NULL,
     `QCStatus` enum('Pass', 'Fail'),
     `QCFirstChangeTime` int(10) unsigned,
     `QCLastChangeTime` int(10) unsigned,
@@ -955,7 +959,8 @@ CREATE TABLE `mri_violations_log` (
   `ValidRange` varchar(255) DEFAULT NULL,
   `ValidRegex` varchar(255) DEFAULT NULL,
   `EchoTime` double DEFAULT NULL,
-  `MriProtocolChecksGroupID` INT(4) UNSIGNED DEFAULT NULL,
+  `PhaseEncodingDirection` VARCHAR(3) DEFAULT NULL,
+  `EchoNumber` VARCHAR(20) DEFAULT NULL,  `MriProtocolChecksGroupID` INT(4) UNSIGNED DEFAULT NULL,
   PRIMARY KEY (`LogID`),
   CONSTRAINT `FK_tarchive_mriViolationsLog_1`
     FOREIGN KEY (`TarchiveID`) REFERENCES `tarchive` (`TarchiveID`),
@@ -1715,7 +1720,8 @@ INSERT INTO `parameter_type` (Name, Alias, Type, Description, SourceFrom) VALUES
   ('fov_dimensions','FieldOfViewDimensions','text','Dimensions of the field of view, in mm. If Field of View Shape (0018,1147) is: RECTANGLE: row dimension followed by column. ROUND: diameter. HEXAGONAL: diameter of a circumscribed circle. DICOM:0018_1149','parameter_file'),
   ('laterality','Laterality','text','Laterality of (paired) body part examined. Required if the body part examined is a paired structure and Image Laterality (0020,0062) or Frame Laterality (0020,9072) are not sent. DICOM:0020_0060','parameter_file'),
   ('position_reference_indicator','PositionReferenceIndicator','text','Part of the imaging target used as a reference. DICOM:0020_1040','parameter_file'),
-  ('pixel_padding_value','PixelPaddingValue','text','Value of pixels added to non-rectangular image to pad to rectangular format. DICOM:0028_0120','parameter_file');
+  ('pixel_padding_value','PixelPaddingValue','text','Value of pixels added to non-rectangular image to pad to rectangular format. DICOM:0028_0120','parameter_file'),
+  ('PhaseEncodingDirection',NULL,'text','BIDS PhaseEncodingDirection (a.k.a. i, i-, j, j-, k, k-)','parameter_file');
 
 CREATE TABLE `parameter_type_category` (
   `ParameterTypeCategoryID` int(11) unsigned NOT NULL auto_increment,
@@ -2155,7 +2161,7 @@ INSERT INTO `feedback_mri_comment_types` (CommentName,CommentType,CommentStatusF
   ('Geometric distortion','volume','a:2:{s:5:\"field\";s:20:\"Geometric_distortion\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"Good\";i:2;s:4:\"Fair\";i:3;s:4:\"Poor\";i:4;s:12:\"Unacceptable\";}}'),
   ('Intensity artifact','volume','a:2:{s:5:\"field\";s:18:\"Intensity_artifact\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"Good\";i:2;s:4:\"Fair\";i:3;s:4:\"Poor\";i:4;s:12:\"Unacceptable\";}}'),
   ('Movement artifact','volume','a:2:{s:5:\"field\";s:30:\"Movement_artifacts_within_scan\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"None\";i:2;s:15:\"Slight Movement\";i:3;s:12:\"Poor Quality\";i:4;s:12:\"Unacceptable\";}}'),
-  ('Packet movement artifact','volume','a:2:{s:5:\"field\";s:31:\"Movement_artifacts_between_packets\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"None\";i:2;s:15:\"Slight Movement\";i:3;s:12:\"Poor Quality\";i:4;s:12:\"Unacceptable\";}}'),
+  ('Packet movement artifact','volume','a:2:{s:5:\"field\";s:34:\"Movement_artifacts_between_packets\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"None\";i:2;s:15:\"Slight Movement\";i:3;s:12:\"Poor Quality\";i:4;s:12:\"Unacceptable\";}}'),
   ('Coverage','volume','a:2:{s:5:\"field\";s:8:\"Coverage\";s:6:\"values\";a:5:{i:0;s:0:\"\";i:1;s:4:\"Good\";i:2;s:4:\"Fair\";i:3;s:5:\"Limit\";i:4;s:12:\"Unacceptable\";}}'),
   ('Overall','volume',''),
   ('Subject','visit',''),
@@ -2217,6 +2223,8 @@ CREATE TABLE `feedback_mri_comments` (
   `FileID` int(10) unsigned default NULL,
   `SeriesUID` varchar(64) default NULL,
   `EchoTime` double default NULL,
+  `PhaseEncodingDirection` VARCHAR(3) DEFAULT NULL,
+  `EchoNumber` VARCHAR(20) DEFAULT NULL,
   `SessionID` int(10) unsigned default NULL,
   `CommentTypeID` int(11) unsigned NOT NULL default '0',
   `PredefinedCommentID` int(11) unsigned default NULL,

diff --git a/...tches/2022-08-10-add_PhaseEncodingDirection_and_EchoNumber_to_files_and_mri_qc_tables.sql b/...tches/2022-08-10-add_PhaseEncodingDirection_and_EchoNumber_to_files_and_mri_qc_tables.sql
@@ -0,0 +1,30 @@
+-- ---------------------------------------------------------------------------------------------
+-- alter files table to add PhaseEncodingDirection and EchoNumber
+-- ---------------------------------------------------------------------------------------------
+ALTER TABLE files ADD COLUMN `PhaseEncodingDirection` VARCHAR(3)  DEFAULT NULL;
+ALTER TABLE files ADD COLUMN `EchoNumber`             VARCHAR(20) DEFAULT NULL;
+
+-- ---------------------------------------------------------------------------------------------
+-- alter files_qcstatus table to add PhaseEncodingDirection and EchoNumber
+-- ---------------------------------------------------------------------------------------------
+ALTER TABLE files_qcstatus ADD COLUMN `PhaseEncodingDirection` VARCHAR(3)  DEFAULT NULL;
+ALTER TABLE files_qcstatus ADD COLUMN `EchoNumber`             VARCHAR(20) DEFAULT NULL;
+
+-- ---------------------------------------------------------------------------------------------
+-- alter feedback_mri_comments table to add PhaseEncodingDirection and EchoNumber
+-- ---------------------------------------------------------------------------------------------
+ALTER TABLE feedback_mri_comments ADD COLUMN `PhaseEncodingDirection` VARCHAR(3)  DEFAULT NULL;
+ALTER TABLE feedback_mri_comments ADD COLUMN `EchoNumber`             VARCHAR(20) DEFAULT NULL;
+
+-- ---------------------------------------------------------------------------------------------
+-- alter mri_violations_log table to add PhaseEncodingDirection and EchoNumber
+-- ---------------------------------------------------------------------------------------------
+ALTER TABLE mri_violations_log ADD COLUMN `PhaseEncodingDirection` VARCHAR(3)  DEFAULT NULL;
+ALTER TABLE mri_violations_log ADD COLUMN `EchoNumber`             VARCHAR(20) DEFAULT NULL;
+
+-- ---------------------------------------------------------------------------------------------
+-- add an entry in parameter_type table to for the BIDS PhaseEncodingDirection parameter
+-- ---------------------------------------------------------------------------------------------
+INSERT INTO parameter_type (Name, Type, Description, SourceFrom)
+SELECT 'PhaseEncodingDirection', 'text', 'BIDS PhaseEncodingDirection (a.k.a. i, i-, j, j-, k, k-)', 'parameter_file'
+WHERE NOT EXISTS (SELECT * FROM parameter_type where Name='PhaseEncodingDirection');
diff --git a/SQL/New_patches/2022-08-11-fix_feedback_mri_comment_types_not_correctly_serialized.sql b/SQL/New_patches/2022-08-11-fix_feedback_mri_comment_types_not_correctly_serialized.sql
@@ -0,0 +1,6 @@
+-- ---------------------------------------------------------------------------------------------
+-- fix incorrectly serialized feedback
+-- ---------------------------------------------------------------------------------------------
+UPDATE feedback_mri_comment_types SET
+    CommentStatusField='a:2:{s:5:"field";s:34:"Movement_artifacts_between_packets";s:6:"values";a:5:{i:0;s:0:"";i:1;s:4:"None";i:2;s:15:"Slight Movement";i:3;s:12:"Poor Quality";i:4;s:12:"Unacceptable";}}'
+WHERE CommentTypeID=4;
diff --git a/modules/imaging_browser/php/viewsession.class.inc b/modules/imaging_browser/php/viewsession.class.inc
@@ -111,6 +111,7 @@ class ViewSession extends \NDB_Form
                 $this->_updateStatus($_POST);
                 $this->_updateSelected();
                 $this->_updateVisitStatus();
+
             }
             $this->_setFilesData();
 
@@ -344,7 +345,6 @@ class ViewSession extends \NDB_Form
                 'QCDate'                     => $QCDate,
                 'Caveat'                     => $caveat,
                 'SNR'                        => $SNR,
-                'SeriesUID'                  => $SeriesUID,
                 'XMLreport'                  => $XMLreport,
                 'XMLprotocol'                => $XMLprotocol,
                 'NrrdFile'                   => $NrrdFile,
@@ -490,8 +490,12 @@ class ViewSession extends \NDB_Form
                     $updateSet['SeriesUID'] = $file->getParameter(
                         'series_instance_uid'
                     );
-                    $updateSet['EchoTime']  = $file->getParameter('echo_time');
-                    $updateSet['FileID']    = $curFileID;
+                    $updateSet['PhaseEncodingDirection'] = $file->getParameter(
+                        'PhaseEncodingDirection'
+                    );
+                    $updateSet['EchoTime']   = $file->getParameter('echo_time');
+                    $updateSet['EchoNumber'] = $file->getParameter('echo_numbers');
+                    $updateSet['FileID']     = $curFileID;
                     $this->_DB->insert("files_qcstatus", $updateSet);
                 }
             }
@@ -527,9 +531,14 @@ class ViewSession extends \NDB_Form
                     //----------------------------------------------------------//
                     $insertSet = [];
                     $file      = new \MRIFile($curFileID);
-                    $insertSet['SeriesUID']   = $file->getParameter(
+                    $insertSet['SeriesUID'] = $file->getParameter(
                         'series_instance_uid'
                     );
+                    $insertSet['PhaseEncodingDirection'] = $file->getParameter(
+                        'PhaseEncodingDirection'
+                    );
+                    $insertSet['EchoTime']    = $file->getParameter('echo_time');
+                    $insertSet['EchoNumber']  = $file->getParameter('echo_numbers');
                     $insertSet['TarchiveID']  = $file->getParameter(
                         'TarchiveSource'
                     );
@@ -650,6 +659,12 @@ class ViewSession extends \NDB_Form
                 $params      = ['FID' => $curFileID];
                 $updateWhere = ['FileID' => $curFileID];
 
+                $file          = new \MRIFile($curFileID);
+                $seriesUID     = $file->getParameter('series_instance_uid');
+                $phase_enc_dir = $file->getParameter('PhaseEncodingDirection');
+                $echo_time     = $file->getParameter('echo_time');
+                $echo_number   = $file->getParameter('echo_numbers');
+
                 if ($curSelected == 'Unselected') {
                     if ($this->_DB->pselectOne(
                         "SELECT COUNT(*)
@@ -679,10 +694,15 @@ class ViewSession extends \NDB_Form
                             $updateWhere
                         );
                     } else {
+
                         $insertSet = [
-                            'FileID'            => $curFileID,
-                            'Selected'          => $curSelected,
-                            'QCFirstChangeTime' => time(),
+                            'FileID'                 => $curFileID,
+                            'Selected'               => $curSelected,
+                            'SeriesUID'              => $seriesUID,
+                            'EchoTime'               => $echo_time,
+                            'EchoNumber'             => $echo_number,
+                            'PhaseEncodingDirection' => $phase_enc_dir,
+                            'QCFirstChangeTime'      => time(),
                         ];
                         $insertSet = \Utility::nullifyEmpty($insertSet, 'Selected');
                         $this->_DB->insert('files_qcstatus', $insertSet);

diff --git a/php/libraries/FeedbackMRI.class.inc b/php/libraries/FeedbackMRI.class.inc
@@ -221,7 +221,8 @@ class FeedbackMRI
         }
 
         // create DB object
-        $DB =& \NDB_Factory::singleton()->database();
+        $database = \NDB_Factory::singleton()->database();
+        $DB       =& $database;
 
         // get the parameter type id
         $query = "SELECT ParameterTypeID FROM parameter_type WHERE Name=:FName";
@@ -419,6 +420,10 @@ class FeedbackMRI
             $file          = new MRIFile($this->fileID);
             $set['SeriesUID'] = $file->getParameter('series_instance_uid');
             $set['EchoTime']  = $file->getParameter('echo_time');
+            $set['PhaseEncodingDirection'] = $file->getParameter(
+                'PhaseEncodingDirection'
+            );
+            $set['EchoNumber'] = $file->getParameter('echo_numbers');
         } else {
             // per-visit
             $set['SessionID'] = $this->sessionID;