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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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, study_area_crs=None, output_crs='EPSG:5070', buffer=None, return_original=False, log=False, verbose=False, **read_file_kwargs)[source]¶

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. If shapely.Geometry, the crs should also be specified using a valid input to gpd.GeoDataFrame(crs=<crs>).

study_area_crsstr, tuple, dict, optional

Not needed unless CRS must be read in manually (e.g, with a shapely.Geometry). CRS designation readable by geopandas/pyproj.

output_crsstr, tuple, dict, optional

CRS to transform study_area to before returning. CRS designation should be readable by geopandas/pyproj. By default, ‘EPSG:5070’.

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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