invert4geom.Inversion.optimize_inversion_zref_density_contrast

invert4geom.Inversion.optimize_inversion_zref_density_contrast#

Inversion.optimize_inversion_zref_density_contrast(n_trials, constraints_df, n_startup_trials=None, zref_limits=None, density_contrast_limits=None, starting_topography=None, starting_topography_kwargs=None, regional_grav_kwargs=None, score_as_median=False, sampler=None, grid_search=False, fname=None, plot_scores=True, plot_cv=None, logx=False, logy=False, progressbar=True, parallel=False, fold_progressbar=True, seed=0)[source]#

Run an Optuna optimization to find the optimal zref and or density contrast values for a gravity inversion. The optimization aims to minimize the cross-validation score, represented by the root mean (or median) squared error (RMSE), between points of known topography and the inverted topography. Follows methods of Uieda and Barbosa[1]. This can optimize for either zref, density contrast, or both at the same time. Provide upper and low limits for each parameter, number of trials and let Optuna choose the best parameter values for each trial or use a grid search to test all values between the limits in intervals of n_trials. The results are saved to a pickle file with the best inversion results and the study. Since each new set of zref and density values changes the starting model, for each set of parameters this function re-calculates the starting gravity, the gravity misfit and its regional and residual components. regional_grav_kwargs are passed to DatasetAccessorInvert4Geom.regional_separation. Once the optimal parameters are found, the regional separation and inversion are performed again and saved to <fname>.pickle and the study is saved to <fname>_study.pickle. The constraint point minimization regional separation technique uses constraints points to estimate the regional field, and since constraints are used to calculating the scoring metric of this function, the constraints need to be separated into training (regional estimation) and testing (scoring) sets. To do this, supply the training constraints to`regional_grav_kwargs` via method=”constraint” or method=”constraint_cv” and constraints_df, and the testing constraints to this function as constraints_df. Typically there are not many constraints and omitting some of them from the training set will significantly impact the regional estimation. To help with this, we can use a K-Folds approach, where for each set of parameter values, we perform this entire procedure K times, each time with a different separation of training and testing points, called a fold. The score associated with that parameter set is the mean of the K scores. Once the optimal parameter values are found, we then repeat the inversion using all of the constraints in the regional estimation. For a K-folds approach, supply lists of dataframes containing only each fold’s testing or training points to the two constraints_df arguments. To automatically perform the test/train split and K-folds optimization, you can also use the convenience function optimize_inversion_zref_density_contrast_kfolds.

Parameters:

  • n_trials (int) – number of trials, if grid_search is True, needs to be a perfect square and >=16.

  • n_startup_trials (int | None) – number of startup trials, by default is automatically determined

  • zref_limits (tuple[float, float] | None) – upper and lower limits for the reference level, in meters, by default None

  • density_contrast_limits (tuple[float, float] | None) – upper and lower limits for the density contrast, in kg/m^-3, by default None

  • starting_topography_kwargs (dict[str, Any] | None) – dictionary of kwargs to pass to function create_topography which must include “method”. kwargs “region”, “spacing”, “dataset_to_add”, “upper_confining_layer” and “lower_confining_layer” will automatically be collected from the model object and passed to create_topography. provided, by default None

  • regional_grav_kwargs (dict[str, Any] | None) – dictionary with kwargs to supply to DatasetAccessorInvert4Geom.regional_separation, by default None

  • score_as_median (bool) – change scoring metric from root mean square to root median square, by default False

  • sampler (BaseSampler | None) – customize the optuna sampler, by default uses GPsampler unless grid_search is True, then uses GridSampler.

  • grid_search (bool) – Switch the sampler to GridSampler and search entire parameter space between provided limits in intervals set by n_trials (for 1 parameter optimizations), or by the square root of n_trials (for 2 parameter optimizations), by default False

  • fname (str | None) – file name to save both study and inversion results to as pickle files, by default fname is tmp_x_zref_density_optimization where x is a random integer between 0 and 999 and will save study to <fname>_study.pickle and the inversion object to <fname>.pickle.

  • plot_scores (bool) – plot the cross-validation results, by default True

  • logx (bool) – use a log scale for the cross-validation plot x-axis, by default False

  • logy (bool) – use a log scale for the cross-validation plot y-axis, by default False

  • progressbar (bool) – add a progressbar, by default True

  • parallel (bool) – run the optimization in parallel, by default False

  • fold_progressbar (bool) – show a progress bar for each fold of the constraint-point minimization cross-validation, by default True

  • seed (int) – random seed for the samplers, by default 0

  • constraints_df (DataFrame)

  • starting_topography (Dataset | None)

  • plot_cv (bool | None)

Returns:

Inversion object with best inversion results and the optimally determined zref and or density contrast values as attributes of the model attribute.

Return type:

Inversion