Support alphanumeric sub or ses labels. (#575)

* Support alphanumeric sub or ses labels.

* Fix linting.

* Fix accidentally included dash in check.

* Fix tests.

* Fixing tests.

* Small fixes, add first tests.

* Add tests.

* Rename placeholder variable.

* Add tooltips.

* Tidying up TUI, trying to get create settings page nice.

* Fix tests.

* Fix tests again.

* Update docs text.

* Update tcss.

* Update documentation.

* Small tidy ups.

* Turn off validation during data transfers, add test.

* Tidy up validation.

* Explain better the leading zero case, do not mention this generally because inconsnstent zeros are not allowed anyway.

* small fix to doc.

* Small fixes to docs and docstrings.

* Small changes to tcss.

* Add test docstring.

* Fix after rebase.

* Rename alphanuermic to letters in in argument name.

* Update tests/tests_tui/test_tui_widgets_and_defaults.py

Co-authored-by: Shrey Singh <96627769+cs7-shrey@users.noreply.github.com>

* Remove 'off'.

* Use allow_letters_in_sub_ses_values in test.

* Get allow_letters_in_sub_ses_values from tui_settings in interface.

* Add comment to check_and_format_names.

* Typo fix.

---------

Co-authored-by: Shrey Singh <96627769+cs7-shrey@users.noreply.github.com>

Author: JoeZiminski

datashuttle/configs/canonical_configs.py

@@ -279,6 +279,7 @@ def get_tui_config_defaults() -> Dict:
             "overwrite_existing_files": "never",
             "dry_run": False,
             "suggest_next_sub_ses_central": False,
+            "allow_letters_in_sub_ses_values": False,
         }
     }
 

datashuttle/datashuttle_class.py

@@ -124,6 +124,7 @@ def create_folders(
         ses_names: Optional[Union[str, List[str]]] = None,
         datatype: Union[str, List[str]] = "",
         bypass_validation: bool = False,
+        allow_letters_in_sub_ses_values: bool = False,
         log: bool = True,
     ) -> Dict[str, List[Path]]:
         """Create a folder tree in the project folder.
@@ -159,6 +160,13 @@ def create_folders(
             If `True`, folders will be created even if they are not
             valid to NeuroBlueprint style.
 
+        allow_letters_in_sub_ses_values
+            If `True`, any alphanumeric character are allowed for the values associated
+            with sub- or ses-  keys. Otherwise, values must be integer
+            and the following additional checks are performed:
+
+            - Labels must be the same length (e.g. sub-01 and sub-002 is invalid).
+
         log
             If `True`, details of folder creation will be logged.
 
@@ -217,6 +225,7 @@ def create_folders(
             ses_names,
             name_templates,
             bypass_validation,
+            allow_letters_in_sub_ses_values,
             log=True,
         )
 
@@ -253,16 +262,25 @@ def _format_and_validate_names(
         ses_names: Optional[Union[str, List[str]]],
         name_templates: Dict,
         bypass_validation: bool,
+        allow_letters_in_sub_ses_values: bool,
         log: bool = True,
     ) -> Tuple[List[str], List[str]]:
         """Central method to format and validate subject and session names."""
         format_sub = formatting.check_and_format_names(
-            sub_names, "sub", name_templates, bypass_validation
+            sub_names,
+            "sub",
+            name_templates,
+            bypass_validation,
+            allow_letters_in_sub_ses_values,
         )
 
         if ses_names is not None:
             format_ses = formatting.check_and_format_names(
-                ses_names, "ses", name_templates, bypass_validation
+                ses_names,
+                "ses",
+                name_templates,
+                bypass_validation,
+                allow_letters_in_sub_ses_values,
             )
         else:
             format_ses = []
@@ -277,6 +295,7 @@ def _format_and_validate_names(
                 display_mode="error",
                 log=log,
                 name_templates=name_templates,
+                allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
             )
 
         return format_sub, format_ses
@@ -1277,6 +1296,7 @@ def validate_project(
         display_mode: DisplayMode,
         include_central: bool = False,
         strict_mode: bool = False,
+        allow_letters_in_sub_ses_values: bool = False,
     ) -> List[str]:
         """Perform validation on the project.
 
@@ -1306,6 +1326,13 @@ def validate_project(
             any folder not prefixed with sub-, ses- or a valid datatype will
             raise a validation issue.
 
+        allow_letters_in_sub_ses_values
+            If `True`, any alphanumeric character are allowed for the values associated
+            with sub- or ses-  keys. Otherwise, values must be integer
+            and the following additional checks are performed:
+
+            - Labels must be the same length (e.g. sub-01 and sub-002 is invalid).
+
         Returns
         -------
         error_messages
@@ -1344,14 +1371,19 @@ def validate_project(
             display_mode=display_mode,
             name_templates=name_templates,
             strict_mode=strict_mode,
+            allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
         )
 
         ds_logger.close_log_filehandler()
 
         return error_messages
 
     @staticmethod
-    def check_name_formatting(names: Union[str, list], prefix: Prefix) -> None:
+    def check_name_formatting(
+        names: Union[str, list],
+        prefix: Prefix,
+        allow_letters_in_sub_ses_values: bool = False,
+    ) -> None:
         """Format a list of subject or session names.
 
         Pass list of names to check how these will be auto-formatted,
@@ -1369,6 +1401,13 @@ def check_name_formatting(names: Union[str, list], prefix: Prefix) -> None:
             The relevant subject or session prefix,
             e.g. ``"sub-"`` or ``"ses-"``
 
+        allow_letters_in_sub_ses_values
+            If `True`, any alphanumeric character are allowed for the values associated
+            with sub- or ses-  keys. Otherwise, values must be integer
+            and the following additional checks are performed:
+
+            - Labels must be the same length (e.g. sub-01 and sub-002 is invalid).
+
         """
         if prefix not in ["sub", "ses"]:
             utils.log_and_raise_error(
@@ -1379,7 +1418,11 @@ def check_name_formatting(names: Union[str, list], prefix: Prefix) -> None:
         if isinstance(names, str):
             names = [names]
 
-        formatted_names = formatting.check_and_format_names(names, prefix)
+        formatted_names = formatting.check_and_format_names(
+            names,
+            prefix,
+            allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
+        )
         utils.print_message_to_user(formatted_names)
 
     # -------------------------------------------------------------------------
@@ -1636,6 +1679,7 @@ def _update_settings_with_new_canonical_keys(self, settings: Dict) -> None:
             "overwrite_existing_files",
             "dry_run",
             "suggest_next_sub_ses_central",
+            "allow_letters_in_sub_ses_values",
         ]:
             if key not in settings["tui"]:
                 settings["tui"][key] = canonical_tui_configs["tui"][key]

datashuttle/datashuttle_functions.py

@@ -28,6 +28,7 @@ def validate_project_from_path(
     display_mode: DisplayMode = "warn",
     strict_mode: bool = False,
     name_templates: Optional[Dict] = None,
+    allow_letters_in_sub_ses_values: bool = False,
 ) -> List[str]:
     """Perform validation on a NeuroBlueprint-formatted project.
 
@@ -58,6 +59,13 @@ def validate_project_from_path(
         to validate against. See ``DataShuttle.set_name_templates()``
         for details.
 
+    allow_letters_in_sub_ses_values
+        If `True`, any alphanumeric character are allowed for the values associated
+        with sub- or ses-  keys. Otherwise, values must be integer
+        and the following additional checks are performed:
+
+        - Labels must be the same length (e.g. sub-01 and sub-002 is invalid).
+
     Returns
     -------
     error_messages
@@ -95,6 +103,7 @@ def validate_project_from_path(
         display_mode=display_mode,
         name_templates=name_templates,
         strict_mode=strict_mode,
+        allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
     )
 
     return error_messages

datashuttle/tui/css/tui_menu.tcss

@@ -314,26 +314,43 @@ config label and button align center */
 #validate_top_container {
     align: center top;
     content-align: center top;
-    margin: 2 0 0 0;
+    margin: 2 0 1 0;
     layout: vertical;
     overflow: hidden auto;
 }
 
-
 #validate_arguments_horizontal{
    height: auto;
-   margin: 0 1 1 1;
+   margin: 0 1 1 0;
 }
 
 #validate_top_level_folder_select {
     width: 30%;
+    margin: 0 0 0 1;
+}
+
+#validate_path_label {
+    margin: 0 0 0 2;
 }
 
 #validate_path_input {
     width: 80%;
     margin: 1 1 1 1;
 }
 
+#validate_allow_letters_in_sub_ses_values_checkbox {
+    margin: 0 0 0 6;
+}
+
+#validate_strict_mode_checkbox {
+    margin: 0 0 0 1;
+}
+
+#validate_include_central_checkbox {
+    margin: 0 6 0 1
+}
+
+
 #validate_select_button {
     margin: 1 1 1 1;
 }
@@ -387,12 +404,8 @@ DisplayedDatatypesScreen {
 CreateFoldersSettingsScreen {
     align: center middle;
 }
-
-#labelTESTEST {
-    padding: 1 0 1 2;
-}
-#tabscreen_toplevel_select {
-    padding: 0 0 0 1;
+#create_folders_settings_toplevel_label {
+    margin: 1 0 0 2;
 }
 #create_tab_settings_outer_container {
     height: 80%;
@@ -401,26 +414,30 @@ CreateFoldersSettingsScreen {
     border: tall $panel-lighten-3;
 }
 #checkbox_container {
-    height: 65%;
+    height: 80%;
     overflow: hidden auto;
 }
-#toplevel_folder_select_container {
-    height: 15%;
+#create_folders_settings_allow_letters_in_checkbox {
+    padding: 0 6;
+}
+#create_folders_settings_checkbox_outer_container {
+    margin: 0 0 0 0;
 }
 #template_top_container {
-    height: 70%;
+    height: 75%;
     background: $primary-background;
     border: tall $panel-lighten-3;
     overflow: hidden auto;
- }
+}
+
 #template_inner_horizontal_container{
     height: 3;
 }
 
- #template_inner_container {
+#template_inner_container {
     height: 15;
     overflow: auto;
- }
+}
 
 #template_message_label {
     width: auto;
@@ -470,7 +487,7 @@ CreateFoldersSettingsScreen {
     background: $boost;
  }
 
- #template_settings_radioset:light:disabled {
+#template_settings_radioset:light:disabled {
     color: $panel-darken-2;
 }
 
@@ -483,6 +500,10 @@ CreateFoldersSettingsScreen {
     color: $panel-darken-2;
 }
 
+#create_folders_settings_close_button {
+    margin: 1 0 0 0;
+}
+
 /* Confirmation Screen --------------------------------------------------------------------- */
 
 ConfirmAndAwaitTransferPopup {

datashuttle/tui/interface.py

@@ -130,21 +130,28 @@ def create_folders(
         ]
         bypass_validation = self.tui_settings["bypass_validation"]
 
+        allow_letters_in_sub_ses_values = self.tui_settings[
+            "allow_letters_in_sub_ses_values"
+        ]
+
         try:
             self.project.create_folders(
                 top_level_folder,
                 sub_names=sub_names,
                 ses_names=ses_names,
                 datatype=datatype,
                 bypass_validation=bypass_validation,
+                allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
             )
             return True, None
 
         except BaseException as e:
             return False, str(e)
 
     def validate_names(
-        self, sub_names: List[str], ses_names: Optional[List[str]]
+        self,
+        sub_names: List[str],
+        ses_names: Optional[List[str]],
     ) -> InterfaceOutput:
         """Validate a list of subject / session names.
 
@@ -166,13 +173,18 @@ def validate_names(
             "create_tab"
         ]
 
+        allow_letters_in_sub_ses_values = self.tui_settings[
+            "allow_letters_in_sub_ses_values"
+        ]
+
         try:
             format_sub, format_ses = self.project._format_and_validate_names(
                 top_level_folder,
                 sub_names,
                 ses_names,
                 self.get_name_templates(),
                 bypass_validation=False,
+                allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
             )
 
             return True, {
@@ -188,6 +200,7 @@ def validate_project(
         top_level_folder: list[str] | None,
         include_central: bool,
         strict_mode: bool,
+        allow_letters_in_sub_ses_values: bool,
     ) -> tuple[bool, list[str] | str]:
         """Wrap the validate project function.
 
@@ -202,6 +215,8 @@ def validate_project(
             If `True`, the central project is also validated.
         strict_mode
             If `True`, validation will be run in strict mode.
+        allow_letters_in_sub_ses_values
+            If `True`, alphanumeric values will not raise an error.
 
         Returns
         -------
@@ -218,6 +233,7 @@ def validate_project(
                 display_mode="print",  # unused
                 include_central=include_central,
                 strict_mode=strict_mode,
+                allow_letters_in_sub_ses_values=allow_letters_in_sub_ses_values,
             )
             return True, results