NLLoc

Parameters

This section describes the parameters specific to the location code NLLoc. These parameters can be grouped in the following categories:

Comments, IDs

  • LOCSIG: Identification of individual or agency running the location code.

  • LOCCOM: Comment about location run (event, sequence, tests, ...).

Location method

  • LOCGRID: defines the grid to perform the search (initial and optionally nested grids).

  • LOCSEARCH: search method to use (exhaustive grid search, Metropolis, Octtree).

  • LOCMETH: location method to use (Tarantola and Valette, EDT, ...).

Stations, phases and travel times

  • LOCPHASEID: maps phase names (e.g., Pg, pg, Sn, ...) into standard names P and S.

  • LOCALIAS: sets aliases for stations with same location but different location codes.

  • LOCEXCLUDE: exclude arrival times for some stations and phases.

  • LOCDELAY: define P and S station corrections.

  • LOCELEVCORR: defines Vp and Vs for calculating elevation correction.

  • LOCSTAWT: defines distance for station distribution weighting.

  • LOCQUAL2ERR: maps HYPO71 weights (0, 1, 2, 3, 4) to time uncertainties.

  • LOCSRCE: defines stations that use default travel time grid.

  • LOCGAU: sets parameters for Gaussian covariances.

  • LOCGAU2: sets parameters for travel-time dependent model errors.

Data and output files

  • LOCFILES:

  • LOCHYPOUT:

Output information

  • LOCPHSTAT:

  • LOCANGLES:

  • LOCMAG:

  • LOCCMP:

Miscellaneous

  • LOCTOPO_SURFACE:

LOCSRCE - LOCGAU - LOCGAU2

LOCSIG

Identification of an individual, institution or other entity. Written in some output files.

Syntax:

LOCSIG signature

LOCCOM

Comment about location run. Written in some output files.

Syntax:

LOCCOM comment

LOCFILES

Specifies the directory path and filename for the phase/observation files, and file root names (no extension) for the input time grids and the output files.

Syntax: 

LOCFILES obsFiles obsFileType ttimeFileRoot outputFileRoot iSwapBytes
  • obsFiles: full or relative path and name for phase/observations files. Mulitple files may be specified with standard UNIX "wild-card" characters * and ?.
  • obsFileType: format type for phase/observations files (see Phase File Formats). Valid values are: NLLOC_OBS HYPO71 HYPOELLIPSE NEIC CSEM_ALERT SIMULPS HYPOCENTER HYPODD SEISAN NORDIC NCSN_Y2K_5 NCEDC_UCB ETH_LOC RENASS_WWW RENASS_DEP INGV_BOLL INGV_BOLL_LOCAL INGV_ARCH
  • ttimeFileRoot: full or relative path and file root name (no extension) for input time grids generated by program Grid2Time, edu.sc.seis.TauP.TauP_Table_NLL, or other software.
  • outputFileRoot: full or relative path and file root name (no extension) for output files.
  • iSwapBytes: flag to indicate if high and low bytes of input time grid files should be swapped. Allows reading of travel-time grids from different computer architecture platforms during TRANS GLOBAL mode location. 0 = no swap, 1 = swap [default = 0].

LOCHYPOUT

Specifies the filetypes to be used for output.

Syntax:

LOCHYPOUT fileType1 [fileType2 ...]

Valid file types are: AVE_NLLOC_ALL SAVE_NLLOC_SUM NLL_FORMAT_VER_2 FILENAME_DEC_SEC SAVE_NLLOC_EXPECTATION SAVE_NLLOC_OCTREE SAVE_FMAMP SAVE_HYPOELL_ALL SAVE_HYPOELL_SUM SAVE_HYPO71_ALL SAVE_HYPO71_SUM SAVE_HYPOINV_SUM SAVE_HYPOINVERSE_Y2000_ARC SAVE_NLLOC_OCTREE [ default: SAVE_NLLOC_ALL SAVE_HYPOINVERSE_Y2000_ARC]

  • SAVE_NLLOC_ALL: save summary and event files of type NLLoc Hypocenter-Phase file, Phase Statistics file, Scatter file and Confidence Level file.
  • SAVE_NLLOC_SUM: save summary file only of type NLLoc Hypocenter-Phase file.
  • NLL_FORMAT_VER_2: save NLLoc Hypocenter-Phase files in new format (WARNING: this new output format is currently under development and subject to modification), NLLoc Hypocenter-Phase file, Phase Statistics file, Scatter file and Confidence Level file.
  • FILENAME_DEC_SEC: output file named with 2 decimal second precision instead of default integer second precision. Avoids overwriting of output files for multiple events or multiple locations with earliest observation time in same second.
  • SAVE_NLLOC_EXPECTATION: hypocenter, location statistics and phase statistics results are based on expectation hypocenter instead of maximum likelihood hypocenter (default) NLLoc Hypocenter-Phase file.
  • SAVE_NLLOC_OCTREE: saving of oct-tree structure to disk file when LOCSEARCH OCT is used.
  • SAVE_FMAMP: saving of fmamp hypocenter-phase file for input to fmamp, probabilistic first-motion mechanism program.
  • SAVE_HYPOELL_ALL: save summary and event files of type Quasi-HYPOELLIPSE file.
  • SAVE_HYPOELL_SUM: save summary file only of type Quasi-HYPOELLIPSE file.
  • SAVE_HYPO71_ALL: save summary and event files of type HYPO71 Hypocenter/Station file.
  • SAVE_HYPO71_SUM: save summary file only of type HYPO71 Hypocenter/Station file.
  • SAVE_HYPOINV_SUM: save summary file only of type HYPOINVERSE Archive file.
  • SAVE_HYPOINVERSE_Y2000_ARC: save summary file only of type HYPOINVERSE Y2000 Archive file.

The HYPOINVERSE Archive format serves as input to the program FPFIT (Reasenberg et al., 1985) for grid-search determination of focal mechanism solutions.

LOCMETH

Specifies the location method (algorithm) and method parameters.

Syntax:

LOCMETH method maxDistStaGrid minNumberPhases maxNumberPhases minNumberSphases VpVsRatio maxNum3DGridMemory minDistStaGrid iRejectDuplicateArrivals

  • method: location method/algorithm. Possible values are

    • GAU_ANALYTIC: the inversion approach of Tarantola and Valette (1982) with L2-RMS likelihood function.
    • EDT: Equal Differential Time likelihood function cast into the inversion approach of Tarantola and Valette (1982)
    • EDT_OT_WT: Weights EDT-sum probabilities by the variance of origin-time estimates over all pairs of readings. This reduces the probability (PDF values) at points with inconsistent OT estimates, and leads to more compact location PDF's.
    • EDT_OT_WT_ML: version of EDT_OT_WT with EDT origin-time weighting applied using a grid-search, maximum-likelihood estimate of the origin time. Less efficient than EDT_OT_WT which uses simple statistical estimate of the origin time.

  • maxDistStaGrid: maximum distance in km between a station and the center of the initial search grid; phases from stations beyond this distance will not be used for event location.

  • minNumberPhases: minimum number of phases that must be accepted before event will be located.

  • maxNumberPhases: maximum number of accepted phases that will be used for event location; only the first maxNumberPhases read from the phase/observations file are used for location.

  • minNumberSphases: minimum number of S phases that must be accepted before event will be located.

  • VpVsRatio: P velocity to S velocity ratio. If VpVsRatio > 0.0 then only P phase travel-times grids are read and VpVsRatio is used to calculate S phase travel-times. If VpVsRatio < 0.0 then S phase travel-times grids are used.

  • maxNum3DGridMemory: maximum number of 3D travel-time grids to attempt to read into memory for Metropolis-Gibbs search. This helps to avoid time-consuming memory swapping that occurs if the total size of grids read exceeds the real memory of the computer. 3D grids not in memory are read directly from disk. If maxNum3DGridMemory < 0 then NLLoc attempts to read all grids into memory.

  • minDistStaGrid: minimum distance in km between a station and the center of the initial search grid; phases from stations closer than this distance will not be used for event location.

  • iRejectDuplicateArrivals: flag indicating if duplicate arrivals used for location (1=reject, 0=use if ). Duplicate arrivals have same station label and phase name.

Notes:

  1. See NLLoc Program Inversion Approach for more information on the GAU_ANALYTIC method.
  2. See NLLoc Program EDT likelihood function for more information on the EDT method.
  3. Phases that are not used for location are written to output files and are used for calculating average residuals.

LOCSEARCH

Specifies the search type and search parameters. The possible search types are GRID (grid search), MET (Metropolis), and OCT (Octtree).

Syntax:

LOCSEARCH GRID numSamplesDraw

LOCSEARCH MET numSamples numLearn numEquil numBeginSave numSkip stepInit stepMin stepFact probMin

LOCSEARCH OCT initNumCells_x initNumCells_y initNumCells_z minNodeSize maxNumNodes numScatter useStationsDensity stopOnMinNodeSize

Parameters for GRID method:

  • numSamplesDraw: specifies the number of scatter samples to draw from each saved PDF grid ( i.e. grid with gridType = PROB_DENSITY and saveFlag = SAVE ) No samples are drawn if saveFlag < 0.

Parameters for MET method:

  • numSamples: total number of accepted samples to obtain.
  • numLearn: number of accepted samples for learning stage of search.
  • numEquil: number of accepted samples for equilibration stage of search.
  • numBeginSave: number of accepted samples after which to begin saving stage of search. Denotes end of equilibration stage.
  • numSkip: number of accepted samples to skip between saves. numSkip = 1 saves every accepted sample.
  • stepInit: initial step size in km for the learning stage ( stepInit < 0.0 gives automatic step size selection. If the search takes too long, the initial step size may be too large; this may be the case if the search region is very large relative to the volume of the high confidence region for the locations.)
  • stepMin: minimum step size allowed during any search stage. This parameter should not be critical, set it to a low value.
  • stepFact: step factor for scaling step size during equilibration stage. Try a value of 8.0 to start.
  • probMin: minimum value of the maximum probability (likelihood) that must be found by the end of learning stage, if this value is not reached the search is aborted. This parameters allows the filtering of locations outside of the search grid and locations with large residuals.

Parameters for OCT method:

  • initNumCells_x, initNumCells_y, initNumCells_z: initial number of octtree cells in the x, y, and z directions.
  • minNodeSize: smallest octtree node side length to process. The octree search is terminated after a node with a side smaller than this length is generated.
  • maxNumNodes: total number of nodes to process.
  • numScatter: the number of scatter samples to draw from the octtree results.
  • useStationsDensity: 1 = weights oct-tree cell probability values used for subdivide decision in proportion to number of stations in oct-tree cell. Gives higher search priority to cells containing stations, stablises convergence to local events when global search used with dense cluster of local stations. 0 = do not use weight [default = 0].
  • stopOnMinNodeSize: 1 = stop search when first minNodeSize reached, 0 = stop subdividing a given cell when minNodeSize reached [default = 1].

Notes:

  1. See NLLoc Program Oct-Tree Algorithm, Grid-Search Algorithm and Metropolis Sampling Algorithm for more information.
  2. Samples are saved to a binary, event Scatter file (see Scatter file formats). For the grid-search, because the samples are drawn stochastically, the number of samples actually obtained my differ slightly from the requested number.
  3. If a large number of samples are saved, the spatial density of samples will be proportional to the PDF.
  4. The scatter samples are useful for plotting the PDF as a transparent "cloud" and for relatively compact disk storage of the PDF.

LOCSRCE