Bgc riverinput from file

[ubbu36]

Summary

Adds RIVR2O-based river BGC forcing to RiverForcing, alongside the existing Dai/Trenberth discharge workflow. River mouths can receive spatially and temporally varying carbon and nutrient export from annual RIVR2O files, while discharge can remain a repeating monthly climatology when Dai data are missing.

Also moves MARBL river tracer defaults from hardcoded values to river_tracer_defaults.nc (32 MARBL tracers plus temp and salt, 34 total), downloaded via the same river_data pooch registry as Dai discharge.

Refactors river BGC so RiverForcing is data-source agnostic: RIVR2O export conversion, MARBL tracer mapping, and gap-filling are handled by BGC dataset classes and a shared merge utility, not hardcoded in the forcing orchestrator.

Motivation

Users should be able to use observationally constrained global river BGC export (RIVR2O) instead of uniform default concentrations, including the common case of repeating seasonal discharge (Dai climatology) combined with year-to-year BGC variation from RIVR2O annual files.

River BGC products are patchy by nature. This PR separates discharge (source → Dai) from BGC (bgc_source), and uses an explicit fill policy for tracers the dynamic source does not provide, rather than bespoke merge logic inside RiverForcing.

Key changes

RiverForcing (orchestration)

• New bgc_source options: CONSTANTS (default) or RIVR2O (requires path).
• Optional bgc_source["fill"] (default {"name": "CONSTANTS"}) supplies scalar concentrations for tracers missing from the dynamic source or non-finite at a given (river_time, nriver).
• Unified BGC path for all sources: _apply_bgc_tracers() calls forcing_concentrations() on the configured dataset, then merges with fill via fill_river_bgc_concentrations().
• RiverForcing no longer contains RIVR2O unit conversion, stoichiometry, or MARBL tracer name logic.
• When Dai discharge is climatology and BGC requires a calendar axis (requires_calendar_discharge_time), expands river_time to a monthly calendar axis; river_volume repeats by month while BGC varies by year via abs_time.
• Sets discharge_climatology dataset attribute for plotting and time-axis behavior.

BGC dataset layer (river_datasets.py)

• RiverBGCDataset protocol: forcing_concentrations() and requires_calendar_discharge_time.
• RiverTracerDefaultsDataset: loads recommended defaults from NetCDF; implements forcing_concentrations() for constant fields.
• Rivr2oRiverBGCDataset: owns RIVR2O I/O, DIC-cell sampling, discharge partitioning, export→concentration conversion, and MARBL tracer combinations via forcing_concentrations().
• fill_river_bgc_concentrations(): generic merge of dynamic (river_time, nriver) arrays with scalar fill values.

Rivr2oRiverBGCDataset (RIVR2O product)

• Loads and concatenates yearly rivr2o_riverinputs_*.nc files.
• Renames DIN→NO3 and DIP→PO4; keeps carbon pools separate.
• Uses nearest grid cell with positive DIC export (DIC-only mask).
• discharge_partition_weights splits export among rivers sharing a cell in proportion to discharge, normalized over river_time so co-located rivers get similar concentrations.
• Warns if sampled DIC cell is more than 100 km from the river mouth.
• Year-based time subsetting for July mid-year timestamps; clamps to 1903–2024.

Tracer defaults and downloads

• get_tracer_defaults() reads recommended values from river_tracer_defaults.nc.
• download_river_tracer_defaults() aligned with other downloads: registered on the river_data pooch object (same pattern as download_river_data()), no separate pooch registry or bundled fallback.

Docs and tests

• Updated docs/river_forcing.ipynb with RIVR2O examples and bgc_source["fill"] documentation.
• Updated docs/methods.md River Forcing section for optional BGC and fill.
• New and updated unit tests for fill_river_bgc_concentrations, RIVR2O dataset logic, RiverForcing BGC sources, tracer defaults, and validation snapshots (river_forcing_with_bgc, river_forcing_no_climatology).
• Changes noted in docs/releases.md.
• Passes pre-commit run --all-files.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[codecov]

Codecov Report

❌ Patch coverage is 82.36842% with 67 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.03%. Comparing base (32e13b1) to head (94eb5c1).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
roms_tools/datasets/river_datasets.py	82.45%	21 Missing and 19 partials ⚠️
roms_tools/setup/river_forcing.py	85.18%	9 Missing and 11 partials ⚠️
roms_tools/datasets/download.py	41.66%	7 Missing ⚠️

@@            Coverage Diff             @@
##             main     #615      +/-   ##
==========================================
+ Coverage   86.27%   89.03%   +2.75%     
==========================================
  Files          28       28              
  Lines        6171     6692     +521     
  Branches     1101     1178      +77     
==========================================
+ Hits         5324     5958     +634     
+ Misses        564      415     -149     
- Partials      283      319      +36     

Flag	Coverage Δ
glorys-regional-invariance	?
with-dask-1	79.76% <82.36%> (-0.47%)	⬇️
with-dask-2	49.61% <17.89%> (-2.09%)	⬇️
with-dask-and-xesmf-1	84.07% <82.36%> (?)
with-dask-and-xesmf-2	52.82% <17.89%> (-2.36%)	⬇️
with-streaming	34.38% <17.89%> (-1.50%)	⬇️
without-dask	83.81% <82.36%> (-0.11%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
roms_tools/setup/utils.py	86.14% <100.00%> (-0.72%)	⬇️
roms_tools/datasets/download.py	78.78% <41.66%> (-21.22%)	⬇️
roms_tools/setup/river_forcing.py	89.54% <85.18%> (-0.65%)	⬇️
roms_tools/datasets/river_datasets.py	86.02% <82.45%> (-5.82%)	⬇️

... and 10 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.