aces · cmadjar · Aug 10, 2026 · Jun 23, 2026 · Jul 7, 2026 · Jul 7, 2026
diff --git a/.github/workflows/integration.yml b/.github/workflows/integration.yml
@@ -31,7 +31,12 @@ jobs:
       uses: actions/checkout@v4
 
     - name: Clone the LORIS core repository
-      run: git clone https://github.com/aces/Loris.git ./test/Loris
+      # Use the corresponding LORIS branch for integration tests.
+      # The branch name is either the target branch for PRs, or the current branch otherwise.
+      # Only copy the current state of the repository, the history is not needed for CI.
+      run: |
+        BRANCH_NAME="${{ github.base_ref || github.ref_name }}"
+        git clone --depth 1 --single-branch --branch "$BRANCH_NAME" https://github.com/aces/Loris.git ./test/Loris
 
     - name: Overwrite Raisinbread SQL files
       run: cp -f ./test/RB_SQL/*.sql ./test/Loris/raisinbread/RB_files/

diff --git a/docs/scripts_md/MRI.md b/docs/scripts_md/MRI.md
@@ -231,19 +231,17 @@ RETURNS: `CandID` (int)
 
 ### getPSC($patientName, $dbhr, $db)
 
-Looks for the site alias using the `session` table `CenterID` as
-a first resource, for the cases where it is created using the front-end,
-otherwise, find the site alias in whatever field (usually `patient_name`
-or `patient_id`) is provided, and return the `MRI_alias` and `CenterID`.
+Looks for the `CenterID` of a scan. If the configuration already provides a
+`CenterID`, it is validated against the `psc` table. Otherwise, the `CenterID`
+is looked up using the `session` table, and as a last resort by matching the site alias against whatever field
+(usually `patient_name` or `patient_id`) is provided.
 
 INPUTS:
   - $patientName: patient name
   - $dbhr       : database handle reference
   - $db         : database object
 
-RETURNS: a two element array:
-  - first is the MRI alias of the PSC or "UNKN"
-  - second is the `CenterID` or 0
+RETURNS: the `CenterID` or 0 if no center could be found
 
 ### getProject($subjectIDsref, $dbhr, $db)
 

diff --git a/docs/scripts_md/delete_imaging_upload.md b/docs/scripts_md/delete_imaging_upload.md
@@ -478,20 +478,6 @@ from the file system and the database, using `gzip`.
 INPUTS:
   - $backupPath: path of the backup file to compress (without the .tar.gz extension).
 
-### updateSessionTable($dbh, $mriUploadsRef, $tmpSQLFile)
-
-Sets to `N` the `Scan_done` column of all `sessions` in the database that do not have an associated upload
-after the script has deleted those whose IDs are passed on the command line. The script also adds an SQL statement
-in the SQL file whose path is passed as argument to restore the state that the `session` table had before the deletions.
-
-INPUTS:
-   - $dbh       : database handle.
-   - $mriUploadsRef: reference on an array of hashes containing the uploads to delete. Accessed like this:
-                 `$mriUploadsRef->[0]->{'TarchiveID'}`(this would return the `TarchiveID` of the first `mri_upload`
-                 in the array. The properties stored for each hash are: `UploadID`, `TarchiveID`, `FullPath`
-                 `Inserting`, `InsertionComplete` and `SessionID`.
-   - $tmpSQLFile: path of the SQL file that contains the SQL statements used to restore the deleted records.
-
 ### updateFilesIntermediaryTable($dbh, $filesRef, $tmpSQLFile)
 
 Sets the `TarchiveSource` and `SourceFileID` columns of all the defaced files to `$tarchiveID` and `NULL`

diff --git a/docs/test_plans/perl/delete_imaging_upload.md b/docs/test_plans/perl/delete_imaging_upload.md
@@ -0,0 +1,11 @@
+# Test plan for `delete_imaging_upload.pl`
+
+## Manual tests
+
+- [ ] Test deletion of an entire MRI upload (UploadID) with SQL and file backup (ensure the SQL and file backup repopulate the database correctly after the deletion)
+- [ ] Test deletion of an UploadID that has the same TarchiveID as an other UploadID - this should fail with an error message explaining there are multiple UploadID for a given TarchiveID
+- [ ] Test deletion of an UploadID with QC information attached - this should fail with proper error message
+- [ ] Test deletion of an UploadID with a parameter_form filled and the option `-form` and ensure the entries in the parameter form have been deleted
+- [ ] On a defaced dataset, test running the delete script with the `-defaced` option - this should delete only non-defaced MINC files for that UploadID
+- [ ] Run the delete script with option `-basename <FileBaseName>` specifying a basename for the MINC files to be deleted - only images matching that basename should be deleted for the UploadID
+
diff --git a/docs/test_plans/perl/dicomTar.md b/docs/test_plans/perl/dicomTar.md
@@ -0,0 +1,8 @@
+# Test plan for `dicomTar.pl`
+
+## Manual tests
+
+- Run `dicomTar.pl` without the `-database` flag and ensure nothing gets inserted into the DB.
+- Run `dicomTar.pl` with the `-database` flag and check that entries got inserted into the DB in the `tarchive*` tables correctly.
+- Run `dicomTar.pl` with the `-mri_upload_update` flag on a DICOM directory that was not previously uploaded via the imaging uploader (ensure there is nothing in `mri_upload` table for that study before running the script) => ensure that an entry has been added to `mri_upload` for the uploaded DICOM study.
+- Run `updateMri_upload.pl` on a DICOM archive and ensure an MRI upload is created.
diff --git a/docs/test_plans/perl/mass_nii.md b/docs/test_plans/perl/mass_nii.md
@@ -0,0 +1,18 @@
+# Test plan for `mass_nii.pl`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+
+- run `mass_nii.pl -help` and ensure the help for the script gets printed
+
+- remove NIfTI images for UploadID 106 (linked to TarchiveID 56)
+     - remove pics from the filesystem using `rm /data/Loris-MRI/data/assembly/400168/V2/mri/native/*nii  /data/Loris-MRI/data/assembly/400168/V2/mri/native/*bval  /data/Loris-MRI/data/assembly/400168/V2/mri/native/*bvec`
+     - in MySQL run the following query to delete path to pic images in `parameter_file`: `DELETE parameter_file FROM parameter_file JOIN files USING (FileID) WHERE TarchiveSource=56 AND Value like "%nii";` (should delete 5 rows)
+     - check that the following query returns no results: `SELECT FileID, Value FROM parameter_file JOIN files USING (FileID) WHERE TarchiveSource=56 AND Value like "%nii";`
+     - go to the imaging browser for CandID 400168 V2 and check that the buttons "download NIfTI" does not show up anymore under the image's screenshot"
+
+- run `mass_nii.pl` on `FileIDs` `335` to `339`: `mass_nii.pl -profile prod -minFileID 335 -maxFileID 339` 
+     - check that the "download NIfTI" button shows up again below the images' screenshots.
+     - check that the following query returns 5 rows: `SELECT FileID, Value FROM parameter_file JOIN files USING (FileID) WHERE TarchiveSource=56 AND Value like "%nii.gz";` 
+     - check that files with extension ".nii" or ".nii.gz" have been created under `/data/Loris-MRI/data/assembly/400168//V2/mri/native/`
diff --git a/docs/test_plans/perl/tarchiveLoader.md b/docs/test_plans/perl/tarchiveLoader.md
@@ -0,0 +1,12 @@
+# Test plan for `tarchiveLoader.md`
+
+## Manual tests
+
+- [ ] Check that -uploadID, -profile and an existing tarchive are mandatory script argument.
+- [ ] Ensure passing an invalid upload ID yields an error.
+- [ ] Ensure passing an invalid tarchive (e.g csv file) yields an error.
+- [ ] Check that if config setting get_dicom_info is not properly set, tarchiveLoader issues an error that the get_dicom_info command could not be run.
+- [ ]  Pick an archive that's already been successfully processed and find its associated upload ID. Run tarchiveLoader using this archive but use option -upload_id with an argument that is not its actual upload ID. Check that you get an error message that the archive and upload ID don't match.
+- [ ] Pick an archive that's already been successfully processed and find its associated upload ID. Run tarchiveLoader using this archive and option -upload_id with an argument that is its actual upload ID. Ensure that no minc files are inserted and you get an error message regarding duplicate md5sum for each scan that was originally inserted when the archive was processed.
+- [ ] Ensure that config setting default_project is not set and that your prod file does not define any PSCID, visitLabel and ProjectID in function getSubjectIDs. Run tarchiveLoader with a matching tarchive and upload ID and ensure that you get an error message saying that config setting default_project has to be set.
+
diff --git a/docs/test_plans/perl/tarchive_validation.md b/docs/test_plans/perl/tarchive_validation.md
@@ -0,0 +1,12 @@
+# Test plan for `tarchive_validation.pl`
+
+- [ ] If not already done, source the `environment` file: `source /opt/Loris-MRI/bin/mri/environment`
+- [ ] run `tarchive_validation.pl -help` and ensure the help for the script gets printed
+- [ ] run the `tarchive_validation.pl` script on a valid archive (example UploadID 106)
+```
+tarchive_validation.pl -profile prod -uploadID 106 /data/Loris-MRI/data/tarchive/2016/DCM_2016-08-19_ImagingUpload-18-26-C4Y94V.tar
+```
+- [ ] test `tarchive_validation.pl` script on an invalid archive (example UploadID 109)
+    - [ ] delete file `/data/Loris-MRI/data/tarchive/2016/DCM_2016-08-15_ImagingUpload-18-34-hhQQY5.tar` 
+    - [ ] recreate the file with `touch` command `touch /data/Loris-MRI/data/tarchive/2016/DCM_2016-08-15_ImagingUpload-18-34-hhQQY5.tar`
+    - [ ] run `tarchive_validation.pl -profile prod -uploadID 109 /data/Loris-MRI/data/tarchive/2016/DCM_2016-08-15_ImagingUpload-18-34-hhQQY5.tar` => this should fail with proper message due to different md5
diff --git a/docs/test_plans/python/import_bids_dataset.md b/docs/test_plans/python/import_bids_dataset.md
@@ -0,0 +1,33 @@
+# LORIS BIDS importer test plan
+
+## Preamble
+
+- The LORIS BIDS importer is a script to import a BIDS dataset in LORIS.
+- Take a look at the documentation in the `loris-bids-importer` package README file.
+
+## Testing instructions
+
+### General
+
+- Ensure that importing an incorrect path or non-BIDS file or directory returns an error.
+- Ensure that the `--create-session` option creates a session in LORIS.
+- Ensure that the `--create-candidate` option creates a candidate in LORIS.
+
+### MRI
+
+Import a BIDS dataset with MRI data.
+- Ensure that the BIDS importer returns no unexpected error.
+- Ensure that the imported MRI data is visible in the LORIS imaging browser, with brain browser visualization and preview pictures.
+- Ensure that the imported MRI files are downloadlable in the LORIS imaging browser (NIfTI, sidecar JSON, BVAL and BVEC files)
+
+### EEG
+
+Import a BIDS dataset with EEG data.
+- Ensure that the BIDS importer returns no unexpected error..
+- Ensure that the imported EEG data is visible in the LORIS electrophysiology browser.
+- Ensure that having the `useEEGBrowserVisualizationComponents` LORIS configuration option set to `1` or `true` during the import creates the electrophysiliogy chunk files, which allows to visualize the EEG signals int the LORIS electrophysiology browser after the import.
+- Ensure that the imported EEG files are downloadlable in the LORIS imaging browser (acquisition file, sidecar JSON, event files, archives).
+
+## Testing data
+
+There is no data readily available for import for now. You can find use the Raisinbread data in the LORIS data directories `assembly_bids` (MRI) and `bids_imports` (Face13 dataset, EEG) if you remove them from LORIS before testing. You are encouraged to use your own datasets (such as public datasets) if you have some.
diff --git a/docs/test_plans/python/import_dicom_study.md b/docs/test_plans/python/import_dicom_study.md
@@ -0,0 +1,49 @@
+# LORIS DICOM importer test plan
+
+## Preamble
+
+- The LORIS DICOM importer is a script to import a DICOM study in LORIS.
+- The LORIS DICOM importer code and documentation is located in the `loris-bids-importer` package.
+- It is advised to take a look at the package README file before starting the tests.
+- The `tarchiveLibraryDir` LORIS configuration option should point to an existing directory before starting the tests.
+
+## Testing instructions
+
+### Running the script
+
+Ensure a DICOM study can be imported into LORIS using the `--insert` CLI option:
+```sh
+import-dicom-study --insert --session --source /path/to/dicom/study
+```
+
+### Imported DICOM study
+
+- Ensure the DICOM study is visible in the LORIS DICOM archive module, with a list of all its DICOM files and working download link.
+- Ensure the DICOM study is attached to a LORIS session based on its patient identifiers (from the `--session` CLI option).
+- Ensure the DICOM study is present in the LORIS database in the `tarchive_*` tables.
+- Ensure the DICOM study archive is present in the LORIS `tarchive` directory.
+- Ensure the DICOM study archive contains a `.log` and `.meta`file, and that both their contents look correct.
+
+### Other commands
+
+- Ensure that a DICOM study that is already imported in LORIS can be updated by using the `--update` and `--overwrite` CLI options instead of `--insert`.
+- Ensure the `summarize-dicom-study` script produces a correct looking DICOM study summary.
+
+### Errors cases
+
+- Ensure that importing a non-DICOM study file or directory results in an error.
+- Ensure that importing a DICOM study that is already in LORIS results in an error.
+- Ensure that updating a DICOM study that is not already in LORIS results in an error.
+
+## Testing data
+
+Usable DICOM studies may be found in the `/data/loris/incoming` directory, as well as already archived DICOM studies in the `/data/loris/tarchive` directory (which should then be untarred for testing).
+
+To test the DICOM study importer with an already imported DICOM study, existing data should first be removed from the LORIS database and data directory.
+
+A DICOM study an be removed from the database using the following SQL statement:
+```sql
+DELETE FROM tarchive WHERE tarchiveID = @id;
+```
+
+If foreign keys exist in other tables (like `mri_upload` or `files`), it is advised to set the relevant attributes to `NULL`.
diff --git a/docs/test_plans/python/mass_nifti_pic.md b/docs/test_plans/python/mass_nifti_pic.md
@@ -0,0 +1,18 @@
+# Test plan for `mass_nifti_pic.py`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+- run `mass_nifti_pic.py -h`
+     => should print the help of the script. Make sure the help documentation is up-to-date.
+- Bonus points: verify that the automated tests are still implemented
+
+## Automated tests already implemented
+
+- test invalid profile
+- test smallest `FileID` bigger than largest `FileID`
+- test invalid FileID provided
+- test on a FileID that already has a pic
+- test force option
+- test running on a text file
+- test successful run
diff --git a/docs/test_plans/python/run_dicom_archive_loader.md b/docs/test_plans/python/run_dicom_archive_loader.md
@@ -0,0 +1,20 @@
+# Test plan for `run_dicom_archive_loader.py`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+- run `run_dicom_archive_loader.py -h`
+     => should print the help of the script. Make sure the help documentation is up-to-date.
+- run `run_dicom_archive_loader.py -p config.py -u <UPLOAD ID>` on a valid upload ID with fieldmaps and BOLD images
+     => ensure that the `IntendedFor` field of the fieldmap has been updated to include the path to the BOLD images
+     => once the script is done running, ensure that the temporary directory that was used to run the script has been cleared out
+- run `run_dicom_archive_loader.py -p config.py -u <UPLOAD ID> -s <SERIES UID>`
+     => ensure only that the file(s) matching the `SeriesUID` have been ingested
+- Bonus points: verify that the automated tests are still implemented
+
+## Automated tests already implemented
+
+- test invalid argument
+- test invalid upload ID
+- test invalid tarchive path
+- test successful run on valid tarchive path
diff --git a/docs/test_plans/python/run_dicom_archive_validation.md b/docs/test_plans/python/run_dicom_archive_validation.md
@@ -0,0 +1,18 @@
+# Test plan for `run_dicom_archive_validation.py`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+- run `run_dicom_archive_validation.py -h`
+     => should print the help of the script. Make sure the help documentation is up-to-date.
+- Bonus points: verify that the automated tests are still implemented
+
+## Automated tests already implemented
+
+- test missing upload ID argument
+- test missing tarchive path argument
+- test invalid argument
+- test invalid upload ID
+- test invalid tarchive path
+- test mixed up upload ID and tarchive path
+- test successful validation
diff --git a/docs/test_plans/python/run_nifti_insertion.md b/docs/test_plans/python/run_nifti_insertion.md
@@ -0,0 +1,25 @@
+# Test plan for `run_nifti_insertion.py`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+- run `run_nifti_insertion.py -h`
+     => should print the help of the script. Make sure the help documentation is up-to-date.
+- Bonus points: verify that the automated tests are still implemented
+
+## Automated tests already implemented
+
+- test invalid argument
+- test missing NIfTI path argument
+- test invalid NIfTI path
+- test missing upload ID or tarchive path argument (one of them should be set)
+- test missing JSON path argument
+- test invalid JSON path
+- test invalid upload ID
+- test invalid tarchive path
+- test tarchive path and upload ID argument provided (only one should be set)
+- test NIfTI and tarchive `PatientName` differ
+- test NIfTI already inserted
+- test NIfTI MRI protocol violated scans features
+- test NIfTI MRI violations log exclude features
+- test DWI insertion with MRI violations warning
diff --git a/docs/test_plans/python/run_push_imaging_files_to_s3_pipeline.md b/docs/test_plans/python/run_push_imaging_files_to_s3_pipeline.md
@@ -0,0 +1,17 @@
+# Test plan for `run_dicom_archive_validation.py`
+
+## Manual tests
+
+- If not already done, source the environment file: `source /opt/Loris-MRI/bin/mri/environment`
+- run `run_push_imaging_files_to_s3_pipeline.py -h`
+     => should print the help of the script. Make sure the help documentation is up-to-date.
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py -u <UPLOAD ID>` on a valid Upload ID and 
+  ensure the files has been properly pushed to the S3 bucket
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py` without the `-u` 
+     => should print `[ERROR   ] argument --upload_id is required`
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py -u <UPLOAD ID>` on an invalid Upload ID 
+     => should print `[ERROR   ] Did not find an entry in mri_upload associated with 'UploadID' 1666`
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py -u <UPLOAD ID>` with the S3 config settings not set in `config.py`
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py -u <UPLOAD ID>` with incorrect S3 authentication settings  in `config.py`
+- run `run_push_imaging_files_to_s3_pipeline.py -p config.py -u <UPLOAD ID>` with the incorrect S3 bucket name in `config.py`
+
diff --git a/install/imaging_install.sh b/install/imaging_install.sh
@@ -216,7 +216,7 @@ echo "Creating python config file with database credentials"
 cp $installdir/templates/config_template.py $mridir/config/config.py
 sudo chmod 640 $mridir/config/config.py
 sudo chgrp $group $mridir/config/config.py
-sed -e "s#DBNAME#$mysqldb#g" -e "s#DBUSER#$mysqluser#g" -e "s#DBPASS#$mysqlpass#g" -e "s#DBHOST#$mysqlhost#g" $installdir/templates/database_config_template.py > $mridir/config/config.py
+sed -e "s#DBNAME#$mysqldb#g" -e "s#DBUSER#$mysqluser#g" -e "s#DBPASS#$mysqlpass#g" -e "s#DBHOST#$mysqlhost#g" $installdir/templates/config_template.py > $mridir/config/config.py
 echo "config file for python import scripts is located at $mridir/config/config.py"
 echo
 

diff --git a/install/imaging_install_MacOSX.sh b/install/imaging_install_MacOSX.sh
@@ -128,6 +128,6 @@ echo "Creating python config file with database credentials"
 cp $installdir/templates/config_template.py $mridir/config/config.py
 sudo chmod 640 $mridir/config/config.py
 sudo chgrp $group $mridir/config/config.py
-sed -e "s#DBNAME#$mysqldb#g" -e "s#DBUSER#$mysqluser#g" -e "s#DBPASS#$mysqlpass#g" -e "s#DBHOST#$mysqlhost#g" $installdir/templates/database_config_template.py > $mridir/config/config.py
+sed -e "s#DBNAME#$mysqldb#g" -e "s#DBUSER#$mysqluser#g" -e "s#DBPASS#$mysqlpass#g" -e "s#DBHOST#$mysqlhost#g" $installdir/templates/config_template.py > $mridir/config/config.py
 echo "config file for python import scripts is located at $mridir/config/config.py"
 echo
diff --git a/install/templates/environment_template b/install/templates/environment_template
@@ -1,6 +1,10 @@
 PROJECT=%PROJECT%
 MINC_TOOLKIT_DIR=%MINC_TOOLKIT_DIR%
 
+# source the Python environment first so that other environment variables are added to this environment
+export LORIS_MRI=/opt/${PROJECT}/bin/mri
+source /opt/${PROJECT}/bin/mri/.venv/bin/activate
+
 # to source the MINC toolkit
 source ${MINC_TOOLKIT_DIR}/minc-toolkit-config.sh
 umask 0002
@@ -11,10 +15,6 @@ export PERL5LIB=/opt/${PROJECT}/bin/mri/uploadNeuroDB:/opt/${PROJECT}/bin/mri/di
 export TMPDIR=/tmp
 export LORIS_CONFIG=/opt/${PROJECT}/bin/mri/config
 
-# for the Python scripts
-export LORIS_MRI=/opt/${PROJECT}/bin/mri
-source /opt/${PROJECT}/bin/mri/.venv/bin/activate
-
 # for the defacing scripts
 export BEASTLIB=${MINC_TOOLKIT_DIR}/../share/beast-library-1.1
 export MNI_MODELS=${MINC_TOOLKIT_DIR}/../share/icbm152_model_09c
diff --git a/pyproject.toml b/pyproject.toml
@@ -135,6 +135,7 @@ locale = "en-us"
 Centre = "Centre"  # McGill Centre for Integrative Neuroscience
 HED = "HED"  # Hierarchical Event Descriptors
 ND = "ND"  # Image Type DICOM attribute
+Colour = "Colour"  # SQL column name in sex table
 
 [tool.typos.default.extend-identifiers]
 ba = "ba"  # A CLI option of dcm2niix