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 :code:`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. .. code-block:: python from bdws import* from bdflopy import * :code:`BDLoG` takes a vector stream network created by `BRAT `_ and generates locations of individual dams on a rasterized stream network. Initialization of :code:`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 :code:`BDLoG`, generate dam locations and dam heights, and save output files for a maximum capacity (1.0) scenario. .. code-block:: python model = BDLoG('path/to/brat.shp', 'path/to/dem.tif', 'path/to/fac.tif', 'out/dir', 1.0) model.run() model.close() :code:`BDSWEA` uses dam locations and dam heights generated by :code:`BDLoG` to estimate the area and surface volume created by beaver dam construction. :code:`BDSWEA` requires output files (see below) from :code:`BDLoG` for initialization. :code:`BDSWEA` initialization requires a DEM, a flow direction raster derived from the DEM, a rasterized stream network, the dam ID raster created by :code:`BDLoG`, an output directory, the dam location and attribute shapefile created by :code:`BDLoG`. The following code will estimate beaver pond inundation and write files necessary for parameterization of MODFLOW. .. code-block:: python 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() :code:`BDflopy` implements the existing `FloPy module `_ to automatically parameterize MODFLOW-2005 to estimate changes to goundwater storage resulting from beaver dam construction. :code:`BDflopy` requires the path to a MODFLOW-2005 executable, path to directory of input rasters, path to directory of :code:`BDSWEA` outputs, path to directory to write outputs, and name of DEM file in inputs directory for initialization. The following code will initialize :code:`BDflopy`. .. code-block:: python model = BDflopy('path/to/modflow.exe', 'input/dir', 'bdswea/out/dir', 'out/dir', 'dem.tif') :code:`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. :code:`BDflopy.run()` can be implemented as follows. .. code-block:: python 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. .. code-block:: python 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 :code:`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 :code:`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).