1. Overview and Description
The Maryland Geological Survey's Interactive Maryland Potentiometric Surface Mapper & Grapher is a web-based tool designed to visualize, analyze, and export groundwater-level data for the Maryland Coastal Plain.
The tool allows the user to:
- Filter and map observation wells by specific aquifers.
- Generate interpolated potentiometric surface contour maps for specific seasons (Spring/Fall) and years.
- Generate difference maps to visualize drawdown or recovery between two specific time periods.
- Exclude anomalous or outlier data points manually to improve interpolation accuracy.
- Plot interactive hydrographs to visualize long-term groundwater elevation trends.
- Calculate localized linear regression trends (in feet/year) for individual wells or well clusters over specific time spans.
- Export raw data, spatial grids, contour lines, PDF reports, and map images for reporting and GIS software.
2. Step-by-Step Guide
Filtering and Setup
- Select an Aquifer: Use the dropdown in the top-left control panel to select a target aquifer. The map will automatically populate with wells tapping into that unit.
Generating Contour Maps
- Single Surface Mode: Select "Single Surface," pick a season (Spring or Fall) and a year, then click Draw Map.
- Difference Map Mode: Select "Difference Map," pick a Base Year/Season and a Target Year/Season, then click Draw Map. The tool will calculate the change in water levels between those two periods.
Excluding Data from Interpolation
- Exclude a Well: To remove anomalous or outlier data, click any well marker on the map and select Exclude. This removes the well from the mathematical interpolation and flags it in data exports. The map will automatically redraw if contours are currently visible.
- Include a Well: Click an excluded well and select Include to return it to the active dataset.
- Reset All: Click the orange Reset Exclusions button in the left panel to clear your exclusion list completely.
Analyzing Hydrographs and Trends
- Plot a Well: Click any well marker on the map and select Plot. A hydrograph will appear showing the well's entire recorded history with a flag marking the targeted map year(s).
- Compare Wells: Click another well on the map and select Compare to overlay its data on the same graph.
- Plot Visible Wells: Zoom to a group of wells (up to 40) and click Plot Visible Wells to show the visible wells' data on the same graph.
- Zoom and Filter Time: Expand the graph and use the native buttons (5Y, 10Y, 15Y, 20Y, All) to snap the view to a strict historical window relative to the most recent measurement. Or you can click and drag to manually set the time range.
- Calculate Trends: Click the red Calculate Trend button. The script will perform a linear regression on the currently visible data.
Exporting Data
Click the Export ▼ dropdown in the top right of the map header to access the following options:
- Export Data (CSV): Downloads a spreadsheet of the exact wells, dates, and values used to generate the current map.
- Export Lines (GeoJSON): Downloads the spatial contour lines for import into ArcGIS or QGIS.
- Export Lines (Shapefile): Downloads a zipped Shapefile containing the contour lines and attributes for traditional GIS workflows.
- Export Grid (GeoJSON): Downloads the underlying interpolated point grid used to draw the contours.
- Export Raster (.asc): Downloads the mathematical grid as an ASCII raster (.asc) accompanied by a projection file (.prj).
- Export Image (PNG): Captures a high-resolution screenshot of the current map view.
- Export PDF Report: Generates a PDF report that contains the map image, a table of the water level data used to generate the contours, and a separate table documenting any manually excluded wells.
Underlying Logic and Workflow
Data Acquisition and Seasonal Filtering
When you request a map, the tool queries the data for all wells in the selected aquifer. To ensure hydrologic consistency, it searches within strict 6-month windows:
- Spring: January 1 through June 30.
- Fall: July 1 through December 31.
Because a well might be measured multiple times in a seasonal window, the script identifies an Ideal Target Date (April 1 for Spring, October 1 for Fall). It evaluates all timestamps in the window and extracts the single measurement mathematically closest to that target date.
Spatial Interpolation (Kriging)
Groundwater levels are only known exactly at the well heads. To estimate the water levels between the wells, the tool uses Kriging, a geostatistical interpolation method.
- It takes the known Z-values (water elevations) and builds a mathematical variogram.
- It lays an invisible, high-resolution grid over the map.
- It predicts the water level at every single grid intersection based on the surrounding known wells.
Contouring and Boundary Masking
Once the grid is generated, the tool draws isolines (contours) connecting points of equal elevation. To ensure geological accuracy:
- It checks the midpoint of every contour segment. If the segment falls outside the official physical boundary of the aquifer (the extent polygon), or if it is further away from a known well than the user-defined "Max Interpolation Distance," the contour is truncated.
- Segments that fall outside the "convex hull" (the polygon created by drawing a perimeter around the outermost wells) are drawn as dashed lines to indicate they are mathematical extrapolations, not strict interpolations.
Difference Math
For difference maps, the tool generates two independent Kriging grids (Base and Target). It then loops through every point in the grid, subtracts the Base Z-value from the Target Z-value, and generates a third, brand-new grid of the difference values. The final contours are drawn based on this delta grid.
Libraries and Scripts Used
The application is built on standard web technologies (HTML, CSS, JavaScript) and relies on several open-source libraries:
- Leaflet.js: The core mapping library. It handles the base maps, plotting the well markers, rendering the GeoJSON aquifer boundaries, and managing user interactions (panning, zooming, popups).
- Plotly.js: A charting library used for the interactive hydrographs. It handles the time-series plotting, axis manipulation, zooming, and dynamic rendering of the trend lines.
- Kriging.js: A JavaScript implementation of geostatistical Kriging. It is the mathematical engine responsible for training the variogram and predicting the groundwater elevations across unmeasured portions of the map grid.
- Turf.js: A geospatial analysis engine. It performs the GIS logic, including generating bounding boxes (turf.bbox), calculating the convex hull for extrapolation detection (turf.convex), converting the Kriged grid points into continuous contour lines (turf.isolines), and determining if contour segments exist inside or outside the defined aquifer polygons (turf.booleanPointInPolygon).
- html2canvas: A utility script that reads the DOM (Document Object Model) of the map container and converts the live HTML/Canvas elements into a downloadable PNG image.
- jsPDF & jsPDF-AutoTable: Libraries utilized to generate and format the downloadable PDF reports and data tables.
Please contact Andrew Staley - [email protected] - with any questions or comments.
