Quick validate project

[JoeZiminski]

[NOTE: this makes a major refactor to the module names. This will completely mess up all other PRs. All other PRs need to be merged before this one, and ensure all changes to datashuttle.py are merged into datashuttle_class.py.]

Description

Expose a new function quick_validate_project that can validate a project given a pass, bypassing the full project management.
Requires only passing a path to the function.

It would be great to also get feedback on the naming. 'Quick' validate is in contrast to using datashuttle fully to manage a project (e.g. setting up configs). But if you don't know how datashuttle works, this reference is lost. However, it is still 'quick' so maybe it is clear enough 😅

There are a few things which need improving and will come in a follow up PR:

• the output of the validation is nonstandard across validation errors, and does not contain path to where the validation error is. In a follow-up PR the format of the error will be standardised + include path.
• Currently output is either error, warn or print. I think it will be useful incl for @viktorpm to also output a list of all validation errors
• validation is not available in the TUI. Need to add this (a tab on the ProjectManager as well as separate screen).

For Reviewing

This PR needed to to some refactoring and renaming which polluted the diff. I added two comments to indicate where the major changes are (new function + tests, there is also a doc).

To build the docs, cd to docs and do:

sphinx-build source build and the website can be accessed from the build/index.html file

The new docs are under 'How to -> Validate Existing Project'. In general the docs lay out is quite confusing and will be improved in an upcoming PR.

To test the function:

from datashuttle import quick_validate_project

quick_validate_project("path/to/project")`

What is this PR

• Addition of a new feature

Why is this PR needed?

Setting up datashuttle for transfer or in 'local-only' mode (validation + creating folders) is a little cumbersome / confusing. It is nice to expose a fast way to validate folders (which will probably be the main use of the package).

How has this PR been tested?

Integration tests added.

[viktorpm]

The documentation says

from datashuttle import quick_validate_project

I found the quick_validate_project function here:

from datashuttle.datashuttle_functions import quick_validate_project

Once imported, it works 🙂

[viktorpm]

I'm not sure if I should get an error when there is a folder in rawdata that does not follow the NBP naming convention.

These don't raise errors:

/mnt/ceph/_projects/pwm_computational
├── derivatives
└── rawdata
    └── rat1 

.
├── derivatives
└── rawdata
    ├── rat10
    ├── sub-001
    │   └── ses-001
    │       ├── anat
    │       ├── behav
    │       ├── ephys
    │       └── funcimg
    ├── sub-002
    │   └── ses-001
    │       ├── anat
    │       ├── behav
    │       ├── ephys
    │       └── funcimg
    └── subbb_033

[viktorpm]

Suggestions based on our discussion:

• Save a log file.
• The display_mode argument doesn't seem to be working as expected (it always displays an error). It is working now
• Provide a more detailed description of validation failures (e.g., specify the folder, describe the issue, and indicate whether it's a critical error, a moderate violation, or just a warning).
• unrelated, but an "Exit datashuttle" button would be nice in the TUI

[viktorpm]

I think, it is working as expected:

.
├── derivatives
└── rawdata
    ├── sub-001
    │   └── ses-001
    │       ├── anat
    │       ├── behav
    │       ├── ephys
    │       └── funcimg
    ├── sub-002_date
    ├── sub-002_date_
    └── sub-1

display_mode="print":

quick_validate_project(project_path="/home/plattnerv/test_project2", top_level_folder="rawdata", display_mode="print")
Problem with name: sub-002_date_. Names must consist of key-value pairs separated by underscores.e.g. 'sub-001_ses-01_date-20230516
Inconsistent value lengths for the key sub were found. Ensure the number of digits for the sub value are the same and prefixed with leading zeros if required.
A sub already exists with the same sub id as sub-1. The existing folder is sub-001.
A sub already exists with the same sub id as sub-002_date. The existing folder is sub-002_date_.
A sub already exists with the same sub id as sub-001. The existing folder is sub-1.
A sub already exists with the same sub id as sub-002_date_. The existing folder is sub-002_date.

[JoeZiminski]

Hey @viktorpm thanks a lot for your review and feedback!

• Save a log file.
  Now that Add local only mode #457 is merged, running validation like:

project = DataShuttle("my_project")
project.make_config_file(local_path=...)  
project.validate_project(...)

will run the same validation but also output a log file. I am not certain if it tells you where the log file is, it should if it does not. Maybe we can revisit this when #464 is merged.

• Provide a more detailed description of validation failures (e.g., specify the folder, describe the issue, and indicate whether it's a critical error, a moderate violation, or just a warning).

Perfect yes this should be complete is #464

• unrelated, but an "Exit datashuttle" button would be nice in the TUI

Good point! CTRL+C will do this, added to docs in #465