cryosparc-examples

Example scripts, notebooks, and code snippets that are helpful for CryoSPARC users!

📜 How do I use these scripts?

These scripts can be run on your own computer or from the computer hosting CryoSPARC. They all require cryosparc-tools and its dependencies. For more information on installing cryosparc-tools, please see the package documentation.

Some scripts also require plotnine for advanced plotting and polars for advanced data manipulation. See the plotnine page and the polars page page for more information. These packages are mostly used for plotting, so if you do not wish to install those packages you can simply remove the cells which require them and the scripts should largely remain functional.

Once dependencies are installed, you can run notebooks (*.ipynb) using your Jupyter Notebook environment of choice. You can run python scripts (*.py) directly in the terminal in the usual way (path/to/script.py or python path/to/script.py). If you click a notebook in GitHub it will open so that you can see the result of each cell. Python scripts do not have this feature, but are contained in their own directory with a README explaining the script's usage.

💻 Where can I run these scripts from?

The scripts and notebooks do not need to be run on the master node --- they simply need to have access to the following ports:

• The CryoSPARC base port (39000 by default)
• Base port + 2 (39002 by default)
• Base port + 3 (39003 by default)
• Base port + 5 (39005 by default)

If the scripts are being run on the master node, these ports are open and the host parameter of CryoSPARC() can be set to localhost. If the scripts are being run on a machine with direct network access to the master node and the above ports, host should be set to the master node's host name and base_port should be set to the appropriate base port (39000) by default.

If the scripts are being run from a machine without direct network access to the master node (e.g., a personal computer), you must first set up SSH tunnels to the appropriate ports, then set host to localhost and base_port to the tunneled base port. For example, running the command

ssh -N -L 39000:localhost:39000 -L 39002:localhost:39002 -L 39003:localhost:39003 -L 39005:localhost:39005 << master host >>

with << master host >> replaced by the hostname for the CryoSPARC master nodes will set up ssh tunnels for each of the (default) required ports, so that setting host to localhost will be sufficient to run the script.

🤔 What is instance-info.json?

CryoSPARC Tools scripts must prove that you are an authenticated user of the CryoSPARC instance. Prior to CryoSPARC v5, your username and password were required. This is just the email and password you use to access the normal CryoSPARC GUI; you do not need to be an administrator or have special access to the installation. The scripts also need to know the hostname and base port for the CryoSPARC installation. We find it convenient to store all of this information in a JSON file in the user's home directory, called instance-info.json. This file has the following content (including the opening and closing {}):

{
        "license": "<< your license >>",
        "email": "<< the email you use to log into the CryoSPARC GUI >>",
        "password": "<< the password you use to log into the CryoSPARC GUI>>",
        "base_port": << the port used to connect to the CryoSPARC instance. If the default 39000 is used, this line can be removed>>,
        "host": "<< the host of the CryoSPARC instance >>"
}

with the relevant information replacing all text surrounded by and including << >>.

Starting with CryoSPARC v5, authentication tokens are used instead. CryoSPARC Tools proves you are an authenticated user once, and then sends this proof (a token) for future uses of the script. You authenticate by running python -m cryosparc.tools login. Whenever you create a CryoSPARC() object in a python script, CryoSPARC Tools checks whether you have an active token for the specified host. If you do, the script proceeds. If you do not, the script will error out and tell you to perform the login process to re-authenticate.

For backwards compatibility with your v4 scripts, you can create v5 instance-info.json files like so:

{
        "base_url": "<< the full URL you use to access cryosparc, like http://localhost:39000 >>",
        "email": "<< the email you use to log into the CryoSPARC GUI >>"
}

If you prefer, you can instead manually enter this information into the cs = CryoSPARC() lines at the beginning of the script. More information on creating and authenticating the CryoSPARC object can be found here.