XCORR(1)



NAME

     xcorr - strategy module to compute  cross  correlations  for
     time-distance analysis.


SYNOPSIS

     xcorr  [-cnvz] [-KFSM] [argument= value


DESCRIPTION

     xcorr computes temporal cross correlations for time-distance
     analysis.  Pairs of points are selected by their position in
     the solar image.

     Setting the verbose option (-v) results in more  information
     being  sent  to the standard output.  Unfortunately, this is
     mostly just a program progress report.

     Data filtering is controlled by arguments FPASS, FWIDTH, and
     flags  -F and -K.  The -F option suppresses filtering of the
     f-mode (note, the default F=0 means filter out the  f-mode).
     The  -K flag will result in a correction of the instrumental
     astigmatism  and  a  flattening  of  the  spatial  frequency
     response of the MDI instrument.

     The -S and -M flags control the form of the output.   Unless
     the  -S  flag  is set, the output will be sorted in order of
     increasing separation between cross correlated  points.   It
     is meaningless to set this flag when AZMUTH=0.0, as the out-
     put will always be sorted in this case.   Set  the  -M  flag
     when  using  the  DRANGE option if you want the full list of
     distances and directions to be output.  This  results  in  a
     lot of extra FITS files.


ARGUMENTS

     in=dataset
          The input dataset name.  The input dataset is  expected
          to  be  a  cube  such  as  output  by  strategy  module
          track_region (see man page) with map=cyleqa.  That  is,
          each  input  dataset  is  a  "data cube" with longitude
          along the fastest axis, sin(latitude)  along  the  next
          axis,  and  time  on  the slowest axis.  The dataset is
          assumed to include  in  its  ancillary  data  the  time
          between   consecutive  images  T_STEP,  the  number  of
          degrees per pixel at map canter MAPSCALE, and the lati-
          tude at map center in degrees HG_LAT.  NO DEFAULT

     out=dataset
          The output dataset name.  NO DEFAULT

     DIRECTION=string
          The target direction.  Possible options  are  north  or
          west.   In the first case, the pairs of pixels selected
          for cross correlation have the same or nearly the  same
          longitude.   In  the second case, they have the same or
          nearly the same latitude.  Default: north

     DTMAX=int
          The maximum correlation time ("lag") to be included  in
          the  output,  as  a  multiple  of  the interval between
          images. The default is the length  of  the  input  time
          series.   This  default  is  not  very intelligent; for
          example, when the input data spans several days.

     DMAX=real
          The maximum distance between pairs of points which  are
          to be cross correlated, in degrees.  By default this is
          the largest possible value that can be  computed  given
          the dimensions of the input cube.

     DMIN=real
          The minimum distance between pairs of points which  are
          to be cross correlated, in degrees.  (Default 0.0; note
          that the cross correlation of points separated by  zero
          distance is the autocorrelation.)

     DRANGE=real
          The range used in binning the  output.   If  0.0,  then
          there  is  one row in the output file for each combina-
          tion of  distance  separation  and  orientation.   When
          DRANGE  is  set, the cross correlations are averaged in
          distance.  Note that setting DRANGE to a non-zero value
          will  cancel  the  -S  flag  (the output will be sorted
          automatically).  (Default: 0.0)

     AZMUTH=real
          The maximum deviation,  in  degrees,  from  the  target
          direction.  The  default  is 0.0, which means that only
          those pairs of points which lie on the same parallel of
          latitude  (if  DIRECTION=west) or meridian of longitude
          (if DIRECTION=north) will  be  cross  correlated.  When
          AZMUTH  is  set to a larger value, more pairs of points
          will be cross correlated. (Default: 0.0)

     FPASS=real
          The input data is passed through a  high-pass  temporal
          filter  with gaussian rolloff before cross correlating.
          FPASS is the cutoff frequency for the default high-pass
          filter, in Hz.  (Default: 0.0017)

     FWIDTH=real
          The width of the gaussian rolloff on the high-pass tem-
          poral   filter,   as  a  fraction  of  FPASS.   setting
          FWIDTH=0.0 results in a square cutoff.  (Default: 0.1)



EXAMPLES

     xcorr                         -v                          -K
     in=prog:mdi,level:lev2,series:track_08h[3723],sel:[0]
     out=prog:mdi,level:lev2,series:rxcor_08h[3723],sel:[0-255]
     DMIN=0.0 DMAX=10.0 AZMUTH=10.0 DRANGE=0.25

     In this case, assume the input is a 256x256x480 cube of data
     (created  by  track_region  with map=cyleqa).  There will be
     256 output files, one for each latitude in the input cube.



SEE ALSO

       track_region


DIAGNOSTICS

     soi_errno is returned and also set as the abortflg value  in
     the results keylist.


BUGS

     The approximation (used in the f-mode  filter)  for  the  p1
     ridge  is a polynomial fit and is probably not very good for
     l > 1500.

     The filtering performed under the -K option is not very well
     tested  on  other  than MDI data and in any case is probably
     only appropriate for other instruments.


AUTHOR

     Peter Giles           pgiles@solar.stanford.edu