Getting Started

Getting Started#

cryosparc-tools is an open-source Python library that enables scripting access to the CryoSPARC cryo-EM software package.

CryoSPARC Architecture with cryosparc-tools

Use it for the following use cases:

Programmatically read and write exposure, particle and volume data
Access project, workspace and job data
Build and run jobs to orchestrate custom cryo-EM workflows
Extend CryoSPARC functionality with third-party software packages

Note

This guide documents usage of the cryosparc-tools Python library. For CryoSPARC installation or general CryoSPARC usage instructions, read the official guide.

For usage questions and general discussion about cryosparc-tools scripts and functions, please post to the CryoSPARC discussion forum under the Scripting category.

If you would like to request or propose a feature, change or fix for cryosparc-tools source code, please either report an issue or submit a pull request.

Source code is available on GitHub.

Pre-requisites#

CryoSPARC installation must be accessible via one of the following methods:

Running on the local machine
Running on a machine on the same network with BASE_PORT + 2, BASE_PORT + 3 and BASE_PORT + 5 open for TCP connections
Running on a remote machine with BASE_PORT + 2, BASE_PORT + 3 and BASE_PORT + 5 forwarded to the local machine

See SSH Port Forwarding documentation for accessing a CryoSPARC instance on a remote machine accessible via SSH.

cryosparc-tools is only available for CryoSPARC v4.1 or newer. If using CryoSPARC v4.0 or older, please see the Manipulating .cs Files Created By CryoSPARC guide.

Python Environment#

cryosparc-tools is intended to be used in a dedicated Python environment outside of the CryoSPARC installation. A virtual environment is recommended to avoid conflicts with global Python installations.

Virtual environment tools such as venv, Conda, Mamba, Pipenv and Poetry all work with cryosparc-tools.

Ensure that the virtual environment is based on a supported version of Python (see Pre-requisites above).

Installation#

Install cryosparc-tools in the command line from PyPI into the current Python environment:

pip install cryosparc-tools

Update an existing installation of cryosparc-tools to the latest release:

pip install -U cryosparc-tools

Note

Use the version of cryosparc-tools that corresponds to your CryoSPARC minor release version. i.e., if the CryoSPARC version is vX.Y.Z, use the latest vX.Y tools package. The Z component does not need to match.

For example, if you are running CryoSPARC v4.1.2, install cryosparc-tools with pip install cryosparc-tools~=4.1.0 (equivalent to pip install "cryosparc-tools>=4.1.0,<4.2"). If you later update to CryoSPARC v4.2.0 or v5.0.0, re-install the corresponding tools package with pip install cryosparc-tools~=4.2.0 or pip install cryosparc-tools~=5.0.0 respectively.

Usage#

Import from a Python module and connect to a CryoSPARC instance. Include your CryoSPARC license ID, the network hostname of the machine hosting your CryoSPARC instance, the instance’s base port number and your email/password login credentials.

from cryosparc.tools import CryoSPARC

cs = CryoSPARC(
    license="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    host="localhost",
    base_port=39000,
    email="ali@example.com",
    password="password123"
)

This assumes CryoSPARC base ports +2, +3 and +5 (e.g., 39002, 39003 and 39005) are available at localhost on the local machine. If CryoSPARC is on another machine on the same network with a different host, say “hostname”, use host="hostname".

Query projects, jobs and result datasets:

project = cs.find_project("P3")
job = project.find_job("J42")
micrographs = job.load_output("exposures")

for mic in micrographs.rows():
    print(mic["blob/path"])

Load and save datasets directly (assumes project directory is available on current machine):

from cryosparc.dataset import Dataset

path = project.dir / "J43" / "particles.cs"
particles = Dataset.load(path)

shift_y, shift_x = particles["alignments2D/shift"].T
mic_shape_y, mic_shape_x = particles["location/micrograph_shape"].T
new_loc_x = particles["location/center_x_frac"] * mic_shape_x - shift_x
new_loc_y = particles["location/center_y_frac"] * mic_shape_y - shift_y
particles["location/center_x_frac"] *= new_loc_x / mic_shape_x
particles["location/center_y_frac"] *= new_loc_y / mic_shape_y

particles.save(path)

Running the Examples#

The example Jupyter notebooks require additional dependencies to run. Use conda to create a new Python environment with the required dependencies. Here the environment is named cryosparc-tools-example but any name may be substituted:

conda create -n cryosparc-tools-example -c conda-forge python=3 numpy==1.18.5
conda activate cryosparc-tools-example
pip install matplotlib~=3.4.0 pandas==1.1.4 cryosparc-tools

For speed, these do not include the dependencies for the crYOLO example notebook. Optionally install crYOLO with these commands:

conda install -c conda-forge pyqt=5 libtiff wxPython=4.1.1 adwaita-icon-theme 'setuptools<66'
pip install nvidia-pyindex
pip install "cryolo[c11]"

If required, install Jupyter:

pip install notebook

Run Jupyter:

jupyter notebook

Note the login token in the output.

This starts a Jupyter Notebook server at http://localhost:8888 on the current machine. Optionally provide the following arguments to make Jupyter available to other machines on the local network:

jupyter notebook --no-browser --ip=0.0.0.0 --port=8888

Note that when initializing a cryosparc.tools.CryoSPARC instance in Python, you will have to provide the license, email and password arguments. For convenience, the examples in this guide avoid this by instead defining them in environment variables. To do the same, define CRYOSPARC_LICENSE, CRYOSPARC_EMAIL and CRYOSPARC_PASSWORD environment variables with your CryoSPARC license and login credentials:

CRYOSPARC_LICENSE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
CRYOSPARC_EMAIL="ali@example.com" \
CRYOSPARC_PASSWORD="password123" \
jupyter notebook --no-browser --ip=0.0.0.0 --port=8888

Example notebooks ran on Ubuntu Linux with x86-64 bit architecture.

Next Steps#

Browse the included examples real-life use cases for cryosparc-tools. Read the API Reference for full usage capabilities.

Guides

Working with Jobs

Examples

API Reference

Modules

Links

Contributing#

Read the contribution guide for full details.

If you publish an open-source tool that uses this package to GitHub, add the cryosparc-tools topic to your repository so others may discover it. Browse tagged packages here.

License#

cryosparc-tools is licensed under the BSD-3-Clause license. View full license text.