How to use BDWS

Input files

Before using the BDWS classes, some input data are required. Below is a brief description of these input files. For more information visit the preparing input data page of the documentation. Note: it is recommended that all inputs be clipped to the valley-bottom extent. This extent can be determined with the V-BET tool.

brat.shp
Shapefile created by the BRAT model. Must contain single-part features. Multi-part features will not be processed by BDLoG.
dem.tif
Digital Elevation Model (DEM) for area of interest. Spatial resoultion of 10 meters or less is recommended.
fac.tif
Rasterized stream network raster. Generally created by applying a threshold to a flow accumulation raster. It is recommended to represent stream network cells with a value of 1 and all other cells with a value less than 1.
fdir.tif
Flow direction raster (D8) derived from the input DEM. Both ESRI and TauDEM D8 flow direction rasters are supported.

General usage

Currently, it is recommended to use BDWS to create python scripts to model beaver dam water storage. BDWS has been developed and tested using the PyCharm IDE. Below are brief examples describing how to use BDWS classes. For more detailed examples of BDWS implementation visit the tutorials page of the documentation.

BDWS code is hosted at https://github.com/konradhafen/beaver-dam-water-storage in the bdws.py and bdflopy.py files. Classes can be imported as follows.

from bdws import*
from bdflopy import *

BDLoG takes a vector stream network created by BRAT and generates locations of individual dams on a rasterized stream network.

Initialization of BDLoG requires a shapefile created by BRAT, a DEM, a rasterized stream network, path to output directory, and a proportion of maximum dam capacity to model. The following code will initialize BDLoG, generate dam locations and dam heights, and save output files for a maximum capacity (1.0) scenario.

model = BDLoG('path/to/brat.shp', 'path/to/dem.tif', 'path/to/fac.tif', 'out/dir', 1.0)
model.run()
model.close()

BDSWEA uses dam locations and dam heights generated by BDLoG to estimate the area and surface volume created by beaver dam construction.

BDSWEA requires output files (see below) from BDLoG for initialization. BDSWEA initialization requires a DEM, a flow direction raster derived from the DEM, a rasterized stream network, the dam ID raster created by BDLoG, an output directory, the dam location and attribute shapefile created by BDLoG. The following code will estimate beaver pond inundation and write files necessary for parameterization of MODFLOW.

model = BDSWEA('path/to/dem.tif', 'path/to/fdir.tif', 'path/to/fac.tif', 'path/to/id.tif',
                'out/dir', 'path/to/pts.shp')
model.run()
model.writeModflowFiles()
model.close()

BDflopy implements the existing FloPy module to automatically parameterize MODFLOW-2005 to estimate changes to goundwater storage resulting from beaver dam construction.

BDflopy requires the path to a MODFLOW-2005 executable, path to directory of input rasters, path to directory of BDSWEA outputs, path to directory to write outputs, and name of DEM file in inputs directory for initialization. The following code will initialize BDflopy.

model = BDflopy('path/to/modflow.exe', 'input/dir', 'bdswea/out/dir', 'out/dir', 'dem.tif')

BDflopy.run() requires additional parameters. Horizontal and vertical hydraulic conductivity (as a raster, numpy array, or single value), a factor to convert conductivity values to meters per second, the fraction of soil available for water storage (e.g. field capacity or porosity), and a factor to convert the soil fraction to a proportion. This will write MODFLOW’s input files, run MODFLOW, and generate output raster files. BDflopy.run() can be implemented as follows.

model.run('path/to/hk.tif', 'path/to/vk.tif', 1.0, 'path/to/frac.tif', 1.0)
#or
model.run(1.0, 1.0, 0.000001, 20.0, 0.01)

Then close the class object.

model.close()

Output files

BDLoG generates the following files:

ModeledDamPoints.shp

A shapefile containing generated beaver dam locations and information about each dam. This file is updated with estimated area and volume of modeled ponds by BDSWEA.

Attributes

  • damType: If the dam is primary or secondary. Primary dams are taller than secondary, this classification determines which distirbution is used to model dam heights.
  • ht_lo: The 0.025 quantile of the values selected from the dam height distribution. Modeled as the low dam height scenario.
  • ht_mid: The 0.5 quantile of the values selected from the dam height distribution. Modeled as the median dam height scenario.
  • ht_hi: The 0.975 quantile of the values selected from the dam height distribution. Modeled as the high dam height scenario.
  • area_*: Area of the pond created by modeling the dam under a given height scenario.
  • vol_*: Volume of the pond created by modeling the dam under a given height scenario.
  • Other fields: For use in adjusting dam heights so pond volume fits within the prediction intervals of an empirical model. This is not yet implemented in the python version.
damID.tif
Rasterized locations of generated beaver dams. Each beaver dam location is represented by a single cell with a number corresponding to the FID in ModeledDamPoints.shp.

BDSWEA generates the following files:

depLo.tif, depMid.tif, depHi.tif
Depths of modeded beaver ponds for low, median, and high dam heights.
htAbove.tif
The height of a cell above the dam it drains to. Used for determining pond dephts.
pondID.tif
FID of the dam a cell drains to. Used to calculate area and volume of modeled ponds.
WSESurf_lo.tif, WSESurf_mid.tif, WSESurf_hi.tif
The sum of the input DEM and each pond depth raster. Used to parameterize the top of the MODFLOW modeling domain.
head_start.tif, head_lo.tif, head_mid.tif, head_hi.tif
The intersection of the rasterized stream network and each WSESurf_*.tif file. This represents the water surface elevation of the stream and beaver dams. Used for MODFLOW parameterization.

BDflopy generates the following files:

start.*, lo.*, mid.*, hi.*
Input files written by flopy as inputs to MODFLOW, or output files written by MODFLOW.
ibound_start.tif, ibound_lo.tif, ibound_mid.tif, ibound_hi.tif
Definitions of the model domain (active, inactive, and constant head boundaries) for each MODFLOW simulation.
shead_start.tif, shead_lo.tif, shead_mid.tif, shead_hi.tif
Starting hydraulic head values for each MODFLOW simulation.
ehead_start.tif, ehead_lo.tif, ehead_mid.tif, ehead_hi.tif
Modeled hydraulic head values (water table elevation) for each MODFLOW simulation.
hdch_lo.tif, hdch_mid.tif, hdch_hi.tif
Estimated change in groundwater elevations from construction of beaver dams with low, median and height heights. Obtained by subtracting ehead_start.tif from water table elevations modeled with beaver pond influence.
hdch_lo_frac.tif, hdch_mid_frac.tif, hdch_hi_frac.tif
hdch_*.tif multiplied by the water holding capacity of the soil (e.g. field capacity or porosity).