Using python-tidegates from python¶

You don’t have to start an ArcGIS session to use python-tidegates. The analytical guts of the library are completely isolated from the ArcGIS interface portions. This allows users to directly use the analytical capabilities from a python script or an interactive python session.

There are two interfaces to the analytic capabilities:

The toolbox API, which is easier to use and parallels the toolboxes.

The analysis API, which is more powerful but requires precise coding.

Common elements of examples¶

The following import statements are prerequisites for all of the code snippets below.

import numpy
import arcpy
import tidegates
from tidegates import utils

The `toolbox` API¶

(see install instructions)

For a full description of the API, see the reference guide

The tidegates.toolbox interface provides a very high-level interface to python-tidgeates that very closely mimics the tooboxes. Just like how there are two forms in the ArcGIS toolbox, there are two analagous classes available in the tidegates.toolbox API.

The tidegates.toolbox.Flooder class allows the user to estimate the extent and impact of flooding at custom elevations.

The tidegates.toolbox.StandardScenarios class automatically estimates the extent and impact of flooding for all combinations of the four storm surge events and sea level rise in 1-ft increments up to 6 feet.

Both classes are instantiated without any arguments and have identical main_execute methods to evaluate their scenarios. The only difference is that tidegates.toolbox.Flooder requires values for the flood elevations.

Common input parameters¶

The following are the parameters shared by both toolboxes. All parameters are required except where noted.

Analysis Workspace (workspace): This is the folder or geodatabase that contains all of the input for the analysis.

Note

All of the input for the analysis (see below) must be in this workspace.
Digital Elevation Model (dem): This is the raster dataset that contains the gridded topographic and bathymetric data that will be used to determine the extent of flooding. The original geodatabases provided contain DEMs: one at 4-m, and a second at 8-m resolution. The finer resolution DEM provides more detailed output, however it also requires more runtime and the analysis requires more computational resources. If the tool runs into a MemoryError during an analysis, try using the lower resolution raster. If these errors persist, other things to try include limiting the number of zones analyzed or reducing the resolution of the raster even further.

Note

The elevations of the DEMs provided in the standard geodatabase are measured in meters. However, care is taken to convert the properly convert the user input into meters to match the DEM when determining the extent of flooding.
Tidegate Zone of Influence (zones): This is a polygon layer found in workspace that delineates the zone of influence of each tidegate. The original geodatabases provided include a dataset called “ZOI” that include this information.
Column with Tidegate IDs (ID_column): This is the name of the field in the zones parameter that contains the unique idenifier of each tidegate. When using the “ZOI” layers provided in the geodatabases, this should be set to “GeoID”.
Output floods layer/filename (flood_output): This is the filename to which the extent of flooding will be saved within workspace.

Warning

Both toolboxes will overwrite any previous output if duplicate filenames are provided.
Wetlands, optional (wetlands): This is a polygon layer found within workspace that delineates wetlands within a study area. If provided, the area of wetlands inundated during each flood scenario will be added to the flood_output layer.
Output layer/filename of impacted wetlands, optional (wetlands_output): This is the filename of the layer created by computing the intersections of flood_output and wetlands. The result is a shapefile/feature class that contains only the inundated areas of the wetlands. If wetlands_output is not provided, the information is not saved to disk.
Building footprints, optional (buildings): This is a polygon layer of the building footprints in the study area. If provided the number of impacted buildings will be added to each record of flood_output.
Output layer/filename of impacted buildings, optional (building_output): This is the filename of an output layer that contains all of the impacted buildings for each flood scenario. If building_output is not provided, the information is not saved to disk.

Warning

Both toolboxes will overwrite any previous output if duplicate filenames are provided.

Custom elevations¶

The tidegates.toolbox.Flooder class allows the user to input multiple elevations to be analyzed. Thus, it has an elevation parameter not used by the tidegates.toolbox.StandardScenarios class. In keeping with the formatted definitions below:

elevation: A series of multiple custom flood elevations (in feet MSL) to be analyzed.

Code examples¶

Below is an example of using the tidegates.toolbox.Flooder class to evaluate custom flood elevations.

# define the workspace as a geodatabase
workspace = r'F:\phobson\Tidegates\MB_Small.gdb'

# define the flood elevations to analyze (in feef MSL)
elevations_feet = [4.8, 6.1, 8.9, 10.5]

# instantiate the flooder
custom_tool = tidegates.toolbox.Flooder()

with utils.OverwriteState(True):  # allow overwriting of any previous output
    custom_tool.main_execute(
        workspace=workspace,
        dem='dem_x08',
        zones='ZOI',
        wetlands='wetlands',
        buildings='buildings',
        ID_column='GeoID',
        flood_output='Custom_floods',
        building_output='Custom_floods_bldg',
        wetland_output='Custom_floods_wetland',
        elevations=elevations_feet
    )

Below is an example of using the tidegates.toolbox.StandardScenarios class to evaluate custom flood elevations.

# define the workspace as a geodatabase
workspace = r'F:\phobson\Tidegates\MB_Small.gdb'

# instantiate the flooder
std_tool = tidegates.toolbox.StandardScenarios()

with utils.OverwriteState(True):  # allow overwriting of any previous output
    std_tool.main_execute(
        workspace=workspace,
        dem='dem_x08',
        zones='ZOI',
        wetlands='wetlands',
        buildings='buildings',
        ID_column='GeoID',
        flood_output='Std_floods',
        building_output='Std_floods_bldg',
        wetland_output='Std_floods_wetland',
    )

The `analysis` API¶

For a full description of the API, see the tidegates.analysis.

The analysis API can be used to taylor a more nuanced, custom analysis of the impacts resulting from a flood event. Where the toolbox API effectively limits the user to computing total area and counts of one asset each, the functions below can be used by a python programmer to assess the impact to any number of assets.

General descriptions¶

The tidegates.analysis submodule contains five functions:

tidegates.analysis.process_dem_and_zones(): Does the preliminary job of converting the elevation data and zones of influence to rasters. This can be quite computationally expensive, so it’s handy have it in a seperate function. This let’s you do that pre-processing once, and then feed its results to the other functions as you evaluate potentially many scenarios.
tidegates.analysis.flood_area(): Estimates spatial extent of flooding behind for a given water surface elevation.
tidegates.analysis.assess_impact(): Estimates the total area of wetlands flooded and buildings impacted behind each tidegates for a (collection of) flood scenarios.
tidegates.analysis.area_of_impacts(): A general function used by tidegates.analysis.assess_impact(). This function takes the output from tidegates.analysis.flood_area() and computes its intersection with another polygon layer. The areas of the resulting geometries behind each tidegate are then added up and inserted into the attribute table of the flood scenario dataset.
tidegates.analysis.count_of_impacts(): Another general function used by tidegates.analysis.assess_impact() that also relies on the output of tidegates.analysis.flood_area(). In this case, instead of determining the total impacted area of the assesst behind each tidegate, this counts the number of impacted assets. For example, this function can be used to determine the number of buildings behind each tidegate that might see any amount of flooding during a flood event.

Code examples¶

The classes in tidegates.toolbox rely on the function in tidegates.analysis to determine

the extent and area of flooding
the number of buildings that recieve some amount of flooding
the extent and area of flooding within wetlands.

The sample script below does all of that and count the number of distinct wetlands impacted by each flood using tidegates.analysis directly.

# common parameters
workspace = r'F:\phobson\Tidegates\MB_Small.gdb'
flood_elevs = [7.8, 13.8, 19.8] # ft MSL
flood_output_template = 'Example_flood_{}'
id_col = 'GeoID'

with utils.WorkSpace(workspace), utils.OverwriteState(True):
    # convert DEM and zone data to rasters
    topo, zones, template = tidegates.process_dem_and_zones(
        dem='dem_x08',
        zones='ZOI',
        ID_columnd=id_col,
        cleanup=True,
    )

    # loop through each elevation defined above
    for elev in flood_elevs:
        # create an output file name for the scenario
        flood_output = flood_output_template.format(elev)

        # estimate the spatial extent of the floods
        flooded_zones = tidegates.flood_area(
            topo_array=topo,
            zones_array=zones,
            template=template,
            ID_column=id_col,
            elevation_feet=elev,
            filename=flood_output,
        )

        # add a field to the output's attribute table indicating the flood elevation
        utils.add_field_with_value(
            table=flood_output,
            field_name='flood_elev',
            field_value=elev,
        )

        # count the number of buildings impacted
        tidegates.count_of_impacts(
            floods_path=flood_output,
            flood_idcol=id_col,
            assets_input='buildings', # building footprint layer in the GeoDB,
            asset_idcol='STRUCT_ID', # unique field for each building
            fieldname='N_bldgs', # name of the field we'll add to 'Example_flood'
        )

        # count the number of wetlands impacted
        tidegates.count_of_impacts(
            floods_path=flood_output,
            flood_idcol=id_col,
            assets_input='wetlands', # wetlands layer in the GeoDB
            asset_idcol='WETCODE', # unique field for each wetland
            fieldname='N_wtlds', # name of the field we'll add to 'Example_flood'
        )

        # sum up the area of impacted wetlands behind each tidegate
        tidegates.area_of_impacts(
            floods_path=flood_output,
            ID_column=id_col,
            assets_input='wetlands', # wetlands layer in the GeoDB
            fieldname='area_wtlds', # name of the field we'll add to 'Example_flood'
        )

Using python-tidegates from python¶

Common elements of examples¶

The toolbox API¶

Common input parameters¶

Custom elevations¶

Code examples¶

The analysis API¶

General descriptions¶

Code examples¶

The `toolbox` API¶

The `analysis` API¶