invert4geom.optimize_regional_trend

optimize_regional_trend(testing_df, grav_ds, trend_limits, score_as_median=False, true_regional=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)

Run an Optuna optimization to find the optimal trend order 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.

• trend_limits (tuple[int, int]) – limits to use for the trend order in degrees.

• 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

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

• 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

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