MLOC Commands

Commands

This section covers all available commands for controlling the actions of mloc. Even if the default values were to be accepted, it would still be necessary to use several commands to define at least one event. Most commands can be issued either in a command file or interactively. The typical usage is to create a command file which is referenced interactively (with the cfil command) and then followed with a few more interactive commands before running the relocation with the command run.

Alphabetical List

When mloc is started it provides an alphabetical list of the available commands. As of v10.5.1 that list is:

mloc has an interactive help system for commands; give the command help, followed by the name of the command.

Functional Summary of Commands

If the help command is issued without an argument a functional summary of commands is listed:

  • Calibration
    • cal_: calibration data for current event
    • ctyp: treatment of calibration events in indirect calibration
    • dcal: direct calibration
  • Informational
    • anno: annotation
    • comm: comment line
    • dbug: extra logging for debugging
    • help: details about commands
    • revi: review current relocation control parameters
    • tlog: logging for tau-p calculations
    • vlog: set verbose mode for logging
    • vscr: set verbose mode for screen display
  • Input
    • cfil: specify a command file
    • diff: differential time data
    • even: event name
    • inpu: specify an event data file
    • kill: kill a block of events
    • memb: start a new event (or kill an event with the “kill” argument)
  • Inversion
    • bias: hypocentroid bias correction
    • clim: epicentral distance limits for cluster vectors
    • flag: use of data flags
    • frec: free parameters for cluster vectors
    • freh: free parameters for the hypocentroid
    • hlim: epicentral distance limits for hypocentroid
    • phyp: set “use only P arrivals for hypocentroid” flag
    • pttt: perfect theoretical travel times for hypocentroid
    • run : begin the relocation process
    • shcl: hypocentroid convergence limits
    • step: number of iterations to run
    • stop: stop processing
    • tikh: Tikhonov regularization
    • weig: residual weighting by reading error
  • Miscellaneous
    • lonr: set longitude range (-180 to 180 or 0 to 360)
  • Output
    • bloc: BayesLoc output file
    • ccat: COMCAT output file
    • datf: output MNF bulletin of all events in their final form
    • lres: LRES file of large cluster residuals
    • mdou: map_dat output file for GMT
    • oldr: output of phase readings over a limited distance range
    • subc: select a subcluster based on data for direct calibration
    • tomo: tomography output files
    • ttou: Empirical TTs for a specific phase
  • Phase Identification
    • phid: toggle phase re-identification
    • ppri: phases that cannot be renamed
    • skip: skip readings of a given phase (also by station and author)
  • Plotting
    • cptf: color palette table for topography
    • dem1: plot regional-scale topography in GMT
    • dem2: plot high-resolution topography in smaller-scale GMT plots
    • ellp: plot an ellipse
    • epap: plot of empirical path anomalies
    • eplt: make a map of locations with only confidence ellipses
    • fdhp: make a histogram of focal depths
    • fmap: digital fault map for GMT script
    • plot: plotting of selected events
    • pltt: travel time plots
    • rdpp: relative depth phase plots for individual events
    • splt: make a seismicity map, same-size symbols for locations
    • star: plot a star to highlight a specific event
    • stat: plot a triangle to indicate a station location
    • tt5e: single-event local distance (tt5) plot
    • tt5s: single-station local distance (tt5) plot
    • vect: which event shift vectors to plot
    • xsec: cross-sections
  • Residuals and Uncertainties
    • cvff: Cluster vector fudge factor (non-gaussian contribution to uncertainty)
    • cvtt: cluster vector travel time error
    • mare: minimum allowed reading error
    • rels: set reading errors for local stations
    • rfil: reading error file (.rderr)
    • tfil: travel time spread file (.ttsprd)
    • wind: windowing of residuals
  • Starting locations
    • dep_: set starting focal depth
    • lat: set starting latitude
    • long: set starting longitude
    • pert: perturbation to all starting locations
    • rhdf: read starting locations from an HDF file
    • time: set starting origin time
  • Stations
    • bdps: list of stations suspected of reporting bogus depth phases
    • nsmd: search NEIC station metadata for missing station codes
    • radf: read agency and deployment fields to resolve station code conflicts for a specified station
    • skip: skip readings from a given station (also by phase and author)
    • sstn: supplemental station file
  • Travel Times
    • bptc: Bounce point topography correction
    • corr: Station elevation correction
    • lgtt: Lg travel time calculation
    • lmod: local velocity model
    • secv: station elevation correction velocities
    • taup: Global TT model, using Tau-P formulation
    • terr: Timing error correction at a station
    • tptt: T-phase travel time calculation

Command Descriptions

The text in these descriptions is taken from the interactive help system.

anno (ANNOtation) is used to provide some extra textual information about an event. The string will be printed at the end of the corresponding line in the HDF files. Maximum 20 characters. This annotation over-writes an annotation given in the event record of an MNF file, in which case a warning will be given.

bdps (Bogus Depth Phase Stations) specifies the pathname of a file containing a list of stations that are suspected of reporting bogus depth phases, i.e., depth phase arrival times that are generated from theoretical arrivals relative to a preliminary hypocenter (e.g., the PDE). Depth phase readings from listed stations will be plotted at a smaller size in “tt6” plots and will have an asterisk next to their entries in the “.depth_phases” file. The generic station file format (type 3) is used for this list because it carries fields for epoch dates “on” and “off”. When used for bogus depth phase reporting, however, the dates are interpreted as the epoch during which bogus depth phases have been reported. These dates are optional, and other station information that can be provided in this format is not used by mloc. It can be useful for station identification, however. The only required field is station code in columns 1-5, but the first line must have “3” in the first column to confirm the format.

bias (BIAS correction) determines if a correction will be made for a minor source of bias in the hypocentroid, related to the fact that some events have more readings than others. See Jordan & Sverdrup (1981) for details. By default, or if the argument is blank or “on”, the correction is made. If the argument is “off” the correction is not made. Correcting the bias increases the variance of the hypocentroid slightly. Compared to the main source of bias in the hypocentroid, i.e., travel time model inadequacies, this is usually negligible.

bloc (BayesLOC) specifies that an output file (with suffix “.bloc”) will be written. The format is designed for easy import of mloc calibrated hypocenters into BayesLoc for use as priors. Default is “off”. Issuing the command with no argument toggles the current state, or the arguments “on” or “off” can be used to explicitly set the state.

bptc (Bounce Point Topography Correction) makes a correction to theoretical travel times of pP and sP for the topography at the bounce point. For areas above sea level the times of pP and sP are increased. For oceanic areas the travel times of pP and sP are reduced because the reflection point (seafloor) is below sea level. The travel time of the pwP phase is calculated by adding a term for the propagation time in the water column to the pP time. No calculation is done for swP. The command can be toggled on and off by issuing the command without an argument, or set explicitly with arguments “on” and “off”.

cal_ (CALibration event) is used to declare a calibration location for the current event. Epicenter is always assumed to be calibrated. The 4th character in the command is used to specify which of the other hypocentral parameters are to be considered calibrated:

  • e : the epicenter alone is calibrated (e.g., from InSAR)
  • f : focal depth is also calibrated, but not origin time
  • t : origin time is constrained by local-distance data but it cannot be considered to be calibrated because focal depth is not calibrated
  • h : epicenter, depth, and origin time are calibrated

The command takes 11 arguments: hour, minutes, and seconds of the origin time, plus latitude, longitude and depth, in that order, followed by 3 arguments giving the 90% confidence ellipse and 2 arguments for the uncertainties in depth and OT. The sequence for confidence ellipse is: azimuth of semi-minor axis (clockwise from north) semi-minor axis length, semi-major axis length (both in km). The command can be given multiple times for an event, in which case the last command will define the calibration parameters.

ccat (ComCAT) specifies that two output files will be written. One is a ~.comcat file, a single file similar to the .datf_mnf file, but with additional information needed for uploading to the USGS/NEIC ComCat server. The same file is used in the GCCEL project. The other is a file named ~_plots.pdf, a single PDF file containing all plots created in the run. The command takes a single optional argument, the filename (assumed to be in the data directory) of a text file containing a commentary on the nature of the cluster and the relocation procedures and results. The commentary file should be hard-wrapped at a reasonable line-length (72 characters is good). The commentary will be added to the .comcat file as comment records.

cfil (Command FILe) takes one argument, the name of a command file. All the commands in that file will be processed before control is returned for interactive command processing. Multiple command files can be invoked (by separate cfil commands), but they must all be found in the data directory specified when the program starts. The cfil command cannot be issued from a command file, only interactively.

clim (Cluster vector LIMits) specifies a set of up to three ranges in epicentral distance that will be used to estimate the cluster vectors. This allows skipping readings, for example, at short distances, in the Pdiff range and near the caustic for PKP phases. Since each range requires two values, this command requires 2, 4, or 6 arguments.

comm (COMMent) declares a comment line. It can be used to disable a command in the command file or simply to add some additional information. It was formerly used as a convenient way to take an event out of the cluster temporarily without losing track of it completely, but that usage has been superceded by the kill command for blocks of events and the “kill” argument to the memb command for single events.

corr (station elevation CORRection) controls station elevation corrections. A single integer argument is required. The allowed arguments are:

  • 0: No correction
  • 1: Station elevation corrections are made

Regardless of the usage of the corr command, ellipticity corrections are always applied. In the case of direct calibration the choice of station elevation correction changes the reference plane for focal depth. If station corrections are made, the reference plane is the reference ellipsoid. If not, the reference plane is, roughly, the surface (average elevation) of the source region.

cptf (Color Palette Table File) defines a color palette table to use for plotting topography. The argument is only the name of the desired color palette table; the path is defined in the main program.

ctyp (Calibration TYPe). This applies only to indirect calibration mode, and only to calibration events. It determines the way in which the uncertainty for calibration events is calculated. There are three options, specified by an integer value:

  • 1 = traditional: use the uncertainty of the supplied calibration data
  • 2 = systematic: add calibration shift uncertainty to cluster vector uncertainty (default)
  • 3 = optimal: traditional or systematic, whichever has smaller semi-major axis

cvff (Cluster Vector Fudge Factor) specifies a radius (km) for additional uncertainty that will be added to the cluster vector covariance matrices to account for bias from non-gaussian components of the arrival time data sets. This is completely ad hoc, but it goes in the right direction. A value of about 1.0 km has been inferred from some tests, but further testing is needed.

cvtt (Cluster Vector Travel Time) adds an additional variance to differential time data. When using differential arrival times from waveform cross-correlation, a pure reading uncertainty is often provided, but the actual variance includes a component from inadequate theoretical differential travel times. This command allows that term to be defined. It is only relevant if differential time data are used. The correction is never added to bulletin data because this error term is already absorbed in the empirical reading error. The two parameters are vmr (velocity model variance), a percent value of velocity variance in the travel time model, (default value 0.05, or 5%), and cscale, a measure of the scale of the cluster in km (default 10 km).

damp (DAMPing) determines if damping will be applied to the cluster vector changes at each iteration. Damping is done by calculating the mean of changes in a parameter for all events and subtracting it from the change for each event. This sometimes helps convergence. The default is off. The state can be toggled by using the command without an argument, or set explicitly with arguments “on” or “off”.

datf (DATa Final) specifies that a .datf output will be written. This is a single file with all the events written in MNF format, but with phase IDs and flags as they are at the end of HD analysis. Flags and phase IDs can be changed during the HD analysis. Arguments “on” and “off” can be used to set the logical state explicitly. Issuing the command without an argument toggles the logical state.

dbug (DeBUG) specifies that extra information about the HD analysis will be written to the output window. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

dcal (Direct CALibration) specifies direct calibration mode, i.e., the hypocentroid is being located with data (usually near-distance data) that has minimal travel time error and so the hypocentroid can be taken as bias-free. The confidence ellipse of the hypocentroid is added to those of the cluster vectors to obtain final estimate of uncertainty for each events location. Four new output files are created:

  • .dcal_phase_data: listing the data used for the hypocentroid
  • _dcal.bash: GMT script, showing stations and raypaths used for hypocentroid
  • _dcal.pdf: PDF file, from the _dcal.bash script
  • .hdf_dcal: hdf with calibrated locations

Confidence ellipses in the .hdf_dcal file are cumulative, from hypocentroid and cluster vector for each event. Can be toggled by using the command without an argument, or set explicitly with arguments “on” or “off”.

dem1 (Digital Elevation Model 1) specifies whether or not commands to plot topography will be added to the GMT script. The argument is “on” or “off” (default). If no argument is given the state is toggled. If plotting of topography is turned on the ETOPO1 1-minute gridded topography and bathymetry model will be used.

dem2 (Digital Elevation Model 2) defines a DEM to be used in the base plot and other plots that benefit from high-resolution topography. It assumes the user has provided a “.grd” file and the argument to the command gives the pathname of that file, relative to the MLOC working directory. Such files are obtainable here. If no argument is given, plotting of topography is turned off.

dep_ (DEPth) specifies a starting focal depth. The 4th character is used to specify the kind of information used to constrain the depth. At least one argument is required, a positive depth value in km, and it can optionally take one or two additional arguments to assign an uncertainty to that depth. Uncertainty in the assigned depth can be symmetric or asymmetric. If a single value is appended to the depth estimate it is taken as a symmetric uncertainty. If two values are appended the first is taken as plus (deeper), the second as minus (shallower) uncertainty, in km. Both values should be positive. Recognized values for the 4th character are:

  • c: cluster default depth
  • d: depth phases
  • e: engineered (man-made explosion)
  • f: fault model (InSAR, GPS, etc.)
  • i: input data file
  • l: local distance readings (more than 2-3 focal depths)
  • m: mloc solution (with free depth)
  • n: near-source station readings
  • r: relocation (outside mloc) with free depth
  • u: unknown/unspecified/unconstrained
  • w: waveform analysis

The command accepts any character in the 4th position so custom values can be used. The dep_ command can be issued multiple times, first to set a default depth for all events (depc), then to set selected events at different depths. If it is issued before any events are declared (by memb commands), it applies to all events in the cluster that do not have a constrained depth declared in the input file. If issued after a memb command it applies only to the current event, and it overrides the depth read from the input file or from an HDF file.

diff (DIFFerential time data) specifies the pathname of a file containing differential time data for pairs of events in the cluster. The command can be issued more than once, but only the last instance will be processed.

ellp (ELLipse Plot) is used to specify the parameters of an ellipse that will be plotted in the map plots by GMT. The command takes five arguments:

  • latitude of the center point
  • longitude of the center point
  • azimuth of the semi-major axis
  • full length of the major axis, in km
  • full length of the minor axis, in km

The command can be issued up to 10 times.

epap (Empirical Path Anomaly Plot) controls creation of a map of empirical path anomalies for a specific phase. A symbol is plotted at each station that recorded the phase of interest at least twice. The symbol is color-coded according to the sign of the empirical path anomaly and the size is proportional to its absolute value. Ray paths can optionally be drawn from the hypocentroid to the symbols. The command takes three arguments: phase name, epicentral distance limit (degrees), and a flag (0 or 1) which controls the plotting of raypaths. The epicentral distance is used to set the boundaries of the map. The command can be issued up to 6 times.

eplt (Ellipse PLoT) specifies whether a “confidence ellipse” plot will be made. This plot includes confidence ellipses for relative location but not event numbers or relocation vectors. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

even (event) is used to specify the name of the current event. This normally has a form like YYYYMMDD.HHMM.SS (i.e., 16 characters). Maximum 30 characters. even takes one argument.

fdhp (Focal Depth Histogram Plot) specifies whether a plot will be made of a histogram of focal depths. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

flag (data FLAGs) determines if data flags encountered in input files will be honored (“on”) or ignored (“off”). Issuing the command with no argument toggles the current state. Default is “on”.

fmap (Fault MAP) specifies a file of digitized faults or other linear features to be plotted in GMT. The standard GMT format – longitude, latitude – is used, in free format. The symbol “>” can be used to separate multiple line segments. The pathname relative to the working directory is given. The normal place for these files is the directory /tables/faults. The command can be issued multiple times.

frec (FREe parameters Cluster vector) is used to specify which location parameters will be free and which will be fixed for cluster vectors. It requires four arguments that are either 0 or 1. 0 indicates a fixed parameter, 1 indicates a free parameter. The order is latitude, longitude, depth, origin time. If frec is invoked before any events are declared, the values apply to all events. If invoked after an event is declared, the values only apply to the current event.

freh (FREe parameters Hypocentroid) is used to specify which location parameters will be free and which will be fixed for the hypocentroid. It requires four arguments that are either 0 or 1. 0 indicates a fixed parameter, 1 indicates a free parameter. The order is latitiude, longitude, depth, origin time.

help (HELP) is used to provide detailed information about the purpose and usage of the commands in mloc. If it is issued without an argument a list of all commands is returned, organized by general category, and with a short description of the function of each command. A particular command may be given as an argument, in which case a more detailed description of that command is returned. Only a single command can be given as argument.

hlim (Hypocentroid LIMits) specifies a set of up to three ranges in epicentral distance that will be used to estimate the hypocentroid. This allows skipping readings around the Pg/P crossover, in the Pdiff range, and near the caustic for PKP phases. Since each range requires two values, this command requires 2, 4, or 6 arguments.

inpu (INPUt file) is used to specify the name of the file containing the phase arrival time information for an event. The command requires a single argument. The standard form of the base filename is YYYYMMDD.HHMM.SS. The only supported format is MNF (MLOC Native Format). The maximum length of the input filename is 20 characters.

kill (KILL event) provides a convenient way to ignore (“kill”) blocks of events listed in a command file. It requires one argument, either “on” or “off”. After the kill on command is issued, no other commands will be processed until the kill off command is processed. To kill a single event, the memb command with the argument “kill” is preferred.

lat (LATitude) specifies a starting latitude. It requires one argument, a latitude value. If it is issued before any events are declared (by memb commands), it applies to all events in the cluster. Otherwise it applies only to the current event. The lat command can be issued many times, first to set a default latitude for all events, then to set selected events at different latitudes. If the lat command is not applied to an event, the latitude read from the input data file will be used as the starting value.

lgtt (LG Travel Time) specifies a custom travel-time model for the Lg phase. The model is linear in epicentral distance. It takes three arguments: a zero-intercept (sec), slope (sec/degree) and minimum epicentral distance (degrees) from which to begin calculating travel tiems for Lg. Default values are 0., 31.5 and 2.5.

lmod (Local MODel) specifies a local velocity model to be used to calculate travel times at short epicentral distance ranges. Local velocity models are normally stored in the tables/crust/ subdirectory. The format of local velocity model files is the format used by HYPOSAT. If a custom velocity model is not specified, the global tau-p model is used for all distances. The command takes one argument, the pathname (relative to the working directory) of the model file. The distance and depth ranges for which it will be used are specified in the file itself.

long (LONGitude) specifies a starting longitude. It requires one argument, a longitude value. If it is issued before any events are declared (by memb commands), it applies to all events in the cluster. Otherwise it applies only to the current event. The long command can be issued many times, first to set a default longitude for all events, then to set selected events at different longitudes. If the long command is not applied to an event, the longitude read from the input data file will be used as the starting value.

lonr (LONgitude Range) specifies the range to which longitudes should be converted. The command takes a single integer argument that gives the center of the longitude range. Two values are accepted:

  • 0 : -180° ≤ longitude < 180° (default)
  • 180: 0° ≤ longitude < 360°

A value should be chosen that keeps longitudes for all events in the cluster in the same range.

lres (Large RESidual) specifies that a .lres output file will be written, containing all readings with cluster residuals (eci) larger than the value given by the single argument.

mare (Minimum Allowed Reading Error) specifies the the minimum reading errors that will be allowed, regardless of what value is read from a .rderr file. Three arguments are required:

  • The minimum value for local phases
  • The minimum allowed value for phases beyond local distance
  • The minimum allowed value for teleseismic depth phases

Local phases are defined as those with “g” or “b” as the second character of the phase name.

mdou (Map Data OUtput) specifies that a file containing lat-lon data will be written. It will have the filename suffix “.map_dat”. This file is designed for easy import by a GMT script for additional plotting. If no argument is given, the status is toggled. The arguments “off” and “on” can be used to set the state explicitly.

memb (MEMBer) is used to define a new event in the cluster or to cause an event in the command file to be skipped (killed). The command takes no argument if a new event is being defined. When the command is issued, the event counter is incremented and specification of a new event starts. To use this command to kill an event, add the argument “kill”. Any text following “kill” is ignored, but it can be used for a comment about the reason for killing the event. This is the preferred way to kill a single event; see the command kill to skip blocks of events.

nsmd (Neic Station MetaData) determines if the NEIC station metadata file will be searched for missing station codes after the master station file and any supplemental station files have been searched. Any station codes that are found in the NEIC metadata file will NOT be used in the current run; a supplemental station file must be created and referenced in a subsequent run. The body of a supplemental station file in “NEIC” format (isstn=5) for any matching station codes will be found in the .log file. If there are multiple instances of a station code with different coordinates they are all listed. Default is no search. Logical state is toggled by issuing the command without an argument, or set explicitly with “on” or “off” as the argument.

oldr (Output Limited Distance Range) specifies an epicentral distance range for which an output file will be created to list all phase readings in that range. Two arguments are required.

pert (PERTurb starting locations) is used to specify a perturbation in location parameters that will be applied to all events in the cluster. Four arguments are required, in the order latitude, longitude, depth, and origin time. Latitude and longitude perturbations are in decimal degrees.

phid (PHase IDentification) is used to toggle phase re-identification, which is done after the data are read in and once more after the first iteration. By default, it is turned on.

phyp (P HYPocentroid) specifies that only P phases will be used to estimate the hypocentroid. This is normally used with hlim to specify only arrivals between 30 and 90 degrees, which provides a consistent, (albeit biased) estimate of the hypocentroid. If direct calibration is being used, S-P readings will be retained as well. If no argument is given, the status is toggled. The arguments “off” and “on” can be used to set the state explicitly. Default = “on”.

plot (selective PLOTting) specifies that the current event is selected for plotting in a secondary GMT script (_selN.bash). All cluster events are always plotted in the main GMT script (_base.bash). The command takes one argument, an integer which specifies which selected-event plots this event will be included in. Limit is 9 selected-event plots, and an event can belong to more than one by using the plot command several times before the following memb command.

pltt (PLot Travel Time) specifies one or more TT vs distance plots to be made. There are nine plot types available (details and examples), which are specified by the indices 1-9 after the command. Up to nine arguments can be given in a single instance of the command:

  • 1 = Summary TT plot, full distance range 0-180 degrees
  • 2 = Teleseismic P residuals, 16-120 degrees
  • 3 = PKP branches around the caustic
  • 4 = Near-source residuals
  • 5 = Local distance, 0-4.0 degrees
  • 6 = Local-regional distances, 0-30 degrees (reduced velocities)
  • 7 = Local and regional S phases (reduced velocities)
  • 8 = Summary plot of relative depth phases, pP-P and sP-P, for all events
  • 9 = S-P times

If no arguments are given, all plots are turned off. If a custom crustal model has been specified for short ranges, the travel times will be calculated from it in the applicable distance range. In all cases, travel times are calculated for the depth of the hypocentroid.

ppri specifies phases that cannot be renamed. It takes one argument, a phase name. The command can be issued multiple times, up to the limit specified by n_no_phreid_max.

pttt (Perfect Theoretical Travel Times) allows the variance of the travel time model (ttsprd) to be set to zero (“on”) for the purpose of calculating the hypocentroid and its uncertainty. Phase spread values (either default or read from a .ttsprd file) are still used in the windowing algorithm (command wind). Issuing the command with no argument toggles the current state. Default is “off”.

radf (Read Agency and Deployment Fields) specifies that agency and deployment fields in event data files (.mnf files) and station lists for the specified station code will be read and used to resolve station code conflicts. This is only used when a dataset contains readings from two or more different stations with the same code. The command takes a single argument, a station code. The command can be issued multiple times, up to the limit specified by “n_radf_max” (currently 10).

rdpp (Relative Depth Phase Plot) makes a plots of misfit vs. depth for relative depth phases (pP-P, sP-P, pwP). The command takes a single argument. To make a plot for a specific event the argument is the event name (as given in the even command). This command can be issued multiple times, up to the maximum number of events. The argument “all” can be used to make plots of all events for which depth phases are reported.

rels (Reading Error Local Stations) specifies the reading errors that will be used for direct-arriving phases Pg, Pb, Sg, and Sb within a specified distance. This is mainly used for single event location of events with local data, e.g., calibration events. Three arguments are required, the reading error for P and S phases, respectively, and the distance range (epicentral degrees) in which these values apply.

revi (REVIew) is used to provide detailed information about the current events in the cluster and the settings that influence how the relocation will be done. It takes no arguments.

rfil (Reading error FILe) specifies a .rderr file to be opened for reading the empirically-derived reading errors of specific station-phases. The file is expected to be in the data directory, so the argument of the command is just the filename, not the full pathname. Revert to the default values by entering the argument “default”.

rhdf (Read HDF file) specifies an HDF file that will be read to obtain starting locations. The hypocentral values read from the HDF file are over-ridden by any of the commands lat, long, time, or dep_ issued later in the command file. If any cluster events are missing from the HDF file, starting locations for those events will revert to those of the corresponding input file. The command takes one argument, the name of the HDF file, which must be stored in the data directory with the input files.

run (RUN the inversion) ends the command processing phase and starts the HD relocation process. There are a few additional queries that provide important controls over the relocation process, but no further opportunities to add events to the cluster or issue any of the standard commands.

secv (Station Elevation Correction Velocities) specifies the velocities that will be used for station elevation corrections. The command takes two arguments, the velocity for P and S. Default values are 5.8 km/s and 3.46 km/s, respectively.

shcl (Set Hypocentroid Convergence Limits) modifies the criteria used to decide if convergence has been reached, i.e., the change in each parameter from one iteration to the next is smaller than the convergence limit. This command only deals with the limits relating to the hypocentroid (origin time, epicenter and focal depth). Actual convergence requires all parameters for the hypocentroid and each cluster vector to satisfy their corresponding convergence criteria, but it is often the case that convergence is prevented by oscillations in the hypocentroid origin time, sometimes coupled with instability in one of the epicentral parameters. The “epicenter” limit is applied separately to latitude and longitude. It should be noted that achieving convergence by increasing the limits may not produce a reliable solution, but there are advantages to having a converged solution for investigating why it was necessary. The command takes three arguments, convergence limits for epicenter (degrees), focal depth (km) and origin time (s). Default values are 0.005 degrees, 0.5 km and 0.1 s.

skip (SKIP) specifies a triplet of station-phase-author for which all readings are flagged (with “s”). Skipped readings will not to be used in the relocation for cluster vectors or hypocentroid. The command takes three arguments, a station code, a phase code and an author code. Wildcards (“*”) are supported:

  • “skip GRMI * *” means skip all readings from GRMI
  • “skip GRMI Pg *” means skip all Pg readings from GRMI
  • “skip GRMI Pg ARGhods” means skip all Pg readings from GRMI by the author “ARGhods”
  • “skip * * ARGhods” means skip all readings from the author “ARGhods”

Readings with blank phase code can be skipped by giving “blank” (without quotes) as the phase code. The command can be issued multiple times, up to the limit specified by n_skip_max.

splt (Seismicity PLoT) specifies whether a “seismicity map” will be made. This type of plot indicates event locations by open circles of 1 km diameter and relocation vectors, but does not carry event numbers. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

spou (S-P OUtput file) specifies that a special file containing all S-P arrivals in the dataset will be written. It will have the filename suffix “.sp”. If no argument is given, the status is toggled. The arguments “off” and “on” can be used to set the state explicitly.

sstn (Supplemental STatioN data) specifies the pathname of a file containing coordinates for stations missing from the main station file. These files are often stored in the “tables/stn/” subdirectory, but can be stored elsewhere, including the cluster data directory. Several formats are supported, specified by an integer in the first column of the first line:

  • 0 – New master station file format, from April 28, 2014
  • 1 – ISC FFB format, (deg-min-sec*10)
  • 2 – SEISAN format, (deg-decimal min)
  • 3 – simplified “mloc” format, decimal degrees, geographic coordinates
  • 4 – China Seismic Bureau format
  • 5 – NEIC format
  • 6 – MSU format (used by Kevin Mackey)
  • 9 – Former master station file format (used index “0”)

There is a support document describing the formats in detail. The command can be called multiple times, up to the value of n_supp_stn_file_max.

star (STAR plot) is used to specify the plotting of a solid red star at the location of the current event in the map plots by GMT. This is normally used to highlight events of special interest, such as a mainshock and major aftershocks. The command takes one argument, the size of the circumscribing circle (recommended sizes are in the range 0.2-0.5). The command can be issued up to 10 times.

stat (STATion plot) is used to specify the parameters of a triangle that will be plotted in the map plots by GMT. The command takes three arguments: latitude and longitude of the center point and size of the circumscribing circle (0.30 is a good choice). The command can be issued up to 30 times.

step (STEP) specifies the number of iterations to run. It takes one argument, an integer between 0 and the maximum number of iterations allowed (4). If the convergence criteria are met before the specified number of iterations, the program ends as usual. An “iteration” is counted when the current hypocenters are updated. step 0 is equivalent to the old fwd command. The residuals to the starting locations will be calculated and the program will exit. No inversion or iteration will be done.

stop aborts the current run while still in the command processing phase. It is normally used when some aspect of the reading of a command file (or interactive input) has gone wrong. It is not needed in normal operation, and cannot be issued after the run command has been given.

subc (SUBCluster) specifies the parameters to use to select events that would be most suitable for a high-quality subcluster with direct calibration. Three parameters are required:

  • 1 – the maximum epicentral distance
  • 2 – the minimum number of readings within that distance
  • 3 – the minimum number of station-phases in common with other events in the cluster

The main body (i.e., event definition blocks) of the corresponding command file is written to the .log file.

taup (Tau-P) specifies a global travel time model using the tau-p formulation. Currently, ak135 is the only option. The command takes a single argument, the model name. The associated “.tbl” and “.hed” files must be stored in the “tables/tau-p” subdirectory.

terr (Timing ERRor) makes a static correction to arrival times at a specified station. The correction is applied to all phases. The command takes two arguments, the station code and time correction. The command can be issued up to 4 times.

tfil (Travel-time spread FILe) specifies a .ttsprd file to be opened for reading the empirically-derived spreads of different phases. The file is expected to be in the data directory, so the argument of the command is just the filename, not the full pathname. Revert to the default values by entering the argument “default”.

tikh (TIKHonov regularization) specifies the value to be used for Tikhonov regularization of the perturbations for cluster vectors. If a value of 0 is used (default) there is no regularization. For data sets exhibiting convergence problems it may be helpful to set a non-zero (positive) value. Determination of the optimal value is a non-trivial task, but values in the range 0.2-0.6 seem to be about right for this application.

time (origin TIME) specifies a starting origin time. It requires three arguments (hours, minutes, seconds). Unlike other location parameters there is never a need to set all starting origin times to a common value, so it can only be aplied to the current event. If the time command is not applied to an event, the time read from the input data file or from an HDF file will be used as the starting value.

tlog (Tau-p LOG) specifies that details of the tau-p calculations will be written to the taup log file (~.taup). This is used for debugging the tau-p code only! The output file can exceed 500 MB for moderately large clusters. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

tomo (TOMOgraphy) specifies output files for tomography. This command requires two arguments, a phase name and a flag for which kind of data to extract:

  • 1 = Extract all readings of the specified phase
  • 2 = Extract only readings which were used for the cluster vectors
  • 3 = Extract empirical path anomalies

The tomo command can be issued multiple times, up to the limit specified by the variable nitomomax.

tptt (T-Phase Travel Time) specifies an intercept (sec) and slope (sec/degree) to be used in calculating travel tiems for T-phases. Default: 15. and 75., respectively.

tt5e (Travel Time type 5 plot for a single Event) allows a type 5 plot (local distance, out to 4°) to be made for a single event. The command takes a single argument, the event name (as given in the even command. The command can be issued multiple times, up to the limit specified by n_tt5e_max.

tt5s (Travel Time type 5 plot for a single Station) allows a type 5 plot (local distance, out to 4°) to be made for a single event. The command takes a single argument, the station code (case-sensitive). The command can be issued multiple times, up to the limit specified by n_tt5s_max.

ttou (Travel Time OUtput) specifies that an output file of empirical travel time data will be written for a specific phase. The command takes a single argument, the phase name (case sensitive). The command may be issued multiple times, up to the limit in n_ttou_max. S-P is supported but the format of the output file is different.

vect (VECTors) controls the plotting of four types of relocation vectors:

  • From data file epicenter to final location, either calibrated or uncalibrated, in black
  • From starting location to final location (but not with calibration shift), in green
  • Calibration shift, for indirect calibration, in red
  • Residual calibration shift, for indirect calibration, in blue

The command takes four arguments which must be either 0 or 1, to set the plotting of these vectors. The default state is TRUE for all four vectors.

vlog (Verbose LOG) specifies that extra information about the HD analysis will be written to the log file. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

vscr (Verbose SCReen) specifies that extra information about the HD analysis will be written to the terminal window. Issuing the command without arguments toggles the current state. The arguments “on” and “off” may be used to set the state explicitly. Default is “off”.

weig (WEIGht) determines if the data (residuals) are weighted equally (“off”), or if the data will be weighted inversely to their reading error (“on”). Issuing the command with no argument toggles the current state. Default is “on”.

wind (WINDowing) specifies two parameters (and an optional third one) used to define windows for each phase that are used to cut readings with large residuals out of the problem. The parameters given here are multipliers for the travel time spread assigned to each phase. The travel time spreads can be taken from default values or read from a .ttsprd file from a previous run. Default values for the multipliers are 3 and 4. With these values, all residuals within 3*tsprd(phase) will be given full weight. Residuals between 3*tsprd(phase) and 4*tsprd(phase) have weights that taper smoothly to zero with a “1-cosine” function. The .ttsprd file also carries a baseline adjustment for each phase that helps keep the window function centered over the actual distribution of that phase, rather than centering it on the ak135 theoretical time for that phase. The optional third parameter is an epicentral distance below which the windows are expanded by a factor of 2. This is used in direct calibration to help keep good readings from being lost because of a poor starting location. The default value is 1.2 degrees. Weights assigned via the wind command are written to the .phase_data output file.

xsec (X-SECtion) controls the plotting of cross-sections. The command takes six arguments:

  • Latitude of the first end-point
  • Longitude of the first end-point
  • Latitude of the second end-point
  • Longitude of the second end-point
  • Depth (km) of the cross-section (all sections start at zero depth)
  • Full width (km) of the cross-section

Multiple cross-sections can be defined, up the limit set by the parameter n_xsec_max.