SUPOLAR - POLarization analysis of three-component data               

 supolar <stdin [optional parameters]                                  

 Required parameters:                                                  
    none                                                               

 Optional parameters:                                                  
    dt=(from header)  time sampling intervall in seconds               
    wl=0.1            correlation window length in seconds             
    win=boxcar        correlation window shape, choose "boxcar",     
                      "hanning", "bartlett", or "welsh
    file=polar        base of output file name(s)                      
    rl=1              1 = rectilinearity evaluating 2 eigenvalues,     
                      2, 3 = rectilinearity evaluating 3 eigenvalues   
    rlq=1.0           contrast parameter for rectilinearity            
    dir=1             1 = 3 components of direction of polarization    
                          (the only three-component output file)       
    tau=0             1 = global polarization parameter                
    ellip=0           1 = principal, subprincipal, and transverse      
                          ellipticities e21, e31, and e32              
    pln=0             1 = planarity measure                            
    f1=0              1 = flatness or oblateness coefficient           
    l1=0              1 = linearity coefficient                        
    amp=0             1 = amplitude parameters: instantaneous,         
                          quadratic, and eigenresultant ir, qr, and er 
    theta=0           1, 2, 3 = incidence angle of principal axis      
    phi=0             1, 2, 3 = horizontal azimuth of principal axis   
    angle=rad         unit of angles theta and phi, choose "rad",    
                      "deg", or "gon
    all=0             1, 2, 3 = set all output flags to that value     
    verbose=0         1 = echo additional information                  


 Notes:                                                                
    Three adjacent traces are considered as one three-component        
    dataset.                                                           
    Correct calculation of angles theta and phi requires the first of  
    these traces to be the vertical component, followed by the two     
    horizontal components (e.g. Z, N, E, or Z, inline, crossline).     
    Significant signal energy on Z is necessary to resolve the 180 deg 
    ambiguity of phi (options phi=2,3 only).                           

    Each calculated polarization attribute is written into its own     
    SU file. These files get the same base name (set with "file=")   
    and the parameter flag as an extension (e.g. polar.rl).            

    In case of a tapered correlation window, the window length wl may  
    have to be increased compared to the boxcar case, because of their 
    smaller effective widths (Bartlett, Hanning: 1/2, Welsh: 1/3).     

 Range of values:                                                      
    parameter     option  interval                                     
    rl            1, 2    0.0 ... 1.0   (1.0: linear polarization)     
    rl            3      -1.0 ... 1.0                                  
    tau, l1       1       0.0 ... 1.0   (1.0: linear polarization)     
    pln, f1       1       0.0 ... 1.0   (1.0: planar polarization)     
    e21, e31, e32 1       0.0 ... 1.0   (0.0: linear polarization)     
    theta         1      -pi/2... pi/2  rad                            
    theta         2, 3    0.0 ... pi/2  rad                            
    phi           1      -pi/2... pi/2  rad                            
    phi           2      -pi  ... pi    rad   (see notes above)        
    phi           3       0.0 ... 2 pi  rad   (see notes above)        



 
 Author: Nils Maercklin, 
         GeoForschungsZentrum (GFZ) Potsdam, Germany, 1998-2001.
         E-mail: nils@gfz-potsdam.de
 

 References:
    Jurkevics, A., 1988: Polarization analysis of three-component
       array data. Bulletin of the Seismological Society of America, 
       vol. 78, no. 5.
    Kanasewich, E. R., 1981: Time Sequence Analysis in Geophysics.
       The University of Alberta Press.
    Kanasewich, E. R., 1990: Seismic Noise Attenuation.
       Handbook of Geophysical Exploration, Pergamon Press, Oxford.
    Meyer, J. H. 1988: First Comparative Results of Integral and
       Instantaneous Polarization Attributes for Multicomponent Seismic
       Data. Institut Francais du Petrole.
    Press, W. H., Teukolsky, S. A., Vetterling, W. T., and Flannery, B. P.
       1996: Numerical Recipes in C - The Art of Scientific Computing.
       Cambridge University Press, Cambridge.
    Samson, J. C., 1973: Description of the Polarisation States of Vector
       Processes: Application to ULF Electromagnetic Fields.
       Geophysical Journal vol. 34, p. 403-419.
    Sheriff, R. E., 1991: Encyclopedic Dictionary of Exploration
       Geophysics. 3rd ed., Society of Exploration Geophysicists, Tulsa.

 Trace header fields accessed: ns, dt
 Trace header fields modified: none