DOI: 10.5281/zenodo.14727521
title: SWOT River Database (SWORD)

description: ** IMPORTANT UPDATE: **

Until now, the project and public versions of SWORD have been kept separate while algorithms were being developed in preparation for SWOT launch. Now that the SWOT mission is here, we have decided to publish the project version of SWORD which is why the version numbers jump after v2. The primary difference between the project and public versions of SWORD are extra "filler" variables in the NetCDF format that will be used for calculating discharge. Everything else, reach definition, attribute values, etc. are the same between the two versions. For details on the filler variables please reference the Product Description Document provided with the downloads. 

If you use the SWORD Database in your work, please cite: Altenau et al., (2021) The Surface Water and Ocean Topography (SWOT) Mission River Database (SWORD): A Global River Network for Satellite Data Products. Water Resources Research. https://doi.org/10.1029/2021WR030054

You can also visit www.swordexplorer.com to explore the current version of SWORD before downloading. 

1. Summary:

The upcoming Surface Water and Ocean Topography (SWOT) satellite mission, planned to launch in 2022, will vastly expand observations of river water surface elevation (WSE), width, and slope. In order to facilitate a wide range of new analyses with flexibility, the SWOT mission will provide a range of relevant data products. One product the SWOT mission will provide are river vector products stored in shapefile format for each SWOT overpass (JPL Internal Document, 2020b). The SWOT vector data products will be most broadly useful if they allow multitemporal analysis of river nodes and reaches covering the same river areas. Doing so requires defining SWOT reaches and nodes a priori, so that SWOT data can be assigned to them. The SWOt River Database (SWORD) combines multiple global river- and satellite-related datasets to define the nodes and reaches that will constitute SWOT river vector data products. SWORD provides high-resolution river nodes (200 m) and reaches (~10 km) in shapefile and netCDF formats with attached hydrologic variables (WSE, width, slope, etc.) as well as a consistent topological system for global rivers 30 m wide and greater.

2. Data Formats:

The SWORD database is provided in netCDF, geopackage, and shapefile formats. All files start with a two-digit continent identifier ("af" – Africa, "as" – Asia / Siberia, "eu" – Europe / Middle East, "na" – North America, "oc" – Oceania, "sa" – South America). File syntax denotes the regional information for each file and varies slightly between netCDF and shapefile formats.

NetCDF files are structured in 3 groups: centerlines, nodes, and reaches. The centerline group contains location information and associated reach and node ids along the original GRWL 30 m centerlines (Allen and Pavelsky, 2018). Node and reach groups contain hydrologic attributes at the ~200 m node and ~10 km reach locations (see description of attributes below). NetCDFs are distributed at continental scales with a filename convention as follows: [continent]_sword_v17.nc (i.e. na_sword_v17.nc).

SWORD shapefiles consist of four main files (.dbf, .prj, .shp, .shx). There are separate shapefiles for nodes and reaches, where nodes are represented as ~200 m spaced points and reaches are represented as polylines. All shapefiles are in geographic (latitude/longitude) projection, referenced to datum WGS84. Shapefiles are split into HydroBASINS (Lehner and Grill, 2013) Pfafstetter level 2 basins (hbXX) for each continent with a naming convention as follows: [continent]_sword_[nodes/reaches]_hb[XX]_v17.shp (i.e. na_sword_nodes_hb74_v17.shp; na_sword_reaches_hb74_v17.shp).

SWORD geopackage files are split into two files for nodes and reaches per continental region, where nodes are represented as 200 m spaced points and reaches are represented as polylines. All geopackage files are in geographic (latitude/longitude) projection, referenced to datum WGS84. Geopackage file names are distributed at continental scales and are defined by a two-digit identifier (Table 2): [continent]_sword_[nodes/reaches]_v17.gpkg (i.e. na_sword_nodes_v17.gpkg; na_sword_reaches_v17.gpkg).

3. Attribute Description:

This list contains the primary attributes contained in the SWORD database.



x: Longitude of the node or reach ranging from 180°E to 180°W (units: decimal degrees).

y: Latitude of the node or reach ranging from 90°S to 90°N (units: decimal degrees).

node_id: ID of each node. The format of the id is as follows: CBBBBBRRRRNNNT where C = Continent (the first number of the Pfafstetter basin code), B = Remaining Pfafstetter basin code up to level 6, R = Reach number (assigned sequentially within a level 6 basin starting at the downstream end working upstream), N = Node number (assigned sequentially within a reach starting at the downstream end working upstream), T = Type (1 – river, 3 – lake on river, 4 – dam or waterfall, 5 – unreliable topology, 6 – ghost node).

node_length (node files only): Node length measured along the GRWL centerline points (units: meters).

reach_id: ID of each reach. The format of the id is as follows: CBBBBBRRRRT where C = Continent (the first number of the Pfafstetter basin code), B = Remaining Pfafstetter basin codes up to level 6, R = Reach number (assigned sequentially within a level 6 basin starting at the downstream end working upstream, T = Type (1 – river, 3 – lake on river, 4 – dam or waterfall, 5 – unreliable topology, 6 – ghost reach).

reach_length (reach files only): Reach length measured along the GRWL centerline points (units: meters).

wse: Average water surface elevation (WSE) value for a node or reach. WSEs are extracted from the MERIT Hydro dataset (Yamazaki et al., 2019) and referenced to the EGM96 geoid (units: meters).

wse_var: WSE variance along the GRWL centerline points used to calculate the average WSE for each node or reach (units: square meters).

width: Average width for a node or reach (units: meters).

width_var: Width variance along the GRWL centerline points used to calculate the average width for each node or reach (units: square meters).

max_width: Maximum width value across the channel for each node or reach that includes island and bar areas (units: meters).

facc: Maximum flow accumulation value for a node or reach. Flow accumulation values are extracted from the MERIT Hydro dataset (Yamazaki et al., 2019) (units: square kilometers).

n_chan_max: Maximum number of channels for each node or reach.

n_chan_mod: Mode of the number of channels for each node or reach.

obstr_type: Type of obstruction for each node or reach based on the Globale Obstruction Database (GROD, Whittemore et al., 2020) and HydroFALLS data (http://wp.geog.mcgill.ca/hydrolab/hydrofalls). Obstr_type values: 0 - No Dam, 1 - Dam, 2 - Channel Dam, 3 - Lock, 4 - Low Permeable Dam, 5 - Waterfall.

grod_id: The unique GROD ID for each node or reach with obstr_type values 1-4.

hfalls_id: The unique HydroFALLS ID for each node or reach with obstr_type value 5.

dist_out: Distance from the river outlet for each node or reach (units: meters).

type: Type identifier for a node or reach: 1 – river, 2 – lake off river, 3 – lake on river, 4 – dam or waterfall, 5 – unreliable topology, 6 – ghost reach/node.

lakeflag: GRWL water body identifier for each reach:  0 – river, 1 – lake/reservoir, 2 – canal,  3 – tidally influenced river.

manual_add (node files only): Binary flag indicating whether the node was manually added to the public GRWL centerlines (Allen and Pavelsky, 2018). These nodes were originally given a width = 1, but have since been updated to have the reach width values.

meand_len (node files only): Length of the meander that a node belongs to, measured from beginning of the meander to its end in meters. For nodes longer than one meander, the meander length will represent the average length of all meanders belonging to the node (units: meters).

sinuosity (node files only): The total reach length the node belongs to divided by the Euclidean distance between the reach end points.

slope (reach files only): Reach average slope calculated along the GRWL centerline points. Slopes are calculated using a linear regression (units: meters/kilometer).

n_nodes (reach files only): Number of nodes associated with each reach.

n_rch_up (reach files only): Number of upstream reaches for each reach.

n_rch_down (reach files only): Number of downstream reaches for each reach.

rch_id_up (reach files only): Reach IDs of the upstream neighboring reaches.

rch_id_dn (reach files only): Reach IDs of the downstream neighboring reaches.

swot_obs (reach files only): The maximum number of SWOT passes to intersect each reach during the 21 day orbit cycle.

swot_orbits (reach files only): A list of the SWOT orbit tracks that intersect each reach during the 21 day orbit cycle.

river_name: All river names associated with a node or reach. If there are multiple names for a node or reach they are listed in alphabetical order and separated by a semicolon.

edit_flag: Numerical flag indicating the type of update applied to SWORD nodes or reaches from the previous version. Flag descriptions are listed in the Product Description Documentation included with the file downloads.

trib_flag: Binary flag indicating if a large tributary not represented in SWORD is entering a node or reach. 0 - no tributary, 1 - tributary.


4. References:

Allen, G. H., & Pavelsky, T. M. (2018). Global extent of rivers and streams. Science, 361(6402), 585-588.

Altenau, E. H., Pavelsky, T. M., Durand, M. T., Yang X., Frasson, R. P. d. 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.

Biancamaria, S., Lettenmaier, D. P., & Pavelsky, T. M. (2016). The SWOT mission and its capabilities for land hydrology. In Remote Sensing and Water Resources (pp. 117-147). Springer, Cham.

JPL Internal Document (2020b). Surface Water and Ocean Topography Mission Level 2 KaRIn high rate river single pass vector product, JPL D-56413, Rev. A, https://podaac-tools.jpl.nasa.gov/drive/files/misc/web/misc/swot_mission_docs/pdd/D-56413_SWOT_Product_Description_L2_HR_RiverSP_20200825a.pdf

Lehner, B., Grill G. (2013): Global river hydrography and network routing: baseline data and new approaches to study the world's large river systems. Hydrological Processes, 27(15): 2171–2186. Data is available at www.hydrosheds.org.

Tessler, Z. D., Vörösmarty, C. J., Grossberg, M., Gladkova, I., Aizenman, H., Syvitski, J. P. M., & Foufoula-Georgiou, E. (2015). Profiling risk and sustainability in coastal deltas of the world. Science, 349(6248), 638-643.

Whittemore, A., Ross, M. R., Dolan, W., Langhorst, T., Yang, X., Pawar, S., Jorissen, M., Lawton, E., Januchowski-Hartley, S., & Pavelsky, T. (2020). A Participatory Science Approach to Expanding Instream Infrastructure Inventories. Earth's Future, 8(11), e2020EF001558.

Yamazaki, D., Ikeshima, D., Sosa, J., Bates, P. D., Allen, G., & Pavelsky, T. (2019). MERIT Hydro: A high-resolution global hydrography map based on latest topography datasets. Water Resources Research. https://doi.org/10.1029/2019WR024873.

Yang, X., Pavelsky, T. M., Allen, G. H. (2019). The past and future of global river ice. Nature.

SWOT Orbits: https://www.aviso.altimetry.fr/en/missions/future-missions/swot/orbit.html

HydroFALLS: http://wp.geog.mcgill.ca/hydrolab/hydrofalls/