RAPID GIS Tools

These tools generate the RAPID input files and weight table files from the GIS stream networks.

Note

To generate your own network from a DEM see Generating Stream Network

Note

For these tools to work, you need GIS dependencies installed (See Installation).

There are also tools by Esri for ArcMap located here:

Workflows

Static RAPID Files

RAPIDpy.gis.workflow.CreateAllStaticRAPIDFiles(in_drainage_line, river_id, length_id, slope_id, next_down_id, rapid_output_folder, kfac_celerity=0.2777777777777778, kfac_formula_type=3, kfac_length_units='km', lambda_k=0.35, x_value=0.3, nhdplus=False, taudem_network_connectivity_tree_file=None, file_geodatabase=None)[source]

To generate the static RAPID files (rapid_connect.csv, riv_bas_id.csv, kfac.csv, k.csv, x.csv, comid_lat_lon_z.csv) with default values.

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • length_id (str) – The field name containging the length of the river segment (Ex. ‘LENGTHKM’ or ‘Length’).
  • slope_id (str) – The field name containging the slope of the river segment (Ex. ‘Avg_Slope’ or ‘Slope’).
  • next_down_id (str) – The name of the field with the river ID of the next downstream river segment (Ex. ‘NextDownID’ or ‘DSLINKNO’).
  • rapid_output_folder (str) – The path to the folder where all of the RAPID output will be generated.
  • kfac_celerity (Optional[float]) – The flow wave celerity for the watershed in meters per second. 1 km/hr or 1000.0/3600.0 m/s is a reasonable value if unknown.
  • kfac_formula_type (Optional[int]) – An integer representing the formula type to use when calculating kfac. Default is 3.
  • kfac_length_units (Optional[str]) – The units for the length_id field. Supported types are “m” for meters and “km” for kilometers. Default is “km”.
  • lambda_k (Optional[float]) – The value for lambda given from RAPID after the calibration process. Default is 0.35.
  • x_value (Optional[float]) – Value for the muskingum X parameter [0-0.5]. Default is 0.3.
  • nhdplus (Optional[bool]) – If True, the drainage line is from the NHDPlus dataset with the VAA fields COMID, FROMNODE, TONODE, and DIVERGENCE. Default is False.
  • taudem_network_connectivity_tree_file (Optional[str]) – If set, the connectivity file will be generated from the TauDEM connectivity tree file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.workflow import CreateAllStaticRAPIDFiles
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__=="__main__":
    CreateAllStaticRAPIDFiles(in_drainage_line="/path/to/drainage_line.shp",
                              river_id="HydroID",
                              length_id="LENGTHKM",
                              slope_id="SLOPE",
                              next_down_river_id="NextDownID",
                              rapid_output_folder="/path/to/rapid/output",
                             )

Weight Table Files

RAPIDpy.gis.workflow.CreateAllStaticECMWFFiles(in_catchment, catchment_river_id, rapid_output_folder, rapid_connect_file, file_geodatabase=None)[source]

This creates all of the ECMWF grid weight tables using an area weighted method based on Esri’s RAPID_Toolbox.

Parameters:
  • in_catchment (str) – Path to the Catchment shapefile.
  • catchment_river_id (str) – The name of the field with the river ID (Ex. ‘DrainLnID’ or ‘LINKNO’).
  • rapid_output_folder (str) – The path to the folder where all of the RAPID output will be generated.
  • rapid_connect_file (str) – The path to the RAPID connectivity file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.workflow import CreateAllStaticECMWFFiles
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__=="__main__":
    CreateAllStaticECMWFFiles(in_catchment="/path/to/catchment.shp",
                              catchment_river_id="DrainLnID",
                              rapid_output_folder="/path/to/rapid/output",
                              rapid_connect_file="/path/to/rapid_connect.csv",
                              )

Static RAPID Files and Weight Table Files

RAPIDpy.gis.workflow.CreateAllStaticECMWFRAPIDFiles(in_drainage_line, river_id, length_id, slope_id, next_down_id, in_catchment, catchment_river_id, rapid_output_folder, kfac_celerity=0.2777777777777778, kfac_formula_type=3, kfac_length_units='km', lambda_k=0.35, x_value=0.3, nhdplus=False, taudem_network_connectivity_tree_file=None, file_geodatabase=None)[source]

This creates all of the static RAPID files and ECMWF grid weight tables.

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • length_id (str) – The field name containging the length of the river segment (Ex. ‘LENGTHKM’ or ‘Length’).
  • slope_id (str) – The field name containging the slope of the river segment (Ex. ‘Avg_Slope’ or ‘Slope’).
  • next_down_id (str) – The name of the field with the river ID of the next downstream river segment (Ex. ‘NextDownID’ or ‘DSLINKNO’).
  • in_catchment (str) – Path to the Catchment shapefile.
  • catchment_river_id (str) – The name of the field with the river ID (Ex. ‘DrainLnID’ or ‘LINKNO’).
  • rapid_output_folder (str) – The path to the folder where all of the RAPID output will be generated.
  • kfac_celerity (Optional[float]) – The flow wave celerity for the watershed in meters per second. 1 km/hr or 1000.0/3600.0 m/s is a reasonable value if unknown.
  • kfac_formula_type (Optional[int]) – An integer representing the formula type to use when calculating kfac. Default is 3.
  • kfac_length_units (Optional[str]) – The units for the length_id field. Supported types are “m” for meters and “km” for kilometers. Default is “km”.
  • lambda_k (Optional[float]) – The value for lambda given from RAPID after the calibration process. Default is 0.35.
  • x_value (Optional[float]) – Value for the muskingum X parameter [0-0.5]. Default is 0.3.
  • nhdplus (Optional[bool]) – If True, the drainage line is from the NHDPlus dataset with the VAA fields COMID, FROMNODE, TONODE, and DIVERGENCE. Default is False.
  • taudem_network_connectivity_tree_file (Optional[str]) – If set, the connectivity file will be generated from the TauDEM connectivity tree file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.workflow import CreateAllStaticECMWFRAPIDFiles
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__=="__main__":
    CreateAllStaticECMWFRAPIDFiles(in_drainage_line="/path/to/drainage_line.shp",
                                   river_id="HydroID",
                                   length_id="LENGTHKM",
                                   slope_id="SLOPE",
                                   next_down_id="NextDownID",
                                   in_catchment="/path/to/catchment.shp",
                                   catchment_river_id="DrainLnID",
                                   rapid_output_folder="/path/to/rapid/output",
                                  )

Individual Tools

Static RAPID Files

RAPIDpy.gis.network.CreateNetworkConnectivity(in_drainage_line, river_id, next_down_id, out_connectivity_file, file_geodatabase=None)[source]

Creates Network Connectivity input CSV file for RAPID based on the Drainage Line shapefile with river ID and next downstream ID fields

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • next_down_id (str) – The name of the field with the river ID of the next downstream river segment (Ex. ‘NextDownID’ or ‘DSLINKNO’).
  • out_connectivity_file (str) – The path to the output connectivity file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.network import CreateNetworkConnectivity
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateNetworkConnectivity(in_drainage_line='/path/to/drainageline.shp',
                              river_id='LINKNO',
                              next_down_id='DSLINKNO',
                              out_connectivity_file='/path/to/rapid_connect.csv',
                             )
RAPIDpy.gis.network.CreateNetworkConnectivityNHDPlus(in_drainage_line, out_connectivity_file, file_geodatabase=None)[source]

Creates Network Connectivity input CSV file for RAPID based on the NHDPlus drainage lines with COMID, FROMNODE, TONODE, and DIVERGENCE fields.

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • out_connectivity_file (str) – The path to the output connectivity file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.network import CreateNetworkConnectivityNHDPlus
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateNetworkConnectivityNHDPlus(in_drainage_line='/path/to/drainageline.shp',
                                     out_connectivity_file='/path/to/rapid_connect.csv',
                                     )
RAPIDpy.gis.network.CreateSubsetFile(in_drainage_line, river_id, out_riv_bas_id_file, file_geodatabase=None)[source]

Creates River Basin ID subset input CSV file for RAPID based on the Drainage Line shapefile with river ID and next downstream ID fields

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • out_riv_bas_id_file (str) – The path to the output river basin ID subset file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.network import CreateSubsetFile
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateSubsetFile(in_drainage_line='/path/to/drainageline.shp',
                     river_id='LINKNO',
                     out_riv_bas_id_file='/path/to/riv_bas_id.csv',
                     )
RAPIDpy.gis.muskingum.CreateMuskingumKfacFile(in_drainage_line, river_id, length_id, slope_id, celerity, formula_type, in_connectivity_file, out_kfac_file, length_units='km', slope_percentage=False, file_geodatabase=None)[source]

Creates the Kfac file for calibration.

The improved methods using slope to generate values for Kfac were proven here:

Tavakoly, A. A., A. D. Snow, C. H. David, M. L. Follum, D. R. Maidment, and Z.-L. Yang, (2016) “Continental-Scale River Flow Modeling of the Mississippi River Basin Using High-Resolution NHDPlus Dataset”, Journal of the American Water Resources Association (JAWRA) 1-22. DOI: 10.1111/1752-1688.12456

Formula Type Options:

  1. River Length/Celerity;
  2. Eta*River Length/Sqrt(River Slope); and 3 is
  3. Eta*River Length/Sqrt(River Slope) [0.05, 0.95]

Where Eta = Average(River Length/Co of all rivers) / Average(River Length/Sqrt(River Slope) of all rivers)

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • length_id (str) – The field name containging the length of the river segment (Ex. ‘LENGTHKM’ or ‘Length’).
  • slope_id (str) – The field name containging the slope of the river segment (Ex. ‘Avg_Slope’ or ‘Slope’).
  • celerity (float) – The flow wave celerity for the watershed in meters per second. 1 km/hr or 1000.0/3600.0 m/s is a reasonable value if unknown.
  • formula_type (int) – An integer representing the formula type to use when calculating kfac.
  • in_connectivity_file (str) – The path to the RAPID connectivity file.
  • out_kfac_file (str) – The path to the output kfac file.
  • length_units (Optional[str]) – The units for the length_id field. Supported types are “m” for meters and “km” for kilometers.
  • slope_percentage (Optional[bool]) – If True, it assumes the slope given is in percentage and will divide by 100. Default is False.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.muskingum import CreateMuskingumKfacFile
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateMuskingumKfacFile(in_drainage_line='/path/to/drainageline.shp',
                            river_id='LINKNO',
                            length_id='Length',
                            slope_id='Slope',
                            celerity=1000.0/3600.0,
                            formula_type=3,
                            in_connectivity_file='/path/to/rapid_connect.csv',
                            out_kfac_file='/path/to/kfac.csv',
                            length_units="m",
                            )
RAPIDpy.gis.muskingum.CreateMuskingumKFile(lambda_k, in_kfac_file, out_k_file)[source]

Creates muskingum k file from kfac file.

Parameters:
  • lambda_k (float) – The value for lambda given from RAPID after the calibration process. If no calibration has been performed, 0.35 is reasonable.
  • in_kfac_file (str) – The path to the input kfac file.
  • out_k_file (str) – The path to the output k file.

Example:

from RAPIDpy.gis.muskingum import CreateMuskingumKFile
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateMuskingumKFile(lambda_k=0.35,
                         in_kfac_file='/path/to/kfac.csv',
                         out_k_file='/path/to/k.csv',
                         )
RAPIDpy.gis.muskingum.CreateMuskingumXFileFromDranageLine(in_drainage_line, x_id, out_x_file, file_geodatabase=None)[source]

Create muskingum X file from drainage line.

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • x_id (str) – The name of the muksingum X field (i.e. ‘Musk_x’).
  • out_x_file (str) – The path to the output x file.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.muskingum import CreateMuskingumXFileFromDranageLine
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateMuskingumXFileFromDranageLine(in_drainage_line='/path/to/drainageline.shp',
                                        x_id='Musk_x',
                                        out_x_file='/path/to/x.csv',
                                        )
RAPIDpy.gis.muskingum.CreateConstMuskingumXFile(x_value, in_connectivity_file, out_x_file)[source]

Create muskingum X file from value that is constant all the way through for each river segment.

Parameters:
  • x_value (float) – Value for the muskingum X parameter [0-0.5].
  • in_connectivity_file (str) – The path to the RAPID connectivity file.
  • out_x_file (str) – The path to the output x file.

Example:

from RAPIDpy.gis.muskingum import CreateConstMuskingumXFile
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    CreateConstMuskingumXFile(x_value=0.3,
                              in_connectivity_file='/path/to/rapid_connect.csv',
                              out_x_file='/path/to/x.csv',
                              )

Weight Tables

RAPIDpy.gis.weight.CreateWeightTableECMWF(in_ecmwf_nc, in_catchment_shapefile, river_id, in_connectivity_file, out_weight_table, area_id=None, file_geodatabase=None)[source]

Create Weight Table for ECMWF Grids

Note

The grids are in the RAPIDpy package under the gis/lsm_grids folder.

Parameters:
  • in_ecmwf_nc (str) – Path to the ECMWF NetCDF grid.
  • in_catchment_shapefile (str) – Path to the Catchment shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘DrainLnID’ or ‘LINKNO’).
  • in_connectivity_file (str) – The path to the RAPID connectivity file.
  • out_weight_table (str) – The path to the output weight table file.
  • area_id (Optional[str]) – The name of the field with the area of each catchment stored in meters squared. Default is it calculate the area.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.weight import CreateWeightTableECMWF

CreateWeightTableECMWF(in_ecmwf_nc='/path/to/runoff_ecmwf_grid.nc'
                       in_catchment_shapefile='/path/to/catchment.shp',
                       river_id='LINKNO',
                       in_connectivity_file='/path/to/rapid_connect.csv',
                       out_weight_table='/path/to/ecmwf_weight.csv',
                       )
RAPIDpy.gis.weight.CreateWeightTableLDAS(in_ldas_nc, in_nc_lon_var, in_nc_lat_var, in_catchment_shapefile, river_id, in_connectivity_file, out_weight_table, area_id=None, file_geodatabase=None)[source]

Create Weight Table for NLDAS, GLDAS grids as well as for 2D Joules, or LIS Grids

Parameters:
  • in_ldas_nc (str) – Path to the land surface model NetCDF grid.
  • in_nc_lon_var (str) – The variable name in the NetCDF file for the longitude.
  • in_nc_lat_var (str) – The variable name in the NetCDF file for the latitude.
  • in_catchment_shapefile (str) – Path to the Catchment shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘DrainLnID’ or ‘LINKNO’).
  • in_connectivity_file (str) – The path to the RAPID connectivity file.
  • out_weight_table (str) – The path to the output weight table file.
  • area_id (Optional[str]) – The name of the field with the area of each catchment stored in meters squared. Default is it calculate the area.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.weight import CreateWeightTableLDAS

CreateWeightTableLDAS(in_ldas_nc='/path/to/runoff_grid.nc',
                      in_nc_lon_var="lon_110",
                      in_nc_lat_var="lat_110",
                      in_catchment_shapefile='/path/to/catchment.shp',
                      river_id='LINKNO',
                      in_connectivity_file='/path/to/rapid_connect.csv',
                      out_weight_table='/path/to/ldas_weight.csv',
                      )

Utilities

RAPIDpy.gis.centroid.FlowlineToPoint(in_drainage_line, river_id, out_csv_file, file_geodatabase=None)[source]

Converts flowline feature to a list of centroid points with their comid in EPSG:4326.

Parameters:
  • in_drainage_line (str) – Path to the stream network (i.e. Drainage Line) shapefile.
  • river_id (str) – The name of the field with the river ID (Ex. ‘HydroID’, ‘COMID’, or ‘LINKNO’).
  • out_csv_file (str) – Path to the output csv file with the centroid points.
  • file_geodatabase (Optional[str]) – Path to the file geodatabase. If you use this option, in_drainage_line is the name of the stream network feature class. (WARNING: Not always stable with GDAL.)

Example:

from RAPIDpy.gis.centroid import FlowlineToPoint
#------------------------------------------------------------------------------
#main process
#------------------------------------------------------------------------------
if __name__ == "__main__":
    FlowlineToPoint(in_drainage_line='/path/to/drainageline.shp',
                    river_id='LINKNO',
                    out_csv_file='/path/to/comid_lat_lon_z.csv',
                    )

How it works:

Snow, Alan D., Scott D. Christensen, Nathan R. Swain, E. James Nelson, Daniel P. Ames, Norman L. Jones, Deng Ding, Nawajish S. Noman, Cedric H. David, Florian Pappenberger, and Ervin Zsoter, 2016. A High-Resolution National-Scale Hydrologic Forecast System from a Global Ensemble Land Surface Model. Journal of the American Water Resources Association (JAWRA) 1-15, DOI: 10.1111/1752-1688.12434

Snow, Alan Dee, “A New Global Forecasting Model to Produce High-Resolution Stream Forecasts” (2015). All Theses and Dissertations. Paper 5272. http://scholarsarchive.byu.edu/etd/5272