= Name =
sxcter - CTF Estimation: Automated estimation of CTF parameters with error assessment.

= Usage =

''usage in command line''

sxcter.py  input_image_path  output_directory  --selection_list=selection_list  --wn=CTF_WINDOW_SIZE --apix=PIXEL_SIZE  --Cs=CS  --voltage=VOLTAGE  --ac=AMP_CONTRAST  --f_start=FREA_START  --f_stop=FREQ_STOP  --kboot=KBOOT  --overlap_x=OVERLAP_X  --overlap_y=OVERLAP_Y  --edge_x=EDGE_X  --edge_y=EDGE_Y  --set_ctf_header  --check_consistency  --stack_mode  --debug_mode  --vpp  --pap


=== Typical usage ===

sxcter exists in for both MPI and non-MPI versions (Running MPI version does not require --MPI flag). 

    All Micrographs Mode - Process all micrographs in a directory:: Specify a list of input micrographs using a wild card (*), called here input micrographs path pattern. Use the wild card to indicate the place of variable part of the file names (e.g. serial number, time stamp, and etc). Running from the command line requires enclosing the string by single quotes (') or double quotes ("). sxgui.py will automatically adds single quotes to the string. BDB files can not be selected as input micrographs. Then, specify output directory where all outputs should be saved. In this mode, all micrographs matching the path pattern will be processed.

    ''' mpirun -np 16 sxcter.py './mic*.hdf' outdir_cter --wn=512 --apix=2.29 --Cs=2.0 --voltage=300 --ac=10.0 ''' <<BR>><<BR>>

    Selected Micrographs Mode - Process all micrographs in a selection list file:: In addition to input micrographs path pattern and output directry arguments, specify a name of micrograph selection list text file using --selection_list option (e.g. output of sxgui_unblur.py or sxgui_cter.py). The file extension must be ".txt". In this mode, only micrographs in the selection list which matches the file name part of the pattern (ignoring the directory paths) will be processed. If a micrograph name in the selection list does not exists in the directory specified by the micrograph path pattern, processing of the micrograph will be skipped.

    ''' mpirun -np 16 sxcter.py './mic*.hdf' outdir_cter --selection_list=mic_list.txt --wn=512 --apix=2.29 --Cs=2.0 --voltage=300 --ac=10.0 ''' <<BR>><<BR>>

    Single Micrograph Mode - Process a single micrograph:: In addition to input micrographs path pattern and output directry arguments, specify a single micrograph name using --selection_list option. In this mode, only the specified single micrograph will be processed. If this micrograph name does not matches the file name part of the pattern (ignoring the directory paths), the process will exit without processing it. If this micrograph name matches the file name part of the pattern but does not exists in the directory which specified by the micrograph path pattern, again the process will exit without processing it. Use single processor for this mode.

    ''' sxcter.py './mic*.hdf' outdir_cter --selection_list=mic0.hdf --wn=512 --apix=2.29 --Cs=2.0 --voltage=300 --ac=10.0 ''' <<BR>><<BR>>

    Stack Mode - Process a particle stack (Not supported by SPHIRE GUI)):: Use --stack_mode option, then specify the path of particle stack file (without wild card "*") and output directory as arguments. This mode ignores --selection_list, --wn --overlap_x, --overlap_y, --edge_x, and --edge_y options. Use single processor for this mode. Not supported by SPHIRE GUI (sxgui.py). 

    ''' sxcter.py bdb:stack outdir_cter --apix=2.29 --Cs=2.0 --voltage=300 --ac=10.0 --stack_mode ''' <<BR>><<BR>>

== Input ==
    input_image_path:: Input micrograph path pattern: Specify input micrographs path pattern with a wild card (*) for any of Micrograph Modes. Images of BDB format can not be used as input micrographs. As an advanced option, a particle stack file path can also be supplied here when using --stack_mode. However, Stack Mode is not supported by sxgui. (default required string)

    selection_list:: Micrograph selecting list: Specify path of a micrograph selection list text file for Selected Micrographs Mode. The file extension must be '.txt'. Alternatively, the file name of a single micrograph can be specified for Single Micrograph Mode. (default none)
    wn:: CTF window size [pixels]: The size should be slightly larger than particle box size. This will be ignored in Stack Mode. (default 512)
    apix:: Pixel size [A/Pixels]: The pixel size of input micrograph(s) or images in input particle stack. (default -1.0)
    Cs:: Microscope spherical aberration (Cs) [mm]: The spherical aberration (Cs) of microscope used for imaging. (default 2.0)
    voltage:: Microscope voltage [kV]: The acceleration voltage of microscope used for imaging. (default 300.0)
    ac:: Amplitude contrast [%]: The typical amplitude contrast is in the range of 7% - 14%. The value mainly depends on the thickness of the ice embedding the particles. (default 10.0)
    f_start:: Lowest frequency [1/A]: Lowest frequency to be considered in the CTF estimation. Determined automatically by default. (default -1.0)
    f_stop:: Highest frequency [1/A]: Highest frequency to be considered in the CTF estimation. Determined automatically by default. (default -1.0)

    * The remaining parameters are optional.
    kboot:: Number of CTF estimates per micrograph: Used for error assessment. (default 16)
    overlap_x:: X overlap [%]: Overlap between the windows in the x direction. This will be ignored in Stack Mode. (default 50)
    overlap_y:: Y overlap [%]: Overlap between the windows in the y direction. This will be ignored in Stack Mode. (default 50)
    edge_x:: Edge x [pixels]: Defines the edge of the tiling area in the x direction. Normally it does not need to be modified. This will be ignored in Stack Mode. (default 0)
    edge_y:: Edge y [pixels]: Defines the edge of the tiling area in the y direction. Normally it does not need to be modified. This will be ignored in Stack Mode. (default 0)
    set_ctf_header:: Export CTF parameters to header: Exports the estimated CTF parameters to the image header. (default False)
    check_consistency:: Check consistency of inputs: Create a text file containing the list of inconsistent Micrograph ID entries (i.e. inconsist_mic_list_file.txt). (default False)
    stack_mode:: Use stack mode: Use a stack as the input. Please set the file path of a stack as the first argument and output directory for the second argument. This is advanced option. Not supported by sxgui. (default False)
    debug_mode:: Enable debug mode: Print out debug information. (default False)
    vpp:: Estimate amplitude contrast: UNDER DEVELOPMENT! Also estimate phase shift as amplitude contrast. Use this option to estimate phase shift induced by Volta Phase Plate imaging. (default False)
    pap:: Use amplitude : UNDER DEVELOPMENT! Use amplitude for CTF parameter search instead of power spectrum. (default False)

== Output ==
    output_directory:: Output directory: The CTF parameters (partres file), rotationally averaged power spectra (rotinf), and micrograph thumbnails (thumb files) will be written here. This directory will be created automatically and it must not exist previously. (default required string)


After successful execution, sxcter will create in the output_directory: 

 1. A CTF parameters file, written to ''partres.txt''<<BR>><<BR>>
 2. A list of rotationally averaged power spectra, written to ''pwrot/*_rotinf.txt''.<<BR>><<BR>>
 3. A collection of micrographs Thumbnails (512 x 512 pixels), written to ''micthumb/*_thumb.hdf''.<<BR>><<BR>>


The CTF parameter file, ''partres.txt'', contains 18 columns with the following information:<<BR>><<BR>>

|| Column || Parameter ||
|| 1 || Image defocus [um] ||
|| 2 || Microscope spherical aberration [mm] ||
|| 3 || Microscope voltage [kV] ||
|| 4 || Pixel size [A] ||
|| 5 || B-factor [A^2] ||
|| 6 || Amplitude contrast [%] ||
|| 7 || Astigmatism amplitude [um] ||
|| 8 || Astigmatism angle [degrees] ||
|| 9 || Standard deviation of defocus [um] ||
|| 10 || Standard deviation of amplitude contrast [%] ||
|| 11 || Standard deviation of astigmatism amplitude [um] ||
|| 12 || Standard deviation of astigmatism angle [degrees] ||
|| 13 || Coefficient of variation of defocus [um] ||
|| 14 || Coefficient of variation of astigmatism amplitude [um] ||
|| 15 || Mean difference between the experimental rotational averages calculated with and without considering astigmatism. The subtraction is only performed at frequencies where the CTF model has a local minimum or maximum. ||
|| 16 || Frequency at which the signal drops by 50% due to estimated error of defocus alone [1/A] ||
|| 17 || Frequency at which the signal drops by 50% due to estimated error of defocus and astigmatism [1/A] ||
|| 18 || Frequency at which the CTF oscillation can no longer be modelled correctly due the pixel size of the image [1/A] ||
|| 19 || Micrograph name ||

<<BR>><<BR>>
The rotationally averaged power spectra or amplitude (rotinf.txt files) will be written to the pwrot directory. These files contain 6 columns with the following information:<<BR>><<BR>>


|| Column || Parameter ||
|| 1 || Line number ||
|| 2 || Spatial frequency [1/A] ||
|| 3 || Experimental rotational average without considering astigmatism ||
|| 4 || Fitted rotational average without considering astigmatism ||
|| 5 || Experimental rotational average including astigmatism ||
|| 6 || Fitted rotational average including astigmatism ||


== Description ==

''''This is work in progress since 11/30/2013''''


== Author / Maintainer ==
Pawel A. Penczek and Toshio Moriya


=== Attachments ===
80S ribosome determined using 35,198 projection images collected with a 300 kV Tecnai Polara (FEI) equipped with the K2 Summit DED camera.  Resolution of the the large subunit is 3.84 Å (using FSC with 0.5 cut-off criterion). [[attachment:80SK2.mrc.gz]] ('''Warning''': file size is 21MB.)


== Keywords ==
    category 1:: APPLICATIONS


== Files ==
sparx/bin/sxcter.py

=== See also ===
[[http://sparx-em.org/sparxwiki/sxgui_cter|sxgui_cter]], [[http://sparx-em.org/sparxwiki/sxwindow|sxwindow]]

=== Maturity ===
    beta::     works for author, often works for others.

=== Bugs ===
Fixed most of the bugs thus far.
