cryosparc.project#

Classes:

Project(cs, uid)

Accessor instance for CryoSPARC projects with ability to add workspaces, jobs and upload/download project files.
class cryosparc.project.Project(cs: CryoSPARC, uid: str)#

Accessor instance for CryoSPARC projects with ability to add workspaces, jobs and upload/download project files. Should be instantiated through CryoSPARC.find_project.

uid#

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

Type:

str

doc#

All project data from the CryoSPARC database. Database contents may change over time, use the refresh method to update.

Type:

ProjectDocument

Methods:

cp(source_path_rel, target_path_rel)

Copy a file or folder within a project to another location within that same project.

create_external_job(workspace_uid[, title, desc])

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

create_job(workspace_uid, type[, ...])

Create a new job with the given type.

create_workspace(title[, desc])

Create a new empty workspace in this project.

dir()

Get the path to the project directory.

download(path_rel)

Open a file in the current project for reading.

download_dataset(path_rel)

Download a .cs dataset file frmo the given relative path in the project directory.

download_file(path_rel, target)

Download a file from the project directory to the given writeable target.

download_mrc(path_rel)

Download a .mrc file from the given relative path in the project directory.

find_external_job(job_uid)

Get the External job accessor instance for an External job in this project with the given UID.

find_job(job_uid)

Get a job accessor instance for the job in this project with the given UID.

find_workspace(workspace_uid)

Get a workspace accessor instance for the workspace in this project with the given UID.

list_files([prefix, recursive])

Get a list of files inside the project directory.

mkdir(target_path_rel[, parents, exist_ok])

Create a directory in the given project.

refresh()

Reload this project from the CryoSPARC database.

save_external_result(workspace_uid, dataset, ...)

Save the given result dataset to the project.

symlink(source_path_rel, target_path_rel)

Create a symbolic link in the given project.

upload(target_path_rel, source, *[, overwrite])

Upload the given file to the project directory at the given relative path.

upload_dataset(target_path_rel, dset, *[, ...])

Upload a dataset as a CS file into the project directory.

upload_mrc(target_path_rel, data, psize, *)

Upload a numpy 2D or 3D array to the job directory as an MRC file.
cp(source_path_rel: Union[str, PurePosixPath], target_path_rel: Union[str, PurePosixPath])#

Copy a file or folder within a project to another location within that same project.

Parameters:

  • source_path_rel (str | Path) – Relative path in project of source file or folder to copy.

  • target_path_rel (str | Path) – Relative path in project to copy to.

create_external_job(workspace_uid: str, title: Optional[str] = None, desc: Optional[str] = None) → ExternalJob#

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

Parameters:

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

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

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

Returns:

created external job instance

Return type:

ExternalJob

create_job(workspace_uid: str, type: str, connections: Dict[str, Union[Tuple[str, str], List[Tuple[str, str]]]] = {}, params: Dict[str, Any] = {}, title: Optional[str] = None, desc: Optional[str] = None) → Job#

Create a new job with the given type. Use CryoSPARC.get_job_sections to query 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 None.

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

Returns:

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

Return type:

Job

Examples

Create an Import Movies job.

>>> from cryosparc.tools import CryoSPARC
>>> cs = CryoSPARC()
>>> project = cs.find_project("P3")
>>> import_job = project.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 = project.create_job("W1", "homo_abinit"
...     connections={"particles": ("J20", "particles_selected")}
...     params={"abinit_K": 3}
... )
create_workspace(title: str, desc: Optional[str] = None) → Workspace#

Create a new empty workspace in this project. At least a title must be provided.

Parameters:

  • title (str) – Title of new workspace

  • desc (str, optional) – Markdown text description. Defaults to None.

Returns:

created workspace instance

Return type:

Workspace

dir() → PurePosixPath#

Get the path to the project directory.

Returns:

project directory Pure Path instance

Return type:

Path

download(path_rel: Union[str, PurePosixPath])#

Open a file in the current project for reading. Use to get files from a remote CryoSPARC instance where the project directory is not available on the client file system.

Parameters:

path (str | Path) – Relative path of file in project directory.

Yields:

HTTPResponse – Use a context manager to read the file from the request body

download_dataset(path_rel: Union[str, PurePosixPath])#

Download a .cs dataset file frmo the given relative path in the project directory.

Parameters:

  • path_rel (str | Path) – Realtive path to .cs file in project

  • directory. –

Returns:

Loaded dataset instance

Return type:

Dataset

download_file(path_rel: Union[str, PurePosixPath], target: Union[str, PurePath, IO[bytes]])#

Download a file from the project directory to the given writeable target.

Parameters:

  • path_rel (str | Path) – Relative path of file in project directory.

  • target (str | Path | IO) – Local file path, directory path or writeable file handle to write response data.

Returns:

resulting target path or file handle.

Return type:

Path | IO

download_mrc(path_rel: Union[str, PurePosixPath])#

Download a .mrc file from the given relative path in the project directory.

Parameters:

path_rel (str | Path) – Relative path to .mrc file in project directory.

Returns:

MRC file header and data as a numpy array

Return type:

tuple[Header, NDArray]

find_external_job(job_uid: str) → ExternalJob#

Get the External job accessor instance for an External job in this project with the given UID. Fails if the job does not exist or is not an external job.

Parameters:

job_uid (str) – Job unique ID, e.g,. “J42”

Raises:

TypeError – If job is not an external job

Returns:

accessor instance

Return type:

ExternalJob

find_job(job_uid: str) → Job#

Get a job accessor instance for the job in this project with the given UID. Fails with an error if job does not exist.

Parameters:

job_uid (str) – Job unique ID, e.g., “J42”

Returns:

accessor instance

Return type:

Job

find_workspace(workspace_uid) → Workspace#

Get a workspace accessor instance for the workspace in this project with the given UID. Fails with an error if workspace does not exist.

Parameters:

workspace_uid (str) – Workspace unique ID, e.g., “W1”

Returns:

accessor instance

Return type:

Workspace

list_files(prefix: Union[str, PurePosixPath] = '', recursive: bool = False) → List[str]#

Get a list of files inside the project directory.

Parameters:

  • prefix (str | Path, optional) – Subdirectory inside project to list. Defaults to “”.

  • recursive (bool, optional) – If True, lists files recursively. Defaults to False.

Returns:

List of file paths relative to the project directory.

Return type:

list[str]

mkdir(target_path_rel: Union[str, PurePosixPath], parents: bool = False, exist_ok: bool = False)#

Create a directory in the given project.

Parameters:

  • target_path_rel (str | Path) – Relative path to create inside project directory.

  • parents (bool, optional) – If True, any missing parents are created as needed. Defaults to False.

  • exist_ok (bool, optional) – If True, does not raise an error for existing directories. Still raises if the target path is not a directory. Defaults to False.

refresh()#

Reload this project from the CryoSPARC database.

Returns:

self

Return type:

Project

save_external_result(workspace_uid: Optional[str], dataset: Dataset[R], type: Literal['exposure', 'particle', 'template', 'volume', 'mask', 'live', 'ml_model', 'symmetry_candidate', 'flex_mesh', 'flex_model', 'hyperparameter'], name: Optional[str] = None, slots: Optional[List[Union[str, Datafield]]] = None, passthrough: Optional[Tuple[str, str]] = None, title: Optional[str] = None, desc: Optional[str] = None) → str#

Save the given result dataset to the project. Specify at least the dataset to save and the type of data.

If workspace_uid or passthrough input is not specified or is None, saves the result to the project’s newest workspace. If passthrough is specified but workspace_uid is not, saves to the passthrough job’s newest workspace.

Returns UID of the External job where the results were saved.

Examples

Save all particle data

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

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

>>> particles = Dataset()
>>> project.save_external_result(
...     workspace_uid='W1',
...     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.

>>> project.save_external_result(
...     workspace_uid="W1",
...     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"
Parameters:

  • workspace_uid (str | None) – Workspace UID to save results into. Specify None to auto-select a workspace.

  • 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 None.

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

Returns:

UID of created job where this output was saved

Return type:

str

Create a symbolic link in the given project. May only create links for files within the project.

Parameters:

  • project_uid (str) – Target project UID, e.g., “P3”.

  • source_path_rel (str | Path) – Relative path in project to file from which to create symlink.

  • target_path_rel (str | Path) – Relative path in project to new symlink.

upload(target_path_rel: Union[str, PurePosixPath], source: Union[str, bytes, PurePath, IO], *, overwrite: bool = False)#

Upload the given file to the project directory at the given relative path. Fails if target already exists.

Parameters:

  • target_path_rel (str | Path) – Relative target path in project directory.

  • source (str | bytes | Path | IO) – Local path or file handle to upload. May also specified as raw bytes.

  • overwrite (bool, optional) – If True, overwrite existing files. Defaults to False.

upload_dataset(target_path_rel: Union[str, PurePosixPath], dset: Dataset, *, format: int = 1, overwrite: bool = False)#

Upload a dataset as a CS file into the project directory. Fails if target already exists.

Parameters:

  • target_path_rel (str | Path) – relative path to save dataset in project directory. Should have a .cs extension.

  • dset (Dataset) – dataset to save.

  • format (int) – format to save in from cryosparc.dataset.*_FORMAT, defaults to NUMPY_FORMAT)

  • overwrite (bool, optional) – If True, overwrite existing files. Defaults to False.

upload_mrc(target_path_rel: Union[str, PurePosixPath], data: NDArray, psize: float, *, overwrite: bool = False)#

Upload a numpy 2D or 3D array to the job directory as an MRC file. Fails if target already exists.

Parameters:

  • target_path_rel (str | Path) – filename or relative path. Should have .mrc extension.

  • data (NDArray) – Numpy array with MRC file data.

  • psize (float) – Pixel size to include in MRC header.

  • overwrite (bool, optional) – If True, overwrite existing files. Defaults to False.