Moving Projects to a New Location
Since the BrainVoyager database is creating and managing project datasets but does not acutally store them, the location of the datasets need to be synchronized with the references in the database. Since the folder structure within the project tree on disk is known to the database (it actually created it), only the location of the top-level project folder need to be known when moving datasets to a new location that is accessible from the same or from a different computer. Moving datasets is useful in case one transitions to a more powerful computer with more disk space or when handing over datasets to users that want to access and further analyze the data. Since version 21.0, BrainVoyager provides new tools that make it easy to update the database on the original (source) as well as on the new (target) computer when moving project datasets.
Moving Projects on the Same Computer
When moving datasets of individual projects to a new location on the same computer, the BrainVoyager database will report that it can no longer find the data in its original location. In case BrainVoyager was running with an open Data Analysis Manger when moving one or more projects to a new location, BrainVoyager and the Data Analysis Manager need to be restarted to detect that data seems to be missing. The program then automatically presents the Update Projects Root Path dialog (see below) allowing to adjust the reference to the moved dataset in the database.
In the example case above, the "Ventral_Visual_Cortex_Mapping" folder had been moved to another disk with more space and the program detected the missing data as indicated by the explanatory text in the dialog. Note also that the data entries (of the currently selected subject) will be colored red indicating unresolved data references as can be partially seen in the background of the screenshot. In order to synchronize the database with the new location, the Browse button on the right side of the Project folder entry (see red arrow) can be used to select the "Ventral_Visual_Cortex_Mapping" folder at its new location.
The screenshot above shows the state of the dialog after the "Ventral_Visual_Cortex_Mapping" directory had been selected at its new location (on a disk called "WD SSD"). In this case the dataset is stored inside a folder called "BrainVoyagerData" (like on the default location in the "Documents" folder). While this is recommended, any folder (including a disk's root folder) can serve as the root path of the project. After clicking the OK button, the new root path (here "/Volumes/WD SSD/BrainVoyagerData") containing the project folder (here: "Ventral_Visual_Cortex_Mapping") will replace the previous root path entry in the database synchronizing the reference to the dataset with its new location. Note that by default, the root folder of the current project is updated in the database. In case one moves the whole "BrainVoyagerData" folder to a new location that is accessed from the same computer, the for all projects option in the Change root path field should be selected to synchronize the new root path with all projects. Otherwise, the program will report (after restart) missing data links for other projects that can also be updated individually.
Moving Projects to Another Computer
When moving datasets to a new computer, two different scenarios can be distinguished. In case that all datasets are moved to a new computer that has no managed data yet (e.g. no datasets are stored yet in the "BrainVoyagerData" root path folder), it is easiest to simply copy the BrainVoyager "brainvoyager.db" database file from the source to the target computer. The locations of the database file for supported operating systems are described in the "The BrainVoyager Database" section of the Data Analysis Manager for Reproducible Processing Pipelines and Reports topic. When then starting BrainVoyager on the target computer, the Data Analysis Manager will recognize that the root paths of the managed projects need to be adjusted, and it presents the Update Projects Root Path dialog automatically as described above. In this situation, the for all projects option in the Change root path field should be selected so that the root path is changed for all moved projects. All datasets can then be accessed and managed on the target computer.
In the second scenario only one or a few projects are moved to a new computer. Even if all projects are moved, it is important to consider that the target computer might already manage other datasets and the respective information would be deleted when copying the database file from the source to the target computer. For these cases a safe and flexible way is provided that allows exporting the database of the respective project(s), that can then be moved to the target computer where the project database can be imported to synchronize the BrainVoyager database with the also moved actual dataset(s). In order to export the database information of a project, the Data Analysis Manager Options dialog can be used that can be invoked by clicking the Options button in the Data Analysis Manager window after selecting the respective project in the Projects pane.
The screenshot above shows the invoked Data Analysis Manager Options dialog with the Project Database tab selected (default). The Export button in the Single project database field can be used to export the database information about the currently selected project ("Ventral Visual Cortex Mapping" in the example). The program suggests a name (here "Ventral Visual Cortex Mapping_database.json") and location (root path folder) but any other location and file name can be chosen. The exported file stores all tables of the project and additional information from the database in a portable JSON file that can be moved to another computer with any supported operating system (Windows, macOS, Linux) for import. After exporting the project database file, it needs to be moved to the target computer in addition to the actual dataset that is stored in the project's folder on disk. An easy way to find that folder is to click the Reveal Project Folder icon in the toolbar of the Projects pane. If the project database JSON file and the actual data have been moved to the target computer, the project entry in the Projects pane should be removed since the data is no longer available on the source computer. In case one wants to keep the data on the source computer (i.e. the data is copied instead of moved), deletion of the project from the database is, of course, not needed. Note that removing the project from the database does NOT remove the corresponding dataset on disk. To be synchronized with the database, ensure that the dataset is removed from the root folder when tranferring the data to the target computer.
After moving the project dataset and the JSON database file of the project to the target computer, the JSON file needs to be imported to inform the database on the target computer about the data and performed analyses of the project. After launching BrainVoyager on the target computer, the Data Analysis Manager Options dialog needs to be invoked. The moved project database JSON file can then be selected by clicking the Import button in the Single project database field. After selecting the database file, it will be imported and stored in the database on the target computer. The imported project can then be accessed and managed immediately on the target computer. Note that the root path of the imported project will be replaced with the one displayed in the Default projects root path field at the bottom of the Data Analysis Manager window. In case the data is stored at another location (not recommended), i.e. outside the default "Documents/BrainVoyagerData" folder, the program will allow adjusting the root path by detecting missing references as described above in section "Moving Projects on the Same Computer" when restarting the program.
In summary, moving managed datasets to another computer involves the following steps:
- Export the project database (tables) using the Export button in the Single Project Database field of the Data Analysis Manager Options dialog. If the dataset is moved (not copied) to another computer, the project (and the actual dataset) should be removed from the database (disk) on the source computer.
- Move (or copy) both the actual dataset (full tree) on disk as well as the exported JSON file to the target computer using the tools of the operating system(s). If the project has been removed from the database in step 1, make sure that also the actual dataset is deleted on disk using the tools of the operating system.
- Start BrainVoyager on the target computer and import the exported project database JSON file using the Import button in the Single Project Database field of the Data Analysis Manager Options dialog.
Note that the exported database information is stored in a human-readable JSON file and the information can be inspected by loading the file in BrainVoyager using the Open JSON item in The File menu as well as with any software supporting viewing JSON files.
Copyright © 2021 Rainer Goebel. All rights reserved.