utils API Reference¶

Basic utility functions for python-tidegates.

This contains basic file I/O, coversion, and spatial analysis functions to support the python-tidegates library. In most cases, these functions are simply wrappers around their arcpy counter parts. This was done so that in the future, these functions could be replaced with calls to a different geoprocessing library and eventually ween the code base off of its arcpy dependency.

3. 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.utils.RasterTemplate(cellsize, xmin, ymin)¶

Georeferencing template for Rasters.

This mimics the attributes of teh arcpy.Raster class enough that it can be used as a template to georeference numpy arrays when converting to rasters.

Parameters:	cellsize : int or float The width of the raster’s cells. xmin, ymin : float The x- and y-coordinates of the raster’s lower left (south west) corner.

See also

arcpy.Extent

Attributes

cellsize	(int or float) The width of the raster’s cells.
extent	(Extent) Yet another mock-ish class that x and y are stored in extent.lowerLeft as an arcpy.Point.

classmethod from_raster(raster)¶

Alternative constructor to generate a RasterTemplate from an actual raster.

Parameters:	raster : arcpy.Raster The raster whose georeferencing attributes need to be replicated.
Returns:	template : RasterTemplate

class tidegates.utils.EasyMapDoc(*args, **kwargs)¶

The object-oriented map class Esri should have made.

Create this the same you would make any other arcpy.mapping.MapDocument. But now, you can directly list and add layers and dataframes. See the two examples below.

Has layers and dataframes attributes that return all of the arcpy.mapping.Layer and arcpy.mapping.DataFrame objects in the map, respectively.

Examples

>>> # Adding a layer with the Esri version:
>>> import arpcy
>>> md = arcpy.mapping.MapDocument('CURRENT')
>>> df = arcpy.mapping.ListDataFrames(md)
>>> arcpy.mapping.AddLayer(df, myLayer, 'TOP')

>>> # And now with an ``EasyMapDoc``:
>>> from tidegates import utils
>>> ezmd = utils.EasyMapDoc('CURRENT')
>>> ezmd.add_layer(myLayer)

Attributes

mapdoc

(arcpy.mapping.MapDocument) The underlying arcpy MapDocument that serves as the basis for this class.

layers¶

All of the layers in the map.

dataframes¶

All of the dataframes in the map.

findLayerByName(name)¶

Finds a layer in the map by searching for an exact match of its name.

Parameters:	name : str The name of the layer you want to find.
Returns:	lyr : arcpy.mapping.Layer The map layer or None if no match is found. Warning Group Layers are not returned.

Examples

>>> from tidegates import utils
>>> ezmd = utils.EasyMapDoc('CURRENT')
>>> wetlands = ezmd.findLayerByName("wetlands")
>>> if wetlands is not None:
...     # do something with `wetlands`

add_layer(layer, df=None, position='top')¶

Simply adds a layer to a map.

Parameters:	layer : str or arcpy.mapping.Layer The dataset to be added to the map. df : arcpy.mapping.DataFrame, optional The specific dataframe to which the layer will be added. If not provided, the data will be added to the first dataframe in the map. position : str, optional (‘TOP’) The positional within df where the data will be added. Valid options are: ‘auto_arrange’, ‘bottom’, and ‘top’.
Returns:	layer : arcpy.mapping.Layer The sucessfully added layer.

Examples

>>> from tidegates import utils
>>> ezmd = utils.EasyMapDoc('CURRENT')
>>> ezmd.add_layer(myLayer)

tidegates.utils.Extension(*args, **kwds)¶

Context manager to facilitate the use of ArcGIS extensions

Inside the context manager, the extension will be checked out. Once the interpreter leaves the code block by any means (e.g., sucessful execution, raised exception) the extension will be checked back in.

Examples

>>> import tidegates, arcpy
>>> with tidegates.utils.Extension("spatial"):
...     arcpy.sa.Hillshade("C:/data/dem.tif")

tidegates.utils.OverwriteState(*args, **kwds)¶

Context manager to temporarily set the overwriteOutput environment variable.

Inside the context manager, the arcpy.env.overwriteOutput will be set to the given value. Once the interpreter leaves the code block by any means (e.g., sucessful execution, raised exception), arcpy.env.overwriteOutput will reset to its original value.

Parameters:	path : str Path to the directory that will be set as the current workspace.

Examples

>>> import tidegates
>>> with tidegates.utils.OverwriteState(False):
...     # some operation that should fail if output already exists

tidegates.utils.WorkSpace(*args, **kwds)¶

Context manager to temporarily set the workspace environment variable.

Inside the context manager, the arcpy.env.workspace will be set to the given value. Once the interpreter leaves the code block by any means (e.g., sucessful execution, raised exception), arcpy.env.workspace will reset to its original value.

Parameters:	path : str Path to the directory that will be set as the current workspace.

Examples

>>> import tidegates
>>> with tidegates.utils.OverwriteState(False):
...     # some operation that should fail if output already exists

tidegates.utils.update_status()¶

Decorator to allow a function to take a additional keyword arguments related to printing status messages to stdin or as arcpy messages.

tidegates.utils.create_temp_filename(filepath, filetype=None, prefix='_temp_')¶

Helper function to create temporary filenames before to be saved before the final output has been generated.

Parameters:	filepath : str The file path/name of what the final output will eventually be. filetype : str, optional The type of file to be created. Valid values: “Raster” or “Shape”. prefix : str, optional (‘_temp_’) The prefix that will be applied to filepath.
Returns:	str

Examples

>>> create_temp_filename('path/to/flooded_wetlands', filetype='shape')
path/to/_temp_flooded_wetlands.shp

tidegates.utils.result_to_raster(*args, **kwargs)¶

Gets the actual arcpy.Raster from an arcpy.Result object.

Parameters:	result : arcpy.Result The Result object returned from some other geoprocessing function.
Returns:	arcpy.Raster

See also

result_to_layer

tidegates.utils.result_to_layer(*args, **kwargs)¶

Gets the actual arcpy.mapping.Layer from an arcpy.Result object.

Parameters:	result : arcpy.Result The Result object returned from some other geoprocessing function.
Returns:	arcpy.mapping.Layer

See also

result_to_raster

tidegates.utils.rasters_to_arrays(*args, **kwargs)¶

Converts an arbitrary number of rasters to numpy arrays. Relies on arcpy.RasterToNumPyArray.

Parameters:	rasters : args of numpy.arrays Rasters that will be converted to arrays. squeeze : bool, optional (False) By default (squeeze = False) a list of arrays is always returned. However, when squeeze = True and only one raster is provided, the array will be squeezed out of the list and returned directly.
Returns:	arrays : list of arrays or array.

See also

array_to_raster, result_to_raster, polygons_to_raster

tidegates.utils.array_to_raster(*args, **kwargs)¶

Create an arcpy.Raster from a numpy.ndarray based on a template. This wrapper around arcpy.NumPyArrayToRaster.

Parameters:	array : numpy.ndarray The array of values to be coverted to a raster. template : arcpy.Raster or RasterTemplate The raster whose, extent, position, and cell size will be applied to array.
Returns:	newraster : arcpy.Raster

See also

RasterTemplate, rasters_to_arrays, polygons_to_raster

Examples

>>> from tidegates import utils
>>> raster = utils.load_data('dem.tif', 'raster') # in meters
>>> array = utils.rasters_to_arrays(raster, squeeze=True)
>>> array = array / 0.3048 # convert elevations to feet
>>> newraster = utils.array_to_raster(array, raster)
>>> newraster.save('<path_to_output>')

tidegates.utils.load_data(*args, **kwargs)¶

Loads vector and raster data from filepaths.

Parameters:

datapath : str, arcpy.Raster, or arcpy.mapping.Layer The (filepath to the) data you want to load. datatype : str The type of data you are trying to load. Must be either “shape” (for polygons) or “raster” (for rasters). greedyRasters : bool (default = True) Currently, arcpy lets you load raster data as a “Raster” or as a “Layer”. When greedyRasters is True, rasters loaded as type “Layer” will be forced to type “Raster”.

Returns:

data : arcpy.Raster or arcpy.mapping.Layer The data loaded as an arcpy object.

tidegates.utils.polygons_to_raster(*args, **kwargs)¶

Prepare tidegates’ areas of influence polygons for flooding by converting to a raster. Relies on arcpy.conversion.PolygonToRaster.

Parameters:	polygons : str or arcpy.mapping.Layer The (filepath to the) zones that will be flooded. If a string, a Layer will be created. ID_column : str Name of the column in the polygons layer that associates each geomstry with a tidegate. cellsize : int Desired cell dimension of the output raster. Default is 4 m.
Returns:	zones : arcpy.Raster The zones of influence as a raster dataset result : arcpy.Result The weird, crpyric results object that so many (but not all) ESRI arcpy function return.

See also

raster_to_polygons, rasters_to_arrays, array_to_raster

Examples

>>> zone_raster, res = utils.polygons_to_raster('ZOI.shp', 'GeoID')
>>> zone_array = utils.rasters_to_arrays(zone_raster, squeeze=True)
>>> # remove all zones with a GeoID less than 5
>>> zone_array[zone_array < 5] = 0
>>> filtered_raster = utils.array_to_raster(zone_array, zone_raster)

tidegates.utils.clip_dem_to_zones(*args, **kwargs)¶

Limits the extent of the topographic data (dem) to that of the zones of influence so that we can easily use array representations of the rasters. Relies on arcpy.management.Clip.

Parameters:	dem : arcpy.Raster Digital elevation model of the area of interest. zones : arcpy.Raster The raster whose cell values represent the zones of influence of each tidegate.
Returns:	dem_clipped : arcpy.Raster The zones of influence as a raster dataset result : arcpy.Result The weird, cryptic results object that so many (but not all) ESRI arcpy function return.

tidegates.utils.raster_to_polygons(*args, **kwargs)¶

Converts zonal rasters to polygons layers. This is basically just a thing wrapper around arcpy.conversion.RasterToPolygon. The returned layers will have a field that corresponds to the values of the raster. The name of this field can be controlled with the newfield parameter.

Relies on arcpy.conversion.RasterToPolygon.

Parameters:	zonal_raster : arcpy.Raster An integer raster of reasonably small set distinct values. filename : str Path to where the polygons will be saved. newfield : str, optional By default, the field that contains the raster values is called “gridcode”. Use this parameter to change the name of that field.
Returns:	polygons : arcpy.mapping.Layer The converted polygons.

See also

polygons_to_raster, add_field_with_value, populate_field

tidegates.utils.aggregate_polygons(*args, **kwargs)¶

Dissolves (aggregates) polygons into a single feature the unique values in the provided field. This is basically just a thim wrapper around arcpy.management.Dissolve.

Parameters:	polygons : arcpy.mapping.Layer The layer of polygons to be aggregated. ID_field : string The name of the field in polygons on which the individual polygons will be grouped. filename : string Path to where the aggregated polygons will be saved.
Returns:	dissolved : arcpy.mapping.Layer The aggregated polygons.

See also

arcpy.management.Dissolve

Examples

>>> from tidegates import utils
>>> dissolved = utils.aggregate_polygons('wetlands.shp', 'GeoID',
...                                      'dissolved.shp')

tidegates.utils.flood_zones(*args, **kwargs)¶

Mask out non-flooded portions of arrays.

Parameters:	zones_array : numpy.array Array of zone IDs from each zone of influence. topo_array : numpy.array Digital elevation model (as an array) of the areas. elevation : float The flood elevation above which everything will be masked.
Returns:	flooded_array : numpy.array Array of zone IDs only where there is flooding.

tidegates.utils.add_field_with_value(*args, **kwargs)¶

Adds a numeric or text field to an attribute table and sets it to a constant value. Operates in-place and therefore does not return anything.

Relies on arcpy.management.AddField.

Parameters:

table : Layer, table, or file path This is the layer/file that will have a new field created. field_name : string The name of the field to be created. field_value : float or string, optional The value of the new field. If provided, it will be used to infer the field_type parameter required by arcpy.management.AddField if field_type is itself not explicitly provided. overwrite : bool, optonal (False) If True, an existing field will be overwritting. The default behaviour will raise a ValueError if the field already exists. **field_opts : keyword options Keyword arguments that are passed directly to arcpy.management.AddField.

Returns:

None

Examples

>>> # add a text field to shapefile (text fields need a length spec)
>>> utils.add_field_with_value("mypolygons.shp", "storm_event",
                               "100-yr", field_length=10)
>>> # add a numeric field (doesn't require additional options)
>>> utils.add_field_with_value("polygons.shp", "flood_level", 3.14)

tidegates.utils.cleanup_temp_results(*args, **kwargs)¶

Deletes temporary results from the current workspace.

Relies on arcpy.management.Delete.

Parameters:	*results : str Paths to the temporary results
Returns:	None

tidegates.utils.intersect_polygon_layers(*args, **kwargs)¶

Intersect polygon layers with each other. Basically a thin wrapper around arcpy.analysis.Intersect.

Parameters:	destination : str Filepath where the intersected output will be saved. *layers : str or arcpy.Mapping.Layer The polygon layers (or their paths) that will be intersected with each other. **intersect_options : keyword arguments Additional arguments that will be passed directly to arcpy.analysis.Intersect.
Returns:	intersected : arcpy.mapping.Layer The arcpy Layer of the intersected polygons.

Examples

>>> from tidedates import utils
>>> blobs = utils.intersect_polygon_layers(
...     "flood_damage_intersect.shp"
...     "floods.shp",
...     "wetlands.shp",
...     "buildings.shp"
... )

tidegates.utils.groupby_and_aggregate(*args, **kwargs)¶

Counts the number of distinct values of valuefield are associated with each value of groupfield in a data source found at input_path.

Relies on arcpy.da.TableToNumPyArray.

Parameters:

input_path : str File path to a shapefile or feature class whose attribute table can be loaded with arcpy.da.TableToNumPyArray. groupfield : str The field name that would be used to group all of the records. valuefield : str The field name whose distinct values will be counted in each group defined by groupfield. aggfxn : callable, optional. Function to aggregate the values in each group to a single group. This function should accept an itertools._grouper as its only input. If not provided, unique number of value in the group will be returned.

Returns:

counts : dict A dictionary whose keys are the distinct values of groupfield and values are the number of distinct records in each group.

See also

itertools.groupby, populate_field

Examples

>>> # compute total areas for each 'GeoID'
>>> wetland_areas = utils.groupby_and_aggregate(
...     input_path='wetlands.shp',
...     groupfield='GeoID',
...     valuefield='SHAPE@AREA',
...     aggfxn=lambda group: sum([row[1] for row in group])
... )

>>> # count the number of structures associated with each 'GeoID'
>>> building_counts = utils.groupby_and_aggregate(
...     input_path=buildingsoutput,
...     groupfield=ID_column,
...     valuefield='STRUCT_ID'
... )

tidegates.utils.rename_column(*args, **kwargs)¶

tidegates.utils.populate_field(*args, **kwargs)¶

Loops through the records of a table and populates the value of one field (valuefield) based on another field (keyfield) by passing the entire row through a function (value_fxn).

Relies on arcpy.da.UpdateCursor.

Parameters:	table : Layer, table, or file path This is the layer/file that will have a new field created. value_fxn : callable Any function that accepts a row from an arcpy.da.SearchCursor and returns a single value. valuefield : string The name of the field to be computed. *keyfields : strings, optional The other fields that need to be present in the rows of the cursor.
Returns:	None Note In the row object, the valuefield will be the last item. In other words, row[0] will return the first values in *keyfields and row[-1] will return the existing value of valuefield in that row.

Examples

>>> # populate field ("Company") with a constant value ("Geosyntec")
>>> populate_field("wetlands.shp", lambda row: "Geosyntec", "Company")

tidegates.utils.copy_data(*args, **kwargs)¶

Copies an arbitrary number of spatial files to a new folder.

Relies on arcpy.conversion.FeatureClassToShapefile.

Parameters:	destfolder : str Path the folder that is the destination for the files. *source_layers : str Paths to the files that need to be copied squeeze : bool, optional (False) When one layer is copied and this is True, the copied layer is returned. Otherwise, this function returns a list of layers.
Returns:	copied : list of arcpy.mapping Layers or just a single Layer.

tidegates.utils.concat_results(*args, **kwargs)¶

Concatentates (merges) serveral datasets into a single shapefile or feature class.

Relies on arcpy.management.Merge.

Parameters:	destination : str Path to where the concatentated dataset should be saved. *input_files : str Strings of the paths of the datasets to be merged.
Returns:	arcpy.mapping.Layer

See also

join_results_to_baseline

tidegates.utils.join_results_to_baseline(*args, **kwargs)¶

Joins attributes of a geoprocessing result to a baseline dataset and saves the results to another file.

Relies on arcpy.analysis.SpatialJoin.

Parameters:	destination : str Path to where the final joined dataset should be saved. results_file : str Path to the results file whose attributes will be added to the baseline_file. baseline_file : str Path to the baseline_file with the desired geometry.
Returns:	arcpy.mapping.Layer

See also

concat_results