invert4geom.optimize_regional_eq_sources

invert4geom.optimize_regional_eq_sources#

optimize_regional_eq_sources(testing_df, grav_ds, score_as_median=False, true_regional=None, n_trials=100, depth_limits=None, block_size_limits=None, damping_limits=None, grav_obs_height_limits=None, sampler=None, plot=False, plot_grid=False, optimize_on_true_regional_misfit=False, separate_metrics=True, progressbar=True, parallel=False, fname=None, seed=0, **kwargs)[source]#

Run an Optuna optimization to find the optimal equivalent source parameters for estimating the regional component of gravity misfit. For synthetic testing, if the true regional grid is provided, the optimization can be set to optimize on the RMSE of the predicted and true regional gravity, by setting optimize_on_true_regional_misfit=True. By default this will perform a multi-objective optimization to find the best trade-off between the lowest RMSE of the residual at the constraints and the highest RMSE of the residual at all locations.

Parameters:

  • testing_df (DataFrame) – constraint points to use for calculating the score with columns “easting”, “northing” and “upward”.

  • grav_ds (Dataset) – gravity dataset with coordinates “easting”, “northing”, and variables “reg” and gravity_anomaly.

  • score_as_median (bool) – use the root median square instead of the root mean square for the scoring metric, by default False

  • true_regional (DataArray | None) – if the true regional gravity is known (in synthetic models), supply this as a grid to include a user_attr of the RMSE between this and the estimated regional for each trial, or set optimize_on_true_regional_misfit=True to have the optimization optimize on the RMSE, by default None

  • n_trials (int) – number of trials to run, by default 100

  • depth_limits (tuple[float, float] | None) – limits to use for source depths, positive down in meters, by default None

  • block_size_limits (tuple[float, float] | None) – limits to use for block size in meters, by default None

  • damping_limits (tuple[float, float] | None) – limits to use for the damping parameter, by default None

  • grav_obs_height_limits (tuple[float, float] | None) – limits to use for the gravity observation height in meters, by default None

  • sampler (BaseSampler | None) – customize the optuna sampler, by default TPE sampler

  • plot (bool) – plot the resulting optimization figures, by default False

  • plot_grid (bool) – plot the resulting regional gravity grid, by default False

  • optimize_on_true_regional_misfit (bool) – if true_regional grid is provide, choose to perform optimization on the RMSE between the true regional and the estimated region, by default False

  • separate_metrics (bool) – if False, returns the scores combined with the formula residual_constraints_score / residual_amplitude_score, by default is True and returns both the residual and regional scores separately.

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

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

  • fname (str | None) – file name to save the study to, by default None

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

  • kwargs (Any) – additional keyword arguments to pass to the DatasetAccessorInvert4Geom.regional_separation

Return type:

tuple[Study, Dataset, FrozenTrial]

Returns:

  • study (optuna.study.Study) – the completed Optuna study

  • resulting_grav_ds (xarray.Dataset) – the resulting gravity dataset of the best trial

  • best_trial (optuna.trial.FrozenTrial) – the best trial