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
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.
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.
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.