Projects, Workspaces and Live Sessions

Do not remove from the filesystem any directory that is managed by an attached CryoSPARC project. First delete unwanted projects using the Delete Project GUI action or the delete_project() method of the CryoSPARC CLI.

Projects in CryoSPARC are high level containers corresponding to a project directory on the filesystem which houses all associated jobs. Each project in CryoSPARC is entirely contained within the project directory. All of the jobs and their respective intermediate and output data created within a Project will be stored within the project directory.

Projects are strict divisions. Files and jobs from different projects are stored in dedicated project directories and jobs cannot be connected from one project to another.

Workspaces, on the other hand, are logical groupings like labels, that are created by the user to separate portions of a workflow for ease of use. A job can be added to multiple workspaces at the same time and can be removed from a workspace at any time. Workspaces do not have any particular directory on the filesystem and there are no file transfers or copies made when jobs are moved between workspaces.

Projects

When to create a new project

Recommendation: Create a new project for each new unrelated sample on which you are collecting data.

Additional recommendations for creating new Projects and Workspaces:

• Collecting new data for the first time on a new target molecule: Create a new project and a new workspace within it. Import the movies/micrographs/particle stacks into the new workspace.

• Collecting data a second or subsequent time on the same sample/target (potentially the same or different grid from the same batch, potentially on a different day): Use the existing project and existing workspace where you processed the first set of images. Import the movies/micrographs/particle stack into the existing workspace or a new workspace, in the same project.

• Collecting data on a new sample/grid/preparation of the same target molecule: Use the existing project, but create a new workspace. This allows easy re-use of 3D volumes, 2D templates, and easy combining of particle images downstream. You can create multiple workspaces within a project, for example if collecting/processing new data from a similar sample.

See similar considerations for creating projects and sessions for CryoSPARC Live in the New Live Session: Start to Finish Guide.

Creating your first project

1. Navigate to the Projects view by clicking on the container icon on the left-side navigation bar

2. To create a project, click the green “New Project” button in the top right of the browse header (above the main content area). This will open the “slide-over”panel where you can enter you project details and create your new project. Alternatively, if no projects currently exist, the “Create a New Project” panel will appear in the main content area. This functions identically to the slide-over panel.

3. Enter a project title and select a container directory, which is the location that a new project directory for the new project will be created. The container directory you select should already exist. The new project directory will be created and will be populated with job directories as you create jobs. All files associated with the project will be stored inside the project directory. You may also wish to enter a description for your project.

4. Clicking the “Create” button at the bottom of the slide-over will create your new project and add it to the project page. This will also automatically take you into the created project where you can then create your first workspace.

A project can be opened either by clicking the navigation button at the bottom of a project card, by selecting the project and pressing the enter key, or by clicking the “View Project” button at the bottom of the sidebar. Alternatively, a project can be selected using the quick switcher at the top of the page. Any of these options will open the corresponding project and show all of its workspaces.

Workspaces

Creating your first workspace

Before you can start processing data inside of a new project, you will need to create at least one workspace.

1. If you have not already opened your project, you can do so from the projects view by clicking on a project to select it and either pressing the enter key, or pressing the “View Project” button at the bottom of the active sidebar. Alternatively, you may simply click the “View x Workspaces” or “No Workspaces” button (which will show when no workspaces exist inside of your project yet) at the bottom of the project card.

2. Once inside your selected Project, create a New Workspace by clicking on the green “New Workspace” button in the top right of the browse header, or simply entering the relevant information into the “Create a New Workspace” panel that shows inside of an empty project. Alternatively, you can open the actions panel by clicking the “Actions” button at the bottom of the project sidebar and then clicking the “New Workspace” button. Any of these actions will open the workspace creation slide-over panel. Workspace titles can be changed later, and descriptions can be added any time.

3. Clicking the “Create” button at the bottom of the slide-over will create your new workspace and add it to the workspaces view. This will also automatically take you into the created workspace where you can begin creating jobs and start processing data.

Project and Workspace Interface Details

Project Card

The project card is composed of four main sections:

Header

The header shows the project’s ID and title as well as a context menu trigger and a star button (visible when the card is hovered).

Preview Panel

The job preview track shows jobs within the project sorted by most recent. These preview cards can be clicked to open the jobs that they represent. They also allow for a quick way to see what was last being worked on within the project.

Information Panel

This panel displays a variety of distinct information that can be useful at a glance.

• The date when the project was created and the user who created it.

• A list of tags associated with the project. Tags can be created and added to all browse items and can be used to organize and filter data in the browse system.

• The description added to the project if applicable. Descriptions are markdown compatible.

Navigation Buttons (Bottom)

This is the the primary way of entering the project, and also displays the number of workspaces/sessions existing within a project.

Project Row

The project row shows in the Table view, and gives a less information dense overview of the project allowing for easier navigation and management of projects on larger instances. It includes counts of all workspaces, sessions, and jobs inside of the projects, as well as a description cell with a markdown formatted tooltip.

Project Sidebar

The right-side sidebar, when a project is selected, shows details about the project. It is composed of a few sections:

Header

The sidebar header shows the project ID, project title, and includes a deselect button on the righthand side. This button will remove the current sidebar selection and fall back to displaying details of the container you are browsing (eg. if a workspace is selected and you are inside of a project, deselecting the workspace sidebar will replace it with the details of the project).

Details

The details panel shows a variety of core information and statistics such as:

• Title: The unique title given to the project to identify it.

• Tags: All tags that have been applied to the project. This section has an edit button visible when hovering over it. Clicking this button will open up a context menu where you can select more tags to add to the project, or deselect added tags to remove them. Clicking the coloured tag pill buttons will add that tag as a filter to the current view.

• Created: This is the timestamp indicating the date and time when the project was initially created.

• Created By: The name of the user who initially created the project.

• Last Accessed: The timestamp indicating the last time the project was opened. This time can represent access by any user who is able to view the project.

• Last Accessed By: The full name of the last user who opened the project.

• Directory: The absolute path to the filesystem directory where the project is located. This path can be copied by clicking on it.

• Size: The total size of the project on disk in gigabytes.

• Size Last Updated: This represents the last time the project size was calculated. CryoSPARC regularly refreshes statistics across the instance on a set schedule to keep them up to date. This limits heavy calculations that would need to be made every time a statistic is viewed. The size displayed can be manually refreshed by clicking the “refresh” button beside the timestamp. This will force the system to recalculate the project size to show the absolute most up to date version.

Description

If no description is present this panel will default to edit mode and display a small markdown editor that saves text automatically as you type into it. If a description has been added to the project this panel will show a markdown formatted read-only pane with an “Edit” button in the top right corner visible on hover.

Sharing

The sharing panel allows you to easily see who you have shared your project with, as well as share with new users and remove users who you no longer wish to share the project with. Clicking the share button at the bottom of the panel will open a context menu populated with the names of other users across your current instance. Clicking any of these users will share the project with them, allowing them to see and modify data inside of it. The selected users will show up in the panel as new rows below the owner row (your user). Each of these rows has a remove button on the righthand side that can be clicked to remove sharing privileges from the user. Removing a user will stop them from being able to see or interact with your project in any way.

Statistics

• Last Updated: Shows when the projects statistics were last updated and includes a button beside the timestamp allowing you to manually refresh them if they are stale.

• Workspaces: Shows the number of workspaces in the project, and allows quick navigation into the project to the workspaces view by clicking the “view” button visible on hover.

• Sessions: Shows the number of sessions in the project, and allows quick navigation into the project to the sessions view by clicking the “view” button.

• Jobs: Shows the total number of jobs in the project across all workspaces, and allows quick navigation into the project to a flattened jobs view by clicking the “view” button. This view shows all jobs across the project regardless of workspace.

• Job Status: Each coloured status button in this section shows the total number of jobs inside of the project with the corresponding status. Clicking any of these buttons will navigate into the project to the jobs view and show all jobs inside of the project filtered by the selected status.

• Job Types: This section shows all of the different job types across the project and a count of the number of jobs corresponding to each type. Each job type indicator is a button that can be clicked to navigate into the project jobs view with a filter of that job type applied (eg. only jobs of that type, from across the entire project, will show in this view).

Project-Level Parameters

Enable SSD Caching: This section includes a selection menu with options for setting a project level override for the top level SSD Caching parameter. This selection will only take effect on the specific project it is set on.

Actions

The “Actions” button at the bottom of the project sidebar will open a slide up command palette when clicked. This palette contains a number of relevant actions that can be taken on the project.

• New Workspace: This will open the slide-over panel for workspace creation. Filling in the required fields and clicking the create button will make a new workspace inside of the project and navigate you to the project’s workspaces view with the new workspace selected.

• New Session: The same functionality as the new workspace action except for creating a live session.

• Archive Project: Allows the project to be archived to remote/slow storage to free up space. A record of this project will remain in your projects view with an “archived” tag.

• Clear Intermediate Results: This will clear all unused intermediate results from all jobs within the project to free up disk space.

• Detach Project: Removes the project and its data for use in attaching to another instance. Detached projects are displayed in the application for reference only. No actions can be taken on a detached project.

• Delete Project: This action removes all data generated in that project, including micrographs, extracted particles, and any other associated data. Deleting a project does not delete the raw data that was imported into the project.

Project Quick Actions Menu

The quick actions menu is accessible on a project by right clicking on a project card or row, or by clicking the button with three horizontal dots on the card header. This will open a context menu with a variety of actions that can be taken on the project. These actions are largely identical to those present in the “Actions Palette” accessible from the sidebar, a reference of which can be seen directly above this section.

Along with the aforementioned actions, the quick access menu also allow tags to be quickly added or removed from the project using a submenu accessible from the “Edit Tags” menu item.

Workspace Card

The workspace card is largely analogous to the project card in terms of composition of available information and actions.

One additional section is available in the workspace card’s information section, an actionable list of job categories with counts of each job within the workspace that fall into said category. Each item in this list is a button that when clicked will automatically open the workspace and show all of its jobs with the relevant filter applied (eg. clicking on a “Particle Picking” category count button will open the workspace and show only the jobs that fall within that category inside: ex. Blob Picker, Inspect Picks, Extract From Micrographs, Template Picker).

Opening the workspace, either by clicking the “view” button or selecting the workspace and pressing the enter key, will take you to the jobs view and show all jobs within.

Workspace Row and Sidebar

The workspace row and sidebar are almost entirely identical to those corresponding to the project, but with a subset of data relevant to the workspace. Refer to the project section above for more information regarding these interface components.

Workspace Quick Actions Menu

The same as with projects, the quick actions menu is accessible on a workspace by right clicking on a workspace card or row, or by clicking the button with three horizontal dots on the card header. This menu shows the same actions as in the sidebar’s “Actions Palette”, along with a submenu for adding and removing tags from the workspace.

CryoSPARC Live Sessions

A CryoSPARC Live Session is actually a special type of workspace. It contains extra metadata and is used primarily for processing data within CryoSPARC live. Sessions have all the same functionality as standard workspaces and therefore are also visible in the workspace section of the browse system.

Sessions view

The sessions view is a special view that shows Live sessions only, and displays them in a way that is more helpful when processing data in Live. The sessions view can be accessed by clicking on the lightning icon on the left-side navigation bar.

This view differs slightly from that of the other browse pages in that it includes a distinct session projects sidebar on the lefthand side of the main content area, and larger item cards to accommodate the extra data useful for identifying and analyzing live sessions at a glance.

Session Projects Bar

The projects bar (left side of the content area when in sessions view) shows all projects that include live sessions for easy navigation. Each project card within the bar displays that project’s ID, name, the user that created it, how many sessions exist inside of it, and the date it was created. These project cards can be selected to filter sessions belonging only to the selected project or projects. Clicking a selected project card will deselect it, and if it was the only selected project then all projects will be selected instead.

Session Card

Header

The session card header is nearly identical to the workspace card header, with the difference of showing the distinct session ID and the current processing status (running, paused, or completed).

Preview Panel

The lefthand side preview image shows an exposure preview that can be clicked on to zoom.

The righthand side shows the job preview track, displaying jobs in the session sorted by most recent (the same view as in the project and workspace cards).

Session Details Panel

• Exposures: Shows the total overall exposures, completed exposures, queued exposures, and failed exposures.

• Particles: Shows the total manual picks, blob picks, template picks, and extracted particles.

• Reconstruction: Shows the current reconstruction resolution and all jobs run in the live reconstruction pipeline. The displayed jobs are buttons that can be clicked on to view the full job dialog.

Details Panel

The details panel shows the same information as the workspace card - creation information, description, job categories, and tags.

Action Buttons

• View Session: This button will open the session in the CryoSPARC Live interface

• View Jobs: This will enter the session and show all the applicable jobs, the same as entering a workspace.

Sessions also support entry by using the same keyboard shortcuts as project and workspace selections (pressing enter). Similarly, the session has its own action menu accessible from the header or by right clicking on the card or row.

Viewing the session will open the CryoSPARC Live view for that session. Viewing the session’s jobs will open the session and show all jobs associated with it.

For comprehensive documentation on CryoSPARC Live, please see the guides at:

About CryoSPARC Live