How	  to	  prepare	  RAPID	  inputs	  from	  Version	  1	  of	  NHDPlus	  By	  Cédric	  H.	  David	  (cedric.david@jpl.nasa.gov),	  	  13	  Jun	  2014,	  updated	  21	  Jan	  2015	  	  Goal	  Learn	  how	  to	  create	  some	  of	  the	  files	  that	  are	  necessary	  to	  run	  RAPID	  from	  Version	  1	  of	  the	  enhanced	  National	  Hydrographic	  Dataset	  (NHDPlus	  v1)	  using	  ArcGIS.	  	  Requirements	  The	  ArcGIS	  software,	  and	  basic	  knowledge	  on	  how	  to	  use	  it.	  	  An	  Internet	  connection.	  	  	  Introduction	  	  RAPID	  needs	  to	  know	  where	  river	  reaches	  are	  and	  how	  they	  are	  connected	  before	  it	  can	  route	  water	  through	  them.	  	  To	  do	  so,	  RAPID	  uses	  two	  routing	  parameters	  (Muskingum	
  k	  and	  x)	  for	  each	  river	  reach.	  	  Also,	  the	  automated	  calibration	  of	  RAPID	  uses	  an	  estimate	  of	  parameter	  k	  which	  is	  necessary	  when	  running	  in	  optimization	  mode.	  	  In	  RAPID	  simulations,	  these	  files	  all	  need	  to	  use	  the	  same	  sorting	  for	  river	  reaches	  and	  are	  traditionally	  named	  as	  follows	  (where	  “Domain”	  is	  the	  name	  of	  the	  river	  basin	  considered):	  ••••rapid_connect_Domain.csv.	
  	  k_Domain.csv.	  
x_Domain.csv.	  
kfac_Domain.csv.	  

Finally,	  because	  RAPID	  can	  run	  in	  a	  subset	  of	  the	  entire	  domain	  where	  data	  is	  available,	  a	  list	  of	  river	  reaches	  in	  this	  subset	  is	  needed.	  	  The	  sorting	  of	  this	  file	  is	  independent	  from	  that	  the	  previous	  files,	  and	  an	  upstream-­‐to-­‐downstream	  sorting	  is	  valuable	  here	  although	  not	  mandatory.	
  •riv_bas_id_Domain.csv	  The	  purpose	  of	  this	  tutorial	  is	  to	  build	  all	  the	  aforementioned	  files.	  	  Focus	  is	  here	  made	  on	  the	  combination	  of	  the	  Guadalupe	  and	  San	  Antonio	  Basins	  in	  Texas	  which	  were	  both	  used	  in	  the	  first	  RAPID	  publication	  (David	  et	  al.,	  2011,	  Journal	  of	  Hydrometeorology).	  	
  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  	  Page	
  1	  of	  10	  	  Download	  NHDPlus	  data	  for	  the	  Guadalupe	  and	  San	  Antonio	  Basins	  Data	  corresponding	  to	  Version	  1	  of	  NHDPlus	  are	  available	  at	  http://www.horizon-­‐systems.com/NHDPlus/NHDPlusV1_data.php.	  	  The	  Guadalupe	  and	  San	  Antonio	  Basins	  are	  located	  in	  the	  Texas	  Gulf	  Coast	  Hydrologic	  Region	  which	  is	  Region	  12	  in	  NHDPlus:	  	  The	  files	  necessary	  for	  this	  tutorial	  can	  be	  downloaded	  by	  clicking	  on	  the	  following	  link	  in	  the	  aforementioned	  webpage:	  	  Of	  interest	  here	  will	  be	  three	  files	  included	  in	  the	  archive	  above:	  nhdflowline.shp,	  Subbasin.shp	  and	  NHDFlowlineVAA.dbf.	  	  Select	  the	  study	  domain	  Open	  the	  files	  nhdflowline.shp	  and	  Subbasin.shp	  in	  ArcGIS.	  	  	  	  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  2	  of	  10	  	  The	  Guadalupe	  and	  San	  Antonio	  Basins	  are	  identified	  by	  their	  6-­‐digit	  hydrologic	  unit	  codes	  from	  the	  classic	  USGS	  classification	  (121002	  and	  121003,	  respectively).	  	  They	  include	  the	  following	  features	  of	  subbasin.shp	  (8-­‐digit	  HUCs):	  	  	  RAPID	  can	  only	  simulate	  the	  river	  reaches	  where	  flow	  direction	  is	  known	  and	  hence	  the	  corresponding	  reaches	  need	  be	  determined.	  	  This	  can	  be	  done	  in	  NHDPlus	  by	  selecting	  features	  based	  on	  “FLOWDIR”=’With	  Digitized’.	  	  The	  river	  reaches	  located	  in	  the	  Guadalupe	  and	  San	  Antonio	  Basins	  can	  be	  selected	  by	  using	  the	  first	
  6	  digits	  of	  their	  REACHCODE	  with	  a	  statement	  similar	  to:	  "REACHCODE"	  LIKE	  '121002%'.	  	  	  Use	  the	  Select	  by	  Attributes	  tool	  to	  determine	  the	  reaches	  located	  in	  the	  Guadalupe	  and	  San	  Antonio	  Basins	  that	  have	
  a	  known	  flow	  direction.	  	  The	  corresponding	  statement	  is	  ("REACHCODE"	  LIKE	  '121002%'	  OR	  "REACHCODE"	  LIKE	  '121003%')	  AND	  "FLOWDIR"	  =	  'With	  Digitized'.	  
©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  3	  of	  10	  	  	  Now	  export	  the	  corresponding	  reaches	  in	  a	  file	  called	  NHDFlowline_San_Guad_with_dir.shp.	  	  The	  file	  NHDFlowline_San_Guad_with_dir.shp	  should	  contain	  only	  5,175	  of	  the	  74,615	  features	  originally	  available	  in	  nhdflowline.shp.	  

©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  4	  of	  10	  	  	  Create	
  a	  table	  with	  information	  related	  to	  the	  river	  reaches	  of	  interest	  Create	
  a	  join	  between	  NHDFlowline_San_Guad_with_dir.shp	  and	  NHDFlowlineVAA.dbf	  (available	  as	  part	  of	  the	  NHDPlus	  archive	  downloaded	  earlier	  in	  this	  tutorial).	  	  	  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  5	  of	  10	  	  	  Now	  export	  this	  table	  as	  NHDFlowline_San_Guad_connect.dbf:	  	  And	  delete	  all	  fields	  except	  for:	  	
  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  6	  of	  10	  	  	  	  	  

©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  	  Page	
  7	  of	  10	  	  Create	  the	  RAPID	  connectivity	  file	  The	  number	  of	  rows	  in	  the	  RAPID	  connectivity	  file	  corresponds	  to	  the	  number	  of	  river	  reaches	  in	  the	  river	  network	  (here	  5,175).	  	  Note	  that	  there	  is	  no	  header	  row.	  	  The	  number	  of	  columns	  is	  3+max_up	  where	  max_up	  is	  the	  maximum	  number	  of	  upstream	  reaches	  for	  any	  reach	  in	  the	  river	  network.	  	  The	  columns	  are	  as	  follows:	
  
•
•
•
•
•
•
••RIV_ID.	  	  The	  unique	  integer	  identifying	
  a	  given	  river	  reach.	  	  DOWN_ID.	  	  The	  unique	  integer	  identifying	  the	  unique	  reach	  located	  directly	  downstream	  of	  RIV_ID.	  
NB_UP.	  	  The	  number	  of	  river	  reaches	  located	  directly	  upstream	  of	  RIV_ID.	  
UP1.	  	  The	  unique	  integer	  of	  a	  reach	  (if	  it	  exists)	  that	  is	  located	  directly	  upstream	  of	  RIV_ID.	  
UP2.	  	  The	  unique	  integer	  of	  a	  reach	  (if	  it	  exists)	  that	  is	  located	  directly	  upstream	  of	  RIV_ID	  and	  that	  differs	  from	  UP1.	  
UP3.	  	  The	  unique	  integer	  of	  a	  reach	  (if	  it	  exists)	  that	  is	  located	  directly	  upstream	  of	  RIV_ID	  and	  that	  differs	  from	  UP1	  and	  UP2.	  
UP4.	  	  The	  unique	  integer	  of	  a	  reach	  (if	  it	  exists)	  that	  is	  located	  directly	  upstream	  of	  RIV_ID	  and	  that	  differs	  from	  UP1,	  UP2	  and	  UP3.	  
etc.	  

Note	  that	  any	  sorting	  can	  be	  used	  for	  sorting	  RIV_ID	  values	  in	  the	  first	  column.	  	  However,	  because	  the	  sorting	  needs	  be	  consistent	  among	  many	  RAPID	  input	  files,	  RIV_ID	  values	  will	  be	  sorted	  here	  in	  increasing	  order.	  
A	  Python	  script	  that	  uses	  the	  file	  NHDFlowline_San_Guad_connect.dbf	  as	  input	  can	  allow	  creating	  the	  RAPID	  connectivity	  file	  rapid_connect_San_Guad.csv.	  	  One	  can	  do	  so	  by	  knowing	  that	
  a	  given	  river	  reach	  i	  flows	  into	  reach	  j	  if	  the	  TONODE	  attribute	  of	  the	  former	  is	  the	  FROMNODE	  attribute	  of	  the	  latter.	  	  Note	  that	  this	  connectivity	  between	  upstream	  and	  downstream	  shall	  only	  be	  kept	  if	  the	  downstream	  reach	  has	
  a	  DIVERGENCE	  attribute	  value	  of	  1	  or	  0.	  	  This	  is	  because	
  a	  DIVERGENCE	  attribute	  value	  of	  2	  indicates	  that	
  a	  reach	  is	  part	  of	  a	  minor	  divergence	  and	  RAPID	  can	  currently	  only	  accommodates	  one	  unique	  downstream	  reach	  for	  each	  river	  reach.	  	  However,	  the	  DIVERGENCE	  attribute	  value	  of	  the	  upstream	  element	  is	  not	  to	  be	  checked	  otherwise	  risking	  that	  reaches	  that	  are	  part	  of	  minor	  divergences	  do	  not	  flow	  anywhere.	  	  	  	  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  8	  of	  10	  	  	  Create	  the	  parameter	  files	  	  The	  number	  of	  rows	  in	  all	  RAPID	  parameter	  files	  corresponds	  to	  the	  number	  of	  river	  reaches	  in	  the	  river	  network	  (here	  5,175)	  and	  these	  files	  only	  contain	
  a	  unique	  column.	  	
  A	  Python	  script	  that	  uses	  the	  file	  NHDFlowline_San_Guad_connect.dbf	  as	  input	  can	  allow	  creating	  all	  RAPID	  parameter	  files	  as	  follows:	
  •••kfac_San_Guad.csv	  contains	  a	  time	  (s)	  which	  is	  computed	  based	  on	  the	  river	  reach	  length	  using	  a	  flow	  wave	  celerity	  of	  1	  km/h.	  	  This	  can	  be	  done	  using	  kfacj	
  =	  LENGTHKM*3600.	  
k_San_Guad.csv	  contains	  a	  time	  (s)	  which	  is	  computed	  based	  on	  the	  river	  reach	  length.	  	  There	  are	  two	  ways	  to	  compute	  k:	  o Based	  on	  a	  wave	  celerity	
  c	  (m/s)	  and	  the	  river	  reach	  length:	  kj	  =	  LENGTHKM*1000/c.	  	
  A	  default	  celerity	  of	  c=0.8	  m/s	  can	  be	  used.	  
o Based	  on	  kfac_San_Guad.csv	  through	  the	  use	  of	  a	  multiplying	  factor	  λk	  >	  0:	  kj	  =	  λk*kfacj.	  	  A	  default	  value	  of	  λk	  =	  0.35	  can	  be	  used.	  	  	  	  x_San_Guad.csv	  contains	  a	  non-­‐dimensional	  number	  varying	  between	  0	  and	  0.5.	  	  While	
  a	  different	  value	  can	  be	  picked	  for	  each	  river	  reach,	  many	  existing	  RAPID	  applications	  use	
  a	  unique	  value	  for	
  x	  throughout	  the	  entire	  river	  network.	  	  This	  can	  be	  done	  by	  selecting	  λx	  ϵ	  [0,5]	  and	  applying:	  xj	  =	  λx*0.1.	  	  The	  value	  λx	  =	  3	  can	  be	  used	  as	  default.	  	  	  Create	  subset	  file	  The	  number	  of	  rows	  in	  the	  subset	  file	  corresponds	  to	  the	  size	  of	  the	  river	  network	  included	  in	  the	  larger	  river	  network	  that	  will	  be	  used	  to	  run	  RAPID.	  	  Here,	  this	  means	  that	  the	  subset	  file	  can	  have	  anywhere	  ©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	
  9	  of	  10	  	  between	
  1	  and	  5,175	  (included)	  river	  reaches.	  	  While	  any	  sorting	  can	  be	  used	  for	  the	  subset	  file,	  computing	  time	  in	  RAPID	  can	  be	  greatly	  decreased	  if	  some	  upstream-­‐to-­‐downstream	  sorting	  is	  used.	  	  Such	  can	  be	  done	  in	  NHDPlus	  by	  sorting	  the	  HYDROSEQ	  attribute	  value	  in	  decreasing	  order.	  	  	  In	  this	  example	  the	  subset	  file	  will	  include	  all	  5,175	  rivers	  of	  the	  Guadalupe	  and	  San	  Antonio	  Basins.	  	  The	  file	  riv_bas_id_San_Guad.csv	  can	  be	  created	  from	  NHDFlowline_San_Guad_connect.dbf	  by	  sorting	  RIV_ID	  such	  that	  the	  corresponding	  HYDROSEQ	  attribute	  value	  is	  in	  decreasing	  order.	  

Further	  information	  RAPID	  website:	  http://rapid-­‐hub.org/	  	  RAPID	  source	  code:	  https://github.com/c-­‐h-­‐david/rapid/	  	  	  

©	  2015	  Cédric	  H.	  David	  	  All	  Rights	  Reserved	  Page	  10	  of	  10