Skip to content

Export from cryoSPARC v2 and later

Jump to bottom
Daniel Asarnow edited this page Jun 14, 2024 · 1 revision

Convert cryoSPARC metadata to Relion STAR format

The command

csparc2star.py particles.cs passthrough_particles.cs particles.star

will convert metadata from a cryoSPARC job to the Relion STAR format.

  • By default particle coordinates will be transformed for extraction in Relion
  • If the coordinates will be used in cryoSPARC (e.g. after importing particles selected with Class3D) then you must use --inverty
  • If the particle coordinates, alignments, or CTF values obtained from cryoSPARC Patch Motion outputs will be used with Relion on RelionCorr or MotionCor3 outputs, which are upside-down, then you must use both --inverty (to adjust the coordinates) and --flipy (to adjust alignments and CTF values)
  • The program can also create micrograph .star files from cryoSPARC jobs with exposure outputs

See below for more details.

Table of Contents

Relion project setup

A converted .star file will contains paths for the cryoSPARC particle extraction job. To account for these paths, you can create a mock directory in your Relion project that matches the extraction job, and then make symbolic links to the actual particle stacks. Relion also requires particle stacks to have a .mrcs extension rather than .mrc, so the links must also be renamed. Finally, you can edit the converted .star file and use it normally via the Relion GUI.

Here's a complete example for a refinement job. Other job types may have slightly different file names, make sure the desired files on your system are being used.

PROJECT=/path/to/cryosparc/P10
JOB=J313
LASTITER=009

cd relion-project
mkdir -p $JOB/extract
cd $JOB/extract
ln -s /$JOB/extract/*.mrc -t .
rename .mrc .mrcs *.mrc
cd ../..
csparc2star.py $PROJECT/$JOB/$JOB_$LASTITER_particles.cs $PROJECT/$JOB/$JOB_passthrough_particles.cs $PROJECT_$JOB.star
sed -i 's/particles.mrc/particles.mrcs/g' $PROJECT_$JOB.star

Missing parameters

Particles extracted in cryoSPARC

Certain particle parameters are found in separate "passthrough" .cs files, or in .cs files from other jobs in the workspace (e.g. coordinates for re-extraction). In order to include these parameters, simply add the relevant .cs files to the csparc2star.py command before the output file:

csparc2star.py cryosparc_exp_etc.cs aux1.cs aux2.cs from_cryosparc.star

The particles will be matched by their workspace-specific UIDs, and any information missing in the main .cs file will be taken from the auxiliary .cs files. Priority is given to the first .cs file in the list containing a parameter.

If you have trouble getting this to work, you can first export the job from within cryoSPARC. The .cs file in the exported job directory will already have all the particle parameters merged, and you can then convert that single .cs file.

Particles extracted outside cryoSPARC

For particles extracted outside cryoSPARC (e.g. in Relion), we can recover the extra parameters from the .star file used for import.

First, we need to revert the cryoSPARC import paths in the converted .star file:

sed -i 's/J9\/imported/Extract\/job010/g' <csparc.star>

The star.py command can then merge micrograph names and particle coordinates from the original STAR file used to create the cryoSPARC dataset back into the converted STAR file.

star.py --copy-micrograph-coordinates original_particles.star from_cryosparc.star from_csparc_with_coords.star

The "smart merge" capability in pyem ensures that the particles are correctly associated, even if their order has been changed or some particles have been removed.

The final star file - from_csparc_with_coords.star in the example - can now be imported back into Relion, and used for extraction of refined particles or other processing.

There are many .star file merging features in star.py, which can be used to fill in other parameters aside from the micrograph coordinates. See star.py --help for details.

Add path for single-stack data

If a single particle stack (.mrcs) file was referenced in original_particles.star, for example for use with Frealign, then we'll also need the path to this single stack.

csparc2star.py --data-path /path/to/original_particle_stack.mrcs ...

Note that absolute paths will probably work, but it's better to keep the Relion convention and use relative paths only. For example, if this file is in Import/job005 in your Relion project directory, you'd use:

cd relion_project_directory
csparc2star.py --data-path Import/job005/original_particle_stack.mrcs ...

Understanding classification results

By default, particles are assigned to their maximum probability class.

Using --minphic T, particles with class membership probability less than the threshold T (a value between 0 and 1) will be dropped from the output.

Adding --keep-bad will assign these "low-confidence" particles to class 0, a dummy class incompatible with Relion, instead of dropping them from the output.

The default in cryoSPARC is different, and is equivalent to --minphic 0.9.

Why do Relion and cryoSPARC results look different?

2D

  • During 2D classification w/ alignment the angles, shifts and classifications from cryoSPARC are not used (only selected particles matter)
  • During 2D classification w/out alignment Relion uses the angles and shifts, but the selected particles may be different
  • By default, cryoSPARC ignores low-confidence particles in the output (same as csparc2star.py --minphic 0.9)
  • Relion marginalizes over poses, cryoSPARC does not (by default)
  • Relion makes full passes (by default), cryoSPARC uses minibatches
  • Relion and cryoSPARC use different default parameters (normalization strategy, circular mask sizes, sampling points, maximum resolution, etc.)
  • Both programs are non-reproducible (per-particle and volume outputs are not deterministic, even for the same random seed).

3D

  • Same points as above with respect to --minphic and particle selection
  • w/ global alignment, the input alignments are not used
  • w/ local alignment, symmetry mismatch may be an issue (e.g. half the orientations could be missing), double-check the symmetry group
  • In refinement, local searches are selected by setting the initial heal pix order to be equal to the order for local searches. In the GUI that is "global sampling N˚" and "local sampling N˚". Otherwise, previously determined angles and shifts are not used.
  • In 3D, Relion marginalizes over poses, cryoSPARC does not
  • Again, many parameter defaults differ, and may be impactful (initial resolution, as well as those mentioned above)
  • Relion and cryoSPARC use different priors over the 2D shifts - try re-rextract the particles using the refined centers from cryoSPARC
  • After re-extracting to recover particle shifts normally distributed around 0, the translational search radius and step size can/should be decreased
  • Reconstruct your particles directly with the known angles to validate angles and shifts, and to generate maps with absolute scale
  • Extra rounds of refinement after GSFSC convergence in cryoSPARC may improve the resolution or improve the Guinier plot. These can be done directly in cryoSPARC using "force extra final passes" in the advanced options.
  • However, at the true GSFSC limit, you will not be able to gain resolution in any program
  • cryoSPARC uses dynamic masking by default, while Relion uses either no mask, or a single, user-provided mask. Try starting Relion without a mask, and using a --continue command to add an (aligned) mask after a few iterations, or once local searches begin

Clone this wiki locally