Appion

h1. Helical Image Processing (PHOELIX)  (Not develop actively.  Use at your own risk)

h2. General Workflow:

# Make sure that the appropriate run name and directory tree are specified.  Appion increments names automatically, but users are free to specify proprietary names and directories.

# Enter the directory tree where the mandatory files are located.  These files include llbo.sa, strong.sa, range.sa, cutfit1.dek, cutfit2.dek, cutfit3.dek, chop1.dek, chop2.dek, and template. If you do not have these files already, complete the steps for [[Helical Image Processing (PHOELIX)#Running-PreHIP| Running preHIP]] and follow the guided protocol to generate them. 

# Enter a description of your run into the description box.

# Select the stack to process from the drop down menu.  Note that stacks can be identified in this menu by stack name, stack ID, and that the number of particles, pixel and box sizes are listed for each.

# Make sure that "Commit to Database" box is checked. (For test runs in which you do not wish to store results in the database this box can be unchecked.  This box is automatically deactivated when running preHIP).

# Enter the Filament Parameters or verify the default values. 

#* Number of Filament Segments - The number of particles to use in the run.

#* Repeat Length - (Helical Repeat) The 360 degree repeat distance along the filament, in Ångströms. Calculated in Fourier space by the distance to the first layer line or in real space by the distance it takes one subunit to travel 360°.

#* Subunits per Repeat - Number of subunits in one helical repeat. Determined by calculating (Helical Repeat/Rise) or finding the Layer Line with a J0 intercept.

#* Diameter - The approximate outer diameter of the filament, in Ångströms

#* Inner Diameter - The approximate inner diameter of the filament, in Ångströms.

# Enter the Processing Parameters or verify the default values.

#* Filament Segment Length - Desired length of the filament segments, usually a certain number of helical repeats, in pixels.  Should be the same as your stack box size.

#* Box Height - Height of the filament box after alignments, usually the power of 2 value greater than the filament diameter, in pixels.

#* Pad Value - Value to pad the filament box to during alignments, usually the power of 2 value greater than the filament length/box size.

#* Phase Residual Cutoff - Maximum phase residual for post averaging.  A phase residual is calculated between the layer lines from the template and the layer line from each filament segment.  Any files with phase residual above this cutoff will not be included in the final average, map, overplot, etc.

#* Filter Value - Lowpass filter value for filament segments used during alignments to find filament edges. 150-200 seems to work well, but should be tested using preHIP before processing the full stack

#* Binning - Binning of the particle images. This quickly shrinks the image to help make the processing faster.

#* Contrast Change - If your filament stack has black on white density, the final reconstruction will need a contrast change.

# Click on "Run HIP" to submit your job to the cluster. Alternatively, click on "Just Show Command" to obtain a command that can be pasted into a UNIX shell.

!http://emg.nysbc.org/attachments/959/hipwiki_fig1.png!

h2. Running PreHIP:

NOTE: Steps requiring user feedback/interaction are in BLUE, steps detailing what the program is doing are in GREEN, warning messages are in RED. 

After completing steps 1-7 in the [[Helical Image Processing (PHOELIX)#General-Workflow|General Workflow]] complete these additional steps:

# Click the "Run PreHIP" checkbox which will activate the indexing parameters below it and display a warning message.

# Fill in the Indexing Parameters.

#* N-fold - Order of the symmetry axis. Default is 1-fold for no symmetry.

#* Maximum Layer Line - Maximum layer line to include in the llbo.sa file.

#* Maximum Bessel Order - Maximum Bessel Order to include in the computation for llbo.sa.

# Select either the "Use rise and twist" or "Use layer line/bessel order" radio button which will activate the parameters below it. You can only choose one of these options, therefore the input parameter boxes under the non-selected option become deactivated.

#* Rise and Twist - Use the rise distance and twist angle between protein subunits to determine selection rule and generate llbo.sa file. Rise is the vertical distance between two subunits in the one-start helix and twist is the angle between two adjacent subunits.

#* (1,0),(0,1) LLBO - Use the layer line and Bessel Order for the (1,0) and (0,1) layer lines to determine selection rule and generate llbo.sa file.

# Click "Just Show Command" to generate the UNIX shell command.  Do NOT click "Run HIP", it will not run because the interactive GUI must be executed from a command line. 

# Note that the "Commit to Database" box is deactivated. preHIP is used only for generating the mandatory files and therefore the preliminary results are not stored to the database.

!http://emg.nysbc.org/attachments/962/hipwiki_fig2.png!

# Copy and paste the command into a UNIX shell.

!http://emg.nysbc.org/attachments/967/hipwiki_fig3.png!

# Review the llbo.sa file when it is displayed and either approve or reject the LLBO assignments. If you reject it, you have the option of either restarting preHIP with different rise/twist/helical repeat values or supplying your own llbo.sa (if you choose this option make sure it is in the proper format! You can use the failed llbo.sa as a reference.)

!http://emg.nysbc.org/attachments/970/hipwiki_fig4.png!

# Scroll through the files using the Tkir viewer to see if the filaments were centered properly (files with extension .s are raw files and .sbut are filtered).  When finished, close both Tkir windows.  Enter either "yes" or "no" after the prompt in the terminal.  If you enter "no", you will be prompted to enter a new filter value and the filaments will be recentered with this value.  Continue this process until you find a filter value that works. 

# All files are diffracted and summed together to find the strongest layer lines. Review the strong layer lines when they are displayed and either approve or reject them.  If they are not correct you have the option to change, remove, or add lines.  Follow the instructions as prompted until you are satisfied. 

!http://emg.nysbc.org/attachments/1003/hipwiki_fig5.png!

# The strong layer lines from step 9 are used to select ranges for out of plane tilt and shift correction. Review/adjust the ranges when they are displayed in the Tkll viewer. Right click to remove points, left click to add a point.  Each layer line can only have 2 points and they must be ordered 0-1. If you modify the file you must save it (File > Save Data > Ok), do not change the filename. Close the Tkll window. Be sure to evaluate each layer line file and choose the best one to use as a template in step 11.

!http://emg.nysbc.org/attachments/1004/hipwiki_fig6.png!

# Select the layer line file from the displayed list that you would like to use as a template for round 1 of averaging. Copy and paste the exact filename. Each subsequent round of averaging uses the previous round's average as the template. If you would like to use a different file as a template, make sure it has the same llbo combo as the current session, then enter the filename including the full directory path. 

# Select a few layer lines for the cutfit1.dek file, which is used during averaging for fitting and scaling to the template. Right click to remove points, left click to add a point. Each layer line can only have 2 points and they must be ordered 0-1. Save the file when  you are done, (File > Save Data > Ok), do not change the filename. Close the Tkll window. There are 3 iterations of fitting in each round of averaging. Repeat this process for cutfit2 and cutfit3, selecting a few more low-moderate resolution layer lines for each. 

!http://emg.nysbc.org/attachments/1006/hipwiki_fig7.png!

# Review/adjust chop1.dek and chop2.dek making sure the ranges are over the significant portion of each layer line, which is the area between the inner and outer radii of the helix. Sniffing searches a region around each predicted layer line location to find and extract the layer line with the lowest phase residual over the ranges specified here. Right click to remove points, left click to add a point. Each layer line can only have 2 points and they must be ordered 0-1. Every layer line needs a range, except for LL 0. Save the file when you are done, (File > Save Data > Ok), do not change the filename. Close the Tkll window.

!http://emg.nysbc.org/attachments/1007/hipwiki_fig8.png!

# When preHIP finishes it will delete all generated files except for the indexing files required for running HIP.  The final average will also be saved as "template" if you want to use it as the template for subsequent runs.  It will display the directory containing these mandatory files and the optimized filter value.