Structurally constrained hierarchical learning for improving river health assessment using tabular transformers

River ecosystems are hierarchically organized systems in which biological responses to environmental stressors emerge across multiple organizational levels. River health indices (RHIs) operationalize this hierarchy by aggregating biological sub-metrics into assemblage-specific multi-metric indices (MMIs) and an integrated assessment index (IAI). However, most predictive models treat RHI estimation as a flat learning problem, disregarding the hierarchical dependencies and producing predictions that violate aggregation relationships. To address this limitation, we developed the hierarchically constrained deep learning (HCDL) framework that combines hierarchical learning with a reconciliation layer to ensure structurally coherent prediction of multi-level RHIs. HCDL employs transformer modules organized across three hierarchical levels: biological sub-metrics, assemblage-specific MMIs for diatoms, benthic macroinvertebrates, and fish, and the IAI. The raw multi-level HCDL outputs are reconciled using exact aggregation rules to obtain the final reconciled predictions, denoted R-HCDL. The framework was evaluated using nationwide biomonitoring data from 2,833 sites across South Korea, including the four major river basins and Jeju Island. R-HCDL achieved NNSE values of 0.599-0.716 across MMIs and the IAI, with the highest NNSE for the IAI and BAI among the compared models, while enforcing exact cross-level consistency and generally reducing regression toward the mean at the distributional extremes. Hierarchical interpretation based on propagated attention weights summarized model-derived information-use patterns across the predefined assessment hierarchy, which were broadly consistent with established ecological understanding. Exploratory scenario analysis showed structurally consistent model-predicted responses to specified changes in environmental inputs across sub-metrics, MMIs, and the IAI. These results suggest that R-HCDL provides a predictive and structurally consistent framework for modeling hierarchical ecological indices, with potential utility for exploratory screening and hypothesis generation pending external validation.