The toolbox API

toolbox API Reference

ArcGIS python toolboxes for python-tidegates.

This contains Classes compatible with ArcGIS python toolbox infrastructure.

  1. Geosyntec Consultants, 2015.

Released under the BSD 3-clause license (see LICENSE file for more info)

Written by Paul Hobson (phobson@geosyntec.com)

class tidegates.toolbox.StandardScenarios

Bases: object

ArcGIS Python toolbox to analyze floods during the standard sea level rise and storm surge scenarios.

Parameters:None

See also

Flooder

isLicensed()

PART OF THE ESRI BLACK BOX.

Esri says:

Set whether tool is licensed to execute.

So I just make this always true b/c it’s an open source project with a BSD license – (c) Geosyntec Consultants – so who cares?

updateMessages(parameters)

PART OF THE ESRI BLACK BOX.

Esri says:

Modify the messages created by internal validation for each parameter of the tool. This method is called after internal validation.

But I have no idea when or how internal validation is called so that’s pretty useless information.

updateParameters(parameters)

PART OF THE ESRI BLACK BOX.

Automatically called when any parameter is updated in the GUI.

The general flow is like this:

  1. User interacts with GUI, filling out some input element
  2. self.getParameterInfo is called
  3. Parameteter are fed to this method as a list

I used to set the parameter dependecies in here, but that didn’t work. So now this does nothing and dependecies are set when the parameters (as class properties) are created (i.e., called for the first time).

getParameterInfo()

PART OF THE ESRI BLACK BOX

This must return a list of all of the parameter definitions.

Esri recommends that you create all of the parameters in here, and always return that list. I instead chose to create the list from the class properties I’ve defined. Accessing things with meaningful names is always better, in my opinion.

execute(parameters, messages)

PART OF THE ESRI BLACK BOX

This method is called when the tool is actually executed. It gets passed magics lists of parameters and messages that no one can actually see.

Due to this mysterious nature, I do the following:

  1. turn all of the elements of the list into a dictionary so that we can access them in a meaningful way. This means, instead of doing something like
dem = parameters[0].valueAsText
zones = parameters[1].valueAsText
# yada yada
nth_param = parameters[n].valueAsText

for EVERY. SINGLE. PARAMETER, we can instead do something like:

params = self._get_parameter_values(parameters, multivals=['elevation'])
dem = params['dem']
zones = params['zones'].
# yada

This is much cleaner, in my opinion, and we don’t have to magically know where in the list of parameters e.g., the DEM is found. Take note, Esri.

  1. generate a list of scenarios usings make_scenarios().
  2. loop through those scenarios.
  3. call analyze() on each scenario.
  4. call finish_results() on all of the layers generated by the loop.
workspace

The directory or geodatabase in which the analysis will occur.

dem

DEM file (topography) to be used in the analysis.

zones

The Zones of influence polygons to be used in the analysis.

ID_column

Name of the field in zones that uniquely identifies each zone of influence.

flood_output

Where the flooded areas for each scenario will be saved.

building_output

Where the flooded buildings for each scenario will be saved.

wetland_output

Where the flooded wetlands for each scenario will be saved.

wetlands

Input layer of wetlands.

buildings

Input layer of building footprints.

make_scenarios(**params)

Makes a list of dictionaries of all scenario parameters that will be analyzed by the toolbox.

Parameters:

**params : keyword arguments

Keyword arguments of analysis parameters generated by _get_parameter_values()
Returns:

scenarios : list of dictionaries

A list of dictionaries describing each scenario to be analyzed. Keys of the dictionaries will be:

  • elev - the custom elevation
  • surge_name - the name of a storm surge event
  • surge_elev - the elevation associated with “surge_name”
  • slr - the amount of sea level rise to be considered.

When analyzing custom elevations, all other entries are set to None. Likewise, when evaluating standard scenarios, “elev” is None.
analyze(topo_array, zones_array, template, elev=None, surge=None, slr=None, **params)

Tool-agnostic helper function for main_execute().

Parameters:

topo_array : numpy array

Floating point array of the digital elevation model.

zones_array : numpy array

Categorical (integer) array of where each non-zero value delineates a tidegate’s zone of influence.

template : arcpy.Raster or tidegates.utils.RasterTemplate

A raster or raster-like object that define the spatial extent of the analysis area. Required attributes are:

  • templatemeanCellWidth
  • templatemeanCellHeight
  • templateextent.lowerLeft

elev : float, optional

Custom elevation to be analyzed

slr : float, optional

Sea level rise associated with the standard scenario.

surge : str, optional

The name of the storm surge associated with the scenario (e.g., MHHW, 100yr).

**params : keyword arguments

Keyword arguments of analysis parameters generated by self._get_parameter_values
Returns:

floods, flooded_wetlands, flooded_buildings : arcpy.mapping.Layers

Layers (or None) of the floods and flood-impacted wetlands and buildings, respectively.
static finish_results(*args, **kwargs)

Merges and cleans up compiled output from analyze.

Parameters:

outputname : str

Path to where the final file sould be saved.

results : list of str

Lists of all of the floods, flooded wetlands, and flooded buildings, respectively, that will be merged and deleted.

sourcename : str, optional

Path to the original source file of the results. If provided, its attbutes will be spatially joined to the concatenated results.
Returns:

None
main_execute(**params)

Performs the flood-impact analysis on multiple flood elevations.

Parameters:

workspace : str

The folder or geodatabase where the analysis will be executed.

dem : str

Filename of the digital elevation model (topography data) to be used in determinging the inundated areas.

zones : str

Name of zones of influence layer.

ID_column : str

Name of the field in zones that uniquely identifies each zone of influence.

elevation : list, optional

List of (custom) flood elevations to be analyzed. If this is not provided, all of the standard scenarios will be evaluated.

flood_output : str

Filename where the extent of flooding and damage will be saved.

wetlands, buildings : str, optional

Names of the wetland and building footprint layers.

wetland_output, building_output : str, optional

Filenames where the flooded wetlands and building footprints will be saved.
Returns:

None
class tidegates.toolbox.Flooder

Bases: tidegates.toolbox.StandardScenarios

ArcGIS Python toolbox to analyze custom flood elevations.

Parameters:None

See also

StandardScenarios

elevation

The flood elevation for a custom scenario.