Utilities

CRS

Coordinate Reference System conversions.

Coordinate Reference Systems (CRSs) differ across datasets, and standardizing and managing these across the workflow is a necessary technical detail. That said, rarely does the user care what coordinate system is being used, as long as it is appropriate for the watershed in question. Watershed Workflow aims to make using datasets in different CRSs as streamlined as possible. Typically, a workflow will pick a CRS based upon either a default for the region or by simply using the CRS of the shapefile that specifies the watershed boundary. This CRS is the passed into each function that acquires more data, and that data’s coordinates are changed to the CRS requested.

This process is made more difficult by the fact that most python GIS packages provide their own class object to store the CRS. This said, nearly all of them are based, to some degree, on the proj4 library and its python wrapper, pyproj for coordinate transformations. Watershed Workflow uses the pyproj.Proj class as its own internal representation of coordinate system, and provides methods for mapping fiona (shapefiles), rasterio (rasters), and cartopy (plotting) CRS objects to and from this type. While this is typically done by calling functions from those libraries, standardizing the API makes dealing with these packages in an integrated form much simpler.

Note

We intend to use the pyproj.Proj object as our standard. But for now we are trying to avoid hard-coding that, so internal code should avoid using that knowledge, and instead map to and from pyproj.Proj objects using the provided interface.

watershed_workflow.crs.is_native(crs)

Is this crs in the native format?

watershed_workflow.crs.from_proj(crs)

Converts a Proj CRS to the workflow CRS standard.

Parameters:

crs (pyproj.crs.CRS) – Input proj CRS object.

Returns:

out – Equivalent workflow CRS.

Return type:

crs-type

watershed_workflow.crs.to_proj(crs)

Converts a workflow CRS standard to a Proj4 CRS.

Parameters:

crs (crs-type) – Workflow standard CRS.

Returns:

out – Equivalent object.

Return type:

pyproj.crs.CRS

watershed_workflow.crs.from_fiona(crs)

Converts a fiona CRS to the workflow CRS standard.

Parameters:

crs (fiona-crs-dict) – Input fiona CRS, which is a dictionary containing an EPSG code.

Returns:

out – Equivalent workflow CRS.

Return type:

crs-type

watershed_workflow.crs.to_fiona(crs)

Converts a workflow CRS to a fiona CRS.

Parameters:

crs (crs-type) – A workflow CRS object.

Returns:

out – Equivalent fiona CRS.

Return type:

fiona-crs-dict

watershed_workflow.crs.from_rasterio(crs)

Converts from rasterio CRS to the workflow CRS standard.

Parameters:

crs (rasterio-crs-object) – Input rasterio crs.

Returns:

out – Equivalent workflow CRS.

Return type:

crs-type

watershed_workflow.crs.to_rasterio(crs)

Converts a workflow CRS to a fiona CRS.

Parameters:

crs (crs-type) – A workflow CRS object.

Returns:

out – Equivalent rasterio object.

Return type:

rasterio.CRS

watershed_workflow.crs.from_epsg(epsg)

Converts from an EPSG code to a workflow CRS.

Parameters:

epsg (int) – An EPSG code. (see EPSG codes)

Returns:

out – Equivalent workflow CRS.

Return type:

crs-type

watershed_workflow.crs.to_epsg(crs)

Attempts to conver to an EPSG code.

Parameters:

crs (crs-type) –

Returns:

• epsg (int) – An EPSG code, if possible.

• If not, this throws.

watershed_workflow.crs.from_cartopy(crs)

Converts a cartopy CRS to a workflow CRS.

Parameters:

epsg (int) –

An EPSG code. (see EPSG codes)

Returns:

out – Equivalent workflow CRS.

Return type:

crs-type

watershed_workflow.crs.to_cartopy(crs)

Converts a workflow CRS to a cartopy.crs.Projection.

Parameters:

crs (crs-type) – The CRS to convert.

Returns:

• A cartopy.crs.Projection object for plotting.

• Adopted from (https://pyproj4.github.io/pyproj/stable/crs_compatibility.html)

watershed_workflow.crs.from_string(string)

Returns a CRS from a proj string

watershed_workflow.crs.from_wkt(string)

Returns a CRS from a WKT string specification

watershed_workflow.crs.to_wkt(crs)

Returns the WKT string of a CRS.

watershed_workflow.crs.default_crs()

Returns a default CRS that is functionally useful for North America.

Returns:

out – The default CRS. The user should not care what this is (if you do, don’t use the default!) but it is EPSG:5070.

Return type:

crs-type

watershed_workflow.crs.default_alaska_crs()

Returns a default CRS that is functionally useful for Alaska.

Returns:

out – The default CRS. The user should not care what this is (if you do, don’t use the default!) but it is EPSG:3338.

Return type:

crs-type

watershed_workflow.crs.daymet_crs()

Returns the CRS used by DayMet files, but in m, not km.

Returns:

out – The DayMet CRS. The user should not care what this is.

Return type:

crs-type

watershed_workflow.crs.daymet_crs_native()

Returns the CRS used by DayMet files natively, in km, not in m.

Returns:

out – The DayMet CRS. The user should not care what this is.

Return type:

crs-type

watershed_workflow.crs.latlon_crs()

Returns the default latitude-longitude CRS.

Returns:

out – The default CRS. The user should not care what this is (if you do, don’t use the default!) but it is EPSG:4269.

Return type:

crs-type

watershed_workflow.crs.equal(crs1, crs2)

Tries to guess at the equality of two CRS objects.

Note this is not trivial, just checking strings or dicts results in false-negatives. Furthermore, this implementation may not be perfect, but it works for all those currently tested. Please report bugs!

Parameters:

• crs1 (crs-type) – Input workflow CRS objects.

• crs2 (crs-type) – Input workflow CRS objects.

Returns:

out – Are equal?

Return type:

bool

Plotting

Plotting relies on cartopy to ensure that coordinate projections are dealt with reasonably within matplotlib. The preferred usage for plotting is similar to the non-pylab interface to matplotlib – first get a figure and axis object, then call plotting functions passing in that ax object.

Note that we use the descartes package to plot shapely objects, which is a simple wrapper to write a shapely polygon as a matplotlib patch.

Note that, for complex plots, it can be useful to manage the ordering of the layers of objects. In this case, all plotting functions accept matplotlib’s zorder argument, an int which controls the order of drawing, with larger being later (on top) of smaller values.

class watershed_workflow.plot.Labeler(ax, items=None)

A labeling widget that can be attached to matplotlib figures to display info on-click.

When an geometry item (e.g. point, line, or polygon) is clicked on the figure, that is mapped into the original WW object that generated the geometry, and then run through a function to generate a label that is written to the title of the figure.

Parameters:

• ax (matplotlib.Axes object) – The axes to work with.

• items (list[tuple[artist, metadata, formatter]]) – See documentation of the addItem() method.

addItem(data, artist, formatter)

Adds an item to the list of things to label.

Parameters:

• data (List[*]) – A list of objects being labeled. This is likely the underlying data, with properties, that was passed to a ww.plot function.

• artist (matplotlib collection) – A matplotlib Collection, likely the return value of a ww.plot call or similar.

• formatter (function or str) – A function that accepts an entry in data and returns a string to label the item selected. If this is a string, it is assumed to be a formattable string to which the item’s properties dictionary is passed.

deselect()

Clears anything plotted in the last click

select(i, j, xy)

Selects item i, collection index j, with a click at xy

update(event)

Acts on click.

watershed_workflow.plot.get_ax(crs, fig=None, nrow=1, ncol=1, index=None, window=None, axgrid=None, ax_kwargs=None, **kwargs)

Returns an axis with a given projection.

Note this forwards extra kwargs for plt.figure().

Parameters:

• crs (CRS object, optional) – A projected CRS for the plot. None can be given for a normal matplotlib axis (useful for plotting lat/lon or other non-projected coordinate systems. Note that if you call plotting on an object with an unprojected CRS, it will project for you, or change coordinates if needed. This can get a bit dicey, so prefer to plot objects all in the same CRS. Defaults to None.

• fig (matplotlib figure, optional) – If you already have a figure, will create the axis on this figure. Defaults to None, at which point a figure will be created.

• nrow (int, optional) – Create a grid of axes of this shape. Calls plt.add_subplot(nrow,ncol,index). Default is 1.

• ncol (int, optional) – Create a grid of axes of this shape. Calls plt.add_subplot(nrow,ncol,index). Default is 1.

• index (int, optional) – Create a grid of axes of this shape. Calls plt.add_subplot(nrow,ncol,index). Default is 1.

• window ([xmin, ymin, width, height], optional) – Matplotlib patch arguments for call to fig.add_axes()

• figsize ((width, height), optional) – Figure size in inches.

• dpi (int, optional) – Dots per inch for figures.

• ax_kwargs (dict) – Other arguments provided to the axes creation call.

• kwargs (dict) – Additional arguments to plt.figure()

Returns:

• *If fig is provided*

• ax (matplotlib axes object)

• *If fig is not provided*

• fig (matplotlib figure object)

• ax (matplotlib ax object)

watershed_workflow.plot.huc(huc, crs, color='k', ax=None, **kwargs)

Plot a HUC polygon.

A wrapper for plot.shply()

Parameters:

• huc (shapely polygon) – An object to plot.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to the plotting method, which is likely descartes.PolygonPatch.

Returns:

patches

Return type:

matplotlib PatchCollection

watershed_workflow.plot.hucs(hucs, crs, color='k', ax=None, outlet_marker=None, outlet_markersize=100, outlet_markercolor='green', **kwargs)

Plot a SplitHUCs object.

A wrapper for plot.shply()

Parameters:

• hucs (watershed_workflow.split_hucs.SplitHucs object) – The collection of hucs to plot.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• outlet_marker (matplotlib marker string, optional) – If provided, also plots the actual points that make up the shape.

• outlet_markersize (float, optional) – Size of the outlet marker.

• outlet_markercolor (matplotlib color string, optional) – Color of the outlet marker.

• kwargs (dict) – Extra arguments passed to the plotting method, which is likely descartes.PolygonPatch.

Returns:

patches

Return type:

matplotib PatchCollection

watershed_workflow.plot.shapes(shps, crs, color='k', ax=None, **kwargs)

Plot an itereable collection of fiona shapes.

A wrapper for plot.shply()

Parameters:

• shapes (list(fiona shape objects)) – The collection of fiona shape objects to plot.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to the plotting method, which is likely descartes.PolygonPatch.

Returns:

patches

Return type:

matplotib PatchCollection

watershed_workflow.plot.river(river, crs, color='b', ax=None, **kwargs)

Plot an itereable collection of reaches.

A wrapper for plot.shply()

Parameters:

• river (list(shapely.LineString)) – An iterable of shapely LineString reaches.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to the plotting method, which is likely matplotlib.collections.LineCollection.

Returns:

lines

Return type:

matplotib LineCollection

watershed_workflow.plot.rivers(rivers, crs, color=None, ax=None, **kwargs)

Plot an itereable collection of river Tree objects.

A wrapper for plot.shply()

Parameters:

• rivers (list(river_tree.RiverTree)) – An iterable of river_tree.RiverTree objects.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to the plotting method, which is likely matplotlib.collections.LineCollection.

Returns:

lines

Return type:

matplotib LineCollection

watershed_workflow.plot.shply(shp, *args, **kwargs)

Plot a single shapely object. See shplys() for options.

watershed_workflow.plot.shplys(shps, crs, color=None, ax=None, marker=None, **kwargs)

Plot shapely objects.

Currently this assumes shps is an iterable collection of Points, Lines, or Polygons. So while a single MultiPolygon is allowed, lists of MultiPolygons are not currently supported. These can easily be unraveled.

Heterogeneous collections are not supported.

Parameters:

• shps (shapely shape, list(shapely shape objects), or MultiShape object) – An iterable of shapely objects to plot.

• crs (CRS object) – The coordinate system to plot in.

• color (str, scalar, or array-like, optional) – See https://matplotlib.org/tutorials/colors/colors.html

• ax (matplotib axes object, optional) – Axes to plot on. Calls get_ax() if not provided.

• marker (matplotlib marker string) – If provided, also plots the actual points that make up the shape.

• kwargs (dict) – Extra arguments passed to the plotting method, which can be: * pyplot.scatter() (if shps are Point objects) * matplotlib.collections.LineCollection() (if shps are LineStrings) * descartes.PolygonPatch() (if shps are Polygons)

Returns:

col

Return type:

collection of matplotlib points or lines or patches

watershed_workflow.plot.triangulation(points, tris, crs, color='gray', ax=None, **kwargs)

Plots a triangulation.

A wrapper for matplotlib’s plot_trisurf() or tripcolor()

Parameters:

• points (np.ndarray(npoints, 3)) – Array of point coordinates, x,y,z.

• tris (list, np.ndarray(ntris, 3)) – List of lists or ndarray of indices into the points array for defining the triangle topology.

• crs (CRS object) – Coordinate system of the points.

• color (matplotlib color object or iterable or str, optional) – Either a matplotlib color object (for uniform colors), or a list of color objects (length equal to the length of tris), or ‘elevation’ to color by z coordinate.

• ax (matplotlib ax object) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to plot_trisurf() (for 3D axes) or tripcolor() (for 2D).

Returns:

col – Collection of patches representing the triangles.

Return type:

matplotlib collection

watershed_workflow.plot.mesh(m2, crs, color='gray', ax=None, **kwargs)

Plots a watershed_workflow.mesh.Mesh2D object.

Parameters:

• m2 (Mesh2D) – The 2D mesh to plot.

• crs (CRS object) – Coordinate system of the points.

• color (matplotlib color object or iterable or str, optional) – Either a matplotlib color object (for uniform colors), or a list of color objects (length equal to the length of tris), or ‘elevation’ to color by z coordinate.

• ax (matplotlib ax object) – Axes to plot on. Calls get_ax() if not provided.

• kwargs (dict) – Extra arguments passed to plot_trisurf() (for 3D axes) or tripcolor() (for 2D).

Returns:

col – Collection of patches representing the triangles.

Return type:

matplotlib collection

watershed_workflow.plot.raster(profile, data, ax=None, vmin=None, vmax=None, mask=True, **kwargs)

Plots a raster.

A wrapper for matplotlib imshow()

Parameters:

• profile (rasterio profile) – Rasterio profile of the input raster.

• data (np.ndarray) – 2D array of data.

• ax (matplotlib ax object) – Axes to plot on. Calls get_ax() if not provided.

• vmin (float) – Min and max value to limit extent of color values.

• vmax (float) – Min and max value to limit extent of color values.

• mask (bool) – If true (default), masks out values given as profile[‘nodata’]

• kwargs (dict) – Dictionary of extra arguments passed to imshow().

Returns:

im – Return value of imshow()

Return type:

matplotlib image object

watershed_workflow.plot.dem(profile, data, ax=None, vmin=None, vmax=None, **kwargs)

See raster documentation

watershed_workflow.plot.basemap(crs=None, ax=None, resolution='50m', land_kwargs=None, ocean_kwargs=None, state_kwargs=None, country_kwargs=None, coastline_kwargs=None, lake_kwargs=None)

Add a basemap to the axis.

Uses cartopy to add political and natural boundaries and shapes to the axes image.

Parameters:

• crs (CRS object, optional) – Coordinate system to plot. May be ignored if ax is provided.

• ax (matplotlib ax object, optional) – Matplotlib axes to plot on. If not provided, get_ax() is called using crs.

• resolution (str) – Resolution of cartopy basemap. One of ‘10m’, ‘50m’, or ‘110m’.

• land_kwargs (dict) – Extra arguments passed to cartopy.feature.NaturalEarthFeature call to get land polygons.

• ocean_kwargs (dict) – Extra arguments passed to cartopy.feature.NaturalEarthFeature call to get ocean polygons.

• state_kwargs (dict) – Extra arguments passed to cartopy.feature.NaturalEarthFeature call to get political state boundary polygons.

• country_kwargs (dict) – Extra arguments passed to cartopy.feature.NaturalEarthFeature call to get political country boundary polygons.

• coastline_kwargs (dict) – Extra arguments passed to cartopy.feature.NaturalEarthFeature call to get natural coastline boundary polygons.

watershed_workflow.plot.feather_axis_limits(ax, delta=0.02)

Adds a small delta to the axis limits to provide a bit of buffer.

Parameters:

• ax (matplotlib Axis object) – The axis to feather.

• delta (2-tuple or double, default=0.02) – If a double, equivalent to (delta,delta). Provides the fraction of the current plot width,height to increase by.

watershed_workflow.colors.enumerated_colors(count, palette=1, chain=True)

Gets an enumerated list of count independent colors.

watershed_workflow.colors.cm_mapper(vmin=0.0, vmax=1.0, cmap=None, norm=None, get_sm=False)

Provide a function that maps scalars to colors in a given colormap.

Parameters:

• vmin (scalar) – Min and max scalars to be mapped.

• vmax (scalar) – Min and max scalars to be mapped.

• cmap (str or matplotlib.cmap instance) – The colormap to discretize.

• norm (optional, matplotlib Norm object) – A normalization.

Return type:

Function, cmap(scalar) -> (r,g,b,a)

Example

# plot 4 lines
x = np.arange(10)
cm = cm_mapper(0,3,'jet')
for i in range(4):
    plt.plot(x, x**i, color=cm(i))

watershed_workflow.colors.cm_discrete(ncolors, cmap=<matplotlib.colors.LinearSegmentedColormap object>)

Calculate a discrete colormap with N entries from the continuous colormap cmap.

Parameters:

• ncolors (int) – Number of colors.

• cmap (str or matplotlib.cmap instance, optional) – The colormap to discretize. Default is ‘jet’.

Return type:

matplotlib.colors.LinearSegmentedColormap instance

Example

# plot 4 lines
x = np.arange(10)
colors = cmap_discretize('jet', 4)
for i in range(4):
    plt.plot(x, x**i, color=colors[i])

watershed_workflow.colors.float_list_type(mystring)

Convert string-form list of doubles into list of doubles.

watershed_workflow.colors.generate_indexed_colormap(indices, cmap=None)

Generates an indexed colormap and labels for imaging, e.g. soil indices. :param indices: Collection of indices that will be used in this colormap. :type indices: iterable(int) :param cmap: Name of matplotlib colormap to sample. :type cmap: optional, str

Returns:

• indices_out (list(int)) – The unique, sorted list of indices found.

• cmap (cmap-type) – A segmented map for use with plots.

• norm (BoundaryNorm) – A norm for use in plot_trisurf() or other plotting methods to ensure correct NLCD colors.

• ticks (list(int)) – A list of tick locations for the requested indices. For use with set_ticks().

• labels (list(str)) – A list of labels associated with the ticks. For use with set_{x,y}ticklabels().

watershed_workflow.colors.generate_nlcd_colormap(indices=None, formatted=False)

Generates a colormap and labels for imaging with the NLCD colors.

Parameters:

indices (iterable(int), optional) – Collection of NLCD indices that will be used in this colormap. If None (default), uses all NLCD indices.

Returns:

• indices_out (list(int)) – The unique, sorted list of indices found.

• cmap (cmap-type) – A segmented map for use with plots.

• norm (BoundaryNorm) – A norm for use in plot_trisurf() or other plotting methods to ensure correct NLCD colors.

• ticks (list(int)) – A list of tick locations for the requested indices. For use with set_ticks().

• labels (list(str)) – A list of labels associated with the ticks. For use with set_{x,y}ticklabels().

• formatted (bool,) – To make the labels formatted nicely (i.e. add newline in long label names)

Example

Plot a triangulation given a set of NLCD colors on those triangles.

Given a triangluation mesh_points, mesh_tris and NLCD color indices for each triangle (tri_nlcd):

indices, cmap, norm, ticks, labels = generate_nlcd_colormap(set(tri_nlcd))

mp = ax.plot_trisurf(mesh_points[:,0], mesh_points[:,1], mesh_points[:,2],
        triangles=mesh_tris, color=tri_nlcd,
        cmap=cmap, norm=norm)
cb = fig.colorbar(mp, orientation='horizontal')
cb.set_ticks(ticks)
cb.ax.set_xticklabels(labels, rotation=45)

watershed_workflow.colors.generate_modis_colormap(indices=None, formatted=False)

Generates a colormap and labels for imaging with the MODIS colors.

Parameters:

indices (iterable(int), optional) – Collection of MODIS indices that will be used in this colormap. If None (default), uses all MODIS indices.

Returns:

• indices_out (list(int)) – The unique, sorted list of indices found.

• cmap (cmap-type) – A segmented map for use with plots.

• norm (BoundaryNorm) – A norm for use in plot_trisurf() or other plotting methods to ensure correct MODIS colors.

• ticks (list(int)) – A list of tick locations for the requested indices. For use with set_ticks().

• labels (list(str)) – A list of labels associated with the ticks. For use with set_{x,y}ticklabels().

• formatted (bool,) – To make the labels formatted nicely (i.e. add newline in long label names)

Example

Plot a triangulation given a set of MODIS colors on those triangles.

Given a triangluation mesh_points, mesh_tris and MODIS color indices for each triangle (tri_modis):

indices, cmap, norm, ticks, labels = generate_modis_colormap(set(tri_modis))

mp = ax.plot_trisurf(mesh_points[:,0], mesh_points[:,1], mesh_points[:,2],
        triangles=mesh_tris, color=tri_modis,
        cmap=cmap, norm=norm)
cb = fig.colorbar(mp, orientation='horizontal')
cb.set_ticks(ticks)
cb.ax.set_xticklabels(labels, rotation=45)

watershed_workflow.colors.colorbar_index(ncolors, cmap, labels=None, **kwargs)

Add an indexed colorbar based on a given colormap.

This sets ticks in the middle of each color range, adds the colorbar, and sets the labels if provided.

Parameters:

• ncolors (int) – Number of colors to display.

• cmap (matplotlib.cmap instance) – The colormap used in the image.

• labels (list) – Optional list of label strings that equal to the number of colors. If not provided, labels are set to range(ncolors).

• kwargs (dict) – Other arguments are passed on to the plt.colorbar() call, which can be used for things like fraction, pad, etc to control the location/spacing of the colorbar.

Returns:

colorbar

Return type:

the colorbar object

Generic utilities

Shape and geometry utilities for working with fiona and shapely objects.

Note this module contains a lot of other simple functions that are commonly used by other functions, but are not included in documentation because they are likely not useful to users.

watershed_workflow.utils.create_shply(shape, properties=None, flip=False)

Converts a fiona style shape to a shapely shape with as much collapsing as possible.

Note this collapses objects – for instance, fiona MultiPolygons of length 1 are turned into shapely Polygons.

Parameters:

• shape (fiona shape) – Fiona shape to convert to shapely.

• properties (dict, optional) – A dictionary of parameters to associate with the object. Defaults to shape[‘properties’] if it exists, None otherwise.

• flip (bool, optional) – Flip x,y coordinates while making the translation. This helps if files provide lat-long ordered coordinates (note that is y,x) as opposed to long-lat (x,y). Default is False.

Returns:

thing

Return type:

shapely shape

watershed_workflow.utils.deepcopy(list_of_shapes)

Deals with properties dictionary

watershed_workflow.utils.create_bounds(f)

General bounding box for fiona and shapely types.

watershed_workflow.utils.create_raster_profile(bounds, crs, resolution, dtype=None, nodata=None, count=1)

Creates a profile for a raster.

Parameters:

• bounds ([x_min, y_min, x_max, y_max]) – Bounding box for the raster.

• crs (CRS object) – Target coordinate system.

• resolution (tuple or float) – Pixel width, in units of the crs. If a tuple, (dx,dy). If a float, then dx = dy.

• dtype (optional) – If provided, sets the data type.

• nodata (dtype, optional) – If provided, sets the nodata value.

• count (int, optional) –

• make (Note that dx/dy are always used. The bounds are adjusted to) –

• dx/dy. (them an even multiple of) –

Returns:

Dictionary profile, including a transform and all other needed metadata to create a raster.

Return type:

dict

watershed_workflow.utils.create_empty_raster(bounds, crs, resolution, nodata, count=1)

Generates a profile and a nodata-filled array.

watershed_workflow.utils.is_empty_shapely(shp)

Is shp None or empty

watershed_workflow.utils.round_shapes(list_of_things, digits)

Rounds coordinates in things or shapes to a given digits.

watershed_workflow.utils.round_shplys(list_of_things, digits)

Rounds coordinates in things or shapes to a given digits.

watershed_workflow.utils.remove_third_dimension(geom)

Removes the third dimension of a shapely object.

watershed_workflow.utils.flatten(list_of_shps)

Flattens a list of shapes, that may contain Multi-objects, into list without multi-objects

watershed_workflow.utils.impute_holes2D(arr, nodata=nan, method='cubic')

Very simple imputation algorithm to interpolate values for missing data in rasters.

Note, this may throw if there is a hole on the boundary?

Parameters:

• arr (np.ndarray) – 2D array, with missing data.

• nodata (optional = np.nan) – Value to treat as a hole to fill.

• method (str, optional = 'cubic') – Algorithm to use (see scipy.interpolate.griddata). Likely ‘cubic’, ‘linear’, or ‘nearest’.

Returns:

New array with no values of nodata.

Return type:

np.ndarray

watershed_workflow.utils.compute_average_year(data, output_nyears=1, smooth=False, **kwargs)

Averages and smooths to form a “typical” year.

Parameters:

• data (the) – Daily array to average, note that NTIMES > 365.

• output_nyears (int, optional) – Number of years to repeat the output. Default is 1.

• filter (bool, optional) – If true, filters the data using a Sav-Gol filter from Scipy

• See (All other parameters are passed to the filter.) –

• scipy.signal.savgol_filter –

• if (but sane default values are used) –

• 0 (these are not provided. Note that if NTIMES % 365 !=) –

• data –

• truncated. (is) –

Returns:

The averaged data.

Return type:

np.ndarray(shape=(365*output_nyears, …))

watershed_workflow.utils.interpolate_in_time_regular(times, data, start, end, dt=datetime.timedelta(days=1), axis=0, **kwargs)

Interpolate time-dependent data to a regularly spaced time array.

Parameters:

• times (np.1darray(dtype=cftime.datetime)) – An array of times, of length NTIMES.

• data (np.ndarray) – Data to interpolate, data.shape[axis] == NTIMES.

• start (cftime.datetime) – Times to begin and end (inclusive) the interpolated array.

• end (cftime.datetime) – Times to begin and end (inclusive) the interpolated array.

• dt (datetime.timedelta, optional) – Delta to interpolate to. Defaults to 1 day.

• axis (int, optional) – Axis of data that corresponds to time. Default is 0.

• Of (All other parameters are passed to scipy.interpolate.interp1d.) –

• or (use particularly is 'kind' which can be 'linear' (default)) –

• 'quadratic' –

• others. ('cubic' or) –

Returns:

• new_times (np.1darray(dtype=datetime.date)) – Times of the new array.

• new_data (np.ndarray) – The data interpolated.

watershed_workflow.utils.interpolate_in_time(times, data, new_times, axis=0, units='days since 2000', **kwargs)

Interpolate time-dependent data to an arbitrary other time array.

Parameters:

• times (np.1darray(dtype=cftime.datetime)) – An array of times, of length NTIMES.

• data (np.ndarray) – Data to interpolate, data.shape[axis] == NTIMES.

• new_times (np.1darray(dtype=cftime.datetime)) – An array of times to interpolate to.

• axis (int, optional) – Axis of data that corresponds to time. Default is 0.

• units (str, optional) – Interpolation must happen in a numeric coordinate – this unit is used to convert from dates to numbers using cftime.date2num. Valid cfunits for time are strings like “days since 2000-1-1”, which is the default.

• Of (All other parameters are passed to scipy.interpolate.interp1d.) –

• or (use particularly is 'kind' which can be 'linear' (default)) –

• 'quadratic' –

• others. ('cubic' or) –

Returns:

new_data – The data interpolated.

Return type:

np.ndarray

watershed_workflow.utils.smooth_array(data, method, axis=0, **kwargs)

Smooths fixed-interval time-series data using a Sav-Gol filter from scipy.

Note that this wrapper just sets some sane default values for daily data – one could just as easily call scipy.signal.savgol_filter themselves.

Parameters:

• data (np.ndarray) – The data to smooth.

• window_length (int, optional) – Length of the moving window over which to fit the polynomial. Default is 61.

• polyorder (int, optional) – Order of the fitting polynomial. Default is 2.

• axis (int, optional) – Time axis over which to smooth. Default is 0.

• mode (str, optional) – See scipy.signal.savgol_filter documentation, but ‘wrap’ is the best bet for data in multiples of years. Default is ‘wrap.’

• scipy.signal.savgol_filter (Any additional kwargs are passed to) –

Returns:

Smoothed data in the same shape as data

Return type:

np.ndarray

watershed_workflow.utils.generate_rings(obj)

Generator for a fiona shape’s coordinates object and yield rings.

As long as the input is conforming, the type of the geometry doesn’t matter.

Parameter

obj : fiona shape

returns:

rings – Iterates over rings, each of which is a list of coordinate tuples.

rtype:

iterator

watershed_workflow.utils.generate_coords(obj)

Generator for a fiona geometry’s coordinates.

As long as the input is conforming, the type of the geometry doesn’t matter.

Parameter

obj : fiona shape

returns:

coord – Iterates over coordinate tuples.

rtype:

iterator

watershed_workflow.utils.close(s1, s2, tol=1e-07)

Are two shapely shapes topologically equivalent and geometrically close?

Note this deals with things like rotations of polygons (clock-rotating the coordinates of the same shape are still close) and other gotchas that keep you from just comparing coordinates.

Parameters:

• s1 (shapely shapes) – Objects to compare.

• s2 (shapely shapes) – Objects to compare.

• tol (double) – Distance to compare geometric closeness.

Returns:

close – Is close?

Return type:

bool

watershed_workflow.utils.contains(s1, s2, tol=1e-07)

A contains algorithm that deals with close/roundoff issues

exception watershed_workflow.utils.CutError(message, line, seg, cutline)

watershed_workflow.utils.cut(line, cutline, tol=1e-05)

Cuts a line at all intersections with cutline. If an existing point in line is within tol of the cutline, do not add an additional coordinate, just move that coordinate. Otherwise, add a new coordinate.

watershed_workflow.utils.distance(p1, p2)

Distance between two points in tuple form

watershed_workflow.utils.in_neighborhood(obj1, obj2, tol=0.1)

Determines if two objects can possibly intersect by performing a quick check of their bounding boxes.

watershed_workflow.utils.intersect_point_to_segment(point, line_start, line_end)

Finds the nearest point on a line segment to a point

watershed_workflow.utils.nearest_point(line, point)

Returns the nearest coordinate on the line to point.

Note point is expected as coordinates.

watershed_workflow.utils.triangle_area(vertices)

Area of a triangle in 2D

watershed_workflow.utils.is_collinear(p0, p1, p2, tol=1e-06)

this function checks if three points are collinear for given tolerance value

watershed_workflow.utils.area(vertices)

Area of polygons in 2D

watershed_workflow.utils.angle(v1, v2)

Given two 2D vectors represented as len 2 arrays or tuples, find the angle of 2 relative to 1 in a clockwise notion.

watershed_workflow.utils.midpoint(p1, p2)

Returns the midpoint of two points

watershed_workflow.utils.closest_point_ind(point, points)

Returns the index of closest point from an array of points

watershed_workflow.utils.center(objects, centering=True)

Centers a collection of objects by removing their collective centroid

watershed_workflow.utils.orientation(p1, p2, p3)

to find the orientation of an ordered triplet (p1,p2,p3) function returns the following values: 0 : Collinear points 1 : Clockwise points 2 : Counterclockwise

watershed_workflow.utils.intersects(shp1, shp2)

Checks whether an intersection exists.

Note that intersection being empty and intersects are not always reliably the same… we avoid using shapely.intersects() for this reason.

watershed_workflow.utils.non_point_intersection(shp1, shp2)

Checks whether an intersection is larger than a point.

Note that intersection being empty and intersects are not always reliably the same… we avoid using intersects() for this reason.

watershed_workflow.utils.volumetric_intersection(shp1, shp2)

Checks whether an intersection includes volume and not just points and lines.

watershed_workflow.utils.filter_to_shape(shape, to_filter, tol=None, algorithm='intersects')

Filters out reaches (or reaches in rivers) not inside the HUCs provided.

algorithm is one of ‘contains’ or ‘intersects’ to indicate whether to include things entirely in shape or partially in shape, respectively.

watershed_workflow.utils.cluster(points, tol)

Given a list of points, determine a list of clusters.

Each cluster is within tol of each other.

Returns (cluster_index, cluster_centroid)

watershed_workflow.utils.treat_segment_collinearity(segment_coords, tol=1e-05)

This functions removes collinearity from a node segment by making small pertubations orthogonal to the segment