Rename make_sub_folders to make_folders. (#223)

* Rename `make_sub_folders` to `make_folders`.

* Rename in docs and tests!

* Add missed cases, fix tests.

* Fix typo.

Author: JoeZiminski

datashuttle/command_line_interface.py

@@ -187,13 +187,13 @@ def setup_ssh_connection_to_central_server(*args: Any) -> None:
 # -----------------------------------------------------------------------------
 
 
-def make_sub_folders(project: DataShuttle, args: Any) -> None:
+def make_folders(project: DataShuttle, args: Any) -> None:
     """"""
     kwargs = make_kwargs(args)
 
     filtered_kwargs = {k: v for k, v in kwargs.items() if v is not None}
 
-    run_command(project, project.make_sub_folders, **filtered_kwargs)
+    run_command(project, project.make_folders, **filtered_kwargs)
 
 
 # -----------------------------------------------------------------------------
@@ -591,19 +591,19 @@ def construct_parser():
     # Make Sub Folder
     # ----------------------------------------------------------------------
 
-    make_sub_folders_parser = subparsers.add_parser(
-        "make-sub-folders",
-        aliases=["make_sub_folders"],
-        description=process_docstring(DataShuttle.make_sub_folders.__doc__),
+    make_folders_parser = subparsers.add_parser(
+        "make-folders",
+        aliases=["make_folders"],
+        description=process_docstring(DataShuttle.make_folders.__doc__),
         formatter_class=argparse.RawTextHelpFormatter,
         help="",
     )
-    make_sub_folders_parser = make_sub_folders_parser.add_argument_group(
+    make_folders_parser = make_folders_parser.add_argument_group(
         "named arguments:"
     )  # type: ignore
-    make_sub_folders_parser.set_defaults(func=make_sub_folders)
+    make_folders_parser.set_defaults(func=make_folders)
 
-    make_sub_folders_parser.add_argument(
+    make_folders_parser.add_argument(
         "--sub-names",
         "--sub_names",
         "-sub",
@@ -612,7 +612,7 @@ def construct_parser():
         required=True,
         help=help("required_str_single_or_multiple_or_all"),
     )
-    make_sub_folders_parser.add_argument(
+    make_folders_parser.add_argument(
         "--ses-names",
         "--ses_names",
         "-ses",
@@ -621,7 +621,7 @@ def construct_parser():
         required=False,
         help="Optional: (str, single or multiple) (selection of datatypes, or 'all')",
     )
-    make_sub_folders_parser.add_argument(
+    make_folders_parser.add_argument(
         "--datatype",
         "-dt",
         type=str,

datashuttle/configs/canonical_folders.py

@@ -37,7 +37,7 @@ def get_datatype_folders(cfg: Configs) -> dict:
         an option for rare cases in which advanced users want to change it.
 
     used : whether the folder is used or not (see make_config_file)
-        if False, the folder will not be made in make_sub_folders
+        if False, the folder will not be made in make_folders
         even if selected.
 
     level : "sub" or "ses", level to make the folder at.

datashuttle/datashuttle.py

@@ -131,7 +131,7 @@ def set_top_level_folder(self, folder_name):
         Set the working top level folder (e.g. 'rawdata', 'derivatives').
 
         The top_level_folder defines in which top level folder new
-        sub-folders will be made (e.g. make_sub_folders) or at which level
+        sub-folders will be made (e.g. make_folders) or at which level
         folders  are transferred with the commands upload / download
         and upload_all / download all.
 
@@ -155,7 +155,7 @@ def set_top_level_folder(self, folder_name):
         self.show_top_level_folder()
 
     @check_configs_set
-    def make_sub_folders(
+    def make_folders(
         self,
         sub_names: Union[str, list],
         ses_names: Optional[Union[str, list]] = None,
@@ -204,13 +204,13 @@ def make_sub_folders(
 
         Examples
         --------
-        project.make_sub_folders("sub-001", datatype="all")
+        project.make_folders("sub-001", datatype="all")
 
-        project.make_sub_folders("sub-002@TO@005",
+        project.make_folders("sub-002@TO@005",
                              ["ses-001", "ses-002"],
                              ["ephys", "behav"])
         """
-        self._start_log("make-sub-folders", local_vars=locals())
+        self._start_log("make-folders", local_vars=locals())
 
         self.show_top_level_folder()
 
@@ -322,7 +322,7 @@ def upload(
             transfer was taking place, but no files will be moved. Useful
             to check which files will be moved on data transfer.
         datatype :
-            see make_sub_folders()
+            see make_folders()
 
         init_log :
             (Optional). Whether to start the logger. This should
@@ -927,7 +927,7 @@ def show_top_level_folder(self):
         'rawdata', 'derivatives')
 
         The top_level_folder defines in which top level folder new
-        sub-folders will be made (e.g. make_sub_folders) or
+        sub-folders will be made (e.g. make_folders) or
         at which level folders are transferred with the commands
         upload / download and upload_all / download all.
         upload_specific_folder_or_file / download_specific_folder_or_file.
@@ -1013,7 +1013,7 @@ def check_name_formatting(
     ) -> None:
         """
         Pass list of names to check how these will be auto-formatted,
-        for example as when passed to make_sub_folders() or upload()
+        for example as when passed to make_folders() or upload()
         or download()
 
         Useful for checking tags e.g. @TO@, @DATE@, @DATETIME@, @DATE@.

datashuttle/utils/data_transfer.py

@@ -250,7 +250,7 @@ def check_input_arguments(
     ):
         """
         Check the sub / session names passed. The checking here
-        is stricter than for make_sub_folderss / formatting.check_and_format_names
+        is stricter than for make_folders / formatting.check_and_format_names
         because we want to ensure that a) non-datatype arguments are not
         passed at the wrong input (e.g. all_non_ses as a subject name).
 

datashuttle/utils/folders.py

@@ -41,7 +41,7 @@ def make_folder_trees(
     Parameters
     ----------
 
-    sub_names, ses_names, datatype : see make_sub_folders()
+    sub_names, ses_names, datatype : see make_folders()
 
     log : whether to log or not. If True, logging must
         already be initialised.

docs/source/pages/documentation.md

@@ -104,7 +104,7 @@ Next, we can start setting up the project by automatically creating standardised
 
 In a typical neuroscience experiment, a data-collection session begins by creating the folder for the current subject (e.g. mouse, rat) and current session. Once created, the data for this session is stored in the created folder.
 
-The command `make-sub-folders` can be used automatically create folder trees that adhere to the [SWC-Blueprint](https://swc-blueprint.neuroinformatics.dev/) specification. The linked specifications contain more detail, but at it's heart this requires:
+The command `make-folders` can be used automatically create folder trees that adhere to the [SWC-Blueprint](https://swc-blueprint.neuroinformatics.dev/) specification. The linked specifications contain more detail, but at it's heart this requires:
 
 - All subjects are given a numerical (integer) number that is prefixed with the key `sub-`.
 - All sessions are also given a numerical (integer) number that is prefixed with the key `ses-`.
@@ -123,7 +123,7 @@ In DataShuttle, this folder tree (excluding the .mp4 file which must be saved us
 ```
 datashuttle \
 my_first_project \
-make-sub-folders -sub 001 -ses 001_@DATE@ -dt behav
+make-folders -sub 001 -ses 001_@DATE@ -dt behav
 ```
 
 The leading `sub-` or `ses-` is optional when specifying folders to create (e.g. both `-sub 001` and `-sub sub-001` are valid inputs). It is possible to automatically create date, time or datetime key-value pairs with the days `@DATE@`, `@TIME@` or `@DATETIME@` respectively (see the [below section](#automatically-include-date-time-or-datetime
@@ -134,7 +134,7 @@ Another example call, which creates a range of subject and session folders, is s
 ```
 datashuttle \
 my_first_project \
-make-sub-folders -sub 001@TO@003 -ses 010_@TIME@ -dt all
+make-folders -sub 001@TO@003 -ses 010_@TIME@ -dt all
 ```
 
 When the `all` argument is used for `--datatype` (`-dt`), the folders created depend on the *datatypes* specified during *configuration* setup. For example, if
@@ -210,7 +210,7 @@ SWC-Blueprint defines two main *top-level folders*, `rawdata` and `derivatives`.
         └── ...
 ```
 
-In DataShuttle, the current working *top level folder* is by default `rawdata`. The working *top level folder* determines where folders are created (e.g. `make_sub_folders`), and from which folder data is transferred.
+In DataShuttle, the current working *top level folder* is by default `rawdata`. The working *top level folder* determines where folders are created (e.g. `make_folders`), and from which folder data is transferred.
 
 For example, `upload` or  `upload-all` will transfer data with `rawdata` from *local* to *central*, if `rawdata` is the current *top-level folder*. `upload` transfers the specified subset of folders, while `upload-all` will upload the entire *top-level folder*.
 
@@ -339,7 +339,7 @@ project.make_config_file(
 and methods for making subject folders and transferring data accessed similarly. Note that the shortcut arguments `-sub`, `-ses`, `-dt` are not available through the Python API, and the full argument names (`sub_names`, `ses_names`, `datatype`) must be used.
 
 ```
-project.make_sub_folders(
+project.make_folders(
 	sub_names="sub-001@TO@002",
 	ses_names="ses-001_@DATE@",
 	datatype="all"
@@ -392,7 +392,7 @@ For example, the command:
 ```
 datashuttle \
 my_first_project \
-make_sub_folders \
+make_folders \
 -sub sub_001@DATE@ \
 -ses 001@TIME@ 002@DATETIME@
 -dt behav
@@ -432,7 +432,7 @@ Note when making folders with the `@TO@` tag, the maximum number of leading zero
 ```
 datashuttle \
 my_first_project \
-make_sub_folders \
+make_folders \
 -sub 0001@TO@02
 ```
 
@@ -622,10 +622,10 @@ Similarly, the command `show-configs` will print all currently set *configuratio
 Detailed logs of all configuration changes, folder creation and data transfers are logged
 to the `.datashuttle` folder that is created in the *local* project folder.
 
-For each command run, a log of that command is placed in the logs folder, with the time and date of the command. The log itself contains relevant information pertaining to that command. For example, if the commands `make_sub_folders`, `upload`, `download` were run sequentially, the logs output folder would look like:
+For each command run, a log of that command is placed in the logs folder, with the time and date of the command. The log itself contains relevant information pertaining to that command. For example, if the commands `make_folders`, `upload`, `download` were run sequentially, the logs output folder would look like:
 
 ```
-20230608T095514_make-sub-folders.log
+20230608T095514_make-folders.log
 20230608T095545_upload-data.log
 20230608T095621_download-data.log
 ```

tests/test_utils.py

@@ -442,7 +442,7 @@ def make_and_check_local_project_folders(
 def make_local_folders_with_files_in(
     project, subs, sessions=None, datatype="all"
 ):
-    project.make_sub_folders(subs, sessions, datatype)
+    project.make_folders(subs, sessions, datatype)
     for root, dirs, files in os.walk(project.cfg["local_path"]):
         if not dirs:
             path_ = Path(root) / "placeholder_file.txt"

tests/tests_integration/test_command_line_interface.py

@@ -173,9 +173,9 @@ def test_make_config_file_non_default_variables(self, tmp_path):
         self.check_kwargs(changed_configs, kwargs_)
 
     @pytest.mark.parametrize("sep", ["-", "_"])
-    def test_make_sub_folders_variable(self, sep):
+    def test_make_folders_variable(self, sep):
         stdout, _ = test_utils.run_cli(
-            f" make{sep}sub{sep}folders "
+            f" make{sep}folders "
             f"--datatype all "
             f"--sub_names 001 "
             f"--ses_names 002 "
@@ -273,9 +273,7 @@ def test_upload_download_folder_or_file(self, upload_or_download, sep):
         assert args_[0] == "/fake/filepath"
         assert kwargs_["dry_run"] is True
 
-    @pytest.mark.parametrize(
-        "command", ["make_sub_folders", "upload", "download"]
-    )
+    @pytest.mark.parametrize("command", ["make_folders", "upload", "download"])
     def test_multiple_inputs(self, command):
         """
         To process lists, a syntax "<>" is used
@@ -394,15 +392,15 @@ def test_make_config_file_not_defaults(
 
         test_utils.check_config_file(config_path, changed_configs)
 
-    def test_make_sub_folders(self, setup_project):
+    def test_make_folders(self, setup_project):
         """
         see test_filesystem_transfer.py
         """
         subs = ["sub-011", "sub-002", "sub-333"]
         ses = ["ses-123", "ses-999"]
 
         test_utils.run_cli(
-            f"make_sub_folders --datatype all --sub_names {self.to_cli_input(subs)} --ses_names {self.to_cli_input(ses)} ",
+            f"make_folders --datatype all --sub_names {self.to_cli_input(subs)} --ses_names {self.to_cli_input(ses)} ",
             setup_project.project_name,
         )
 

tests/tests_integration/test_filesystem_transfer.py

@@ -74,7 +74,7 @@ def test_transfer_empty_folder_structure(
         )
 
     def test_empty_folder_is_not_transferred(self, project):
-        project.make_sub_folders("sub-001")
+        project.make_folders("sub-001")
         project.upload_all()
         assert not (project.cfg["central_path"] / "sub-001").is_dir()
 
@@ -290,7 +290,7 @@ def test_transfer_with_keyword_parameters(
         """
         Test the @TO@ keyword is accepted properly when making a session and
         transferring it. First pass @TO@-formatted sub and sessions to
-        make_sub_folders. Then transfer the files (upload or download).
+        make_folders. Then transfer the files (upload or download).
 
         Finally, check the expected formatting on the subject and session
         is observed on the created and transferred file paths.
@@ -425,7 +425,7 @@ def test_rclone_transfer_verbosity(
         """
         see test_rclone_options()
         """
-        project.make_sub_folders(["sub-001"], ["ses-002"], ["behav"])
+        project.make_folders(["sub-001"], ["ses-002"], ["behav"])
         project.update_config("transfer_verbosity", transfer_verbosity)
 
         test_utils.clear_capsys(capsys)
@@ -455,7 +455,7 @@ def test_rclone_overwrite_modified_file(
             Path("rawdata") / "sub-001" / "histology" / "test_file.txt"
         )
 
-        project.make_sub_folders("sub-001")
+        project.make_folders("sub-001")
         local_test_file_path = project.cfg["local_path"] / path_to_test_file
         central_test_file_path = (
             project.cfg["central_path"] / path_to_test_file
@@ -554,7 +554,7 @@ def test_specific_file_or_folder(
 
     def setup_specific_file_or_folder_files(self, project):
         """ """
-        project.make_sub_folders(["sub-001", "sub-002"], "ses-003")
+        project.make_folders(["sub-001", "sub-002"], "ses-003")
 
         path_to_test_file_behav = (
             Path("rawdata")

tests/tests_integration/test_formatting.py

@@ -97,7 +97,7 @@ def test_format_names_prefix(self):
         ]
 
     def test_warning_non_consecutive_numbers(self, project):
-        project.make_sub_folders(
+        project.make_folders(
             ["sub-01", "sub-2", "sub-04"], ["ses-05", "ses-10"]
         )