subsettools.domain

Functions to define a domain on the CONUS grids.

A domain is defined by the grid ij bounds and a mask array.

The grid bounds is a tuple (imin, jmin, imax, jmax) that defines a bounding box on the CONUS grid that encompases the domain. Note that the origin (0, 0) of the CONUS grids is always the southwest corner. Thus, (imin, jmin) is the southwest corner of the bounding box, and (imax - 1, jmax - 1) the northeast corner (upper bounds are exclusive in keeping with Python convention).

The mask is a 0/1 NumPy array which has the same shape as the bounding box and indicates which cells are part of the subset domain.

SubsetTools provides functions to define domains in different ways.

A domain that is a collections of HUCs.
A box that is defined by two latitude-longitude points.
A domain that is the upstream area of a collection of outlets.

Functions

`define_huc_domain`(hucs, grid)	Define a domain by a collection of HUCs.
`huc_to_ij`(huc_list, grid)	This function is deprecated.
`define_latlon_domain`(latlon_bounds, grid)	Define a domain by latitude/longitude bounds.
`latlon_to_ij`(latlon_bounds, grid)	This function is deprecated.
`write_mask_solid`(mask, grid, write_dir[, mode, ij_bounds])	Create ParFlow mask and solid files from a mask array.
`create_mask_solid`(huc_list, grid, write_dir)	This function is deprecated.
`define_upstream_domain`(outlets, grid)	Define a domain that is the upstream area of the points in outlets.

subsettools.domain.define_huc_domain(hucs, grid)[source]

Define a domain by a collection of HUCs.

The domain is defined by the grid ij bounds of a bounding box that encompasses the HUCs in the list and a mask for that bounding box indicating which cells in the bounding box are part of these HUCs.

All HUC IDs in hucs must be the same length (HUCs of the same level). All HUCs should be adjacent. If a HUC is only partially covered by the provided grid, the grid bounds for the covered area will be returned.

Parameters:

hucs (list[str]) – a list of USGS HUC IDs
grid (str) – The spatial grid that the ij indices are calculated relative to and that the subset data will be returned on. Possible values: “conus1” or “conus2”

Returns:

A tuple (bounds, mask).

Bounds is a tuple of the form (imin, jmin, imax, jmax) representing the bounds in the conus grid of the area defined by the HUC IDs in hucs. imin, jmin, imax, jmax are the west, south, east and north sides of the box respectively and all i,j indices are calculated relative to the lower southwest corner of the domain.

Mask is a 2D numpy.ndarray that indicates which cells inside the bounding box are part of the selected HUC(s).

Raises:

ValueError – If the area defined by the provided HUCs is not part of the given grid.

Example:

grid_bounds, mask = define_huc_domain(
    hucs=["14080201", "14080202", "14080203"], grid="conus1"
)

subsettools.domain.huc_to_ij(huc_list, grid)[source]

This function is deprecated.

Use define_huc_domain() instead.

subsettools.domain.define_latlon_domain(latlon_bounds, grid)[source]

Define a domain by latitude/longitude bounds.

The domain is defined by the grid ij bounds of a bounding box formed by the latitude/longitude bounds (latlon_bounds) relative to the selected conus grid and a mask for that bounding box indicating which cells are active CONUS points.

Parameters:

latlon_bounds (List[List[float]]) – list of the form [[lat1, lon1], [lat2, lon2]]. [lat1, lon1] and [lat2, lon2] define the northwest and southeast corners of the desired box respectively.
grid (str) – The spatial grid that the ij indices are calculated relative to and that the subset data will be returned on. Possible values: “conus1” or “conus2”.

Returns:

A tuple (bounds, mask).

Bounds is a tuple of the form (imin, jmin, imax, jmax) representing the bounds in the conus grid of the area defined by the latlon_bounds. imin, jmin, imax, jmax are the west, south, east and north sides of the box respectively and all i,j indices are calculated relative to the lower southwest corner of the domain.

Mask is a 2D numpy.ndarray that indicates which cells inside the bounding box are active CONUS points (for example, if ocean is part of the bounding box the corresponding cells will not be part of the mask).

Example:

grid_bounds, mask = define_latlon_domain(
    latlon_bounds=[[37.91, -91.43], [37.34, -90.63]], grid="conus2"
)

subsettools.domain.latlon_to_ij(latlon_bounds, grid)[source]

This function is deprecated.

Use define_latlon_domain() instead.

subsettools.domain.write_mask_solid(mask, grid, write_dir, mode='single-mask', ij_bounds=None)[source]

Create ParFlow mask and solid files from a mask array.

Given an integer mask array consisting of 0s and 1s, this function will create three files in write_dir.

a 2D mask file that indicates which cells inside the box domain are part of the selected HUCS.

a solid file that defines a 3D domain extending to the depth of whichever grid has been selected and tracing the boundaries of the selected HUCS.

a vtk file, which can be used to visualize the solid file in ParaView.

If the mode is ‘multi-mask’, another six masks will be written for the top, bottom, left, right, front and back masks for each cell in the domain.

Parameters:

mask (numpy.ndarray) – an integer array such that mask[i, j] == 1 if the cell (i, j) is part of the domain, and mask[i, j] == 0 otherwise.
grid (str) – The spatial grid that the ij indices are calculated relative to and that the subset data will be returned on. Possible values: “conus1” or “conus2”
write_dir (str) – directory path where the mask and solid files will be written
mode (str) – This is the mode that the pfmask-to-pfsol script will be run. It can be either ‘single-mask’ or ‘multi-mask’. Currently, ‘multi-mask’ mode is only supported for the CONUS2 grid.
ij_bounds (tuple[int]) – bounding box for subset. This should be given as i,j index values where 0,0 is the lower left hand corner of a domain. ij_bounds are given relative to whatever grid is being used for the subset. This is only necessary if mode is ‘multi-mask’.

Returns:

A dictionary mapping the keys (“mask”, “mask_vtk”, “solid”) to the: corresponding filepaths of the created files. If the mode is ‘multi-mask’ the dictionary will contain additional keys for the side masks for each cell in the domain.

Return type:

dict

Example:

filepaths = write_mask_solid(
    mask=np.array([[0, 1], [1, 1]]),
    grid="conus2",
    write_dir="/path/to/your/chosen/directory"
)

subsettools.domain.create_mask_solid(huc_list, grid, write_dir)[source]

This function is deprecated.

Use write_mask_solid() instead.

subsettools.domain.define_upstream_domain(outlets, grid)[source]

Define a domain that is the upstream area of the points in outlets.

The domain is defined by the grid ij bounds of the bounding box that encompasses the upstream area of all the points in outlets and a mask for that bounding box indicating which cells are part of the selected area.

The flow_direction files that are used to define the upstream area follow the convention: down: 1, left: 2, up: 3, right: 4.

Parameters:

outlets (List[List[float]]) – list of lat-lon points of the form [[lat1, lon1], [lat2, lon2], …]
grid (str) – The spatial grid that the ij indices are calculated relative to and that the subset data will be returned on. Possible values: “conus1” or “conus2”

Returns:

A tuple (bounds, mask).

Bounds is a tuple of the form (imin, jmin, imax, jmax) representing the bounds in the conus grid of the upstream area of the outlets. imin, jmin, imax, jmax are the west, south, east and north sides of the box respectively and all i,j indices are calculated relative to the lower southwest corner of the domain.

Mask is a 2D numpy.ndarray that indicates which cells inside the bounding box are part of the computed upstream area of the outlets.

Raises:

ValueError – If the computed upstream area of the outlets is empty.

Example:

bounds, mask = define_upstream_domain(
    outlets=[[44.1348, -95.5084], [44.1352, -95.4949]],
    grid="conus2"
)