Bias Correction: The RAPID2 Sandbox¶

This tutorial demonstrates how to correct biases in external inflows using the Long-Term Inverse Routing (LTIR) methodology in RAPID2.

Prerequisites: We assume you have already completed the Quick Start tutorial (quick-start-sandbox.md). Your Python virtual environment should be activated, and the Sandbox data must already be downloaded into the input/Sandbox/ and output/Sandbox/ directories.

This tutorial was written for rapid2 2.0.0b5.

1. Calculate the Scaling Factors¶

First, we need to compute the scaling factors using our "First Guess" (FG) flawed external inflow and our "True" (TR) observations. We'll use the ltir_scl tool to generate a scaling parameter file (scl_Sandbox.parquet):

rapid2 prep ltir \
  -con input/Sandbox/con_Sandbox.parquet \
  -bas input/Sandbox/bas_Sandbox_ascend.parquet \
  -Qex input/Sandbox/Qex_Sandbox_19700101_19700110_FG.nc4 \
  -Qob input/Sandbox/Qob_Sandbox_19700101_19700110_TR.nc4 \
  -scl input/Sandbox/scl_Sandbox_tst.parquet

2. Apply Bias Correction to External Inflow¶

Now, we apply the computed scalars to the flawed First Guess inflow (Qex_..._FG.nc4) to create a new, Bias Corrected external inflow file (Qex_..._BC.nc4) using the ltir_cor tool:

rapid2 core ltir \
  -prv input/Sandbox/Qex_Sandbox_19700101_19700110_FG.nc4 \
  -scl input/Sandbox/scl_Sandbox.parquet \
  -now input/Sandbox/Qex_Sandbox_19700101_19700110_BC_tst.nc4

3. Run the Bias-Corrected Simulation¶

With our corrected inflow ready, we can run the model using the Bias Correction (BC) namelist:

rapid2 core run --namelist input/Sandbox/nml_Sandbox_BC.yml

Note: This namelist is pre-configured to use the newly generated Qex_..._BC.nc4 inflow file. It will output Qou_Sandbox_19700101_19700110_BC_tst.nc4 and Qfi_Sandbox_19700101_19700110_BC_tst.nc4 in your output/Sandbox/ folder.

4. Subsample the Output¶

To compare our corrected model output with the true observations, we need to spatially and temporally subsample the high-resolution output (Qou) to match the daily cadence of our gauges, creating our Model Equivalent (Qme):

rapid2 prep sample \
  -Qou output/Sandbox/Qou_Sandbox_19700101_19700110_BC.nc4 \
  -obs input/Sandbox/obs_Sandbox.parquet \
  -dtO 86400 \
  -Qme output/Sandbox/Qme_Sandbox_19700101_19700110_BC_tst.nc4

5. Visualize the Improvement¶

Finally, let's plot the hydrographs to see how well the bias correction worked! We'll compare the new Model Equivalent (Qme) to the True observations (Qob):

rapid2 eval graph \
  -Qob input/Sandbox/Qob_Sandbox_19700101_19700110_TR.nc4 \
  -Qme output/Sandbox/Qme_Sandbox_19700101_19700110_BC.nc4 \
  -max 125 \
  -hyd output/Sandbox/hyd_Qou_BC.svg

Check your output/Sandbox/ folder for the newly generated .svg files (e.g., hyd_BC_30.svg and hyd_BC_50.svg). You will see that the red dashed line (model equivalent) now has a mean that aligns beautifully with that of the black solid line (observations)! Also note that the amplitude was changed because LTIR uses a multiplier correction.

Explore Further: Now that you've mastered Bias Correction, try running the new Data Assimilation (DA).