DOI: 10.5281/zenodo.14675925
title: MERIT-SWORD: Bidirectional Translations Between MERIT-Basins and the SWOT River Database (SWORD)

description: Corresponding peer-reviewed publication

This dataset corresponds to all input and output files that were used in the study reported in:



Wade, J., David, C.H., Collins, E.L., Altenau, E.H., Coss, S., Cerbelaud, A., Tom, M., Durand, M., Pavelsky T.M. (In Review), Bidirectional Translations Between Observational and Topography-based Hydrographic Datasets: MERIT-Basins and the SWOT River Database (SWORD).


When making use of any of the files in this dataset, please cite both the aforementioned article and the dataset herein.

 

Summary

The MERIT-SWORD data product reconciles critical differences between the SWOT River Database (SWORD; Altenau et al., 2021), the hydrography dataset used to aggregate observations from the Surface Water and Ocean Topography (SWOT) Mission, and MERIT-Basins (MB; Lin et al., 2019; Yang et al., 2021), an elevation-derived vector hydrography dataset commonly used by global river routing models (Collins et al., 2024). The SWORD and MERIT-Basins river networks differ considerably in their representation of the location and extent of global river reaches, complicating potential synergistic data transfer between SWOT observations and existing hydrologic models.

MERIT-SWORD aims to:



Generate bidirectional, one-to-many links (i.e. translations) between river reaches in SWORD and MERIT-Basins (ms_translate files).

Provide a reach-specific evaluation of the quality of translations (ms_diagnostic files).


 

Data sources

The following sources were used to produce files in this dataset:



MERIT-Basins (version 1.0) derived from MERIT-Hydro (version 0.7) available under a CC BY-NC-SA 4.0 license. https://www.reachhydro.org/home/params/merit-basins

SWOT River Database (SWORD) (version 16) available under a CC BY 4.0. https://zenodo.org/records/10013982. DOI: 10.5281/zenodo.10013982

Mean Discharge Runoff and Storage (MeanDRS) dataset (version v0.4) available under a CC BY-NC-SA 4.0 license. https://zenodo.org/records/10013744. DOI: 10.5281/zenodo.10013744; 10.1038/s41561-024-01421-5


 

Software

The software that was used to produce files in this dataset are available at https://github.com/jswade/merit-sword.

 

Primary Data Products

The following files represent the primary data products of the MERIT-SWORD dataset. Each file class generally has 61 files, corresponding to the 61 global hydrologic regions (region ii). For typical use of this dataset, download the 3 following zip folders listed below. The ms_translate.zip and ms_diagnostic.zip NetCDF files are best suited for scripting applications, while the ms_translate_shp.zip shapefiles are best suited for GIS applications.

The MERIT-SWORD translation tables (.nc) establish links between corresponding river reaches in MERIT-Basins and SWORD in both directions. The mb_to_sword translations relate the COMID values of all MERIT-Basins reaches in region ii (as defined by MERIT-Basins) to corresponding SWORD reach_id values, which are ranked by their degree of overlap and stored in columns sword_1 – sword_40. The partial intersecting lengths (m) of SWORD reaches within related MERIT-Basins unit catchments are stored in columns part_len_1 – part_len_40 and can be used to weight data transfers from more than one SWORD reach. The sword_to_mb translations relate the reach_id values of all SWORD reaches in region ii (as defined by SWORD) to corresponding MERIT-Basins COMID values, which are ranked by their degree of overlap and stored in columns mb_1­ – mb_40. The partial intersecting lengths (m) of SWORD reaches within related MERIT-Basins unit catchments are again stored in columns part_len_1 – part_len_40.



ms _translate.zip



mb_to_sword: mb_to_sword_pfaf_ii_translate.nc

sword_to_mb: sword_to_mb_pfaf_ii_translate.nc




 

The MERIT-SWORD diagnostic tables (.nc) contain evaluations of the quality of translations between MERIT-Basins and SWORD reaches, stored in column flag.  The mb_to_sword diagnostic files contain integer quality flags for each MERIT-Basins reach translation in region ii. The sword_to_mb diagnostic files contain integer quality flags for each SWORD reach translation in region ii. The quality flags are as follows:



0 = Valid translation.

1 = Translated reaches are not topologically connected to each other.

2 = Reach does not have a corresponding reach in the other dataset (absent translation).

21 = Reach does not have a corresponding reach in the other dataset due to flow accumulation mismatches.

22 = Reach does not have a corresponding reach in the other dataset because it is located in what the other dataset defines as the ocean.




ms_diagnostic.zip



mb_to_sword: mb_to_sword_pfaf_ii_diagnostic.nc

sword_to_mb: sword_to_mb_pfaf_ii_diagnostic.nc




 

For GIS applications, the translations and diagnostic tables are also available in shapefile format, joined to their respective MERIT-Basins and SWORD river vector shapefiles. The MERIT-Basins and SWORD shapefiles retain their original attribute tables, in additional to the added translation and diagnostic columns.



ms _translate_shp.zip



mb: riv_pfaf_ii_MERIT_Hydro_v07_Basins_v01_translate.shp

sword: jj_sword_reaches_hbii_v16_translate.shp




 

 

Example Applications Data Products

The following files are example use cases of transferring data between MERIT-Basins and SWORD. They are not required for typical use of the MERIT-SWORD dataset.

The MeanDRS-to-SWORD application example files demonstrate how the MERIT-SWORD translation tables can be used to transfer discharge simulations along MERIT-Basins reaches (i.e. MeanDRS; https://zenodo.org/records/8264511) to corresponding SWORD reaches in region ii and continent xx. MeanDRS discharge simulations (m3 s-1) are transferred to SWORD reaches based on a weighted average translation of corresponding reaches and stored in the column meanDRS_Q.



app_meandrs_to_sword.zip: xx_sword_reaches_hbii_v16_meandrs.shp


 

The SWORD-to-MERIT-Basins application example files demonstrate how the MERIT-SWORD translation tables can be used to transfer variables of interest (in this case, river width) from SWORD reaches to corresponding MERIT-Basins reaches in region ii. SWORD width estimates (m) are transferred to MERIT-Basins reaches based on a weighted average translation of corresponding reaches and stored in the column sword_wid.



app_sword_to_mb.zip: riv_pfaf_ii_MERIT_Hydro_v07_Basins_v01_sword.shp


 

Intermediate Data Products

The following files are intermediates used in generating the primary data. They are not required for typical use of the MERIT-SWORD dataset.

The MERIT-SWORD river trace files represent our first approximation of MERIT-Basins reaches that correspond to SWORD reaches in region ii, prior to the manual removal of mistakenly included reaches. The river trace files are only used to generate the final river network files and are not used elsewhere in the dataset.



ms_riv_trace.zip: meritsword_pfaf_ii_trace.shp


 

The MERIT-SWORD river network shapefiles contain the MERIT-Basins reaches that in aggregate best correspond to the location and extent of the SWORD river network for each of the Pfafstetter level 2 regions as defined by SWORD v16 (i.e. the 61 values of ii). The MERIT-SWORD river networks serve as an intermediary data product to enable reliable translations.



ms_riv_network.zip: meritsword_pfaf_ii_network.shp 


 

The MERIT-SWORD transpose files are used to confirm that the translation tables in one direction can recreated in their entirety using only data from the translation tables in the other direction, ensuring ~3,500 less data transfer. These files are exact copies of the files contained in ms_translate.zip.



ms _transpose.zip



mb_transposed: mb_to_sword_pfaf_ii_transpose.nc

sword_transposed: sword_to_mb_pfaf_ii_transpose.nc




 

The MERIT-SWORD translation catchment files contain the MERIT-Basins unit catchments corresponding to each reach used in generating the mb_to_sword and sword_to_mb translations for each region ii. The files are used internally during the translation process and not required for typical dataset use.



ms_translate_cat.zip



mb_to_sword: mb_to_sword_pfaf_ii_translate_cat.nc

sword_to_mb: sword_to_mb_pfaf_ii_translate.cat.nc




 

The hydrologic regions as defined by MERIT-Basins and SWORD are not identical and overlap in many cases, complicating translations. The region overlap files provide bidirectional mappings between region identifiers in both datasets. The files are used in most dataset scripts to determine the regional files from each dataset that need to be loaded.



ms_region_overlap.zip: sword_to_mb_reg_overlap.csv, sword_to_mb_reg_overlap.csv


 

The MERIT-SWORD river edit files contain ~3,500 MERIT-Basins river reaches that were mistakenly included during river network generation and do not correspond to any SWORD reaches. These reaches are removed from the river trace files to generate the final MERIT-SWORD river network data product.



ms_riv_edit.zip: meritsword_edits.csv


 

Near the antimeridian, MERIT-Basins and SWORD shapefiles differ in their longitude convention. Additionally, the SWORD dataset lacks a shapefile for region 54, which does not have any SWORD reaches. The SWORD edit files contain copies of SWORD files, altered to match the longitude convention of MERIT-Basins and including a dummy shapefile for region 54.



sword_edit.zip: xx_sword_reaches_hbii_v16.shp


 

Known bugs in this dataset or the associated manuscript

No bugs have been identified at this time.

 

References

Altenau, E. H., Pavelsky, T. M., Durand, M. T., Yang, X., Frasson, R. P. de M., & Bendezu, L. (2021). The Surface Water and Ocean Topography (SWOT) Mission River Database (SWORD): A Global River Network for Satellite Data Products. Water Resources Research, 57(7), e2021WR030054. https://doi.org/10.1029/2021WR030054

Collins, E. L., David, C. H., Riggs, R., Allen, G. H., Pavelsky, T. M., Lin, P., Pan, M., Yamazaki, D., Meentemeyer, R. K., & Sanchez, G. M. (2024). Global patterns in river water storage dependent on residence time. Nature Geoscience, 1–7. https://doi.org/10.1038/s41561-024-01421-5

Lin, P., Pan, M., Beck, H. E., Yang, Y., Yamazaki, D., Frasson, R., David, C. H., Durand, M., Pavelsky, T. M., Allen, G. H., Gleason, C. J., & Wood, E. F. (2019). Global Reconstruction of Naturalized River Flows at 2.94 Million Reaches. Water Resources Research, 55(8), 6499–6516. https://doi.org/10.1029/2019WR025287

Yang, Y., Pan, M., Lin, P., Beck, H. E., Zeng, Z., Yamazaki, D., David, C. H., Lu, H., Yang, K., Hong, Y., & Wood, E. F. (2021). Global Reach-Level 3-Hourly River Flood Reanalysis (1980–2019). Bulletin of the American Meteorological Society, 102(11), E2086–E2105. https://doi.org/10.1175/BAMS-D-20-0057.1