'''Q:''' Explain the contents of the cls*.lst files, and how they relate to extracting individual oriented particles.

'''A:''' There is one of these files for each projection within a specific orientation. The results from each iteration are combined into a cls.#.tar file in case they are needed later. However, the same information is also present in the particle.log file (for all iterations).

LST files are basically text files containining

{{{
#LST
<img #>    <img path>    <comment>
...}}}
An alternate form of these files, which has been optimized with 'lstfast.py' is:

{{{
#LSX
# warning message
#<line length>
<img #>    <img path>    <comment><padding>
...}}}
EMAN will treat these files as if they actually contained the image they reference. That is, if you read image 0 from cls0005.lst, you will get whatever image is referenced on the first non-comment line in the file.

The next trick is the <comment> blocks. These comments can contain different things in different contexts, and in certain cases can actually override values stored in the referenced image's header. That is how the comments are used in cls*.lst files. A typical cls*.lst file will look like this:

{{{
#LST
0       proj.img
196     start.hed       496.53,  1.520236,-2.799,1.570,1
452     start.hed       497.05,  1.600393,3.648,-5.227,0
2198    start.hed       497.36,  0.049543,12.167,12.800,0
2755    start.hed       496.65,  1.511230,6.844,-2.461,0
...
}}}
The first image in a cls*.lst file is always a projection image (with no comment). This is the projection the individual particle images in this file should ostensibly look like, and is present in this file primarily because the image comparison utilities in the 'eman' browser can only look at images within a single file.

The individual particle images, as you can see, are always references to particular images within start.hed. Since the images in start.hed represent the original data (unaligned), the <comment> text contains the necessary parameters to align this particle 2-dimensionally to the reference. '''However, it is important to note that this may not be the final 2-D alignment used in the class-average !'''. These parameters represent the alignment that was done to achieve the classification of the particle. Normally, EMAN goes through a 2-D iterative process when making class averages, in which the particles are realigned to the average of the particles rather than to the original projection reference. This is an important step in eliminating or reducing model-bias during reconstruction. The final 2-D alignment parameters used in the class-average are not currently stored anywhere by default, so the parameters in the cls*lst file are typically the best you can do within the context of the normal 'refine' command.

Finally, the alignment parameters themselves:

{{{
<quality>,   <da>,<dx>,<dy>,<isflipped>
}}}
The 'quality' value is in arbitrary units. Larger is better, but comparing between particles from different frames may not be wise. da is the rotational alignment in radians. dx and dy are the translational alignments in pixels. isflipped indicates whether the image had to be flipped to produce a match. This is necessary because in EMAN1, projections are generated over only the unit hemisphere, not the full unit sphere. That is mirror-image projections are not generated, but instead, particles may be 'flipped' during alignment.

Here is a block of python code which will produce an aligned particle from a cls*.lst entry:

{{{
# EMAN/python/clstoaligned.py
from EMAN import *
from sys import argv
for fsp in argv[1:]:
        n=fileCount(fsp)[0]
        b=EMData()
        b.readImage(fsp,0)
        e=b.getEuler()
        a=EMData()
        for i in range(1,n):
                a.readImage(fsp,i)
                a.edgeNormalize()
                a.rotateAndTranslate()
                if a.isFlipped() :
                        a.hFlip()
                a.setRAlign(e)
                a.writeImage("aligned.spi",-1)
}}}
Note that this script simply reads in each particle using 'readImage' then proceeds to call 'rotateAndTranslate' on it. readImage will recognize the comment in the LST files and set the rotation/translation programs in the image automatically. Note, that the horizontal flip operation must be performed separately.