mc_fit_plot options

The behavior of the mc_fit plotting scripts is controlled by logical switches and user parameters defined near the beginning of each MATLAB script. These options control unit conversion, statistical filtering, graphical elements, legend formatting, auxiliary plotting scripts, and figure export.

Unless a default is explicitly identified as script-specific, the default listed below is the value used by the standard mc_fit_plot workflow. The options most relevant to interpreting the standard figure are discussed in mc_fit_plot; this chapter provides the complete reference.

Only the imprecision filter is fundamental to the uncertainty strategy. Other filters, including the fit-all-data filter and objective-function outlier filters, are diagnostic or practical filters applied to the data delivered by mc_fit.

Option keywords grouped by functionality

—

Unit conversion

Warning

Only one of convert_to_MPa, convert_to_kbar, or convert_to_GPa may be true.

—

Statistical interpretation

—

Filtering and model classification

—

Graphical presentation

—

Diagnostic and console output

—

Figure export

—

Multi-panel and auxiliary plotting scripts

Option details

—

arrow_line_width

Type: real; Default: get(groot,'DefaultLineLineWidth')

Line width used by mc_fit_imprecision_band_plot for arrows and guide lines associated with the imprecision interval.

—

ask_projection

Type: logical; Default: true

If true, mc_fit_imprecision_band_plot prompts the user to choose the projection. If false, the script uses the value specified by projection.

—

auto_filled_symbols_for_nofit

Type: logical; Default: true

If true, the marker-fill convention is inferred automatically from the distribution of the fit-all-data criterion. If all, none, or only some models fit all data, the script chooses the convention intended to make the plotted distinction most useful.

—

cap_fraction

Type: real; Default: 0.10

Relative half-length of error-bar caps, expressed as a fraction of the corresponding orthogonal uncertainty. For example, a value of 0.10 sets cap lengths to 10% of the orthogonal error magnitude.

—

convert_to_C

Type: logical; Default: false

If true, temperature is converted from K to \(^\circ\mathrm{C}\).

—

convert_to_GPa

Type: logical; Default: false

If true, pressure is converted from bar to GPa.

—

convert_to_kbar

Type: logical; Default: true

If true, pressure is converted from bar to kbar.

—

convert_to_MPa

Type: logical; Default: false

If true, pressure is converted from bar to MPa.

—

export_resolution

Type: integer; Default: 300

Resolution, in dots per inch, used by mc_fit_multi_plot when exporting the combined multi-panel figure as a bitmap image.

—

filled_symbols_for_nofit

Type: logical; Default: false

Used only if auto_filled_symbols_for_nofit is false.

Controls the marker-fill convention for the fit-all-data criterion. If true, filled symbols denote models that do not fit all data. If false, filled symbols denote models that do fit all data.

—

filter

Type: logical; Default: varies by script

If true for central-model results, central models are filtered using the perturbation-derived misfit imprecision. The retained central models are used to characterize aleatoric uncertainty. If false, central-model results are plotted without this automatic imprecision filter.

—

fitonly_prompt

Type: logical; Default: true

If true, the user is prompted whether to retain only models that satisfy the fit-all-data criterion. If false, this fit-based prompt is suppressed.

—

interval_alpha

Type: real; Default: 0.10

Transparency of the shaded imprecision interval in mc_fit_imprecision_band_plot. A value of 0 is fully transparent, and a value of 1 is fully opaque.

—

interval_color

Type: RGB triplet; Default: [1.0 0.85 0.0]

Fill color used by mc_fit_imprecision_band_plot for the shaded imprecision interval.

—

interval_label_factor

Type: real; Default: 1.10

Horizontal label-position factor used by mc_fit_imprecision_band_plot when annotating the imprecision interval relative to the best central model coordinate.

—

legend_coord_digits

Type: integer; Default: 4

Number of significant digits used for model coordinates printed in legend entries, including the best central model, best overall model, and MPP coordinates.

—

legend_sigma_digits

Type: integer; Default: 2

Number of significant digits used for uncertainties and imprecision values printed in legend entries, including \(\sigma\) values and \(\epsilon_{\ln(\mathrm{Misfit})}\).

—

maksub

Type: logical; Default: varies by script

If true, function_to_do_mc_fit_plots creates its own subplot layout. If false, the function plots into the current or supplied axes. This option is mainly useful for scripts that compose custom layouts.

—

manual_filter

Type: logical; Default: varies by script

If true, the user may apply a manual filter to the transformed objective-function range, e.g., to restrict the plotted interval in ln(misfit) or ln(Bayes). If false, this manual filtering dialog is suppressed.

—

outfile_base

Type: character vector or string; Default: 'combined_mc_fit_multi_plot'

Base name used by mc_fit_multi_plot when exporting the combined multi-panel figure. The output directory is taken from the first selected input file.

—

outlier_filter

Type: logical; Default: true

Master switch for objective-function outlier filtering of perturbation results. Outlier filtering is a practical filter applied to the perturbation data delivered by mc_fit; it is not part of the central-to-perturbation inversion strategy itself.

If true, the enabled outlier filters are applied to the transformed objective-function values immediately before estimating the misfit imprecision, data uncertainty, and covariance. The filtered perturbation results are subsequently used to identify the central models retained for estimating aleatoric uncertainty.

Outlier filtering is applied only to perturbation results and only when the plotting script requests filtering. In the standard mc_fit_plot workflow this means filter = true and model = "Perturbation". Central-model results are not outlier-filtered. However, because central-model filtering in mc_fit_plot uses the perturbation-derived imprecision estimate, perturbation outlier filtering can affect which central models are retained and plotted.

—

outlier_filter_convergence

Type: real; Default: 0.01

Convergence threshold for the robust one-sided z-filter.

Filtering terminates when the fractional change in the number of retained perturbation results between successive iterations is less than this value. For example, a value of 0.01 causes filtering to stop when fewer than 1% of the retained perturbation results are eliminated in an iteration.

Smaller values may increase computational cost without materially changing the resulting uncertainty estimates.

—

outlier_filter_delta_z

Type: logical; Default: false

If true, perturbation results are filtered by their distance from the best value of the transformed objective function.

For ln(misfit), smaller values are better and a model is rejected if

\[\ln(\mathrm{misfit}) - \ln(\mathrm{misfit})_\mathrm{best} > \mathrm{outlier\_filter\_delta\_z\_max}.\]

For ln(Bayes), larger values are better and a model is rejected if

\[\ln(\mathrm{Bayes})_\mathrm{best} - \ln(\mathrm{Bayes}) > \mathrm{outlier\_filter\_delta\_z\_max}.\]

The number of models eliminated by this filter is written to the MATLAB console. If both outlier_filter_z and outlier_filter_delta_z are enabled, the delta-z filter is applied after the robust one-sided z-filter and reports only the additional models it removes.

Warning

The delta-z filter is a robust diagnostic filter, not a formal hypothesis test. It excludes perturbation models that are much worse than the best model according to the objective function. The cutoff should therefore be chosen deliberately and reported when results depend on it.

—

outlier_filter_delta_z_max

Type: real; Default: 3.91

Maximum allowed difference from the best transformed objective-function value for the outlier_filter_delta_z filter.

For ln(misfit), the default value corresponds approximately to allowing models whose misfit is at most 50 times larger than the best perturbation model:

\[\ln(50) \approx 3.91.\]

Smaller values make the filter more restrictive; larger values make it more permissive.

—

outlier_filter_iterations

Type: integer; Default: 10

Maximum number of iterations for the robust one-sided z-filter controlled by outlier_filter_z.

Increasing this value may improve the robustness of the imprecision estimate when extreme poor-fit z-outliers are present. Excessive iteration, however, can progressively contract the retained perturbation cloud and remove legitimate tail structure.

Note

Filtering terminates early if no additional models are eliminated or if the convergence criterion specified by outlier_filter_convergence is satisfied.

—

outlier_filter_z

Type: logical; Default: true

If true, perturbation results are filtered iteratively using a robust, one-sided z-filter applied to the transformed objective-function variable, e.g., ln(misfit) or ln(Bayes).

At each iteration, the filter centers the retained z-values on their median, estimates the scale from 1.4826*MAD, and rejects only the bad tail of the distribution. For ln(misfit), high-z values are rejected; for ln(Bayes), low-z values are rejected. The best retained perturbation model is protected from rejection.

The cutoff is the 99% normal-equivalent value sqrt(6.6348). The number of models eliminated at each iteration is written to the MATLAB console.

This filter is intended to remove anomalously poor perturbation solutions without rejecting unusually good solutions. For a filter based on distance from the best transformed objective-function value, use outlier_filter_delta_z.

—

outPDF

Type: logical; Default: false

If false, figures are exported as PNG bitmap files. If true, figures are exported as vector PDF files.

—

plotbst

Type: logical; Default: true

If true, the best overall model is highlighted and identified in the perturbation-analysis legend when its objective-function value is better than that of the best central model. If false, the best overall model is not highlighted separately.

The best overall model remains part of the perturbation ensemble used to estimate data uncertainty. Its separate identification is diagnostic: it indicates that the perturbation analysis found a model with lower misfit than the best central model.

—

plotbst_default

Type: logical; Default: true

Used by mc_fit_multi_plot to determine whether the best overall model is plotted in panels generated from perturbation files.

—

plotcov

Type: logical; Default: varies by script

If true, a covariance ellipse is plotted where applicable. If false, the ellipse is omitted.

—

ploterr

Type: logical; Default: true

If true, error bars are plotted where applicable. If false, error bars are omitted.

—

plotMPP

Type: logical; Default: false

If true, the maximum prior probability (MPP) coordinate is plotted. If false, the MPP is not shown.

—

print

Type: logical; Default: true

If true, figure properties are adjusted for print-quality output (larger fonts, thicker lines). If false, settings are optimized for on-screen display (e.g., presentations).

—

printz

Type: logical; Default: varies by script

If true, the value of the third plotted variable (typically ln(misfit)) is included in legend entries for best models. If false, only the first two plotted variables are shown.

—

projection

Type: character vector or string; Default: 'xz'

Used by mc_fit_imprecision_band_plot to choose the imprecision-interval projection. The value 'xz' plots the x variable against ln(misfit) or ln(Bayes); 'yz' plots the y variable against the transformed objective function.

—

sigma_level

Type: real; Default: 1

Scaling factor that controls the imprecision interval (\(\pm \mathrm{sigma\_level}\,\epsilon_{\ln(\mathrm{misfit})}\)) used for filtering central model results and the visual scaling of uncertainty.

Error bars are scaled linearly:

\[\pm \, \mathrm{sigma\_level} \, \sigma\]

Covariance ellipses are scaled by mapping the 1D Gaussian sigma-level to a 2D confidence region:

\[p = \mathrm{erf} \left( \frac{\mathrm{sigma\_level}}{\sqrt{2}} \right), \quad c = \chi^2_2(p)\]

with ellipse defined by:

\[(\mathbf{x} - \boldsymbol{\mu})^T \Sigma^{-1} (\mathbf{x} - \boldsymbol{\mu}) = c\]

Hence:

\[\mathrm{sigma\_level} = 1 \;\Rightarrow\; p \approx 0.68, \quad \mathrm{sigma\_level} = 2 \;\Rightarrow\; p \approx 0.95\]

This is an informal correspondence between 1D and 2D uncertainty; it is exact only for Gaussian statistics.

Warning

sigma_level in mc_fit_plot corresponds to the sigma_multiplier option in mc_fit. These options must be consistent if the fit-all-data criterion is used to filter central model results in mc_fit_plot.

—

target_rse

Type: real; Default: 0.2

Target relative standard error used to assess whether the sample size is sufficient for reliable estimation of standard deviation.

The required number of samples is estimated as:

\[n_{\mathrm{req}} = \left\lceil 1 + \frac{1}{2\,\mathrm{target\_rse}^2} \right\rceil\]

If fewer than \(n_{\mathrm{req}}\) points are available, a warning dialog is issued and the user must choose whether to continue.

target_rse is independent of sigma_level and cap_fraction. target_rse controls only the warning threshold for small sample size; it does not change the plotted uncertainties or the filtering of models.