workspace

workspace#

Classes:

WorkspaceController

Accessor class to a workspace in CryoSPARC with ability create jobs and save results.
class WorkspaceController#

Accessor class to a workspace in CryoSPARC with ability create jobs and save results. Should be created with` cs.find_workspace() or project.find_workspace().

Parameters:

workspace (tuple[str, str] | Workspace) – either _(Project UID, Workspace UID)_ tuple or Workspace model, e.g. ("P3", "W4")

model#

All workspace data from the CryoSPARC database. Contents may change over time, use refresh() to update.

Type:

Workspace

Attributes:

desc

Workspace description

project_uid

Project unique ID, e.g., "P3"

title

Workspace title

uid

Workspace unique ID, e.g., "W42"

Methods:

__init__(cs, workspace)

create_external_job([title, desc])

Add a new External job to this workspace to save generated outputs to.

create_job(type[, connections, params, ...])

Create a new job with the given type.

find_job(job_uid)

Find a job in the current workspace by its UID.

find_jobs(*[, order])

Search jobs in the current workspace.

refresh()

Reload this workspace from the CryoSPARC database.

save_external_result(dataset, type[, name, ...])

Save the given result dataset to a workspace.

set_description(desc)

Set the workspace description.

set_title(title)

Set the workspace title.
__init__(cs: CryoSPARC, workspace: Tuple[str, str] | Workspace) → None#
create_external_job(title: str = '', desc: str = '') → ExternalJobController#

Add a new External job to this workspace to save generated outputs to.

Parameters:

  • workspace_uid (str) – Workspace UID to create job in, e.g., “W1”

  • title (str, optional) – Title for external job (recommended). Defaults to “”.

  • desc (str, optional) – Markdown description for external job. Defaults to “”.

Returns:

created external job instance

Return type:

ExternalJobController

create_job(type: str, connections: Dict[str, Tuple[str, str] | List[Tuple[str, str]]] = {}, params: Dict[str, Any] = {}, title: str = '', desc: str = '') → JobController#

Create a new job with the given type. Use cs.job_register to find available job types on the connected CryoSPARC instance.

Parameters:

  • project_uid (str) – Project UID to create job in, e.g., “P3”

  • workspace_uid (str) – Workspace UID to create job in, e.g., “W1”

  • type (str) – Job type identifier, e.g., “homo_abinit”

  • connections (dict[str, tuple[str, str] | list[tuple[str, str]]]) – Initial input connections. Each key is an input name and each value is a (job uid, output name) tuple. Defaults to {}

  • params (dict[str, any], optional) – Specify parameter values. Defaults to {}.

  • title (str, optional) – Job title. Defaults to “”.

  • desc (str, optional) – Job markdown description. Defaults to “”.

Returns:

created job instance. Raises error if job cannot be created.

Return type:

JobController

Examples

Create an Import Movies job.

>>> from cryosparc.tools import CryoSPARC
>>> cs = CryoSPARC("http://localhost:61000")
>>> workspace = cs.find_workspace("P3", "W3")
>>> import_job = workspace.create_job("W1", "import_movies")
>>> import_job.set_param("blob_paths", "/bulk/data/t20s/*.tif")
True

Create a 3-class ab-initio job connected to existing particles.

>>> abinit_job = workspace.create_job("homo_abinit"
...     connections={"particles": ("J20", "particles_selected")}
...     params={"abinit_K": 3}
... )
property desc: str | None#

Workspace description

find_job(job_uid: str) → JobController#

Find a job in the current workspace by its UID.

Parameters:

job_uid (str) – Job UID to find, e.g., “J42”

Returns:

job accessor object

Return type:

JobController

find_jobs(*, order: Literal[1, -1] = 1, **search: Unpack[JobSearch]) → Iterable[JobController]#

Search jobs in the current workspace.

Example

>>> jobs = workspace.find_jobs()  # all jobs in workspace
>>> jobs = workspace.find_jobs(
...     type="homo_reconstruct",
...     completed_at=(datetime(2025, 3, 1), datetime(2025, 3, 31)),
...     order=-1,
... )
>>> for job in jobs:
...     print(job.uid)
Parameters:

**search (JobSearch) – Additional search parameters to filter jobs, specified as keyword arguments.

Returns:

job accessor objects

Return type:

Iterable[JobController]

project_uid: str#

Project unique ID, e.g., “P3”

refresh()#

Reload this workspace from the CryoSPARC database.

Returns:

self

Return type:

WorkspaceController

save_external_result(dataset: Dataset[R], type: Literal['exposure', 'particle', 'template', 'volume', 'volume_multi', 'mask', 'live', 'ml_model', 'symmetry_candidate', 'flex_mesh', 'flex_model', 'hyperparameter', 'denoise_model', 'annotation_model'], name: str | None = None, slots: List[str | Slot | Datafield] | None = None, passthrough: Tuple[str, str] | None = None, title: str = '', desc: str = '', image: str | PurePath | IO[bytes] | Any | None = None, savefig_kw: dict = {'bbox_inches': 'tight', 'pad_inches': 0}) → str#

Save the given result dataset to a workspace.

Parameters:

  • dataset (Dataset) – Result dataset.

  • type (Datatype) – Type of output dataset.

  • name (str, optional) – Name of output on created External job. Same as type if unspecified. Defaults to None.

  • slots (list[SlotSpec], optional) – List of slots expected to be created for this output such as location or blob. Do not specify any slots that were passed through from an input unless those slots are modified in the output. Defaults to None.

  • passthrough (tuple[str, str], optional) – Indicates that this output inherits slots from the specified output. e.g., ("J1", "particles"). Defaults to None.

  • title (str, optional) – Human-readable title for this output. Defaults to “”.

  • desc (str, optional) – Markdown description for this output. Defaults to “”.

  • image (str | Path | IO | Figure, optional) – Optional image file or matplotlib Figure to set as the image for this output. Defaults to None.

  • savefig_kw (dict, optional) – Additional keyword arguments to pass to figure.savefig() when saving matplotlib Figures. Defaults to dict(bbox_inches="tight", pad_inches=0).

Returns:

UID of created job where this output was saved.

Return type:

str

Examples

Save all particle data

>>> particles = Dataset()
>>> workspace.save_external_result(particles, 'particle')
"J43"

Save new particle locations that inherit passthrough slots from a parent job

>>> particles = Dataset()
>>> workspace.save_external_result(
...     dataset=particles,
...     type='particle',
...     name='particles',
...     slots=['location'],
...     passthrough=('J42', 'selected_particles'),
...     title='Re-centered particles'
... )
"J44"

Save a result with multiple slots of the same type.

>>> workspace.save_external_result(
...     dataset=particles,
...     type="particle",
...     name="particle_alignments",
...     slots=[
...         {"dtype": "alignments3D", "prefix": "alignments_class_0", "required": True},
...         {"dtype": "alignments3D", "prefix": "alignments_class_1", "required": True},
...         {"dtype": "alignments3D", "prefix": "alignments_class_2", "required": True},
...     ]
... )
"J45"
set_description(desc: str)#

Set the workspace description. May include Markdown formatting.

Parameters:

desc (str) – New workspace description

set_title(title: str)#

Set the workspace title.

Parameters:

title (str) – New workspace title

property title: str | None#

Workspace title

uid: str#

Workspace unique ID, e.g., “W42”

Contents