~~NOTOC~~

===== sp_eval_isac =====
Separate Into Classes : Separates stacks of particle images into stacks for each class and evaluates results.

\\
===== Usage =====

Usage in command line (beta version):

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --align_isac_dir=isac_or_beautifier_dir --filtrad=filter_radius --apix=pixel_size --shrink=shrink_factor --ctf=ctf_mode --nvec=number_of_eigenimages --pca_radius=radius --chains_radius=radius --chains_exe=spchains_executable --applyparams=centering_mode --write_centered --debug --imgformat=image_format --verbosity=verbosity_level
  
  
\\
===== Typical usage =====
[{{ :pipeline:utilities:regular-evil-isac.png?275|Regular ISAC (top) vs. Evil ISAC (bottom)}}]
The purpose of sp_eval_isac.py is to: 
  : write particle-membership lists for each class
  : write separate stacks for each class, 
  : optionally low-pass filter and/or downsample the images, and
  : optionally compute eigenimages (basis images) for each class
\\ __1. Standard usage: create separate stacks for each class__:

  sp_eval_isac.py input_class_avgs output_directory 

\\ __2. Apply a low-pass filter to the image stacks__:

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --filt=filter_radius --apix=pixel_size

Filter radius is in units of Angstroms. If --apix is not specified, program will assume units of pixels^-1. 

\\ __3. Downsample output image stack__:

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --shrink=shrink_factor
  
\\ __4. Apply ISAC alignments to particles__:

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --align_isac_dir=isac_or_beautifier_directory
  
Alignments used by ISAC or beautification will be applied to the particles. In addition, the average and variance for each map will be written.

\\ __5. Compute eigenimages (basis images) for each class__:

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --align_isac_dir=isac_directory --nvec=number_of_eigenimages --pca_radius=radius
  
In addition to the average and variance, the requested number of eigenimages will be computed also. If --pca_radius is not provided, the whole image will be used to compute the eigenimages.

\\ __6. Apply centering to each class as determined by sp_center_2d3d.py__:

  sp_eval_isac.py input_class_avgs output_directory --particles=input_image_stack --align_isac_dir=isac_directory --write_centered --applyparams=centering_mode
  
If you ran sp_center_2d3d.py, you can also apply those centering parameters to the individual particles.  The --write_centered flag will write out the particles; omitting the flag will simply write out the alignment parameters without applying them. The options for --applyparams are 'intshifts' for integer shifts and no rotation (i.e., no interpolation) and 'combined' (rotation and shifts).

\\ __7. Apply a Gaussian band-pass filter to an image stack (e.g., class averages)__:[{{ :pipeline:utilities:plotbandpass.png?400|Shape of the band-pass filter}}]
  sp_eval_isac.py input_class_avgs output_directory --apix=pixel_size --bandpass_radius=bandpass_radius_angstroms

The default beautifier settings (CTF-correction using a Wiener filter and power-spectrum adjustment) will amplify the low-resolution data, and may make the averages more difficult to interpret. A band-pass filter will dampen the lowest-resolution data, and also the high-resolution noise. This filtration may be helpful for recognizing smaller complexes.

[{{pipeline:utilities:bandpass-example.png?400|(top) Beautified images and (bottom) band-pass filtered images, centered at 14 Angstroms}}]

\\
===== Input =====
=== Main Parameters ===
  ; input_class_avgs : Set of 2D class averages, with particle-membership information in header. (default required string)[{{ :pipeline:utilities:class084.png?400|Filtered, aligned particles of TcdA1 corresponding to class #9 below}}]
  ; output_directory : Directory where outputs will be written. (default required string)
  ; %%--%%particles : Particle image stack. (default required string)
  ; %%--%%filtrad : Gaussian low-pass filter radius, Angstroms if apix specified below, else pixels^-1. (default None)
  ; %%--%%apix : Angstroms per pixel, might be downsampled already by ISAC2. (default None)
  ; %%--%%shrink : Downsampling factor, e.g., 6 -> 1/6 original size. (default None)
  ; %%--%%align_isac_dir : If applying alignments, directory for ISAC output (default None)
  ; %%--%%nvec : Number of eigenimages to compute. (default None)
  ; %%--%%pca_radius : Radius (pixels) to use for computation of eigenimages. (default None)
  ; %%--%%ctf : Applies CTF correction: 'flip' for phase-flipping, 'wiener' for Wiener filter. (default None)
  ; %%--%%bandpass_radius : Radius for the center of the band-pass filter, Angstroms.
  ; %%--%%bandpass_width : Width of the band-pass filter, units absolute frequency (i.e., px^-1).
  ; %%--%%verbosity : Controls how much information to write to screen. (default 1)
  
\\
=== Advanced Parameters ===
  ; %%--%%chains_radius : Runs sp_chains.py internally to order input class averages. (default None)
  ; %%--%%chains_exe : Path for sp_chains.py if not the default. (default None)
  ; %%--%%imgformat : Format of optional output aligned-imaged stacks. (default .mrcs)
  ; %%--%%debug : Tests --applyparams=intshifts by applying rotation and integer shifts separately and computing average. (default False)

\\
===== Output =====
  ; classmap.txt : Class-to-particle lookup table, one file for all classes[{{ :pipeline:utilities:ave_eig75-84.png?400|For each class (from left to right): average, variance, and first 5 eigenimages}}]
  ; docclass???.txt : List of particles for each class, one file per class
  ; bdb:stkclass_??? : Virtual stacks of particles for each class
  ; bdb:stkflt_??? : (Optional) Virtual stacks of filtered particles for each class
  ; params_???.txt : (Optional) Particle alignment parameters, one file per class
  ; stkavgvar.hdf : (Optional) Montage of class averages and variances
  ; stkeigen.hdf : (Optional) Montage of class averages, variances, and eigenimages
 

\\

===== Description =====

\\
==== Method ====

\\
==== Reference ====

\\
==== Developer Notes ====
  : Should allow filter types other than Gaussian low-pass

\\
==== Author / Maintainer ====
Tapu Shaikh

\\
==== Keywords ====
Category 1:: APPLICATIONS

\\
==== Files ====
sphire/bin/sp_eval_isac.py

\\
==== See also ====

\\
==== Maturity ====
Beta:: Under evaluation and testing. Please let us know if there are any bugs.

\\
==== Bugs ====
There are no known bugs so far.

\\