fzblender

Produce a smooth blended FZ trace

Synopsis

gmt fzblender [ -D ] [ -Esfilter ] [ -Fpfilter ] [ -IFZid ] [ -Qq_min/q_max ] [ -Sb|d|e|t|u[weight] ] [ -Tprefix ] [ -V[level] ] [ -Zacut/vcut/fcut/wcut ]

Note: No space is allowed between the option flag and the associated arguments.

Description

fzblender is a tool developed as part of the Global Seafloor Fabric and Magnetic Lineation Project [see GSFML for a full description of the project]. It reads an analysis file produced by fzanalyzer and optionally filters those results along track. Then, given the specified signal codes we will produce an optimal FZ track that is a weighted blend between the user’s original digitized trace and one or more of the model traces obtained by fzanalyzer. The blend is based on quality indices determined for the model traces: If the quality index is high we favor this track, else we favor the digitized line; in between values leads to a weighted blend. We expect to read the analysis results from the file prefix_analysis.txt produced by fzanalyzer; the blend results will be written to file prefix_blend.txt. Optionally, the intermediate filtered analysis file can be written to prefix_filtered.txt if -D is given.

Optional Arguments

-D

Do not remove filtered output but save them to prefix_filtered.txt. [By default we delete these intermediate files].

-Esfilter

Apply a secondary filter after the primary required filter has completed. This is sometimes useful if you apply a robust filter first, which may result in short length-scale noise after removing gross outliers. See -F for how to specify the filter.

-Fpfilter

Sets the along-track primary filter. Choose among convolution and non-convolution filters. Append the filter directive followed by the full (6-sigma) width. Available convolution filters are:

  • b: Boxcar: All weights are equal.

  • c: Cosine Arch: Weights follow a cosine arch curve.

  • g: Gaussian: Weights are given by a Gaussian function.

Non-convolution filters are:

  • m: Median: Returns median value.

  • p: Maximum likelihood probability (a mode estimator): Return modal value. If more than one mode is found we return their average value. Append +l or +u to the filter width if you rather want to return the lowermost or uppermost of the modal values.

  • l: Lower: Return the minimum of all values.

  • L: Lower: Return minimum of all positive values only.

  • u: Upper: Return maximum of all values.

  • U: Upper: Return maximum or all negative values only.

In the case of L|| U it is possible that no data passes the initial sign test; in that case the filter will return 0.0.

-IFZid

By default, we will analyze the cross-profiles generated for all FZs. However, you can use -I to specify a particular FZid (first FZid is 0).

-Qq_min/q_max

Sets the range of quality indices that will be used in the blended result. The quality index q(d) ranges from q_min) (0 or bad) to q_max (1 or very good) and varies continuously with distance d along the FZ trace. The quality weight assigned to the modeled FZ trace is w_q(d) = (q(d) - q_min)/(q_max - q_min)), unless w_q(d) > q_max) (w_q(d) = 1) or w_q(d) < q_min) (w_q(d) = 0). You can use the -Q option to change this weight assignment. The quality weight assigned to the digitized FZ trace is w_q(d) = 1 - mean{model quality weights} (see -S). For the calculation of quality indices, see -Z.

-Sb|d|e|t|u[weight]

Specify the model and data traces you wish to blend and the relative custom weights of each [Defaults to 1 for all traces]. Repeat this option for each trace to consider. If you specify more than one model trace then the models are first averaged according to their quality indices and weights before blending with the digitized trace (if specified). Hence, the quality index assigned to the digitized trace is q_r = 1 - mean(model quality indices). The final blend is thus a weighted average that takes into account both the quality indices and the custom weights (if specified). Choose among these directives:

  • b: The trough location for the optimal trough/edge model blend model. This is the best fit obtained to the data using a blend of “Atlantic”-, “Pacific”-, and “Compression”-style synthetic shapes.

  • d: This is the empirical picks of the trough locations along the trace.

  • e: This is the location of maximum slope for the optimal trough/edge model blend model.

  • t: This is the best fit using the “Atlantic”-style trough model only.

  • u: The user’s original digitized trace.

In addition to the blended FZ locations, we also output estimates of the FZ width and the traces of the 1-sigma boundaries on either side of the FZ.

-Tprefix

Sets the file name prefix used for all output files [fztrack].

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-Zacut/vcut/fcut/wcut

We will attempt to assign a single quality index Q that summarize how good we believe a model fit to be. This assignment relies of four threshold values that need to be determined empirically. Here, a_cut is the minimum peak-to-trough amplitude (in Eotvos) of a model for the crossing profile [25], v_cut is the minimum variance reduction offered by the model (in %) [50], f_cu is the minimum F statistic computed for the model [50], and w_cut is a typical FZ trough width (in km) [15]. Currently, the first three quantities are used to arrive at a 5-level quality index (0-1) for fitted models, as follows: (1) Very Good: Requires model parameters to exceed all three thresholds; (0.75) Good: Requires amplitude and variance reduction to exceed thresholds; (0.5) Fair: Requires the variance reduction only to exceed its threshold; (0.25) Poor: Requires the amplitude only to exceed its threshold; and (0) Bad: None of the criteria were met. We compute separate quality indices for the trough and blend models. For the empirical trough model we only have estimates or peak-to-trough amplitude, A, and trough width, W. Here, we form the ratio (A/a_cut) over (W/w_cut), take \(\tan^{-1}\) of this ratio and scale the result to yield the range 0-1 rounded to the nearest multiple of 0.25.

-borecord[+b|l] (more …)

Select native binary format for table output.

-donodata[+ccol] (more …)

Replace output columns that equal NaN with nodata.

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …)

Select input columns and transformations (0 is first column, t is trailing text, append word to read one word only).

-ocols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …)

Select output columns and transformations (0 is first column, t is trailing text, append word to write one word only).

-q[i|o][~]rows|limits[+ccol][+a|t|s] (more …)

Select input or output rows or data limit(s) [all].

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

ASCII Format Precision

The ASCII output formats of numerical data are controlled by parameters in your gmt.conf file. Longitude and latitude are formatted according to FORMAT_GEO_OUT, absolute time is under the control of FORMAT_DATE_OUT and FORMAT_CLOCK_OUT, whereas general floating point values are formatted according to FORMAT_FLOAT_OUT. Be aware that the format in effect can lead to loss of precision in ASCII output, which can lead to various problems downstream. If you find the output is not written with enough precision, consider switching to binary output (-bo if available) or specify more decimals using the FORMAT_FLOAT_OUT setting.

Output Columns

fzblender reports 10 columns of data, which are lon, lat, dist, shift, width, qweight, lon_l, lat_l, lon_r, lat_r, where lon, lat contain the blended track along dist, with across-track widt and shift in origin. The blend obtained a quality weight of qweight, and the four last columns contains the coordinates for the left/right bounds along the FZ.

Filtering

Filtering always runs of of data near the FZ end points. We utilize filter1d with its -E option to extend the result to the end. Because we are filtering data columns that may contain a strong trend (e.g., longitude versus along-track distance) we first remove such linear trends before filtering, then restore the trends before blending. However, you should be cautions in interpreting the blended results close to the ends of the FZs. You can examine the effect of filtering more directly by using the -D option to save the filtered profiles.

Blend Considerations

Note that of the various directives in -S, the e is different in that it reflects the FZ location estimate based on the theoretical prediction that the FZ crossing may be associated with the steepest VGG slope. As such it will be offset from the trough by several km (unless the blend is mostly “Atlantic”) and combining it with the others is unlikely to be productive. It is best used by itself with filtering.

Examples

To produce a weighted average of your digitized trace, the empirical trough locations, and the trough model locations, giving the empirical locations a weight of 2 and the model troughs a weight of 1, reading the file Pac_analysis.txt and selecting a median filter of 70 km width followed by a 50-km Gaussian filter, try:

gmt fzblender -Su1 -Sd2 -St1 -Fm70 -Eg50 -TPac

To produce a smooth trace of the maximum slope locations along track for the same file, we try the same filters with the command:

gmt fzblender -Se -Fm70 -Eg50 -TPac

See Also

gmt fzanalyzer, fzinformer, fzmapper, fzmodeler, fzprofiler, filter1d, mlconverter

References

Wessel, P., Matthews, K. J., Müller, R. D., Mazzoni, A., Whittaker, J. M., Myhill, R., Chandler, M. T., 2015, “Semiautomatic fracture zone tracking”, Geochem. Geophys. Geosyst., 16 (7), 2462–2472. https://doi.org/10.1002/2015GC005853.