w4h.mapping module

The Mapping module contains the functions used for geospatial analysis throughout the package. This includes some input/output as well as functions to make manipulatin of geospatial data more simple

w4h.mapping.align_rasters(grids_unaligned=None, model_grid=None, no_data_val_grid=0, verbose=False, log=False)

Reprojects two rasters and aligns their pixels

Parameters:

grids_unalignedlist or xarray.DataArray

Contains a list of grids or one unaligned grid

model_gridxarray.DataArray

Contains model grid

no_data_val_gridint, default=0

Sets value of no data pixels

logbool, default = False

Whether to log results to log file, by default False

Returns:

alignedGridslist or xarray.DataArray

Contains aligned grids

w4h.mapping.clip_gdf2study_area(study_area, gdf, log=False, verbose=False)

Clips dataframe to only include things within study area.

Parameters:

study_areageopandas.GeoDataFrame

Inputs study area polygon

gdfgeopandas.GeoDataFrame

Inputs point data

logbool, default = False

Whether to log results to log file, by default False

Returns:

gdfClipgeopandas.GeoDataFrame

Contains only points within the study area

w4h.mapping.coords2geometry(df_no_geometry, xcol='LONGITUDE', ycol='LATITUDE', zcol='ELEV_FT', input_coords_crs='EPSG:4269', output_crs='EPSG:5070', use_z=False, wkt_col='WKT', geometry_source='coords', verbose=False, log=False)

Adds geometry to points with xy coordinates in the specified coordinate reference system.

Parameters:

df_no_geometrypandas.Dataframe

a Pandas dataframe containing points

xcolstr, default=’LONGITUDE’

Name of column holding x coordinate data in df_no_geometry

ycolstr, default=’LATITUDE’

Name of column holding y coordinate data in df_no_geometry

zcolstr, default=’ELEV_FT’

Name of column holding z coordinate data in df_no_geometry

input_coords_crsstr, default=’EPSG:4269’

Name of crs used for geometry

use_zbool, default=False

Whether to use z column in calculation

geometry_sourcestr {‘coords’, ‘wkt’, ‘geometry’}

logbool, default = False

Whether to log results to log file, by default False

Returns:

gdfgeopandas.GeoDataFrame

Geopandas dataframe with points and their geometry values

w4h.mapping.get_drift_thick(surface_elev=None, bedrock_elev=None, layers=9, plot=False, verbose=False, log=False)

Finds the distance from surface_elev to bedrock_elev and then divides by number of layers to get layer thickness.

Parameters:

surface_elevrioxarray.DataArray

array holding surface elevation

bedrock_elevrioxarray.DataArray

array holding bedrock elevation

layersint, default=9

number of layers needed to calculate thickness for

plotbool, default=False

tells function to either plot the data or not

Returns:

driftThickrioxarray.DataArray

Contains data array containing depth to bedrock at each point

layerThickrioxarray.DataArray

Contains data array with layer thickness at each point

w4h.mapping.grid2study_area(study_area, grid, output_crs='EPSG:5070', verbose=False, log=False)

Clips grid to study area.

Parameters:

study_areageopandas.GeoDataFrame

inputs study area polygon

gridxarray.DataArray

inputs grid array

output_crsstr, default=’EPSG:5070’

inputs the coordinate reference system for the study area

logbool, default = False

Whether to log results to log file, by default False

Returns:

gridxarray.DataArray

returns xarray containing grid clipped only to area within study area

w4h.mapping.read_grid(grid_path=None, grid_type='model', no_data_val_grid=0, use_service=False, study_area=None, grid_crs=None, output_crs='EPSG:5070', verbose=False, log=False, **kwargs)

Reads in grid

Parameters:

grid_pathstr or pathlib.Path, default=None

Path to a grid file

grid_typestr, default=’model’

Sets what type of grid to load in

no_data_val_gridint, default=0

Sets the no data value of the grid

use_servicestr, default=False

Sets which service the function uses

study_areageopandas.GeoDataFrame, default=None

Dataframe containing study area polygon

grid_crsstr, default=None

Sets crs to use if clipping to study area

logbool, default = False

Whether to log results to log file, by default False

Returns:

gridINxarray.DataArray

Returns grid

w4h.mapping.read_model_grid(model_grid_path, study_area=None, no_data_val_grid=0, read_grid=True, node_byspace=True, grid_crs=None, output_crs='EPSG:5070', verbose=False, log=False)

Reads in model grid to xarray data array

Parameters:

grid_pathstr

Path to model grid file

study_areageopandas.GeoDataFrame, default=None

Dataframe containing study area polygon

no_data_val_gridint, default=0

value assigned to areas with no data

readGridbool, default=True

Whether function to either read grid or create grid

node_byspacebool, default=False

Denotes how to create grid

output_crsstr, default=’EPSG:5070’

Inputs study area crs

grid_crsstr, default=None

Inputs grid crs

logbool, default = False

Whether to log results to log file, by default False

Returns:

modelGridxarray.DataArray

Data array containing model grid

w4h.mapping.read_study_area(study_area=None, output_crs='EPSG:5070', buffer=None, return_original=False, log=False, verbose=False, **read_file_kwargs)

Read study area geospatial file into geopandas

Parameters:

study_areastr, pathlib.Path, geopandas.GeoDataFrame, or shapely.Geometry

Filepath to any geospatial file readable by geopandas. Polygon is best, but may work with other types if extent is correct.

study_area_crsstr, tuple, dict, optional

CRS designation readable by geopandas/pyproj

bufferNone or numeric, default=None

If None, no buffer created. If a numeric value is given (float or int, for example), a buffer will be created at that distance in the unit of the study_area_crs.

return_originalbool, default=False

Whether to return the (reprojected) study area as well as the (reprojected) buffered study area. Study area is only used for clipping data, so usually return_original=False is sufficient.

logbool, default = False

Whether to log results to log file, by default False

verbosebool, default=False

Whether to print status and results to terminal

Returns:

studyAreaINgeopandas dataframe

Geopandas dataframe with polygon geometry.

w4h.mapping.read_wcs(study_area, wcs_url='https://data.isgs.illinois.edu/arcgis/services/Elevation/IL_Statewide_Lidar_DEM_WGS/ImageServer/WCSServer?request=GetCapabilities&service=WCS', res_x=30, res_y=30, verbose=False, log=False, **kwargs)

Reads a WebCoverageService from a url and returns a rioxarray dataset containing it.

Parameters:

study_areageopandas.GeoDataFrame

Dataframe containing study area polygon

wcs_urlstr, default=lidarURL

Represents the url for the WCS

res_xint, default=30

Sets resolution for x axis

res_yint, default=30

Sets resolution for y axis

logbool, default = False

Whether to log results to log file, by default False

**kwargs

Returns:

wcsData_rxrxarray.DataArray

A xarray dataarray holding the image from the WebCoverageService

w4h.mapping.read_wms(study_area, layer_name='IL_Statewide_Lidar_DEM_WGS:None', wms_url='https://data.isgs.illinois.edu/arcgis/services/Elevation/IL_Statewide_Lidar_DEM_WGS/ImageServer/WCSServer?request=GetCapabilities&service=WCS', srs='EPSG:3857', clip_to_studyarea=True, bbox=[-9889002.6155, 5134541.069716, -9737541.607038, 5239029.6274], res_x=30, res_y=30, size_x=512, size_y=512, format='image/tiff', verbose=False, log=False, **kwargs)

Reads a WebMapService from a url and returns a rioxarray dataset containing it.

Parameters:

study_areageopandas.GeoDataFrame

Dataframe containg study area polygon

layer_namestr, default=’IL_Statewide_Lidar_DEM_WGS:None’

Represents the layer name in the WMS

wms_urlstr, default=lidarURL

Represents the url for the WMS

srsstr, default=’EPSG:3857’

Sets the srs

clip_to_studyareabool, default=True

Whether to clip to study area or not

res_xint, default=30

Sets resolution for x axis

res_yint, default=512

Sets resolution for y axis

size_xint, default=512

Sets width of result

size_yint, default=512

Sets height of result

logbool, default = False

Whether to log results to log file, by default False

Returns:

wmsData_rxrxarray.DataArray

Holds the image from the WebMapService

w4h.mapping.sample_raster_points(raster=None, points_df=None, well_id_col='API_NUMBER', xcol='LONGITUDE', ycol='LATITUDE', new_col='SAMPLED', verbose=False, log=False)

Sample raster values to points from geopandas geodataframe.

Parameters:

rasterrioxarray data array

Raster containing values to be sampled.

points_dfgeopandas.geodataframe

Geopandas dataframe with geometry column containing point values to sample.

well_id_colstr, default=”API_NUMBER”

Column that uniquely identifies each well so multiple sampling points are not taken per well

xcolstr, default=’LONGITUDE’

Column containing name for x-column, by default ‘LONGITUDE.’ This is used to output (potentially) reprojected point coordinates so as not to overwrite the original.

ycolstr, default=’LATITUDE’

Column containing name for y-column, by default ‘LATITUDE.’ This is used to output (potentially) reprojected point coordinates so as not to overwrite the original. new_col : str, optional

new_colstr, default=’SAMPLED’

Name for name of new column containing points sampled from the raster, by default ‘SAMPLED’.

verbosebool, default=True

Whether to send to print() information about progress of function, by default True.

logbool, default = False

Whether to log results to log file, by default False

Returns:

points_dfgeopandas.geodataframe

Same as points_df, but with sampled values and potentially with reprojected coordinates.

w4h.mapping.xyz_metadata_merge(xyz, metadata, verbose=False, log=False)

Add elevation to header data file.

Parameters:

xyzpandas.Dataframe

Contains elevation for the points

metadatapandas dataframe

Header data file

logbool, default = False

Whether to log results to log file, by default False

Returns:

headerXYZDatapandas.Dataframe

Header dataset merged to get elevation values