MLOC Output

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.

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:

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).