cryosparc-tools is an open-source Python library that enables scripting access to the CryoSPARC cryo-EM software package.
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
This guide documents usage of the
cryosparc-tools Python library. For CryoSPARC installation or general CryoSPARC usage instructions, read the official guide.
Source code is available on GitHub.
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 + 3and
BASE_PORT + 5open for TCP connections
Running on a remote machine with
BASE_PORT + 2,
BASE_PORT + 3and
BASE_PORT + 5forwarded 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.
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.
Ensure that the virtual environment is based on a supported version of Python (see Pre-requisites above).
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
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.
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="firstname.lastname@example.org", password="password123" )
This assumes CryoSPARC base ports +2, +3 and +5 (e.g., 39002, 39003 and 39005) are
localhost on the local machine. If CryoSPARC is on another
machine on the same network with a different host, say “hostname”, use
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 pip install nvidia-pyindex pip install "cryolo[c11]"
Install Jupyter with this command:
pip install notebook
Example notebooks ran on Ubuntu Linux with x86-64 bit architecture.
Browse the included examples real-life use cases for
cryosparc-tools. Read the
API Reference for full usage capabilities.
- 1. Re-center Particles
- 2. Pick particles with crYOLO
- 3. 3D Flex: Custom Latent Trajectory
- 4. 3D Flex: Custom Mesh Rigidity
- 5. Generate High-Res 2D Classes
- 6. Import from EPU XML File
- 7. Custom Workflow
- 8. Delete Rejected Exposures
- 9. Revert downsampled, symmetry expanded particles
- 10. Connect a volume series to Class3D
For questions, bug reports, suggestions or source code contributions, please read the contribution guide.
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.
cryosparc-tools is licensed under the BSD-3-Clause license. View full license text.