diff --git a/datashuttle/datashuttle_class.py b/datashuttle/datashuttle_class.py index 018707d8e..f339f8391 100644 --- a/datashuttle/datashuttle_class.py +++ b/datashuttle/datashuttle_class.py @@ -1077,7 +1077,17 @@ def make_config_file( ds_logger.close_log_filehandler() def update_config_file(self, **kwargs) -> None: - """Update the configuration file.""" + """Update the configuration file. + + Parameters + ---------- + **kwargs + A dictionary of key-value pairs containing the config + settings to update. For example, + ``{"connection_method": "local_filesystem", "central_path": "/my/local/path"}`` + will update the ``connection_method`` and ``central_path`` settings. + + """ if not self.cfg: utils.log_and_raise_error( "Must have a config loaded before updating configs.", diff --git a/docs/source/_static/screenshots/how-to-create-folders-example-dark.png b/docs/source/_static/screenshots/how-to-create-folders-example-dark.png index 08fbbdd06..e5df8d4a4 100644 Binary files a/docs/source/_static/screenshots/how-to-create-folders-example-dark.png and b/docs/source/_static/screenshots/how-to-create-folders-example-dark.png differ diff --git a/docs/source/_static/screenshots/how-to-create-folders-example-light.png b/docs/source/_static/screenshots/how-to-create-folders-example-light.png index 840e14084..79b7f1728 100644 Binary files a/docs/source/_static/screenshots/how-to-create-folders-example-light.png and b/docs/source/_static/screenshots/how-to-create-folders-example-light.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-aws-dark.png b/docs/source/_static/screenshots/how-to-create-project-aws-dark.png index c028fe40e..4fb0c50c4 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-aws-dark.png and b/docs/source/_static/screenshots/how-to-create-project-aws-dark.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-aws-light.png b/docs/source/_static/screenshots/how-to-create-project-aws-light.png index 67d37ab06..00b68f912 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-aws-light.png and b/docs/source/_static/screenshots/how-to-create-project-aws-light.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-gdrive-dark.png b/docs/source/_static/screenshots/how-to-create-project-gdrive-dark.png index 26f2dcd0c..b7a6a3226 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-gdrive-dark.png and b/docs/source/_static/screenshots/how-to-create-project-gdrive-dark.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-gdrive-light.png b/docs/source/_static/screenshots/how-to-create-project-gdrive-light.png index b29d9db95..1bdf0e6ef 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-gdrive-light.png and b/docs/source/_static/screenshots/how-to-create-project-gdrive-light.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-ssh-dark.png b/docs/source/_static/screenshots/how-to-create-project-ssh-dark.png index 238a25d36..3c736b5f0 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-ssh-dark.png and b/docs/source/_static/screenshots/how-to-create-project-ssh-dark.png differ diff --git a/docs/source/_static/screenshots/how-to-create-project-ssh-light.png b/docs/source/_static/screenshots/how-to-create-project-ssh-light.png index 58804e9ea..66d0da059 100644 Binary files a/docs/source/_static/screenshots/how-to-create-project-ssh-light.png and b/docs/source/_static/screenshots/how-to-create-project-ssh-light.png differ diff --git a/docs/source/_static/screenshots/how-to-quick-validate-project-dark.png b/docs/source/_static/screenshots/how-to-quick-validate-project-dark.png index 5236b76ed..87458765a 100644 Binary files a/docs/source/_static/screenshots/how-to-quick-validate-project-dark.png and b/docs/source/_static/screenshots/how-to-quick-validate-project-dark.png differ diff --git a/docs/source/_static/screenshots/how-to-quick-validate-project-light.png b/docs/source/_static/screenshots/how-to-quick-validate-project-light.png index cd561c3cc..974a508d7 100644 Binary files a/docs/source/_static/screenshots/how-to-quick-validate-project-light.png and b/docs/source/_static/screenshots/how-to-quick-validate-project-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-create-datatype-dark.png b/docs/source/_static/screenshots/tutorial-1-create-datatype-dark.png index d0e827a15..5da360493 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-create-datatype-dark.png and b/docs/source/_static/screenshots/tutorial-1-create-datatype-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-create-datatype-light.png b/docs/source/_static/screenshots/tutorial-1-create-datatype-light.png index e7c3cb75d..910bfd50d 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-create-datatype-light.png and b/docs/source/_static/screenshots/tutorial-1-create-datatype-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-create-screen-dark.png b/docs/source/_static/screenshots/tutorial-1-create-screen-dark.png index 6a3c1d958..80ae93ade 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-create-screen-dark.png and b/docs/source/_static/screenshots/tutorial-1-create-screen-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-create-screen-light.png b/docs/source/_static/screenshots/tutorial-1-create-screen-light.png index 43ff2aaf9..4678e7191 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-create-screen-light.png and b/docs/source/_static/screenshots/tutorial-1-create-screen-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-landing-screen-dark.png b/docs/source/_static/screenshots/tutorial-1-landing-screen-dark.png index 87ac9b93d..22f206a20 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-landing-screen-dark.png and b/docs/source/_static/screenshots/tutorial-1-landing-screen-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-landing-screen-light.png b/docs/source/_static/screenshots/tutorial-1-landing-screen-light.png index 0e84ca616..8a48f1fef 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-landing-screen-light.png and b/docs/source/_static/screenshots/tutorial-1-landing-screen-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-make-screen-dark.png b/docs/source/_static/screenshots/tutorial-1-make-screen-dark.png index eda1d7f1b..3e00477ae 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-make-screen-dark.png and b/docs/source/_static/screenshots/tutorial-1-make-screen-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-make-screen-light.png b/docs/source/_static/screenshots/tutorial-1-make-screen-light.png index 6822e7cb6..d93f79c02 100644 Binary files a/docs/source/_static/screenshots/tutorial-1-make-screen-light.png and b/docs/source/_static/screenshots/tutorial-1-make-screen-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-dark.png b/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-dark.png new file mode 100644 index 000000000..e9de17834 Binary files /dev/null and b/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-light.png b/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-light.png new file mode 100644 index 000000000..1bee6fa8b Binary files /dev/null and b/docs/source/_static/screenshots/tutorial-1-make-screen-local-filesystem-light.png differ diff --git a/docs/source/_static/screenshots/tutorial-validation-dark.png b/docs/source/_static/screenshots/tutorial-validation-dark.png index c264ef244..248c7954b 100644 Binary files a/docs/source/_static/screenshots/tutorial-validation-dark.png and b/docs/source/_static/screenshots/tutorial-validation-dark.png differ diff --git a/docs/source/_static/screenshots/tutorial-validation-light.png b/docs/source/_static/screenshots/tutorial-validation-light.png index ae4e124c6..f0886b304 100644 Binary files a/docs/source/_static/screenshots/tutorial-validation-light.png and b/docs/source/_static/screenshots/tutorial-validation-light.png differ diff --git a/docs/source/_static/screenshots/updating-configs-dark.png b/docs/source/_static/screenshots/updating-configs-dark.png index 969b975a0..92a1fbdce 100644 Binary files a/docs/source/_static/screenshots/updating-configs-dark.png and b/docs/source/_static/screenshots/updating-configs-dark.png differ diff --git a/docs/source/_static/screenshots/updating-configs-light.png b/docs/source/_static/screenshots/updating-configs-light.png index 1e20e55e6..7b006c02f 100644 Binary files a/docs/source/_static/screenshots/updating-configs-light.png and b/docs/source/_static/screenshots/updating-configs-light.png differ diff --git a/docs/source/pages/get_started/getting-started.md b/docs/source/pages/get_started/getting-started.md index 885376528..7a3624bde 100644 --- a/docs/source/pages/get_started/getting-started.md +++ b/docs/source/pages/get_started/getting-started.md @@ -94,7 +94,7 @@ We need to set the: ``datashuttle`` supports connecting to the central storage machine either as a mounted drive or through SHH. \ -See [Set up configs for transfer(set-up-a-project-for-transfer) +See [Set up configs for transfer](set-up-a-project-for-transfer) for detailed instructions for connecting a mounted drive or by using SSH. @@ -198,7 +198,7 @@ from datashuttle import DataShuttle project = DataShuttle("my_first_project") ``` -Next, we will use the `make_config_file()` method set the +Next, we will use the [](make_config_file()) method set the configurations ('configs') for our project. @@ -220,7 +220,7 @@ project.make_config_file( ) ``` -If you want to change any config in the future, use the `update_config_file()` method +If you want to change any config in the future, use the [](update_config_file()) method ```python project.update_config_file( @@ -315,12 +315,12 @@ we only create `behav` and `ephys` folders. ```{image} /_static/screenshots/tutorial-1-create-datatype-dark.png :align: center :class: only-dark - :width: 400px + :width: 375px ``` ```{image} /_static/screenshots/tutorial-1-create-datatype-light.png :align: center :class: only-light - :width: 400px + :width: 375px ```
@@ -328,7 +328,7 @@ Finally, click `Create Folders` to create the project folders. ::: :::{tab-item} Python API :sync: python -We will create project folders with the `create_folders()` method. +We will create project folders with the [](create_folders()) method. Following the [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/) style we will call the first subject `sub-001`. Additional key-value pairs @@ -360,8 +360,8 @@ An error will be raised if names break with the specification and the folders will not be created. ``` -Two useful methods to automate folder creation are `get_next_sub()` and -`get_next_ses()`. These can be used to automatically get the next subject +Two useful methods to automate folder creation are [](get_next_sub()) and +[](get_next_ses()). These can be used to automatically get the next subject and session names in a project. To get the next subject in this project (`sub-002`) and the next @@ -450,7 +450,7 @@ Finally, hover the mouse over the `Directory Tree` and press `CTRL+R` to refresh :::{tab-item} Python API :sync: python -`create_folders()` returns the full filepaths of created datatype folders. +[](create_folders()) returns the full filepaths of created datatype folders. These can be used in acquisition scripts to save data to these folders: @@ -543,7 +543,7 @@ Next, we will use `Custom` transfers to move only a subset of the dataset. :::{tab-item} Python API :sync: python -`upload_entire_project()` is a high level method that uploads all files +[](upload_entire_project()) is a high level method that uploads all files in the project. This includes both the `rawdata` and `derivatives` top-level folders—see the [NeuroBlueprint specification](https://neuroblueprint.neuroinformatics.dev/latest/specification.html) @@ -560,7 +560,7 @@ All files will be uploaded from the local version of the project to central stor Navigating to the `central_path` in your systems file browser, the newly transferred data will have appeared. -Other methods (e.g. `upload_rawdata()` and `upload_custom()`) provide customisable +Other methods (e.g. [](upload_rawdata()) and [](upload_custom())) provide customisable transfers (and every `upload` method has an equivalent `download` method). See the [How to Transfer Data](how-to-transfer-data) page for full details @@ -683,8 +683,8 @@ of files will now be available in the **local path**. :::{tab-item} Python API :sync: python -We will use the `download_custom()` method (the download equivalent method of -the `upload_custom()`). +We will use the [](download_custom()) method (the download equivalent method of +the [](upload_custom())). Convenience tags can be used to make downloading subsets of data easier: diff --git a/docs/source/pages/get_started/set-up-a-project.md b/docs/source/pages/get_started/set-up-a-project.md index c9c79a6b6..bd94b023c 100644 --- a/docs/source/pages/get_started/set-up-a-project.md +++ b/docs/source/pages/get_started/set-up-a-project.md @@ -20,12 +20,12 @@ Enter the name of your project, the path to your project folder and select `No connection (local only)` (note that the `Central Path` option will be disabled). -```{image} /_static/screenshots/how-to-make-local-project-configs-dark.png +```{image} /_static/screenshots/tutorial-1-make-screen-dark.png :align: center :class: only-dark :width: 900px ``` -```{image} /_static/screenshots/how-to-make-local-project-configs-light.png +```{image} /_static/screenshots/tutorial-1-make-screen-light.png :align: center :class: only-light :width: 900px @@ -74,11 +74,13 @@ project.make_config_file( ``` \ -The project is now ready for use, and in future can be instantiated -with the line ``project = DataShuttle("my_project_name")`` (i.e. you will not -have to set the `local_path` again). +The project is now ready for use, and in future can be instantiated with the line: +```python +project = DataShuttle("my_project_name") +``` +(i.e. you will not have to set the `local_path` again). -If you wish to change the project settings at a later time, use ``project.update_config_file()``. +If you wish to change the project settings at a later time, use [](update_config_file()). ::: :::: @@ -159,12 +161,12 @@ First, click the `Make New Project` button from the launch page. The `Make New Project` screen will be displayed: -```{image} /_static/screenshots/tutorial-1-make-screen-dark.png +```{image} /_static/screenshots/tutorial-1-make-screen-local-filesystem-dark.png :align: center :class: only-dark :width: 900px ``` -```{image} /_static/screenshots/tutorial-1-make-screen-light.png +```{image} /_static/screenshots/tutorial-1-make-screen-local-filesystem-light.png :align: center :class: only-light :width: 900px @@ -201,7 +203,7 @@ project = DataShuttle("my_first_project") ``` -Next, the `make_config_file()` method can be used to set up a new +Next, the [](make_config_file()) method can be used to set up a new project with the desired **local path**, **central path** and **connection method**. diff --git a/docs/source/pages/user_guides/create-folders.md b/docs/source/pages/user_guides/create-folders.md index 2842c6d0a..28772d097 100644 --- a/docs/source/pages/user_guides/create-folders.md +++ b/docs/source/pages/user_guides/create-folders.md @@ -161,7 +161,7 @@ any alphanumeric character, rather than restricted to integers. :::{tab-item} Python API :sync: python -The `create_folders()` method is used for folder creation. +The [](create_folders()) method is used for folder creation. We simply need to provide the subject, session and datatypes to create: @@ -178,9 +178,8 @@ created_folders = project.create_folders( ) ``` -The method outputs `created_folders`, which contains the -`Path`s to created datatype folders. See the below section for -details on the `@DATE@` and other convenience tags. +`created_folders` is a list containing `Path`s to created datatype folders. +See the below section for details on the `@DATE@` and other convenience tags. By default, an error will be raised if the folder names break with [Neuroblueprint](https://neuroblueprint.neuroinformatics.dev/) diff --git a/docs/source/pages/user_guides/read-logs.md b/docs/source/pages/user_guides/read-logs.md index 381926f17..b2c985de1 100644 --- a/docs/source/pages/user_guides/read-logs.md +++ b/docs/source/pages/user_guides/read-logs.md @@ -44,7 +44,7 @@ Clicking `Open Most Recent` will open the most recently saved logs. :sync: python The path where logs are stored can be accessed by running -`get_logging_path()`: +[](get_logging_path()): ```python logs_path = project.get_logging_path() diff --git a/docs/source/pages/user_guides/transfer-data.md b/docs/source/pages/user_guides/transfer-data.md index bbd54d6de..7b7c5ad55 100644 --- a/docs/source/pages/user_guides/transfer-data.md +++ b/docs/source/pages/user_guides/transfer-data.md @@ -146,7 +146,7 @@ Click `Transfer` to begin. :::{tab-item} Python API :sync: python -The `upload_rawdata()`, `upload_derivatives()` and `download_rawdata()`, `download_derivatives()` +The [](upload_rawdata()), [](upload_derivatives()) and [](download_rawdata()), [](download_derivatives()) methods target transfer to a particular top-level folder. The below example will upload `rawdata` then download `derivatives`. @@ -221,7 +221,7 @@ Finally, click `Transfer` to begin. :::{tab-item} Python API :sync: python -The `upload_custom()` and `download_custom()` methods can be used for custom +The [](upload_custom()) and [](download_custom()) methods can be used for custom data transfers. For example, to perform a custom upload: ```python diff --git a/docs/source/pages/user_guides/update-configs.md b/docs/source/pages/user_guides/update-configs.md index 75e2531fc..bed8bd39b 100644 --- a/docs/source/pages/user_guides/update-configs.md +++ b/docs/source/pages/user_guides/update-configs.md @@ -11,12 +11,12 @@ The project configs can be updated at any time following the initial set up. ```{image} /_static/screenshots/updating-configs-dark.png :align: center :class: only-dark - :width: 900px + :width: 1100px ``` ```{image} /_static/screenshots/updating-configs-light.png :align: center :class: only-light - :width: 900px + :width: 1100px ```
@@ -35,7 +35,7 @@ If SSH configs are changed the connection may need to be :sync: python The project configs on the local machine can be selectively -updated with the `update_config_file()` method. +updated with the [](update_config_file()) method. For example, to change the `local_path` and `central_path`: @@ -46,12 +46,8 @@ project.update_config_file( ) ``` -If SSH configs are changed the connection may need to be -[set up again](new-project-ssh) with: - -```python -project.setup_ssh_connection() -``` +If SSH, AWS or Google Drive configs are changed the connection +may need to be [set up again](new-project-ssh). ::: :::: diff --git a/docs/source/pages/user_guides/use-name-templates.md b/docs/source/pages/user_guides/use-name-templates.md index b1df20d17..db462aede 100644 --- a/docs/source/pages/user_guides/use-name-templates.md +++ b/docs/source/pages/user_guides/use-name-templates.md @@ -61,10 +61,10 @@ will be automatically saved. These settings will persist across :::{tab-item} Python API :sync: python -The `set_name_templates()` and `get_name_templates()` can be used +The [](set_name_templates()) and [](get_name_templates()) can be used to set and get current name template settings. -`set_name_templates` takes as input the `name_template` dictionary, +[](set_name_templates()) takes as input the `name_template` dictionary, which is formatted as below: ``` diff --git a/docs/source/pages/user_guides/validate.md b/docs/source/pages/user_guides/validate.md index 2651a9a4e..10115a3bd 100644 --- a/docs/source/pages/user_guides/validate.md +++ b/docs/source/pages/user_guides/validate.md @@ -38,13 +38,13 @@ for details on the options. ```{image} /_static/screenshots/tutorial-validation-light.png :align: center :class: only-light -:width: 600px +:width: 800px ``` ```{image} /_static/screenshots/tutorial-validation-dark.png :align: center :class: only-dark -:width: 600px +:width: 800px ``` ::: @@ -53,7 +53,7 @@ for details on the options. :sync: python -Project validation can be run with the [](datashuttle.DataShuttle.validate_project) function. +Project validation can be run with the [](validate_project) function. Violations of the [NeuroBlueprint](https://neuroblueprint.neuroinformatics.dev/latest/index.html) can be set to raise an error, be displayed as warnings or printed as output. They are also returned in a list of strings.