Wells Classification

[prayaslashkari]

Summary

The Well Source filter right now shows only two choices, Illinois (ISGS) and Maine (MGS). This issue explains how that works today and suggests two ways we could classify wells.

Important background: there are two separate well datasets

	Inventory wells	Sampled wells
What they are	Full well registries from state geological surveys. They tell us where wells exist.	Wells where someone took a contaminant sample. They tell us where contamination was measured.
Endpoint	hydrologykg	sawgraph
Size	379k (IL) plus 153k (ME), about 532k total	about 5,330
States	Illinois and Maine only	about 10 states (ME, MN, AZ, MA, AL, IN, IL, NH, KS, SC)
Classified by	IL: il_isgs:wellPurpose. ME: me_mgs:ofWellType	coso:ofFeatureType (shared vocabulary)
In the current dropdown?	Yes	No

The current dropdown filters the inventory dataset. Full inventories only exist for Illinois and Maine, so the two choices are correct for that data. Wells from other states only show up in the small sampled dataset.

1. Current behavior

What we show: a multi select called Well Source with two fixed choices, Illinois Wells (ISGS) and Maine Wells (MGS). There is no live query and no counts. Picking a source limits the query to that state's well class. If nothing is picked, both are used.

How it works:

• The options are a fixed list in code (WELL_TYPE_OPTIONS).
• Each option maps to a class, il_isgs:ISGS-Well or me_mgs:MGS-Well.
• A WELL_TO_STATE map (ISGS to FIPS 17, MGS to FIPS 23) shows a warning when the chosen state does not match the chosen source.
• The chosen types become UNION clauses in the well query, which runs against the hydrologykg endpoint.

SPARQL (from buildWellsByIri in src/engine/templates/hydrate.ts):

# well type filter. If nothing is picked, both states are used.
{ ?well rdf:type il_isgs:ISGS-Well } UNION { ?well rdf:type me_mgs:MGS-Well }

SELECT DISTINCT ?well ?wellWKT ?wellName ?s2cell
  ?meUse ?meWellType ?meDepth ?meOverburden
  ?ilOwner ?ilDepth ?ilPurpose ?ilYield
WHERE {
  VALUES ?well { ... }
  ?s2cell spatial:connectedTo ?well ;
          rdf:type kwg-ont:S2Cell_Level13 .
  { ?well rdf:type il_isgs:ISGS-Well } UNION { ?well rdf:type me_mgs:MGS-Well }
  ?well geo:hasGeometry/geo:asWKT ?wellWKT .
  OPTIONAL { ?well rdfs:label ?wellName . }
  # Maine (MGS) attributes
  OPTIONAL { ?well me_mgs:hasUse ?meUse . }
  OPTIONAL { ?well me_mgs:ofWellType ?meWellType . }
  OPTIONAL { ?well me_mgs:wellDepth/qudt:numericValue ?meDepth . }
  OPTIONAL { ?well me_mgs:wellOverburden/qudt:numericValue ?meOverburden . }
  # Illinois (ISGS) attributes
  OPTIONAL { ?well il_isgs:hasOwner ?ilOwner . }
  OPTIONAL { ?well il_isgs:wellDepth/qudt:numericValue ?ilDepth . }
  OPTIONAL { ?well il_isgs:wellPurpose ?ilPurpose . }
  OPTIONAL { ?well il_isgs:wellYield/qudt:numericValue ?ilYield . }
}

Relevant files:

• src/components/QueryEditor/WellFilters.tsx holds the fixed options, the state map, and the warning.
• src/engine/templates/hydrate.ts (buildWellsByIri) has the well query and the type filter.
• src/engine/templates/fusedQueries.ts (buildWellTypeFilterSuffixed) has the same type filter for fused queries.
• src/engine/planner.ts sends wells blocks to the hydrologykg endpoint.
• src/constants/prefixes.ts defines the il_isgs and me_mgs prefixes.
• src/types/query.ts defines WellFilters.wellTypes.

2. Proposed classification

Approach A: one scheme for every state

Classify by coso:ofFeatureType, which uses the same words in every region. It applies to the roughly 5,330 sampled wells across about 10 states.

Bucket	Count	Codes
Water Supply	about 3,053	PWSW, PUWSW, IWSW, DWS, MUW
Generic Well	1,285	Well
Monitoring	953	MW
Extraction or Agricultural	37	AW, EW

Good points: it is the same everywhere, it works across regions by design, and it needs no per state logic.

Weak points: it only covers the roughly 5,330 sampled wells, which is about 1 percent of the inventory. Maine makes up about 76 percent of it. It is also a different dataset and endpoint (sawgraph) than the current dropdown (hydrologykg).

Approach B: each state uses its own scheme

Each state is classified by its own field. There is no forced mapping between states, because the two states genuinely record different things. This is the same idea the dropdown already uses at the source level (Illinois versus Maine), taken one step deeper into each state's own categories.

Illinois (ISGS), by purpose. Field il_isgs:wellPurpose. About 379,496 wells, 33 codes. Describes what the well was drilled for. Many codes have a "Plugged" twin (WATERP, MONITP, and so on) that we would collapse.

Category	Count
Water Well	297,955
Engineering Test	52,016
Monitoring Well	5,802
Water Well Test Hole	5,553
Stratigraphic Test	4,547
Mineral Test	4,159
Mining (MSFT, SLOPE, DRIFT, STRIP, MSERV)	about 800
Observation Well	830
Water Supply Well	530
Waste Disposal Well	14
plus more

Maine (MGS): we offer both of Maine's fields. Maine records wells on two separate axes, and the analyst can use either or both.

Axis 1, construction and geology. Field me_mgs:ofWellType. Describes what the well is drilled into.

Type	Count
Bedrock	145,408
Gravel	2,884
Overburden	1,205
Other	161
Spring	127
GravelPacked	62
Observation	23
Dug	20

Axis 2, use. Field me_mgs:hasUse. Describes what the well is used for.

Use	Count
Domestic	143,864
Commercial	2,467
Other	881
Municipal	595
Institutional	342
FarmDomestic	226
Geothermal	221
Test	206
Industrial	190
Irrigation	80
Farm	44
Observation	34
Monitoring	21

Other states have no inventory data, so they have no native scheme. Only Approach A applies to them.

Behavior when no state is chosen

The classification is state specific, so with no state chosen we show all of it grouped by state and field, using the same section header dropdown already built for the Material filter.

Well classification
ILLINOIS · PURPOSE
  [ ] Water Well (297,955)
  [ ] Engineering Test (52,016)
  [ ] Monitoring Well (5,802)
MAINE · TYPE
  [ ] Bedrock (145,408)
  [ ] Gravel (2,884)
  [ ] Overburden (1,205)
MAINE · USE
  [ ] Domestic (143,864)
  [ ] Municipal (595)
  [ ] Commercial (2,467)

• With no state chosen, the analyst sees every state's categories under clear headers. Nothing is hidden.
• Picking a category implicitly scopes to that state, because a category only exists in one state. Ticking Bedrock filters to Maine. Ticking Water Well filters to Illinois.
• If a state is already chosen, the dropdown collapses to just that state's groups.

Selection rules

• Same field, same state: OR. Water Well or Engineering in Illinois. Widens results.
• Maine Type and Maine Use, same state: AND. Bedrock and Domestic gives Maine wells that are bedrock and are drunk from. Narrows results. This is the payoff for offering both Maine fields.
• Different states: OR. Illinois plus Maine shown together, because no single well is in two states, so AND would always be empty. This lets an analyst compare two states in one view.

Short version: AND only ever happens between two facts about the same well, which in practice is only Maine Type plus Maine Use. Everywhere else it is OR.

Trade off

Good points: covers all of the roughly 532k inventory wells, gives the richest per state detail, and offering both Maine fields lets an analyst combine construction and use.

Weak points: the two states do not line up. Illinois classifies by purpose, Maine adds construction and geology on top of use, so categories are not comparable across states. Only Illinois and Maine have any scheme. Extra attributes exist per state if we want richer filtering later: Illinois has owner, depth, and yield; Maine has depth and overburden thickness.

Approach A versus Approach B

There is no option that is both full coverage and the same across states, because the graph has no shared classification over the inventory data. The choice depends on which set of wells the filter should target, the sampled wells (Approach A) or the full inventory (Approach B).

Open question

Confirm which set of wells the Well Source filter is meant to serve, the map layer of inventory wells or the contaminant sample queries, before we pick Approach A or Approach B.