invert4geom.regional ==================== .. py:module:: invert4geom.regional Functions --------- .. autoapisummary:: invert4geom.regional._check_grav_cols invert4geom.regional.regional_constant invert4geom.regional.regional_filter invert4geom.regional.regional_trend invert4geom.regional.regional_eq_sources invert4geom.regional.regional_constraints invert4geom.regional.regional_constraints_cv invert4geom.regional.regional_separation Module Contents --------------- .. py:function:: _check_grav_cols(grav_df) ensure gravity dataframe has the necessary columns :param grav_df: gravity dataframe :type grav_df: pandas.DataFrame .. py:function:: regional_constant(grav_df, constant = None, constraints_df = None, regional_shift = 0, mask_column = None) approximate the regional field with a constant value. If constraint points of the layer of interested are supplied, the constant value will be the median misfit value at the constraint points. :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param constant: shift to apply to the data :type constant: float :param constraints_df: a dataframe of constraint points with columns easting and northing. :type constraints_df: pandas.DataFrame :param regional_shift: shift to add to the regional field, by default 0 :type regional_shift: float, optional :param mask_column: Name of optional column with values to multiply estimated regional field by, should have values of 1 or 0, by default None. :type mask_column: str | None, optional :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_filter(grav_df, filter_width, regional_shift = 0, mask_column = None) separate the regional field with a low-pass filter :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param filter_width: width in meters to use for the low-pass filter :type filter_width: float :param regional_shift: shift to add to the regional field, by default 0 :type regional_shift: float, optional :param mask_column: Name of optional column with values to multiply estimated regional field by, should have values of 1 or 0, by default None. :type mask_column: str | None, optional :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_trend(grav_df, trend, regional_shift = 0, mask_column = None) separate the regional field with a trend :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param trend: order of the polynomial trend to fit to the data :type trend: int :param regional_shift: shift to add to the regional field, by default 0 :type regional_shift: float, optional :param mask_column: Name of optional column with values to multiply estimated regional field by, should have values of 1 or 0, by default None. :type mask_column: str | None, optional :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_eq_sources(grav_df, depth = 'default', damping = None, block_size = None, points = None, grav_obs_height = None, regional_shift = 0, cv = False, weights_column = None, cv_kwargs = None, mask_column = None) separate the regional field by estimating deep equivalent sources :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param depth: depth of each source relative to the data elevation :type depth: float :param damping: smoothness to impose on estimated coefficients, by default None :type damping: float | None, optional :param block_size: block reduce the data to speed up, by default None :type block_size: float | None, optional :param points: specify source locations for equivalent source fitting, by default None :type points: list[numpy.ndarray] | None, optional :param grav_obs_height: Observation height to use predicting the eq sources, by default None and will use the data height from grav_df. :type grav_obs_height: float, optional :param regional_shift: shift to add to the regional field, by default 0 :type regional_shift: float, optional :param cv: use cross-validation to find the best equivalent source parameters, by default False, provide dictionary `cv_kwargs` which is passed to `optimize_eq_source_params` and can contain: "n_trials", "damping_limits", "depth_limits", "block_size_limits", "sampler", "plot", "progressbar", "parallel", "dtype", or "delayed". :type cv: bool, optional :param weights_column: column name for weighting values of each gravity point. :type weights_column: str | None, optional :param mask_column: Name of optional column with values to multiply estimated regional field by, should have values of 1 or 0, by default None. :type mask_column: str | None, optional :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_constraints(grav_df, constraints_df, grid_method = 'eq_sources', constraints_block_size = None, constraints_weights_column = None, tension_factor = 1, registration = 'g', spline_dampings = None, depth = None, damping = None, cv = False, block_size = None, points = None, grav_obs_height = None, cv_kwargs = None, regional_shift = 0, mask_column = None) Separate the regional field by sampling and re-gridding the gravity misfit at points of known topography (constraint points). The re-gridding can be done with: 1. Tensioned minimum curvature with PyGMT, using `grid_method` "pygmt", 2. Bi-Harmonica splines with Verde, using `grid_method` "verde", or 3. Equivalent Sources with Harmonica, using `grid_method` "eq_sources". Optionally, a dc-shift can be added to the calculated regional with `regional_shift`. :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param constraints_df: dataframe of constraints with columns "easting", "northing", and "upward". :type constraints_df: pandas.DataFrame :param grid_method: method used to grid the sampled gravity data at the constraint points. Choose between "verde", "pygmt", or "eq_sources", by default "eq_sources" :type grid_method: str, optional :param constraints_block_size: size of block used in a block-mean reduction of the constraints points, by default None :type constraints_block_size: float | None, optional :param constraints_weights_column: column name for weighting values of each constraint point. Used if `constraint_block_size` is not None or if `grid_method` is "verde" or "eq_sources", by default None :type constraints_weights_column: str | None, optional :param tension_factor: Tension factor used if `grid_method` is "pygmt", by default 1 :type tension_factor: float, optional :param registration: grid registration used if `grid_method` is "pygmt",, by default "g" :type registration: str, optional :param spline_dampings: damping values used if `grid_method` is "verde", by default None :type spline_dampings: float | list[float] | None, optional :param depth: depth of each source relative to the data elevation, positive downwards in meters, by default None :type depth: float | str | None, optional :param damping: damping values used if `grid_method` is "eq_sources", by default None :type damping: float | None, optional :param cv: 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". :type cv: bool, optional :param block_size: block size used if `grid_method` is "eq_sources", by default None :type block_size: float | None, optional :param points: specify source locations for equivalent source fitting, by default None :type points: list[numpy.ndarray] | None, optional :param grav_obs_height: Observation height to use if `grid_method` is "eq_sources", by default None :type grav_obs_height: float, optional :param cv_kwargs: additional keyword arguments for the cross-validation optimization of equivalent source parameters, by default None. Can contain: "n_trials", "damping_limits", "depth_limits", "block_size_limits", "points", "sampler", "plot", "progressbar", "parallel", "fname", "dtype", or "delayed". :type cv_kwargs: dict[str, typing.Any] | None, optional :param regional_shift: shift to add to the regional field, by default 0 :type regional_shift: float, optional :param mask_column: Name of optional column with values to multiply estimated residual field by, should have values of 1 or 0, by default None. :type mask_column: str | None, optional :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_constraints_cv(constraints_df, split_kwargs = None, **kwargs) This is a convenience function to wrap `optimization.optimize_regional_constraint_point_minimization`. It takes a full constraints dataframe and dictionary `split_kwargs`, to split the constraints into testing and training sets (with K-folds), uses these folds in a K-Folds hyperparameter optimization to find the set of parameter values which estimates the best regional field. It then uses the optimal parameter values and all of the constraint points to re-calculate the best regional field. All kwargs are passed to the function :func:`.optimize_regional_constraint_point_minimization` :param constraints_df: dataframe of un-separated constraints :type constraints_df: pandas.DataFrame :param split_kwargs: kwargs to be passed to `split_test_train`, by default None :type split_kwargs: dict[str, typing.Any] | None, optional :param \*\*kwargs: kwargs to be passed to `optimize_regional_constraint_point_minimization` :type \*\*kwargs: typing.Any :returns: a gravity dataframe with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame .. py:function:: regional_separation(method, grav_df, remove_starting_grav_mean = False, **kwargs) Separate the regional field from the gravity data using the specified method and return the dataframe with a new column for the regional field. :param method: choose method to apply; one of "constant", "filter", "trend", "eq_sources", "constraints" or "constraints_cv". :type method: str :param grav_df: gravity data with columns "easting", "northing", "gravity_anomaly", and "starting_gravity". :type grav_df: pandas.DataFrame :param remove_starting_grav_mean: add the mean of the starting gravity to the regional gravity field, by default False. :type remove_starting_grav_mean: bool, optional :param \*\*kwargs: additional keyword arguments for the specified method. :type \*\*kwargs: typing.Any :returns: grav_df with new columns 'misfit', 'reg', and 'res'. :rtype: pandas.DataFrame