28.4 Catalogue merging and comparison with merge_seisan.pl

This program was provided by Frederik Tilmann, (tilmann at gfz-potsdam.de) (c) 2002-2011.

merge_seisan.pl is a `swiss-army knife' command line tool for catalogue merging and comparison. Unlike ASSO and ASSOCIATE, it operates always on two catalogues (either a catalogue file or extracted from the database). Its uses are

Usage: merge_seisan.pl [options] cat1 cat2 > out.nor

Usage: merge_seisan.pl [options] cat1 cat2 > out.nor

Reads two CAT Files or Sfiles in nordic format and associates events,
merging the information and respective files.  Merged events have information
from both files interspersed. Both files must be sorted.  Also each event
of the first set can only be associated with at most one event of the second set,
and vice versa.

cat1 and cat2 can be one of the following:

<file.nor>    The filename of a file in Nordic format

DBASE         If cat1 is three to five letters long and a file of the same 
              name does not exist the corresponding catalogues is created on 
              the fly from the S-files in the respectiv database. If the code
	      DBASE or D is used, use the current database

-             read from standard in (only one - is allowed, of course)


Method of association:

-I            associate events by ID (default)
-T=tol        associate events within (tol) s of each other

-D=<dist>[h]  Maximum epicentral distance in km. If h is appended then the hypocentral
              distance is used instead.

-D can be combined with -T but cannot be used on its own (both conditions need to be fulfilled).
 It also cannot be used with -I option

Output control

-S=I,-i     Only output associated events (Intersection)

-S=U,-u     Output all events (Union)

-S=A        Output only events in A (only makes sense when combined with -b or -B option)
-S=B        Ouptut only events in B

-S=~A       Output only events not in A (i.e. only in B, only makes sense with -B option)
-S=~B       Output only events not in B (i.e. only in A, only makes sense with -A option)

-s          Show different sets side-by-side (split screen)

-A          For associated events, only show event from first set
-B          For associated events, only show event from second set

-b=1,2,m    For associated events, take all header lines of the type listed from second 
            set, all other headerlines from first set (implies -A).  If the second set 
            does not have the required headerline, they will not be included in the output
            (i.e., specified header lines will never be taken from first set if there is 
            an event association) 

            1...9,F,E,I,H :  the corresponding header lines (Note that line type 4 refers
                             to phase pick lines, even if they have a blank in column 80
            o:            :  Origin time (from type 1 line only)
            e:            :  Epicentral coordinates (from type 1 only)
            d:            :  Depth (from type 1 line only)
            m             :  copy all magnitude information into header line
            mW,mL,mb,mS   :  only copy designated magnitudes (note that magnitudes are copied
                             into the same slot unless option -M is set

-a=1,2,..   Like -b, but copy information from first set to 2nd set, implies -B (not 
            implemented yet)

-m=1,2,..   Like -b, but add header lines to existing header lines, effectively merging
            the information in both files. Other header lines are taken from A (implies -A).

-M          Find named slot for copied magnitudes (only relevant if -b={mW,ML,mb,mS} is set
            Both type and agency need to match; otherwise the first empty slot is occupied, or
            the last slot is overwritten)

-d=xyz      Plot differences in hypocentre (in km) (loc2-loc1)
-d=gmt      Plot differences in epicentre as gmt-style multi-segment file (for input into psxy)
-d=gmtd     Plot differences in hypocentre as gmt-style multi-segment file.  This is similar
            to the output of -d=gmt, but insted of just latitude and longitude include latitude,
            longitude and depth (for pre-processing with awk before passing to psxy)
            Calculate bias vector between the two sets (i.e. the vector that needs to be
            added to loc1 locations to make them coincide with loc2 locations on average). 
            The calculation weighs pairings according to their horizontal errors and an error
            estimate is provided for the resulting bias vector.  For combined error estimates 
            less than 1 km (or <minerr>) if set, the weighing is applied assuming the error 
            is 1 km (minerr).   The calculation assumes the area of interest is small such 
            that all calculations ignore spherical geometry.  The average latitude of the 
            events is used to determine the latitude for the spherical to Cartesian 

            Example Output (actual output without line number)

            1 Bias (set B - set A) #eq: 58 
            2 (Lon,Lat,Dep) = (  0.01,  0.04, -8.21 )
            3 (R,THETA,Z)   = ( 4.427799,  19.4, -8.209310 )
            4 (X,Y,Z) (km)  = ( 1.470831, 4.176369, -8.209310 )
            5 (EX,EY,EZ)    = ( 0.147675, 0.159429, 0.339260 )
            6 CXX,CXY,CXZ,CYY,CYZ,CZZ = 0.0218079551088708, -0.000638279192795213, 
                           -0.000749725773138676, 0.0254174912655165, 0.00139172909726588, 
            7 96.1097639008737 2.39858930837142 1.47083143290329 4.17636917834104 
                            0.0897062757410673 0.0968460018196738 -0.0271104591760068

            2 Average shift of events in B with associated events in A in deg latitude, deg 
              longitude and depth (km)
            3 As line 2, but horizontal shift is expressed in terms of a distance R (km)and 
              a direction theta (deg)
            4 As line 2, but horizontal distances expressed in km rather than degree
            5 Formal errors of the mean shift in km. Note that this is the error of the mean
              and not the standard deviation.
              The formal location errors and covariance matrices of the catalogue events are 
              taken into account in this calculation 
            6 Input line for gmt commandpsvelo.  psvelo expects errors to be specified for 
              68% confidence intervals.
              If covariances are given for a different confidence interval, then they are 
              divided by covscale prior to working out the quantities for psvelo (the error 
              and covariance output lines are always left unchanged).  You can use the 
              following table:

            Input file 
            Confidence    covscale
            68%           1.0
            90%           2.71    [ Value for NEIC and JHD Oxford ]
            95.4%         4.0
            99%           6.63
            99.73%        9.00

            [Defaults: minerr=1.0 ; covscale=2.71 (Native Confidence Interval 90%)]

 Note: all -d options require -i option

Author: F. Tilmann (tilmann at gfz-potsdam.de)  (c) 2002-2011


  1. merge_seisan.pl -s -S=U -T=4 -D=50 cat1.nor cat2.nor
    Display events in both catalogues. The left side (cols 1-80) shows events from the first catalogue, and the right side (cols 83-163) shows events from the second one. Where an event in the first catalogue is within 4 s and 50 km epicentral distance of an event in the second catalogue, the events are displayed side-by-side where corresponding header lines are matched up.
    merge_seisan.pl -s -S=U -T=4 -D=50 DBASE cat2.nor does the same as above but the first catalogue is compiled from all the events in the current database. Instead of DBASE, it is also possible to give an explicit database code.
  2. merge_seisan.pl -M -T=10 -i -b=F,mW local.nor cmt.nor > local-with-cmt-mech.nor If cmt.nor is a nordic file with the CMT focal mechanism represented by a 'F' type header line, and magnitude mW set, then the focal mechanism and magnitude information from cmt.nor is combined with all other parameters from local.nor. The -M option forces the mW magnitude to be entered into an empty magnitude slot if available (association requires a time-difference of less than 10 s).
  3. merge_seisan.pl -T=10 -i -d=gmt global.nor local.nor > lines.xy produces a multi-segment file suitable as input to gmt command psxy with -m option which will then draw the line connecting the epicentres of associated events in the two catalogues.
  4. merge_seisan.pl -T=10 -i -d=xyz global.nor local.nor > bias.xyz produces a file suitable for plotting a histogram of the difference between locations in both catalogues.
  5. merge_seisan.pl -T=10 -i -d=bias global.nor local.nor > lines.xy works out the mean shift between events that are present in both catalogues (see usage information above for explanation of output format).

Figure 28.1: (Left) Histogram of the offsets between locations in the GCMT catalogue and a catalogue based on an OBS/land deployment offshore Nortern Sumatra (Tilmann et al., 2010), generated using the -d=xyz option and GMT pshistogram. (Right) Map and cross-sectional views. Large rimmed circles are events in the local catalogue, and small borderless circles are locations in the GCMT catalogue. Lines connect associated events (drawn using -d=gmtd option and GMT psxy). The red arrow points in the direction of the average shift between CMT and local locations, with the little red circle showing the formal uncertainty of the average shift vector (generated using -d=bias option and GMT psvelo). Its absolute size is only meaningful if the formal errors of the contributing locations are all realistic. The plots show the tendency of CMT centroids in subduction zones to be located seaward off and deeper than their actual location.