MLOC Data Files
This section discusses the details of the data files that support mloc. All necessary files are included in the distribution package, but there circumstances where the user may wish to edit, replace or augment some of them. All data files reside in subdirectories of the /mloc_distribution/mloc_working/tables directory.
/tables/crust/
The only function of this directory is to hold custom crustal velocity models, but you also have the option of storing them in the cluster directory itself. The only difference is the pathname of the crustal model file assigned with the lmod command in the command file. My convention is to give crustal models the filename suffix ~.cr but you can name them any way you like.
My strategy is to keep most custom crustal models with the individual clusters (same directory as the event data files) because they are usually cluster-specific. I reserve the tables/crust directory for crustal models that may be used across many clusters. It is nearly mandatory to develop a custom crustal model for any cluster that is undergoing a calibrated relocation, but it’s usually not possible to place strong constraints on a crustal model for an uncalibrated relocation study, so a reasonable regional model may be used. In particular I store a model (ak135.cr) of the crust and upper mantle from the 1-D global model ak135 (Engdahl et al., 1998) in this directory. This is normally the starting model for a new cluster, from which a cluster-specific model is developed through trial and error. Specifically, I make a copy of ak135.cr, rename it for the intended cluster and move it to the cluster directory.
The file simple.cr provided in the distribution package is an example of the simplest possible crustal model (one layer crust of constant velocity over a pseudo-halfspace upper mantle) which, nevertheless, would provide a good fit to many datasets after adjusting the velocities and crustal thickness.
The details of the file format for crustal models and many aspects of working with crustal velocity models are discussed in the Crustal Models section.
/tables/ellipticity/
Corrections to theoretical travel times for the ellipticity of the Earth are a standard part of traditional earthquake location programs because the location is usually based mainly on the fit of (corrected) theoretical travel times to observed regional and teleseismic phases. Ellipticity corrections are usually on the order of a tenth of a second. For a calibrated location in mloc, however, these corrections are irrelevant since only the relative times of regional and teleseismic phases are being used to determine the relative locations of the events in the cluster. The absolute location of the cluster (hypocentroid) will be determined from near-source data for which ellipticity corrections are not relevant. Nevertheless, ellipticity corrections are made in mloc with the same algorithm used in Bob Engdahl’s single event code (i.e., the EHB catalog), based on the Dziewonski and Gilbert (1976) representation with further work by Brian Kennett and Wim Spakman.
Ellipticity corrections are based on a single data file: /mloc_distribution/mloc_working/ellipticity/tau.table.
/tables/faults/
The map plots (e.g., the base plot) produced by mloc can display faults (command fmap). The data files follow the format for GMT, with coordinates given in the order longitude, latitude. They can be stored in this directory or in the cluster directory itself. Data files that cover a large region are probably best stored here. The example is a file of major faults in Turkey: /mloc_distribution/mloc_working/tables/faults/turkey_faults.dat.
/tables/gmt/
Two types of data are stored in this directory (in sub-directories) for use in plotting: color palettes and digital elevation models (DEMs). These are only used for the map-like plots, e.g., the base plot.
/tables/gmt/cpt/
The default color palette for showing topographic data in mloc plots is topo.cpt. It works well in most circumstances, but there are many others and GMT documentation includes detailed instructions about designing your own.
/tables/gmt/dem/
In versions of mloc prior to 10.5.0, DEM files for several different models (e.g., GLOBE and GINA) were installed in subdirectories of the /tables/gmt/dem directory. GMT6 introduces support for DEMs that can be automatically downloaded from the GMT server, as documented in Section 3.7 of the GMT Cookbook. mloc now makes use of that capability, specifically calling ETOPO1 if the argument to command dem1 is “on”. The DEM (earth_relief_01m.grd, 270 MB) is downloaded the first time plotting of topography is called for, and stored in the invisible directory ~/.gmt/server/, where “~” is the user’s home directory.
The /tables/gmt/dem directory will therefore be empty in the standard mloc distribution, but it is an appropriate place to store custom high-resolution DEMs if they are ever used (see Plotting Topography).
mloc uses ETOPO1 to plot topography (command dem1), regardless of whether GMT5 or GMT6 is used, but under GMT5 the ~.grd file for ETOPO1 (bedrock version, not ice) must be stored in a subdirectory of /tables/gmt/dem/ named “ETOPO” that must be created by the user. The zipped archive of the ETOPO1 ~.grd file (ETOPO1_Bed_g_gmt4.grd.gz) can be downloaded from
NOAA. When unzipped it will be ~1 GB is size.
If GMT5 is used without installing the ETOPO1 DEM you should accept the default (“off”) state of the command dem1.
/tables/kml/
The ~.kml file that is a standard output file of mloc uses icons in two shades each of five colors for earthquakes at different depths. The icons are in PNG format and must be stored in this directory.
mloc uses a copy of the /tables/kml directory (“_kml”) which is made in the cluster directory on the first run. The ~.kml files created in the cluster directory always reference the locally-stored icons so that the display will still work if the cluster directory is moved to a new location.
/tables/spread/
One of the more important aspects of using mloc is the use of empirical reading errors, estimated for each station-phase pair from the actual data. For the first run (at least), when those estimates are not yet available, mloc uses a set of phase-specific default reading errors, read from a file named psdre.dat in this directory.
Current values in this file are listed in the table:
| Phase | Reading Error (s) |
|---|---|
| Pg | 0.4 |
| Pn | 0.8 |
| P | 0.5 |
| pP | 1.0 |
| sP | 1.5 |
| Sg | 0.8 |
| Sn | 2.0 |
| S | 3.0 |
| Lg | 4.0 |
| T | 5.0 |
| S-P | 0.4 |
The user can edit this file to change the default values or to add or remove phases.
/tables/stn/
This directory holds several data files related to seismograph stations, especially the geographic coordinates and elevation for a given station code. The most important file here is the master station file (master_stn.dat), which is meant to carry information only on stations in the International Registry of Seismograph Stations (IR) at the ISC. The reason for this policy will become clear(er) when the user encounters the full suite of problems related to station codes and the strategy used in mloc to manage conflicts. In some cases the precise coordinates (especially elevation) of a station from the IR are over-ridden by more trusted information from other sources, but non-IR-registered stations should be handled with supplemental station files (command sstn), not entered into the master station file.
The other two data files in this directory are related to specific commands:
- bdps.dat: a list of seismic stations that are suspected of reporting bogus depth phase readings. Specifically, it is suspected that some station operators take focal depths from preliminary locations by agencies such as the NEIC, and report depth phase arrivals taken from theoretical travel time calculations. The command bdps takes the pathname of the file relative to the mloc working directory so it does not have to be stored here, but this is the natural place for it.
- neic_stn.dat: This file is used by the command nsmd which causes a search to be made for station codes that were not found in the master station file. It is only needed (possibly) if an arrival time dataset includes data obtained from the NEIC. Many stations of the U.S. regional networks that report to the NEIC use codes that conflict with stations registered in the IR, and for that matter, with each other. NEIC solves this problem by carrying FDSN network codes along with station codes (and a lot more) in their metadata server and location software. This data file is a recent download of the entire contents of the metadata server, so a search for a given station code may well return multiple hits from different networks. The strategy used in mloc to manage these issues is discussed elsewhere.
Supplemental station files (command sstn) may be stored here also, especially when one may be working regularly with data from a regional or local network whose stations are not all registered in the IR. Then it may be worth building a supplemental station file named for that network. Supplemental station files that are carefully tuned for a specific cluster are best kept in the relevant cluster directory.
/tables/tau-p/
Two binary data files (ak135.hed and ak135.tbl) are needed by mloc to use the tau-p formulation of the 1-D global travel-time model ak135. These files should work on a Macintosh system, and perhaps other OS’s, but if not, they will need to be built for your system. Software to create the binary data files from the ak135 model is widely distributed on-line.
The etopo5 digital elevation model is also stored in this directory for use by mloc in calculating bounce-point corrections for depth phases, following the algorithms used in the EHB Catalog.