invert4geom.DatasetAccessorInvert4Geom.regional_constraints

invert4geom.DatasetAccessorInvert4Geom.regional_constraints#

DatasetAccessorInvert4Geom.regional_constraints(constraints_df, grid_method='eq_sources', constraints_block_size=None, constraints_weights_column=None, tension_factor=1, spline_dampings=None, depth=None, damping=None, cv=False, block_size=None, grav_obs_height=None, cv_kwargs=None, regional_shift=0, mask_column=None, reverse_regional_residual=False)[source]#

Calculate the gravity misfit as the difference between dataset variables gravity_anomaly and forward_gravity. Then separate the misfit into regional and residual components where residual = misfit - regional.

Approximate the regional field by sampling the gravity misfit at constraint points (points of known elevation of the layer of interest) and interpolating those sampled values. The interpolation can be accomplished with the following methods:

Equivalent sources (grid_method=”eq_sources”)
Tensioned splines (grid_method=”pygmt”)

  • uses pygmt.surface

  • amount of tension (0-1) can be set with tension_factor

Bi-harmonic splines (grid_method=”verde”)

  • uses verde.Spline

  • amount of damping can be set with spline_dampings, or a list of damping values can be provided to find the optimal damping through cross-validation using optimal_spline_damping

If there are many constraints, they can be block reduced with constraints_block_size and optional constraints_weights_column can be used to weight the constraints during block reduction.

The resulting regional field can be shifted with regional_shift, and the calculated residual field can be multiplied by the values in mask_column.

The following new variables are added to the dataset: misfit, reg, res, starting_forward_gravity, starting_misfit, starting_reg, starting_res

Parameters:

  • constraints_df (DataFrame) – dataframe of constraints with columns easting, northing (or longitude, latitude), and upward.

  • grid_method (str) – method used to grid the sampled gravity data at the constraint points. Choose between verde, pygmt, or eq_sources, by default eq_sources

  • constraints_block_size (float | None) – size of block used in a block-mean reduction of the constraints points, by default None

  • constraints_weights_column (str | None) – column name for weighting values of each constraint point. Used if constraints_block_size is not None or if grid_method is verde or eq_sources, by default None

  • tension_factor (float) – Tension factor used if grid_method is pygmt, by default 1

  • spline_dampings (float | list[float] | None) – damping values used if grid_method is verde, by default None

  • depth (float | str | None) – depth of each source relative to the data elevation, positive downwards in meters, by default None

  • damping (float | None) – damping values used if grid_method is eq_sources, by default None

  • cv (bool) – use cross-validation to find the best equivalent source parameters, by default False, provide dictionary cv_kwargs which is passed to optimization.optimize_eq_source_params and can contain: n_trials, damping_limits, depth_limits, block_size_limits, and progressbar.

  • block_size (float | None) – block size used if grid_method is eq_sources, by default None

  • grav_obs_height (float | None) – Observation height to use if grid_method is eq_sources, by default None

  • cv_kwargs (dict[str, Any] | None) – additional keyword arguments to be passed to optimize_eq_source_params, by default None. Can contain: n_trials, damping_limits, depth_limits, block_size_limits, sampler, plot, progressbar, parallel, fname, dtype, or delayed.

  • regional_shift (float) – shift to add to the regional field, by default 0

  • mask_column (str | None) – Name of optional dataset variable with values to multiply the calculated residual gravity field by, should have values of 1 or 0, by default None.

  • reverse_regional_residual (bool) – if True, reverse the regional and residual fields after calculation, by default False

See also

DatasetAccessorInvert4Geom.regional_separation

Return type:

None