Support auxiliary hydrofabric attribute tables as source for catchment attributes

[robertbartel]

Some hydrofabric files (or, supplemental files) may be created that contain per-divide model params for different formulations (e.g., from regionalization tools). These may be in tables named something other than divide-attributes - the previous standard - or even multiple tables. This PR adds configuration and functional capabilities to join data from these auxiliary tables with catchment features data from divides table. This then makes the auxiliary data available to the existing mechanisms for setting formulation module parameter values via the realization config; i.e., with the model_params "source": "hydrofabric" syntax. For example:

"model_params": {
    "bexp": { "source": "hydrofabric", "from": "reg.b" }
}

The PR introduces a new, optional, top-level key for the realization config: auxiliary_hydrofabric_attributes. It can be used as follows:

"auxiliary_hydrofabric_attributes": [                     
    {
        "table": "cfexnom__v___regn_jul26_cfexnom_clust_test2_gower_agglomerative_k15",
        "alias": "reg",              // optional; prefix defaults to the table name
        "file": "path/to/other.gpkg",// optional; defaults to the CLI catchment data file
        "key_column": "divide_id",   // optional; this is the default used to join table to `divides`
        "required": false            // optional; this is the default
    }
]

Tables are expected to be in the catchment data hydrofabric file provided on the command line, but optionally another file can be provided via the config.

A configured table must exist. Rows only must exist if "required": true within that table's entry in "auxiliary_hydrofabric_attributes"; if false, params will be skipped for missing-row catchments.

[aaraney]

This is something i've wanted for a while! This is great!

Having just glanced at the semantics, I was a little confused that the source remains hydrofabric when pulling from an auxiliary. What was your thinking in keeping source: hydrofabric over source: reg / the full table name?

[robertbartel]

The design works by joining the aux data to divide data from the hydrofabric. So, we are appending something to the data already exposed to things when source: hydrofabric is used. In that sense, it isn’t a different source.

At a higher level, I was anticipating the/a common use case would be for the aux tables to actually be included in the hydrofabric file (largely because I was working with an example file where this was the case). In that situation also, source: hydrofabric seemed natural and appropriate.

[robertbartel]

Converting to draft for the moment. The design of #960 (and potentially further refinements to it) will likely impact the details of this significantly. Some initial review is fine, but full formal review should probably wait until #960 is settled.

[PhilMiller]

I haven't looked at the code yet, but from the description, am I right to understand that these values must still be in the same file as the hydrofabric itself? I think we can pretty clearly see to a future where that won't be desirable - Hydrofabric v.N is finalized, and then we're doing various runs to generate auxiliary parameter values associated with it. We should expect to reference the hydrofabric from a read-only file, and load other data that references it from elsewhere (e.g. another SQLite file).

[PhilMiller]

That "multiple SQLite file" thing would even still allow full database query functionality:
https://stackoverflow.com/questions/6824717/sqlite-how-do-you-join-tables-from-different-databases

[PhilMiller]

Oops, I'm apparently illiterate today. Your description showed a "file: other.gpkg" line, and I totally missed it.