Output
This section describes the various output files (including plots) that may be generated by a successful run of mloc. Plots are always in PDF format. All text files and plots are identified by the basename for the run which is the first interactive input to mloc, and filename suffixes are used to identify the nature of file. There is a set of default output files that are always produced and many optional files whose creation is controlled by commands, either directly or as a consequence of the type of relocation (i.e., calibration) specified.
The terminal window in which mloc is run will contain some textual information that is not repeated in any output file but all information that has been found to be worth retaining is written to at least one output file. It is not necessary to save the terminal window after a run of mloc.
Default Output Files
The following files and plots are always created, whether a cluster is to be calibrated or not. The simpler files are described in more detail after the list. The more complex files are described on their own page.
- ~_base.pdf: Base Plot (map of final locations)
- ~.dat0: Input Data Bulletin (record of all input data)
- ~.depth_phases: Depth Phases File (all data relevant to depth constraint)
- ~.hdf: HDF File (hypocenter data summary, at least one of several flavors)
- ~.kml: KML File (for plotting in Google Earth or equivalent)
- ~.log: Log File
- ~.phase_data: Phase Data File (complete list of phase data and usage)
- ~.plog: Phase Identification Log (information related to changing phase names)
- ~.rderr: Empirical Reading Error File (for each station-phase with 2 or more instances)
- ~.stn: Station Data File (especially useful when there are supplemental station files)
- ~.summary: Summary File (summary of the input parameters, progress through iterations and final locations)
- ~.ttsprd: Travel Time Spread File (for each observed phase)
- ~.xdat: Gross Outliers
Every run of mloc also creates a folder named ~_gmt_scripts containing the GMT scripts used to create any plots (the ~_base.bash script at a minimum). These are preserved for cases where the user may wish to modify a script for research or publication purposes.
Input Data Bulletin (~.dat0_mnf)
As each event’s data file is read it is added line-for-line to a bulletin in MNF format named ~.dat0_mnf for archival purposes. This is the only reliable record of the input data to a specific run of mloc, since event data files are constantly being edited during the course of a relocation analysis. If necessary the ~.dat0_mnf file could be unpacked into event files using the mnf_search utility program in order to recover the input of a particular run. This has almost never been necessary but it is simply good practice to retain the capability. Differential time data cannot be retained in the ~.dat0_mnf file since each datum references two events.
KML File (~.kml)
The final locations of the cluster are written in Keyhole Markup Language (KML) to an output file named ~.kml for plotting in Google Earth or compatible programs. The file references icons that vary in size according to magnitude, and in color according to focal depth:
- 0-9 km: red
- 10-19 km: green
- 20-29 km: skyblue
- 30+ km: blue
A yellow icon is used for events set to the cluster default depth.
The icon image files are stored in the directory /mloc_distribution/mloc_working/kml/, but on the first run of mloc they are copied into a subdirectory of the cluster directory named _kml and the relative paths are referenced in the ~.kml file. This makes it possible to open the ~.kml file after the cluster directory is moved to the /mloc_distribution/clusters/ directory (or elsewhere) and display the correct icons in Google Earth.
Log File (~.log)
The file ~.log is used to collect information about the relocation that is normally of little interest, but may be helpful if mloc is behaving strangely or giving unexpected results. The main sections deal with:
- Events that were killed (commands memb and kill) in the command file.
- Convergence limits (command shcl).
- The local velocity model (command lmod).
- Starting locations read from a previous run (command rhdf).
- If the bdps command has been set “on”, the list of stations read from the file /mloc_distribution/mloc_working/tables/stn/bdps.dat.
- Progress of reading the input data file for each event and the number of phases re-identified.
- Depth phase readings converted to relative depth phases (e.g., pP-P).
- For each iteration, statistics on the number of readings used to estimate the hypocentroid, the number lost because of epicentral distance, the number lost because of large residual.
- For each iteration, the change in hypocentroid, weighted epicentroid, bias correction (command bias).
- For each iteration, the changes in cluster vector parameters for each event.
- For a calibrated relocation, a list of events with hypocentral data written in the form needed for the cal_ command, so that they could be cut and pasted into another command file to implement indirect calibration.
- A simplified list of hypocentral parameters for each event, useful for some forms of publication and communication.
- For direct calibration, statistics on mean residuals of readings used for the hypocentroid and their use for indicating the need for depth adjustment. Outliers from this list are listed in the terminal output of mloc.
There are two commands that will cause additional information to be written to ~.log. They are both normally used only in a development environment, to track down bugs in the code, but the “lighter” one, vlog, may be of interest to a new user of mloc who wants to better understand the inner workings. Most of the extra logging will not be comprehensible without making frequent reference to the source code. The “heavy duty” logging command is dbug. Its use will result in a ~.log file several tens of MB in size, but it is nearly always possible to isolate the source of a bug through careful inspection of the file. In dire circumstances it can help to enable both logging options, although there is some overlap.
Phase Identification Log (~.plog)
This log file, named ~.plog, is not, technically, part of the “default” set of output files because it could be turned off using the phid command. The default state is to do phase re-identification. Most data sets would perform poorly if phase re-identification is turned off.
The standard content of the phase identification log is a list of cases where the name of a phase read from the event file has been changed. Phase re-identification is done as event files are read and again after the first relocation iteration; each pass is logged.
Optional Output
Depending on the use of various commands there will be additional output files from a run of mloc, in the form of text files or plot files (PDFs). Commands that lead to additional output files are:
- bloc: Output file ~.bloc for export of mloc hypocenters to BayesLoc as priors.
- cal_: One new output file ~.cal and an extra ~.hdf file from indirect calibration.
- ccat: Two output files (~.comcat and ~_plots.pdf) in a subdirectory, containing detailed results of a run for import to the GCCEL or NEIC ComCat databases.
- datf: Output file of the final state of the cluster in MNF v1.3 bulletin format.
- dcal: Two extra output files and a new plot from direct calibration.
- epap: Map of empirical path anomalies for a selected phase.
- eplt: Simplified base plot, showing only confidence ellipses.
- fdhp: Histogram of focal depths.
- lres: Output file ~.lres of readings with cluster residual above a threshold.
- mdou: Output of event locations in a form for easy import to GMT.
- oldr: Output file containing all readings within a specified epicentral distance range.
- plot: Base plot for selected subset of events.
- pltt: Standard summary travel-time plots.
- rdpp: Plots of relative depth phase data for single events.
- splt: Simplified base plot, all events shown with the same symbol (traditional seismicity plot).
- tlog: Output file ~.taup with detailed logging of tau-p calculations.
- tomo: Output files ~.tomo designed for tomographers.
- tt5e: Local distance travel-time plot for a specified event.
- tt5s: Local distance travel-time plot for a specified station.
- ttou: Output files ~.ttou with travel-time and residual data for specified phases.
- xsec: Cross section plot.
Direct Calibration Output
The dcal command tells mloc that a direct calibration relocation is being conducted, meaning that the epicentral distance range of data used to estimate the hypocentroid is restricted in order to minimize the biasing effect of unknown Earth structure. The epicentral distance range for this purpose is usually in the range 0.5-1.5°. In this case, the only HDF file produced is the ~.hdf_dcal file.
When a direct calibration relocation is done, two new files are produced in addition to the default output files:
- ~.dcal: Some extra details about the uncertainties of the calibrated locations.
- ~.dcal_phase_data: Details of the arrival time data used to estimate the hypocentroid.
Direct calibration also produces a new plot, the direct calibration raypath plot, named ~_dcal.pdf, which makes a base map over a region several hundred km across in order to display the raypaths of the arrival time data used to estimate the hypocentroid. This is very useful for evaluating the azimuthal coverage for direct calibration.
Indirect Calibration Output
The cal_ command (actually, family of commands) tells mloc that an indirect calibration relocation is being conducted. In this case the calibration step occurs separately, after the relocation, so two HDF files are written. The first one will be either ~.hdf or ~.hdf_dcal, depending on whether the initial relocation was done as uncalibrated or as a direct calibration The second will be ~.hdf_cal, reflecting the indirect calibration. In the case where both direct and indirect calibration are done, the user must evaluate which outcome is to be preferred; the level of calibration achieved by each method is one criterion, but not necessarily the only one.
The output from indirect calibration also includes a file named ~.cal, containing a detailed record of the analysis used to determine the shift of the hypocentroid that provides the optimal match with the calibration data for a subset of events in the cluster. This analysis takes into account the uncertainties of the relative locations (cluster vectors) of the events with calibration data and the uncertainties assigned to the calibration data itself.
When indirect calibration is done, even if direct calibration was done beforehand, the results from indirect calibration will be reflected in all output files and plots (except ~.hdf or ~.hdf_dcal files).