Overview:
- Explanation of Local and Server project versions.
- How Byosphere projects are opened, edited, saved, and version controlled.
- Explanation of Conversion and Report Job Types.
- Explanation and guidance for common prompts when opening Byosphere projects.
NOTE: This article was written for Byos v5.6. Most/all of the concepts are likely to apply to other Byosphere versions, but there may be differences.
Server vs. Local Project Versions
When using the Byosphere Virtual and Desktop Client to open and edit projects, an important concept to understand is the need for both Server and Local project versions.
The Server project version is the current "source of truth". It is the most recent version of the project saved to the Byosphere ENT Server and is accessible to all users. To view and edit a Byosphere project, a user must first download the Server project version as a Local project file saved to a "Local" directory that is only accessible to the individual Byosphere user. The download happens automatically when a user opens a Byosphere project with the Byosphere Virtual/Desktop Client.
- For the Byosphere Virtual Client the "Local" directory is located on an individual user's Virtual Client AWS Instance (virtual computer).
- For the Byosphere Desktop Client, the "Local" directory is located on the desktop computer running the Byosphere Desktop Client.
Individual users view and edit the Local project file with the Byosphere Desktop or Virtual Client just as they would in Byos. After editing, the Local project file should be saved to the Byosphere Server to update the project on the Server, allowing other users and tools (like Dashboards) to access the updated project version.
The project on the Server is always the most recently saved version of the project. However, Byosphere includes version tracking. When the project is created and every time a user saves a new version of the project to the server, the project version is saved in the project file's History (discussed more in the section below).
Tip: The Byosphere Virtual Client AWS instances have direct contact over a fast network to the Byosphere Server, making project upload and download to and from the Byosphere ENT Server very fast compared to the Byosphere Desktop Client.
Opening, Editing, and Saving a Byosphere Project
This section walks through an example of how a Byosphere project is opened, edited, and saved. The Byosphere Virtual Client is used in this example, but the same process also applies to the Byosphere Desktop Client.
Users can open a project from the Byosphere Web Client by browsing to the project file and clicking the Virtual Client Icon. Or by opening the project from the Byosphere Virtual Client using File>Open Project... or from the Byosphere Virtual Client Jobs tab.
Before the project opens, the latest Server project version is downloaded from the Byosphere ENT Server to the user's Byosphere Virtual Client AWS Instance, or to the "Local" directory.
The Local project version is now accessible for the individual Byosphere user to view and edit.
The user can edit the project exactly as they would in Byos. In this example, 2/3 trace peaks are deleted and the third remaining trace peak boundaries are adjusted. After adjusting the trace peak boundaries, the neutral mass spectrum is recomputed. When finished editing the user should save the edited Local project version to the Byosphere server to update the Server project version.
Now the Server project version has been updated (usually takes a few seconds for the Virtual Client). If any other Byosphere user opens this same project from the Byosphere ENT Server, they will see the updated project version.
When saving projects to the server, a Conversion job appears in the job queue. The Conversion job makes project data accessible and readable for Byosphere Deep Query and Dashboards. The Conversion job does not need to complete for the Project file changes to save to the Server (the green "Success" in the figure above indicates the project changes are saved to the Server). If you checked on the Generate a report option (see figure above), you will also see a Report job. The Report Job makes the project report readable and directly accessible from the Byosphere Web Client.
When a project is created and every time a project is uploaded to the Server by any user, that version of the project is tracked and could be reverted to if needed.
Guidance and explanations of common Byopshere Virtual/Desktop Client prompts
Missing Resources:
When opening a project for the first time, users are prompted to retrieve resources.
There are two options...
1. Retrieve and open downloads the project file and associated files, and opens the project. In this case:
- It takes longer to open the project, since additional time is needed to download raw MS datafiles and other associated files. How much longer depends largely on the size of raw datafiles, in addition to other factors impacting download speed.
- Choose Retrieve and open if project functions requiring raw MS datafiles are needed. A few examples of functions requiring raw MS datafile downloads include:
- Adding In Silico peptides to .blgc peptide projects (Add missing via existing, Add In silico peptides from CSV etc.)
- Adjusting trace peaks in .ntms intact projects.
- TIP: The raw MS datafiles will persist in the "Local" directory after the first download. This means download of the raw MS datafiles does not need to be repeated when opening the same project again or another project using the same raw MS datafiles.
2. Open without retrieving downloads and opens the project file without downloading corresponding raw datafiles and other associated files. This means:
- The project will open faster, significantly faster for projects created with large MS datafiles.
- Choose this option if project functions requiring the raw MS datafiles are not needed.
- TIP: You can always choose to retrieve resources after downloading and opening the project if raw MS datafiles are needed later (File>Retrieve missing resources...).
Files Exists:
NOTE: The figure and description below describes the File exists prompt for Byosphere v5.6. The File Exists prompt looks different for other Byosphere versions, but for the most part the same concepts apply.
Sometimes when opening a Byosphere project, users are prompted with File exists.
When a user saves a project to the Server, the Local version of the project is deleted automatically. The next time the project is opened, the most recent Server project version is downloaded and opened.
Alternatively, if a user closes a Local project without saving it to the server, the Local version of the project persists in the "Local" directory. When the user reopens this project, the prompt above appears, asking if the user wants to open the Local project saved in the individual user's "Local" directory, or if the user wants to delete the Local project and open the latest version of the project saved to the Server.
Open Local opens the Local version of the project. Users should select Open Local if they want to continue working with the Local version. All edits made when working with the Byosphere Virtual/Desktop Client are saved automatically to the individual user's Local version. There may be important project edits saved to the Local project version.
Override Local permanently deletes the Local project version. Selecting this option can lead to lost work if important edits were made on the Local project version without saving to the Server. Users should only select Override Local if they're absolutely sure the Local version of the project is not needed. If they are sure the Local version isn't needed, users should select Override Local to work with the latest version of the project saved to the Server.
Additional Tips:
- If unsure, it is safest to select Open Local and check if important/desired edits are saved to the Local project version. If the user realizes the Local version is not actually needed/desired or if they would rather work with the latest Server project version, simply close and reopen the project, this time selecting Override Local.
- In most cases, it is good practice to save project edits to the Server before exiting Byosphere or completing a working session, even if work on the specific project is not fully completed. This keeps the Server project "source of truth" updated, with latest changes accessible to all users and reduces the chances of accidental data loss.