Blueprints

Introduction

Blueprints allow you to customize parameter settings of individual job types in CryoSPARC, and then save those customizations as templates to be used later in any project or workspace. The saved customizations, called blueprints, become available right from the CryoSPARC job builder and quick actions menus and can be easily created, applied, edited, and exported/imported to another instance.

As an example, if movies are frequently imported from the same microscope at the same magnification, an Import Movies blueprint could be created for that microscope to automatically set the Cs, pixel size, number of frames, electron dose, etc.

At a high level, blueprints are meant to create an organizational space that can be accessed quickly in any project and workspace to deploy relevant jobs from a curated template. They remove the need to maintain workspaces full of separate template jobs and alleviate the act of searching across the instance for a job previously used to process similar data that yielded good results; these jobs can be scattered across projects and workspaces and searching for them can be difficult and time consuming. Instead, with blueprints, templates of jobs are only a click away in the job builder.

Creating a Blueprint

A blueprint can be created either from a pre-existing job, or from a job type (eg. Import Movies, 3D Classification, etc). When creating a blueprint from a pre-existing job the Create Blueprint dialog will have it’s custom parameters pre-populated with the custom parameters of that job. When creating from a job type, the dialog will have no pre-set custom parameters.

Creating from a Pre-existing Job

There are two ways to create a blueprint based on an existing job. First, by clicking the “Create Blueprint” option in the job’s quick access menu. Second, by selecting the job and clicking the “Create Blueprint” option in the job sidebar’s actions panel. Either of these options will open the Create Blueprint dialog. Similarly, with the job card selected, you can navigate to the job sidebar and open the actions panel by clicking the “Actions” button on the footer. You can select the “Create Blueprint” option in the panel to open the corresponding dialog.

From here you can add a title - which will be the name of the blueprint shown in the job builder - and modify or add any parameters you would like to have applied when using your blueprint. Clicking the green “Create” button at the bottom of the dialog will create your new blueprint.

Creating from the Builder Sidebar Panel

You can also create a blueprint from scratch using the Job Builder. This will open the same creation dialog but with no custom parameters pre-populated. To do this, navigate to the Job Builder sidebar panel, find the job type from which you would like to create a blueprint, and use the “triple dot” overflow menu button to open the overflow menu; from here you can select the “Create Blueprint” option which will open the Create Dialog enabling you to build your blueprint.

Applying a Blueprint

To apply a blueprint, simply navigate to any relevant workspace and either choose a blueprint you would like to use from the Job Builder, or select a currently building job and apply the blueprint to it.

Applying to a Pre-existing Job

Select the job you would like to apply the blueprint to, and using either the quick access menu or the job sidebar actions panel, select the “Apply Blueprint” option to open a submenu with relevant blueprint options for that job type. Selecting a blueprint will clear all of the pre-existing custom parameters (if any have been set) and apply all of the blueprint parameters.

Applying from the Job Builder

Navigate into a workspace and then select the Job Builder sidebar panel. Find the job type that you would like to apply a blueprint from and open the blueprint drawer. The drawer can be opened by clicking on the down arrow beside the job type, or by navigating to it using the keyboard and pressing shift + down arrow to open the drawer. Select the blueprint you would like to apply. This will create a new job of the relevant type, and apply all of the blueprint parameters to it. From here it can have its inputs connected and be run as expected.

Modifying a Blueprint

Blueprints cannot be edited or deleted unless you are the creator of the blueprint or an administrator.

Modification options can be accessed in the Job Builder by navigating to a blueprint and clicking the “triple dot” button on the far right side to open the overflow menu. This will present options to edit or delete the blueprint.

Editing a Blueprint

Selecting the “Edit” option from the overflow menu will open an Edit Blueprint dialog which, for all intents and purposes, is the same as the “Create Blueprint” dialog. Any and all parameters can be added, reset, and removed, and the blueprint will be permanently updated with the new parameters by pressing the “Update” button at the bottom of the dialog.

Deleting a Blueprint

Selecting the “delete” option from the overflow menu will open a confirmation popover which, upon confirming the deletion, will irreversibly remove the blueprint from the instance.

Annotating a Blueprint

Blueprints are meant to facilitate consistency and repeatability in creating jobs for a specific purpose. This often means that a Blueprint will have a variety of specific parameters set to particular values. In order to maintain intelligibility over the reasons for setting those parameter values, and even the parameters themselves, Blueprints includes a suite of annotation options.

Job Details

Job details operate nearly identically to those found in the job builder. They allow you to apply annotations on a job by job basis by adding a title and/or description. When creating a Blueprint these fields will be pre-populated with any pre-existing titles or descriptions that the original job was given. An additional option to the far right of the field label allows you to check or uncheck an “Apply to Job” option. This option determines whether the Blueprint title and/or description will be added to jobs that the Blueprint is applied to. These options are checked by default.

Parameter Details

Each parameter includes an option for annotation. This can be accessed by clicking the “Additional Options” toggle button to the far right of the parameter.

From here you can add any relevant notes about the parameter, for instance why it was set to the current value and/or in what situations it should be changed. The parameter note will be visible inside of the sidebar information tooltip for the relevant Blueprint when hovered.

Importing / Exporting a Blueprint

Blueprints, like workflows, are designed for portability. This means that they can be easily saved, stored, and shared between instances. Blueprints contain no identifying information of the instance that they were created in, and no references to the jobs that were used to create them. This allows blueprints to be a powerful tool for maintaining a catalog of your proprietary job templates, or cooperatively iterating on a processing approach agnostic of institution or instance.

Exporting a Blueprint

A blueprint can be exported by clicking on the the “triple dot” overflow button beside the individual blueprint you would like to export. Clicking on the “Export” option in the menu will download the blueprint to your device. The downloaded file is a .json (JavaScript Object Notation) file and can be easily inspected using any modern web browser. This compact file includes all of the necessary information to recreate a blueprint in any CryoSPARC instance (running on a version current to or greater than the introduction of the blueprints feature).

Importing a Blueprint

Importing a blueprint can be done by clicking the “Import Blueprint” button on the footer of the Job Builder sidebar panel. This will open a device native file browser where you can find and upload a previously exported blueprint .json file.

Once selected the file will be imported into your instance and will appear in the Job Builder sidebar panel like any other blueprint. The imported blueprint has no special properties outside of a imported attribute to demarcate it as created outside of the instance. The imported blueprint can be used, modified, and exported like any other blueprint.

Summary

Blueprints are a template library for single jobs that allow you to consolidate useful template jobs in a single place where they can be easily created, applied, edited, and exported/imported agnostic of instance. They can be created from pre-existing jobs or from scratch using the Job Builder, and can be applied to pre-existing jobs or new ones. Blueprints can be modified by the creator or administrators, and can be exported and imported as .json files for portability.