TongaLau_Spherical.yml

The inversion is controlled by a single YAML configuration file, typically named TongaLau_Spherical.yml. This file defines all key parameters related to the model setup, data paths, inversion priors, and MCMC sampling strategy in a human-readable format.

When the inversion begins, QtomoMCMC will automatically create a directory named after the YAML file (e.g., TongaLau_Spherical/) to store output models and figures.

Note: You can run multiple experiments simply by providing different YAML files with custom settings (e.g., test1.yml, etc.).

The file is organized into six main blocks:

+-------------------------+
|  TongaLau_Spherical.yml |
+-------------------------+
|  Inversion Settings     |
|  File Paths             |
|  Voronoi Parameters     |
|  Monte Carlo Parameters |
|  Map Parameters         |
|  Plotting Parameters    |
+-------------------------+

Each block is described below.

1. Inversion Settings

These parameters are used for the initial inversion settings.

Parameter	Description
coordinates	Coordinate system: 1 = spherical, 2 = Cartesian. Affects model setup, ray geometry, and interpolation.
lon0, lat0, beta	Origin and rotation angle (in radians). ⚠️ Used only when coordinates = 2 (Cartesian mode).
debug_prior	Debug mode toggle: 0 = normal inversion, 1 = test mode. ⚠️ Use only to validate code behavior.
plot_voronoi	If true, plots individual Voronoi cells per model. ⚠️ Enable only when computational resources permit.
add_yVec	Enables full 3D inversion when set to 1. ⚠️ 2D/1D options are experimental and not yet fully supported.
add_systematic_tsterr	Whether to add a constant systematic error to all t* values.
systematic_tsterr	Magnitude (in seconds) of the systematic t* error to be added.
ray_interpolate	If true, interpolates ray paths to improve model resolution.
seg_len	Maximum segment length (in km) when splitting rays for interpolation.
interp_depth	Maximum depth (in km) to which raypaths are interpolated.
add_litho	If true, includes a fixed lithospheric layer with low attenuation (from PREM).
litho_thickness	Thickness (in km) of the lithosphere layer, typically based on lithospheric age.

2. File Paths

These parameters define the input files required for inversion. All paths are relative to the working directory unless specified.

Parameter	Description
DataDir	Directory containing input data files (e.g., raypaths, t*, stations).
PREM	Path to the 1-D PREM attenuation model. Used to initialize the low-attenuation lithosphere layer.
sta_info	Station metadata file (station name, longitude, latitude, elevation).
vel_type	Velocity model type selector: 1-3. They will be specified in the next section.
vel_file	The velocity model file.
tstar_file	The input t* data.
rayp_file	The input raypath data, matching the coordinate system specified.

3. Voronoi Diagram Parameters

These parameters control the spatial parameterization of the model using Voronoi cells and the statistical properties of the prior distribution.

Parameter	Description
sig	Spread of model parameters (as a percentage). Applies globally to all sampled parameters. 0.1 is a good choice.
zeta_scale	Maximum number of zeta (1000/Q) in the prior distribution when building the initial model.
max_cells	Maximum number of Voronoi cells in the prior distribution when building the initial model.
min_cells	Minimum number of Voronoi cells in the prior distribution when building the initial model.
max_sig	Maximum allowable uncertainty on t* ⚠️ (currently unused. Refer to perturbation of errors in Byrnes and Bezada, 2020
interp_style	Interpolation method for mapping Voronoi to output grid: 1 = nearest neighbor, 2 = inverse distance weighting.
enforce_discon	Set to 0. ⚠️ experimental feature: If nonzero, applies a pre-defined discontinuity in the model
prior	Prior distribution type: 1 = uniform (usually for absolute t*), 2 = normal (usually for relative t*), 3 = exponential (not recommended)

4. Monte Carlo Parameters

These parameters control how the transdimensional MCMC sampling is run, saved, and monitored during inversion.

Parameter	Description
n_chains	Number of MCMC chains launched per script (can be parallelized).
n_iter	Total number of iterations per chain.
burn_in	Number of initial iterations to discard before saving models.
keep_each	Save interval (e.g., 10 = save every 10 iterations after burn-in).
print_each	Console print interval. Useful for tracking progress in real time.
save_percent	Checkpointing frequency, as a percentage of total iterations.

5. Map Parameters

These parameters define the spatial domain and gridding for inversion and visualization.

Parameter	Description
max_depth	Maximum depth of the inversion domain (in km).
min_depth	Minimum depth (in km). Usually 0 for surface.
buffer_cart	Horizontal buffer (in km) when using Cartesian coordinates. Adds margin beyond the station extent.
buffer_sph	Horizontal buffer (in degree) when using Spherical coordinates. Adds margin beyond the station extent.
ZnodeSpacing	Vertical grid spacing (in km) used for interpolation and visualization in both coordinates. Not used in inversion.
XYnodeSpacing	Horizontal grid spacing (in km) used for interpolation and visualization in Cartesian coordinates. Not used in inversion.
latlonnodeSpacing	Lat/Lon grid spacing (in degrees) used for interpolation and visualization in Spherical coordinates. Not used in inversion.

6. Plot Cross Section Parameters

These parameters control the visualization of inverted models.

The options cmax, xyMap, z0, xzMap, and y0 are used to plot cross sections directly in Julia for quick inspection and diagnostics. For publication-quality figures, it is recommended to export the results and use GMT (Generic Mapping Tools).

Parameter	Description
average_style	Method for averaging models across chains:
	1 = Arithmetic mean
	2 = Bayesian Model Averaging (BMA) (recommended)
	3 = Inverse variance weighting
	4 = Likelihood weighting
cmax	Maximum value for 1000/Q colorbar. Controls color scale for all figures.
xyMap	If true, plot x-y (horizontal) slices at specified z0 depths.
z0	Depth values (in km) for horizontal slices. Example:
	- 50
	- 100
	- 300
	- 500
xzMap	If true, plot x-z (vertical) slices at specified y0 locations.
y0	Horizontal coordinates (in km) for vertical slices. Example:
	- -20

/Data

This directory contains all input data files required to run the inversion.

1. PREM_1s.csv

Use this file as provided in the example folder. It contains the reference attenuation values from the PREM model and is required only if add_litho = true (to apply a low-attenuation lithosphere prior).

2. stations.dat

A plain text file listing all seismic stations used in the inversion.

Format:

StationName Latitude Longitude Elevation

• Elevation is in meters (positive above sea level; negative for ocean-bottom stations).

3. vel_file

The three types of velocity files are provided in the example folder

⚠️ Can modify function load_vel_type1-3 in ./scripts/load.jl to adapt to customized input velocity model

4. tstar_file

In the current configuration, in the Spherical Coordinates

Format:

eventID StationName Latitude Longitude Depth t* error misfit AverageAttenuation

in the Cartesian Coordinates

Format:

StationName Latitude Longitude Depth t* error misfit AverageAttenuation

• Depth is in kilometers (positive beneath sea level).
• t* is the measured attenuation parameter for each raypath.
• error is the uncertainty of the measured t*.
• AverageAttenuation is calculated using (1000 x t*) / t, where t is the travel time of the raypath.

5. rayp_file

The ray path files in Cartesian and Spherical coordinates are provided in the example folder

⚠️ Can modify prepare_data.jl to adapt to customized input ray path files