Mainstem support in indexing functions

[dblodgett-usgs]

This is an issue to document use cases that need to be supported as use of mainstems as a cross-dataset identifier progresses.

Most will relate to point indexing hydrolocations along mainstem flowpaths. I see two key use cases that will need to be supported:

Linking: As a user with data describing locations thought to be along a river, I need to link my locations to rivers to establish the hydrologic context of the location in question.

For linking, most of the same logic as has been used for indexing in the passed applies and additional information may be useful, such as a previously established "event" or "comid" link that would be immediately transferable to mainstem.

Lookup: As a user of hydrologic data linked to mainstems, I need to retrieve the precise point location and catchment identifier for my point from a given dataset of interest.

In this case, pulling from the data in the mainstems data release(s) will be necessary. Given a mainstem, it will need to be retrieved from the relevant hydrographic data source and the required catchment index returned.

A third use case worth writing down as a generally needed utility is around finding updates to mainstems:

Update: As a user of data linked to mainstems, I need to check if the mainstemids used by my data are up to date so I can be sure I am using the most accurate and current data sources.

For this use case, the reference mainstems and USGS mainstems will need to be evaluated to ensure each is the most recent available. If one is found to be superceded or deleted, a new maintsem will need to be established using the Linking functionality.

Translate: As a user with data indexed to one hydrography product, I need to translate my data’s location references to another hydrography product while maintaining consistent catchment/flowpath identity.

For this use case, the inlet and outlet hydrolocations of one set of catchment flowpaths need to be located along the catchment/flowpaths of another hydrography. For datasets like the WBD -- where catchments are not well defined, only drainage area outlet locations would be translated. Some of these translations are already established in the mainstems data release and code from creating them could be a baseline for satisfying the use case.

[dblodgett-usgs]

An interesting concept with all this is whether we will preserve upstream / downstream topology and to what degree those checks are done. Theoretically, we could use a set of reference hydrologic locations (such as confluences) as locations that are known on various datasets / versions of the network and do some checks to make sure we are gerenally getting a relationship right along the network so far as the end user cares.

[ksonda]

this one is like, more geoconnex-adjacent, but something we are running into with USBR right now:

Linking: As a USBR data manager with dam/reservoir locations, I need to find corresponding features in reference datasets to validate and establish the identity of my locations. When multiple reference features exist in close proximity, I want to use mainstem associations to help determine which is the correct match for my location.

For linking, spatial proximity and name matching provides initial candidates, but mainstem context in the reference feature set helps disambiguate between similar features. By identifying which mainstem my dam relates to versus nearby candidates, I can more confidently establish feature identity and avoid incorrect matches to nearby but hydrologically distinct features.
This becomes particularly important when:

• Multiple dam/reservoirs exist along different tributaries in close proximity
• A dam has different names in different datasets (e.g., "Hugh Butler Lake" vs "Red Willow Dam")
• I need to validate that my existing location references align with authoritative sources