mapgwm.headobs module

Code for preprocessing head observation data.

mapgwm.headobs.fill_well_open_intervals(well_info, out_plot='open_interval_lengths.pdf')[source]

Many or most of the well_info output from visGWDB <https://doi.org/10.5066/P9W004O6> may not have complete open interval information. A much greater proportion may have depth information. Use reported well depths and a computed median open interval length to estimate a screen top and bottom where available. Categorize well_info based on the quality of open interval information:

  1. top and bottom elevations included

  2. only bottom (median open interval length of 40 ft. used for top)

  3. bottom and well depth are inconsistent

  4. neither top or bottom are known

Parameters
well_infoDataFrame

Metadata from preprocess_headobs() Columns (all lengths in model units):

screen_top

open interval top elevation

screen_botm

open interval bottom elevation

well_botm

well bottom elevation
Returns
well_infoDataFrame

Metadata from preprocess_headobs(), with additional screen top and bottom estimates and category column with above categories.

mapgwm.headobs.get_data(data_file, metadata_files, aquifer_names=None, column_renames=None, data_kwargs={}, metadata_kwargs={})[source]

Read groundwater level data output from the visGWDB program.

Parameters
data_filestr

Text file with groundwater level time series. Expected to have the following columns, or their renames. See the Head Observation Input for more details. (NAME: rename):

SITE_BADGE: site_no
DEC_LAT_VA: lat
DEC_LONG_VA: lon
MONTHLY_LEV_ALT_VA: head
MONTHLY_STDEV_LEV_ALT_VA: head_std
MONTHLY_LAST_LEV_ALT_VA: last_head
MONTHLY_LEV_COUNT: n
YEAR: year
MONTH: month
# columns in version with statistical estimates
LEV_DT: datetime
EST_LEV_ALT_STDEV: head_std
metadata_filesstr

Text file with groundwater level metadata. Expected to have the following columns, or their renames. See the Head Observation Input for more details. (NAME: rename):

WELL_DEPTH_VA: well_depth
OPEN_TOP_VA: screen_top
OPEN_BOTTOM_VA: screen_botm
ALT_VA: well_el
AQFR_CD: aqfr_cd
NAT_AQFR_CD: nat_aqfr_cd
aquifer_namesdict, optional

Option to explicitly specify regional aquifer names associated with local aquifer codes. Example:

aquifer_names={'124SPT': 'middle clairborne'}

by default None, in which case the names listed in the Regional Aquifer Code Names lookup are used.

column_renamesdict, optional

Option to rename columns in the data or metadata that are different than those listed above. For example, if the data file has a ‘SITE_NO’ column instead of ‘SITE_BADGE’:

column_renames={'SITE_NO': 'site_no'}

by default None, in which case the renames listed above will be used. Note that the renames must be the same as those listed above for mapgwm.headobs.preprocess_headobs() to work.

data_kwargsdict, optional

Keyword arguments to pandas.read_csv() for reading data_file, by default None

metadata_kwargsdict, optional

Keyword arguments to pandas.read_csv() for reading metadata_files, by default None

Returns
dataDataFrame

Head observation timeseries, e.g. for input to func:mapgwm.headobs.preprocess_headobs

Key columns:

site_no

site identifier

lat

lattitude

lon

longitude

datetime

measurement dates in pandas datetime format

head

average head for the period represented by the datetime

last_head

last head measurement for the period represented by the datetime

head_std

standard deviation of measured heads within the datetime period

n

number of measured heads within the period represented
metadataDataFrame

Head observation metadata, e.g. for input to func:mapgwm.headobs.preprocess_headobs

Key columns:

site_no (index)

site identifier

aqfr_cd

Local aquifer code

nat_aqfr_cd

National aquifer code

screen_botm

Well screen bottom, as a depth below land surface, in feet

screen_top

Well screen top, as a depth below land surface, in feet

well_depth

Well depth, in feet

well_el

Altitude of land surface, in feet

local_aquifer

Local aquifer name corresponding to aqfr_cd, see Aquifer Code Names

regional_aquifer

Lumped regional aquifer, see Regional Aquifer Code Names
mapgwm.headobs.get_header_length(sitefile, col0='SITE_BADGE')[source]

Detect the number of rows to skip when reading a tabular file with ‘#’ head comments.

mapgwm.headobs.preprocess_headobs(data, metadata, head_data_columns=['head', 'last_head', 'head_std'], dem=None, dem_units='meters', start_date='1998-04-01', active_area=None, active_area_id_column=None, active_area_feature_id=None, source_crs=4269, dest_crs=5070, data_length_units='meters', model_length_units='meters', geographic_groups=None, geographic_groups_col=None, max_obsname_len=None, outfile='../source_data/observations/head_obs/preprocessed_head_obs.csv')[source]

Preprocess head observation data, for example, groundwater level data output from the visGWDB program.

  • Data are reprojected from a source_crs (Coordinate reference system; assumed to be in geographic coordinates) to the CRS of the model (dest_crs)

  • Data are culled to a start_date and optionally, a polygon or set of polygons defining the model area

  • length units are converted to those of the groundwater model. Open intervals for the wells are converted from depths to elevations

  • missing open intervals are filled based on well bottom depths (if availabile) and the median open interval length for the dataset.

  • Wells are categorized based on the quality of the open interval information (see the documentation for mapgwm.headobs.fill_well_open_intervals()).

  • Prefixes for observation names (with an optional length limit) that identify the location are generated

  • Preliminary observation groups can also be assigned, based on geographic areas defined by polygons (aoi parameter)

Parameters
dataDataFrame

Head observation data, e.g. as output from mapgwm.headobs.get_data(). Columns:

site_no

site identifier

lat

lattitude

lon

longitude

datetime

measurement dates in pandas datetime format

head

average head for the period represented by the datetime

last_head

last head measurement for the period represented by the datetime

head_std

standard deviation of measured heads within the datetime period

Notes:

  • lat and lon columns can alternatively be in the metadata table

  • last_head and head_std only need to be included if they are in head_data_columns

metadataDataFrame

Head observation data, e.g. as output from mapgwm.headobs.get_data().

Must have the following columns:

site_no (index)

site identifier

aqfr_cd

Local aquifer code

screen_botm

Well screen bottom, as a depth below land surface, in feet

screen_top

Well screen top, as a depth below land surface, in feet

well_depth

Well depth, in feet

well_el

Altitude of land surface, in feet
head_data_columnslist of strings

Columns in data with head values or their statistics. By default, ‘head’, ‘last_head’, ‘head_std’, which allows both the average and last head values for the stress period to be considered, as well as the variability of water levels contributing to an average value.

demstr, optional

DEM raster of the land surface. Used for estimating missing wellhead elevations. Any reprojection to dest_crs is handled automatically, assuming the DEM raster has CRS information embedded (arc-ascii grids do not!) By default, None.

dem_unitsstr, {‘feet’, ‘meters’, ..}

Units of DEM elevations, by default, ‘meters’

start_datestr (YYYY-mm-dd)

Simulation start date (cull observations before this date)

active_areastr

Shapefile with polygon to cull observations to. Automatically reprojected to dest_crs if the shapefile includes a .prj file. by default, None.

active_area_id_columnstr, optional

Column in active_area with feature ids. By default, None, in which case all features are used.

active_area_feature_idstr, optional

ID of feature to use for active area By default, None, in which case all features are used.

source_crsobj

Coordinate reference system of the head observation locations. A Python int, dict, str, or pyproj.crs.CRS instance passed to pyproj.crs.CRS.from_user_input()

Can be any of:

  • PROJ string

  • Dictionary of PROJ parameters

  • PROJ keyword arguments for parameters

  • JSON string with PROJ parameters

  • CRS WKT string

  • An authority string [i.e. ‘epsg:4326’]

  • An EPSG integer code [i.e. 4326]

  • A tuple of (“auth_name”: “auth_code”) [i.e (‘epsg’, ‘4326’)]

  • An object with a to_wkt method.

  • A pyproj.crs.CRS class

By default, epsg:4269

dest_crsobj

Coordinate reference system of the model. Same input types as source_crs. By default, epsg:5070

data_length_unitsstr; ‘meters’, ‘feet’, etc.

Length units of head observations.

model_length_unitsstr; ‘meters’, ‘feet’, etc.

Length units of model.

geographic_groupsfile, dict or list-like

Option to group observations by area(s) of interest. Can be a shapefile, list of shapefiles, or dictionary of shapely polygons. A ‘group’ column will be created in the metadata, and observation sites within each polygon will be assigned the group name associated with that polygon.

For example:

geographic_groups='../source_data/extents/CompositeHydrographArea.shp'
geographic_groups=['../source_data/extents/CompositeHydrographArea.shp']
geographic_groups={'cha': <shapely Polygon>}

Where ‘cha’ is an observation group name for observations located within the the area defined by CompositeHydrographArea.shp. For shapefiles, group names are provided in a geographic_groups_col.

geographic_groups_colstr

Field name in the geographic_groups shapefile(s) containing the observation group names associated with each polygon.

max_obsname_lenint or None

Maximum length for observation name prefix. Default of 13 allows for a PEST obsnme of 20 characters or less with <prefix>_yyyydd or <prefix>_<per>d<per> (e.g. <prefix>_2d1 for a difference between stress periods 2 and 1) If None, observation names will not be truncated. PEST++ does not have a limit on observation name length.

outfilestr

Where output file will be written. Metadata are written to a file with the same name, with an additional “_info” suffix prior to the file extension.

Returns
dfDataFrame

Preprocessed time series

well_infoDataFrame

Preprocessed metadata

References

The PEST++ Manual <https://github.com/usgs/pestpp/tree/master/documentation>

mapgwm.headobs.read_metadata(metadata_files, column_renames=None, aquifer_names=None, metadata_kwargs={})[source]

Read groundwater level metadata output from the visGWDB program.

Parameters
metadata_filesstr

Text file with groundwater level metadata. Expected to have the following columns, or their renames. See the Head Observation Input for more details. (NAME: rename):

WELL_DEPTH_VA: well_depth
OPEN_TOP_VA: screen_top
OPEN_BOTTOM_VA: screen_botm
ALT_VA: well_el
AQFR_CD: aqfr_cd
NAT_AQFR_CD: nat_aqfr_cd
aquifer_namesdict, optional

Option to explicitly specify regional aquifer names associated with local aquifer codes. Example:

aquifer_names={'124SPT': 'middle clairborne'}

by default None, in which case the names listed in the Regional Aquifer Code Names lookup are used.

column_renamesdict, optional

Option to rename columns in the data or metadata that are different than those listed above. For example, if the data file has a ‘SITE_NO’ column instead of ‘SITE_BADGE’:

column_renames={'SITE_NO': 'site_no'}

by default None, in which case the renames listed above will be used. Note that the renames must be the same as those listed above for mapgwm.headobs.preprocess_headobs() to work.

metadata_kwargsdict, optional

Keyword arguments to pandas.read_csv() for reading metadata_files, by default None

Returns
metadataDataFrame

Head observation metadata, e.g. for input to func:mapgwm.headobs.preprocess_headobs

Key columns:

site_no (index)

site identifier

aqfr_cd

Local aquifer code

nat_aqfr_cd

National aquifer code

screen_botm

Well screen bottom, as a depth below land surface, in feet

screen_top

Well screen top, as a depth below land surface, in feet

well_depth

Well depth, in feet

well_el

Altitude of land surface, in feet

local_aquifer

Local aquifer name corresponding to aqfr_cd, see Aquifer Code Names

regional_aquifer

Lumped regional aquifer, see Regional Aquifer Code Names