== e2classextract ==
Provides various methods for extracting the particles associated with class-averages in various contexts. The program has 3 mutually exclusive modes for different purposes.

=== Command Line Arguments ===

==== refinemulti mode ====
|| ||--refinemulti||Extract particles based on model_id in header||
|| ||--excludebad||If provided, particles originally excluded from the class-average will be excluded from the extracted set||
|| ||--input_set||Normally the set used to create the class-averages is used as input. Use this with another version of the same set of particles, for example '__ctf_flip_proc' instead of '__ctf_flip'||
|| ||--setname||Name of the new set to generate||
|| ||--noderef||If specified, and the input particles were a .lst file, the output .lst will reference the input .lst, instead of referencing the original particles/* files directly||
|| ||--sort||If set, the output file will be sorted by particle number, otherwise the particles will be grouped by class-average||
==== classlist mode ====
|| ||--classlist||The name of a text file containing the image number of class-averages to include in the output set. One number per line.||
|| ||--excludebad||If provided, particles originally excluded from the class-average will be excluded from the extracted set||
|| ||--setname||Name of the new set to generate||
|| ||--noderef||If specified, and the input particles were a .lst file, the output .lst will reference the input .lst, instead of referencing the original particles/* files directly||
==== orientedparticles mode ====
|| ||--orientedparticles||The name of the set used in generating the specific set of class-averages||
|| ||--orientcls||The name of the classmx or cls_result file associated with the class-averages||
|| ||--evenoddmerge||Optional flag. If used, _even/odd should be omitted from the previous 2 options.||
==== General Options ====
||-h||--help||bool||show this help message and exit||
||-v||--verbose||int||verbose level [0-9], higner number means higher level of verboseness||


There are 3 mutually exclusive modes for this program:
 * --refinemulti - Extracts the particles associated with each of the output 3-D maps generated by an e2refinemulti run
 * --classlist - Extracts references to all of the particles in a user specified list of class numbers (the list of integers is in a text file)
 * --orientedparticles - Extracts rotated/translated particles associated with each class-average into a separate stack (also requires --orientcls)

==== Separate particles from a multi-model refinement ====
When e2refinemulti is run, the final product is multiple 3-D maps. However, it is generally advisable to re-refine the particles associated with each of these maps through a standard gold-standard refinement (e2refine_easy.py). While the particle separation is run automatically following the successful completion of a run of e2refinemulti.py, it can still be run manually in cases where the refinement is terminated early, or if you want to compare the results from earlier iterations (e2refinemulti outputs the particle separation from the final iteration only). 

==== Extract particles associated with a few specific class-averages ====
Generally this task is much easier to accomplish using the graphical tools in e2evalparticles.py. If something programmatic is required, however, this program can still be useful. To use this mode, you must create a text file containing a list of the image numbers of specific class-averages from a classes_XX file. The file should contain one number per line.

The output file will normally be a .lst file referencing the original particles, sorted by class-average. A few options for modifying this behavior are listed above. 

==== Oriented Particle extraction ====
Method 1:  only even or odd
This will extract particles for all of the even-particle class-averages in refine_08/classes_03_even.hdf. What you specify is a particle stack (normally a .lst file) and a classification matrix file, which contains the information on which particle is in which class and the orientation of each. There are several choices you can make here. First, you could specify any of the variants on the input particles, such as all__ctf_flip_even.lst instead of the _hp version, as long as the particle numbering matches the set actually used for the average.

You also have a choice on the classification matrix. When the particles are classified, the classification alignment is stored in classmx_xx_even.hdf. However, after class-averaging, the final 2-D alignments may have changed slightly. If you want to use these final alignments instead, you should use cls_result_xx_even.hdf instead.

e2classextract.py --orientedparticles sets/all__ctf_flip_hp_even.lst --orientcls refine_08/classmx_03_even.hdf  -v 2

will produce classptcl_XXXX.hdf files. Particles are in the same order they are in in the input .lst file, NOT sorted by quality. These stacks will include particles which were excluded (based on quality) from the final class-average.

Method 2: Merge even and odd particles for each class

In this method, you specify the names of the files up to the final _even or _odd, and all of the particles from both the even and odd sets from each class-average will be combined into a single stack. In this case the ordering will be the same as the input file, but all of the even particles will come first, followed by all of the odd particles.

e2classextract.py --orientedparticles sets/all__ctf_flip_hp --orientcls refine_08/cls_result_03 --evenoddmerge -v 2