invert4geom.utils

Module Contents

Functions

rmse(data[, as_median])	function to give the root mean/median squared error (RMSE) of data
nearest_grid_fill(grid[, method])	fill missing values in a grid with the nearest value.
filter_grid(grid[, filter_width, filt_type])	_summary_
dist_nearest_points(targets, data[, coord_names])	for all gridcells calculate to the distance to the nearest target.
normalize_xarray(da[, low, high])	Normalize a grid between provided values
normalized_mindist(points, grid[, low, high, mindist, ...])	Find the minimum distance between each grid cell and the nearest point. If low and
sample_grids(df, grid, sampled_name, **kwargs)	Sample data at every point along a line
extract_prism_data(prism_layer)	extract necessary info from starting prism layer, adds variables 'topo' and
get_spacing(prisms_df)	Extract spacing of harmonica prism layer using a dataframe representation.
sample_bounding_surfaces(prisms_df[, ...])	sample upper and/or lower confining layers into prisms dataframe
enforce_confining_surface(prisms_df, iteration_number)	alter the surface correction values to ensure when added to the current iteration's
apply_surface_correction(prisms_df, iteration_number)	update the prisms dataframe and dataset with the surface correction. Ensure that
update_prisms_ds(prisms_ds, correction_grid, zref)	apply the corrections grid and update the prism tops, bottoms, topo, and
add_updated_prism_properties(prisms_df, prisms_ds, ...)	update the prisms dataframe the the new prism tops, bottoms, topo, and densities
grids_to_prisms(surface, reference, density[, ...])	create a Harmonica layer of prisms with assigned densities.
best_spline_cv(coordinates, data[, weights, dampings, ...])	find the best damping parameter for a verde.SplineCV() fit
eq_sources_score(params, coordinates, data[, delayed])	_summary_

rmse(data, as_median=False)

function to give the root mean/median squared error (RMSE) of data

Parameters:

• data (NDArray) – input data

• as_median (bool, optional) – choose to give root median squared error instead, by default False

Returns:

RMSE value

Return type:

float

nearest_grid_fill(grid, method='verde')

fill missing values in a grid with the nearest value.

Parameters:

• grid (xr.DataArray) – grid with missing values

• method (str, optional) – choose method of filling, by default “verde”

Returns:

filled grid

Return type:

xr.DataArray

filter_grid(grid, filter_width=None, filt_type='lowpass')

_summary_

Parameters:

• grid (xr.DataArray) – grid to filter the values of

• filter_width (float, optional) – width of the filter in meters, by default None

• filt_type (str, optional) – type of filter to use, by default “lowpass”

• change_spacing (bool, optional) – if True, will filter the grid and resample the grid to be at the same spacing of the filter width, by default False

Returns:

a filtered grid

Return type:

xr.DataArray

dist_nearest_points(targets, data, coord_names=None)

for all gridcells calculate to the distance to the nearest target.

Parameters:

• targets (pd.DataFrame) – contains the coordinates of the targets

• data (pd.DataFrame | xr.DataArray | xr.Dataset) – the grid data, in either gridded or tabular form

• coord_names (tuple[str, str] | None, optional) – the names of the coordinates for both the targets and the data, by default None

Returns:

the distance to the nearest target for each gridcell, in the same format as the input for data.

Return type:

Any

normalize_xarray(da, low=0, high=1)

Normalize a grid between provided values

Parameters:

• da (xr.DataArray) – grid to normalize

• low (float, optional) – lower value for normalization, by default 0

• high (float, optional) – higher value for normalization, by default 1

Returns:

a normalized grid

Return type:

xr.DataArray

normalized_mindist(points, grid, low=None, high=None, mindist=None, region=None)

Find the minimum distance between each grid cell and the nearest point. If low and high are provided, normalize the min dists grid between these values. If region is provided, all grid cells outside region are set to a distance of 0.

Parameters:

• points (pd.DataFrame) – coordinates of the points

• grid (xr.DataArray) – gridded data to find min dists for each grid cell

• low (float | None, optional) – lower value for normalization, by default None

• high (float | None, optional) – higher value for normalization, by default None

• mindist (float | None, optional) – the minimum allowed distance, all values below are set equal to, by default None

• region (list[float] | None, optional) – bounding region for which all grid cells outside will be set to low, by default None

Returns:

grid of normalized minimum distances

Return type:

xr.DataArray

sample_grids(df, grid, sampled_name, **kwargs)

Sample data at every point along a line

Parameters:

• df (pd.DataFrame) – Dataframe containing columns ‘x’, ‘y’, or columns with names defined by kwarg “coor_names”.

• grid (str or xr.DataArray) – Grid to sample, either file name or xr.DataArray

• sampled_name (str,) – Name for sampled column

• kwargs (Any)

Returns:

Dataframe with new column (sampled_name) of sample values from (grid)

Return type:

pd.DataFrame

extract_prism_data(prism_layer)

extract necessary info from starting prism layer, adds variables ‘topo’ and ‘starting_topo’ to prism layer dataset (prisms_ds), converts it into dataframe (prisms_df), gets the prism spacing (spacing) from prisms_ds, and creates a grid of the starting topography (topo_grid) from the tops and bottoms of the prism layer.

Parameters:

prism_layer (xr.Dataset) – starting model prism layer

Returns:

prisms_df, prisms_ds, spacing, topo_grid

Return type:

tuple[pd.DataFrame, pd.Dataset, float, xr.DataArray]

get_spacing(prisms_df)

Extract spacing of harmonica prism layer using a dataframe representation.

Parameters:

prisms_df (pd.DataFrame) – dataframe of harmonica prism layer

Returns:

spacing of prisms

Return type:

float

sample_bounding_surfaces(prisms_df, upper_confining_layer=None, lower_confining_layer=None)

sample upper and/or lower confining layers into prisms dataframe

Parameters:

• prisms_df (pd.DataFrame) – dataframe of prism properties

• upper_confining_layer (xr.DataArray | None, optional) – layer which the inverted topography should always be below, by default None

• lower_confining_layer (xr.DataArray | None, optional) – layer which the inverted topography should always be above, by default None

Returns:

a dataframe with added columns ‘upper_bounds’ and ‘lower_bounds’, which are the sampled values of the supplied confining grids.

Return type:

pd.DataFrame

enforce_confining_surface(prisms_df, iteration_number)

alter the surface correction values to ensure when added to the current iteration’s topography it doesn’t intersect optional confining layers.

Parameters:

• prisms_df (pd.DataFrame) – prism layer dataframe with optional ‘upper_bounds’ or ‘lower_bounds’ columns, and current iteration’s topography.

• iteration_number (int) – number of the current iteration, starting at 1 not 0

Returns:

a dataframe with added column ‘iter_{iteration_number}_correction

Return type:

pd.DataFrame

apply_surface_correction(prisms_df, iteration_number)

update the prisms dataframe and dataset with the surface correction. Ensure that the updated surface doesn’t intersect the optional confining surfaces.

Parameters:

• prisms_df (pd.DataFrame) – dataframe of prism properties

• iteration_number (int) – the iteration number, starting at 1 not 0

Returns:

updated prisms dataframe and correction grid

Return type:

tuple[pd.DataFrame, xr.DataArray]

update_prisms_ds(prisms_ds, correction_grid, zref)

apply the corrections grid and update the prism tops, bottoms, topo, and densities.

Parameters:

• prisms_ds (xr.Dataset) – harmonica prism layer

• correction_grid (xr.DataArray) – grid of corrections to apply to the prism layer

• zref (float) – reference level for the prism layer

Returns:

updated prism layer with new tops, bottoms, topo, and densities

Return type:

xr.Dataset

add_updated_prism_properties(prisms_df, prisms_ds, iteration_number)

update the prisms dataframe the the new prism tops, bottoms, topo, and densities the iteration number, starting at 1 not 0

Parameters:

• prisms_df (pd.DataFrame) – dataframe of prism properties

• prisms_ds (xr.Dataset) – dataset of prism properties

• iteration_number (int) – the iteration number, starting at 1 not 0

Returns:

updated prism dataframe with new tops, bottoms, topo, and densities

Return type:

pd.DataFrame

grids_to_prisms(surface, reference, density, input_coord_names=('easting', 'northing'))

create a Harmonica layer of prisms with assigned densities.

Parameters:

• surface (xr.DataArray) – data to use for prism surface

• reference (float | xr.DataArray) – data or constant to use for prism reference, if value is below surface, prism will be inverted

• density (float | int | xr.DataArray) – data or constant to use for prism densities.

• input_coord_names (tuple[str, str], optional) – names of the coordinates in the input dataarray, by default [“easting”, “northing”]

Returns:

a prisms layer with assigned densities

Return type:

xr.Dataset

best_spline_cv(coordinates, data, weights=None, dampings=None, delayed=False, force_coords=None)

find the best damping parameter for a verde.SplineCV() fit

Parameters:

• coordinates (tuple[pd.Series | NDArray, pd.Series | NDArray]) – easting and northing coordinates of the data

• data (pd.Series | NDArray) – data for fitting the spline to

• weights (pd.Series | NDArray | None, optional) – if not None, then the weights assigned to each data point. Typically, this should be 1 over the data uncertainty squared, by default None

• dampings (Any | None, optional) – the positive damping regularization parameter. Controls how much smoothness is imposed on the estimated forces. If None, no regularization is used, by default None

• delayed (bool, optional) – if True, will use dask.delayed to dispatch computations and allow mod:dask to execute the grid search in parallel, by default False

• force_coords (tuple[pd.Series | NDArray, pd.Series | NDArray] | None, optional) – the easting and northing coordinates of the point forces. Same as force_coords if it is not None. Otherwise, same as the data locations used to fit the spline, by default None

Returns:

the spline which best fits the data

Return type:

vd.Spline

eq_sources_score(params, coordinates, data, delayed=False, **kwargs)

_summary_

Parameters:

• params (dict[str, float]) – dictionary with damping and depth parameters for the equivalent sources fit

• coordinates (tuple[pd.Series | NDArray, pd.Series |) – NDArray, pd.Series | NDArray] easting, northing, and upwards coordinates of the gravity data

• data (pd.Series | NDArray) – gravity data values

• delayed (bool, optional) – If True, will use dask.delayed to dispatch computations without actually executing them. The returned scores will be a list of delayed objects, by default False

• kwargs (Any)

Returns:

the mean score of the equivalent sources fit

Return type:

float