Additional Information on DISTL/Spotfinder Options

Please see the Newsletter Article for complete details. The purpose of this page is to give a quick summary sheet of the command line options in the current release, showing how they relate to the original SSRL distribution, as well as the internal source code variables.

usage:   distl.signal_strength image_filename [parameter=value ...]
example: distl.signal_strength lysozyme_001.img distl.res.outer=2.0 distl.res.inner=6.0 distl.minimum_spot_area=8

Detailed list of command line options

Command line option & Default Description Legacy flag libdistl variable
distl.image=None Image file name    
distl.res.outer=None High resolution limit in angstroms    
distl.res.inner=None Low resolution limit in angstroms    
distl.verbose=False Lengthy spot printout    
distl.minimum_spot_area=None Override application default (PADs:5, others:10) and set minimum spot area (in pixels) within spotfinder. -s2, -s3 The two corresponding variables (spotarealowcut and spotbasesize) are both set to the value
distl.minimum_signal_height=None Override application default (PADs:2.5, CCDs:1.5) and set minimum signal height (in units of background noise sigma) within spotfinder. -bg0, -bg1, -bg2 bgupperint[0],bgupperint[1],bgupperint[2] are all set to the value.
distl.minimum_spot_height=None Expert use only; after pixels are classified as signals rather than noise, minimum height to be considered a spot maximum (in units of background noise sigma). Default=3.5 -d1 difflowerint
distl.spot_area_maximum_factor=None Expert use only; max spot area expressed as a multiple of minimum_spot_area. Default=5.0 -s7 spotareamaxfactor
distl.peak_intensity_maximum_factor=None Expert use only; peak intensity filter used by libdistl. Default=10.0 -s8 spotpeakintmaxfactor
distl.scanbox_windows=101,51,51 Expert use only; Integer scanbox sizes (for calculating background) for cycles 1, 2, and 3, respectively. The program defaults are 101, 51, and 51 pixels; square boxes have this number of pixels on an edge. -bx0, -bx1, -bx2 scanboxsize
distl.peripheral_margin=20 No spot detection within a peripheral margin of this width (in pixels) imgmargin
distl.pdf_output=None File name for optional PDF graphical output for distl.signal_strength (*.pdf). Requires PHENIX. pink=max_pixel; red=center_of_mass    
distl.image_viewer=False Start up the interactive image viewer to see the spotfinder chosen spots.    
distl.bins.verbose=False Additional printout binned by resolution range.    
distl.bins.N=20 Maximum number of bins, but fewer can result if there are few spots.    
distl.bins.corner=True Extend the binning all the way to detector corner, otherwise to outermost spot on first image.    
distl.port=8125 For the server version, port number to listen for requests    
distl.processors=1 For the multithreaded server version, number of server processes to be used    

Resolution-binned table output

Verbose analysis of spots, broken down by resolution bin, can be obtained by adding the following command line options:

 distl.signal_strength distl.bins.verbose=True distl.bins.N=[number of bins] /home/data/user/PI09_1_E1_001.img
The following information is tabulated in the verbose output:
Limit The outer edge of the (equal-volume) resolution shell (Angstroms).
Population The number of spots in each resolution shell.
Missing The fraction of that resolution shell that would be recorded by a 360-degree rotation, accounting for the missing cone.
Fract The fraction of that resolution shell recorded on an image, accounting for resolution shells that are geometrically outside the detector edge, but are recorded in the detector corners.
PxlBkgrd The mean pixel background at center of the scanbox windows in each resolution shell.
MnWndwSz The mean scanbox window size in square pixels after discarding pixels classified as signals (such as Bragg spots).
Integrated The total integrated signal (for all spots) within the shell in analog-digital units above background.
MeanI The mean integrated signal for spots within the shell.
MeanBkg The mean integrated background for spots within the shell.
MeanSz The mean number of pixels for spots within the shell.
MeanIsigI The mean[I / sig(I)] for spots within the shell. Sigma is defined as sqrt(variance) with variance being the variance in I + variance in Bkg + variance in the WndwSz pixels used to compute background. Variances add in quadrature as in Acta Cryst D55, p 1696 eq. 9 (Andrew Leslie) and the gain is taken as 1.0.
MnEccen The mean eccentricity for spots within the shell; 0=circle, 1=parabola.
MnSkew The mean skewness for spots within the shell; skew:= (maximum-center_of_gravity)/semimajor_axis.

Example text output is:

Analysis of spots after ice removal, but prior to resolution cutoff, for image PI09_1_E1_001.img:
Limit  Population  Missing  Fract  PxlBkgrd  MnWndwSz  Integrated  MeanI  MeanBkg  MeanSz  MeanIsigI  MnEccen  MnSkew 
 2.33         871     0.99   1.00     104.0       597     5986386   6873   7991.0      67     37.906    0.825   0.206 
 1.85          53     0.97   1.00      67.9       582       42144    795   2618.4      37     11.831    0.842   0.230 
 1.61          44     0.95   0.40      56.4       696        5752    131    728.7      13      4.267    0.847   0.258 
 1.47           7     0.94   0.14      53.9       618         436     62    648.2      12      2.304    0.813   0.227 
        ----------                                      ----------                                                    
              975                                         6034717   6189   7318.5      63     34.715    0.826   0.210 

Analysis of spots after resolution filtering, but prior to spot quality heuristics, for image PI09_1_E1_001.img:
Limit  Population  Missing  Fract  PxlBkgrd  MnWndwSz  Integrated  MeanI  MeanBkg  MeanSz  MeanIsigI  MnEccen  MnSkew 
 2.33         648     0.99   1.00     104.0       597     5495315   8480   8802.3      71     44.186    0.814   0.202 
        ----------                                      ----------                                                    
              648                                         5495315   8480   8802.3      71     44.186    0.814   0.202 

Analysis of good Bragg spots after quality heuristics, for image PI09_1_E1_001.img:
Limit  Population  Missing  Fract  PxlBkgrd  MnWndwSz  Integrated  MeanI  MeanBkg  MeanSz  MeanIsigI  MnEccen  MnSkew 
 2.33         312     0.99   1.00     104.0       597     2529932   8109   6271.6      50     45.496    0.753   0.137 
        ----------                                      ----------                                                    
              312                                         2529932   8109   6271.6      50     45.496    0.753   0.137 

                     File : PI09_1_E1_001.img
               Spot Total :    986
               Remove Ice :    975
      In-Resolution Total :    648
    Good Bragg Candidates :    312
                Ice Rings :      0
      Method 1 Resolution :   2.24
      Method 2 Resolution :   3.41
        Maximum unit cell :  272.1
<Spot model eccentricity> :   0.762 
%Saturation, Top 50 Peaks :   4.32
In-Resolution Ovrld Spots :      0

Bin population cutoff for method 2 resolution: 20%

Number of focus spots on image #1 within the input resolution range: 648
Total integrated signal, pixel-ADC units above local background (just the good Bragg candidates) 2529931
Signals range from 234.2 to 228761.6 with mean integrated signal 8480.4
Saturations range from 0.0% to 13.6% with mean saturation 0.5%

Even more command line options

As of 19 July 2011, the following additional options can be included on the distl.signal_strength command line:
Command line option & Default Description Expert level
autoindex_override_beam=None x and y coordinates of the direct beam in mm (two values separated by comma). Basic
autoindex_override_distance=None Crystal-to-detector distance in mm. Basic
autoindex_override_wavelength=None Incident wavelength in Angstroms. Basic
autoindex_override_twotheta=None Detector swing angle in degrees. Basic
autoindex_override_deltaphi=None Single-shot rotation angle in degrees. Basic
image_specific_osc_start=None A Python lambda x expression giving the rotation in degrees, given the image number; for example "lambda x: x-1.0" signifies 0 degrees for image 1; 1 degree for image 2, etc. Basic
wedgelimit=2 Maximum number of images to use for Labelit indexing [does not affect Spotfinder directly]. Advanced
spotfinder_verbose=True Set Spotfinder to print software development messages. Advanced
tnear_resolution_divisor=5 Control of the cutoff for determination of resolution by Method 2. A lower value (1.1) makes a more stringent cutoff, so the outer resolution cutoff is at a higher d-spacing (lower resolution). A higher value (10) is more permissive and allows higher resolution Bragg spots, but can cause Labelit indexing failure in some cases. Advanced
force_method2_resolution_limit=None Override the normal Method 2 resolution analysis based on the falloff of spot count. Force spots to be chosen to this limit (Angstroms). Advanced
distl_binned_image_spot_size=4 Special case; hardcoded algorithm. For CCD-based area detectors with large pixel count (>4000-squared); images are binned 2x2 in software prior to spot analysis, and minimum spot area set to this number of binned pixels. Advanced
distl_profile_bumpiness=2 Maximum number of local maxima permitted in good Bragg spots. It is necessary to set this parameter higher for home-lab sources with double-focusing mirrors. Contact authors with questions. Advanced
distl_permit_binning=True Permit 2x2 binning for large images (>4000 pixels-squared). Advanced
distl_force_binning=False Force 2x2 binning for all images; only used for development and troubleshooting. Advanced
codecamp.maxcell=None Directly specify the maximum unit cell (based on previous knowledge of the molecule); new algorithm to permit Labelit indexing on contiguous images. Advanced
codecamp.minimum_spot_count=None For determining spot masks on single images, minimum allowable spot count. Advanced