cryosparc.project

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[, target_path])	Copy a file or folder into the job direcotry.
`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)	Open a file in the current project for reading.
`download_dataset`(path)	Download a .cs dataset file from the given relative path in the project directory.
`download_file`(path[, target])	Download a file from the project directory to the given target path or writeable file handle.
`download_mrc`(path)	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[, 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[, target_path])	Create a symbolic link in the given project.
`upload`(target_path, source, *[, overwrite])	Upload the given file to the project directory at the given relative path.
`upload_dataset`(target_path, dset, *[, ...])	Upload a dataset as a CS file into the project directory.
`upload_mrc`(target_path, data, psize, *[, ...])	Upload a numpy 2D or 3D array to the job directory as an MRC file.

cp(source_path: str | PurePosixPath, target_path: str | PurePosixPath = '')#

Copy a file or folder into the job direcotry.

Parameters:

source_path (str | Path) – Relative or absolute path of source file or folder to copy. If relative, assumed to be within the project directory.
target_path (str | Path, optional) – Name or path in the project directory to copy into. If not specified, uses the same file name as the source. Defaults to “”.

create_external_job(workspace_uid: str, title: str | None = None, desc: str | None = 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, Tuple[str, str] | List[Tuple[str, str]]] = {}, params: Dict[str, Any] = {}, title: str | None = None, desc: str | None = 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: str | None = 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: 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) – Name or path of file in project directory.
Yields:: HTTPResponse – Use a context manager to read the file from the request body.

Examples

Download a project’s metadata

>>> cs = CryoSPARC()
>>> project = cs.find_project("P3")
>>> with project.download("project.json") as res:
>>>     project_data = json.loads(res.read())

download_dataset(path: str | PurePosixPath)#

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

Parameters:: path (str | Path) – Name or path to .cs file in project directory.
Returns:: Loaded dataset instance
Return type:: Dataset

download_file(path: str | PurePosixPath, target: str | PurePath | IO[bytes] = '')#

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

Parameters:

path (str | Path) – Name or path of file in project directory.
target (str | Path | IO, optional) – Local file path, directory path or writeable file handle to write response data. If not specified, downloads to current working directory with same file name. Defaults to “”.

Returns:

resulting target path or file handle.

Return type:

Path | IO

download_mrc(path: str | PurePosixPath)#

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

Parameters:: path (str | Path) – Name or 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: 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: str | PurePosixPath, parents: bool = False, exist_ok: bool = False)#

Create a directory in the given project.

Parameters:

target_path (str | Path) – Name or path of folder to create inside the 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: str | None, 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 | Datafield] | None = None, passthrough: Tuple[str, str] | None = None, title: str | None = None, desc: str | None = 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

symlink(source_path: str | PurePosixPath, target_path: str | PurePosixPath = '')#

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

Parameters:

source_path (str | Path) – Relative or absolute path of source file or folder to create a link to. If relative, assumed to be within the project directory.
target_path (str | Path) – Name or path of new symlink in the project directory. If not specified, creates link with the same file name as the source. Defaults to “”.

upload(target_path: str | PurePosixPath, source: 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 (str | Path) – Name or path of file to write 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: 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 (str | Path) – Name or path of dataset to save in the 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: 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 (str | Path) – Name or path of MRC file to save in the project directory. Should have a .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.

cryosparc.project

Contents

cryosparc.project#