Getting Started - CLI

After installing ASPIRE, the module can be invoked as a script, allowing you to perform several actions on a stack of CRYO projections (MRC files).

aspire <command>

Running the aspire module as a script allows one to run different stages of the cryo-EM data pipeline. Substitute <command> with one of the available aspire commands. Use aspire --help to display all available commands and aspire <command> --help to display configurable options for a particular <command>.

Currently, the following operations can be run with ASPIRE:

1. Particle-Picking

The apple command takes in a file or folder of one or more *.mrc files, picks particles using the Apple-Picker algorithm described at [HAndenS18], and generates *.star files, one for each *.mrc file processed, at an output folder location.

For example, to run the command on sample data included in ASPIRE (a single sample.mrc file provided from the 5.3 GB Beta-galactosidase Falcon-II micrographs EMPIAR dataset) and save results to a particles folder:

mkdir apple_output
aspire apple --mrc_path /path/to/aspire/data/sample.mrc --output_dir particles

2. Particle Extraction

Given a dataset of full micrographs (*.mrc file) and corresponding coordinate files containing the locations of picked particles in the *.mrc, the extract-particles command extracts the particles into one or more .mrcs stacks and generates a .star file.

Example usage:

aspire extract-particles --mrc_paths=my/data/sample.mrc --coord_paths=my/data/coords/sample.coord --starfile_out=my_dataset_stack.star --particle_size=256 --centers

3. Estimate Contrast Transfer Function

The estimate-ctf command estimates the CTF from experimental data and saves the CTF as an .mrc file. For example,

aspire estimate-ctf --data_folder path_to_input_data_folder

Note

This command expects data files are in the directory prescribed by --data_folder, and will process all files with the extension .mrc and .mrcs contained there. This command will output .mrc files to a --output_dir (./results by default).

4. Image Preprocessing

The preprocess command takes in a *.star file representing particle stacks and applies a selection of preprocessing methods such as phase flipping, downsampling, normalization to background noise, noise whitening, and contrast inversion. Resulting images are saved as a starfile.

For example, to run the command on sample data included in ASPIRE:

aspire preprocess --starfile_in path/to/aspire/data/sample_relion_data.star --starfile_out preprocess_output.star --downsample 8

5. Image Denoising

The denoise command takes in a *.star file, downsamples the images (*.mrcs files) found in the starfile to a desired resolution, then estimates the noise of the images and whitens that noise using the covariance Weiner filtering method. The denoised images (*.mrcs) and a corresponding starfile are saved in an output folder.

For example, to run the command on sample data included in ASPIRE:

mkdir denoise_output
aspire denoise --starfile_in path/to/aspire/data/sample_relion_data.star --starfile_out denoise_output/denoised_images.star

6. Orientation Estimation

The orient3d command takes in a *.star file contaning images and performs an orientation estimation using the common lines algorithm employing synchronization and voting described at [SS12]. The estimated rotations are saved in a starfile along with the original images.

For example, to run the command on sample data included in ASPIRE:

aspire orient3d --starfile_in path/to/aspire/data/sample_relion_data.star --starfile_out orient3d_output.star

7. Reconstructing a mean volume with covariance

The cov3d command takes in a *.star file, processes the images (*.mrcs files) found in the starfile, and runs the ASPIRE pipeline to determine the estimated mean volume and estimated covariance on the mean volume. No results are saved currently, but this command is a good way to exercise most parts of the ASPIRE pipeline.

For example, to run the command on a sample data included in ASPIRE:

aspire cov3d --starfile /path/to/aspire/data/sample_relion_data.star --pixel_size 1.338 --max_resolution 8 --cg_tol 0.2

Note

Pay special attention to the flags specified in the example above. The --max_resolution 8 flag down-samples images to 8x8 pixels (needed otherwise you may run out of memory, and/or the script may take way too long to execute). --cg_tol 0.2 sets very liberal (and unrealistic) limits on optimization convergence tolerance, which is needed for such a small dataset. For real datasets, you typically do not want to override this parameter.

Arguments, options and flags

  • Arguments are mandatory inputs.

    For example, when running ‘compare’ command, you must provide 2 MRC files to compare.

  • Options are, like their name suggests, optional inputs.

    For example, aspire accepts option ‘-v 2’ for setting verbosity level to 2. All options have a default value set for them.

  • Flags are optional values which tells Aspire to activate/deactivate certain behaviour.
    A good example would be ‘-\-debug’.
    All flags also have a default value pre-set for them, ‘-\-no-debug’ in case of the debug flag.

Aspire CLI is built in levels. A level is basically a command which can be followed by another command. The most basic command is aspire itself, the base layer. It accepts its own flags such as ‘-\-help’, ‘-\-debug’ or ‘-v N’. Each of those optional flags will be directed into the preceding level.

Then we can call aspire with a command such as compare, and provide another layer of arguments, options and flags. For example, in case of compare these can be:

$ aspire -v 2 --debug compare  a.mrc  b.mrc --max-error=0.123
[HAndenS18]

Ayelet Heimowitz, Joakim Andén, and Amit Singer. APPLE picker: automatic particle picking, a low-effort cryo-em framework. CoRR, 2018. URL: http://arxiv.org/abs/1802.00469, arXiv:1802.00469.

[SS12]

Yoel Shkolnisky and Amit Singer. Viewing direction estimation in cryo-em using synchronization. SIAM J. Imaging Sci., 5(3):1088–1110, 2012. URL: https://doi.org/10.1137/120863642, doi:10.1137/120863642.

[SS11]

Amit Singer and Yoel Shkolnisky. Three-dimensional structure determination from common lines in cryo-em by eigenvectors and semidefinite programming. SIAM J. Imaging Sciences, 4(2):543–572, 2011. URL: https://doi.org/10.1137/090767777, doi:10.1137/090767777.