Add support for NeuroGEARS logging structure

[sumiya-kuroda]

Is your feature request related to a problem? Please describe.
NeuroGEARS team has their own format of saving acquired data from NIDAQ, Harp, cameras etc. In their format the data is always logged like session_date > Experiment_data (including animal names) in order to support experiments with multiple animals, which is opposite of how NeuroBlueprint formats data. Below is a more detailed structure:

.
└── data/
    ├── 2024_12_12-16_36_42/
    │   ├── ExperimentEvents
    │   ├── HarpData
    │   ├── SessionSettings/
    │   │   └── SessionSettings_2024_12_12_12_00_00.yaml
    │   ├── VideoData1
    │   ├── VideoData2
    │   └── ...
    └── 2024_12_15-13_23_32/
        ├── ExperimentEvents
        ├── HarpData
        ├── SessionSettings/
        │   └── SessionSettings_ 2024_12_15_12_00_00.yaml
        ├── VideoData1
        ├── VideoData2
        └── ...

SessionSettings_YYYY_MM_DD_HH_MM_SS.yaml has session-specific info, including the name of the animal.

Describe the solution you'd like
Allow datashuttle to convert the format when uploading the data from local to servers.

[JoeZiminski]

Hey @sumiya-kuroda thanks a lot for this, we can definitely write a converter. We can discuss further when we meet tomorrow, but I'll leave some thoughts below. I'll break it up into two cases, one is converting a single session when the sub- and ses- IDs are known. The other is how these IDs can be inferred from an existing project.

1) Convert a single session to neuroblueprint:

1. If we know the subject ID, we could add the name field from the yaml e.g. sub-xxx_name-xxx?
2. If we know the session ID, we can add the session folder as a datetime key, e.g. ses-xxx_datetime-xxx?
3. The NeuroGears folder names can be fixed to convert to particular datatypes e.g. ExperimentEvents, VideoData... would make sense to go into behav? Same for HarpData? Or, we could introduce a new datatype sync if these time alignment data should be shared across datatypes.
4. We could rename the NeuroGears folders into a more NeuroBlueprint style e.g. behav/sub-01_ses-01_type-videodata1, but there are no hard rules on what goes in the datatype folder, so if very inconvenient we can keep the NeuroGears folder names as-is within the datatype folder.

2) Inferring the sub / ses ID from the project folder

I think the main two uses for a converter would be:

1. Convert a whole NeuroGears project to NeuroBlueprint
2. As you mention, convert a recently acquired folder to NeuroBlueprint prior to data transfer. In this case one or more NeuroGears sessions might be collected within a NeuroBlueprint folder structure. These could then be converted to NeuroBlueprint prior to transfer:

e.g.

sub-001_name-xxx
    ses-001_datetime-xxx
sub-002_name-xxx
2024_12_12-16_36_42/
2024_12_15-13_23_32/

I think as long as all subjects had a name tag that matches the name in the SessionSettings yaml file, this would be quite straightforward. However, it would only work for 1-subject per session folder (which is the case we are interested in, if multiple subjects are found in the dataset an error could be raised until that case is supported later).

1. In the NeuroGears session folder, get the subject name from the .yaml. If a sub with this name tag exists, this session will go into the existing subject folder, otherwise create a new sub- ID as the biggest existing sub- ID + 1. If there are NeuroBlueprint names without the name field, raise an error.
2. Set the sub- ID to the last ses- ID + 1, and add the NeuroGears session folder as a datetime key-value pair. Perform some confidence checks that all datetimes are in order.

[JoeZiminski]

Thanks for this @sumiya-kuroda I will close this now further to #534 but feel free to reopen if anything else comes up related to this.