Title: | Hydrologic Network Refactoring and Aggregation Tools |
---|---|
Description: | A collection of tools for manipulating hydrologic and hydraulic networks |
Authors: | Mike Johnson [aut, cre] , David Blodgett [ctb] |
Maintainer: | Mike Johnson <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.6.1 |
Built: | 2024-12-06 07:25:46 UTC |
Source: | https://github.com/NOAA-OWP/hydrofab |
Compute km2 area Short hand for safely computing area in sqkm and returning as numeric vector.
Compute area in square kilometers
add_areasqkm(x) add_areasqkm(x)
add_areasqkm(x) add_areasqkm(x)
x |
POLYGON sf object |
numeric vector
numeric vector
library(sf) nc = st_read(system.file("shape/nc.shp", package="sf")) add_areasqkm(nc[1,])
library(sf) nc = st_read(system.file("shape/nc.shp", package="sf")) add_areasqkm(nc[1,])
Add small area to crosswalk
add_areasqkm_to_crosswalk(crosswalk, comid = "hf_id")
add_areasqkm_to_crosswalk(crosswalk, comid = "hf_id")
crosswalk |
an existing crosswalk table |
comid |
the shared ID |
data.frame
Generate Catchment Network Table
add_flowpath_edge_list(gpkg)
add_flowpath_edge_list(gpkg)
gpkg |
a hydrofabric gpkg |
data.frame with ID, toID, length, area, and levelpath
Add hydrosequence
add_hydroseq(flowpaths)
add_hydroseq(flowpaths)
flowpaths |
sf object (LINESTRING) |
sf object
Compute length in kilometers
add_lengthkm(x)
add_lengthkm(x)
x |
LINESTRING sf object |
numeric vector
This function replicates the member_COMID column of a refactored network but adds a new notation Following each COMID is '.' which is proceeded by the fraction of that COMID making up the new flowpath. For example 101.1 would indicate 100 Equally 101.05 would indicate 50
add_lengthmap(flowpaths, length_table)
add_lengthmap(flowpaths, length_table)
flowpaths |
a refactored flowpath network containing an member_COMID column |
length_table |
a table of NHDPlus COMIDs and LENGTH to use as weights.
Can be found with |
sf object
## Not run: path <- system.file("extdata/walker_reconcile.gpkg", package = "hydrofab") fps <- add_lengthmap(flowpaths = sf::read_sf(path), length_table = nhdplusTools::get_vaa("lengthkm")) ## End(Not run)
## Not run: path <- system.file("extdata/walker_reconcile.gpkg", package = "hydrofab") fps <- add_lengthmap(flowpaths = sf::read_sf(path), length_table = nhdplusTools::get_vaa("lengthkm")) ## End(Not run)
Generate Lookup table for refactored or aggregated network
add_lookup_table( gpkg = NULL, refactored_gpkg = NULL, reconciled_layer = "flowpaths" )
add_lookup_table( gpkg = NULL, refactored_gpkg = NULL, reconciled_layer = "flowpaths" )
gpkg |
character path to gpkg containing aggregated network. Omit for refactored network lookup table creation. |
refactored_gpkg |
character path to the gpkg for the refactored network used to create the aggregate network. If no aggregatedd gpkg is passed in, a lookup table will be added to this gpkg. |
reconciled_layer |
character path layer name containing fully reconciled flowpaths. Ignored for aggregated network lookup table creation. |
file path to modified gpkg
Add a mapped_POI layer to network_list
add_mapped_hydrolocations( network_list, type = c("HUC12", "Gages", "TE", "NID", "WBIn", "WBOut"), refactored_gpkg = NULL, verbose = TRUE )
add_mapped_hydrolocations( network_list, type = c("HUC12", "Gages", "TE", "NID", "WBIn", "WBOut"), refactored_gpkg = NULL, verbose = TRUE )
network_list |
a list with flowpath and catchment data |
refactored_gpkg |
a (optional) path to |
verbose |
should messages be emited? |
list()
Add/sync/update length and area measures
add_measures(flowpaths, divides)
add_measures(flowpaths, divides)
cat |
sf object (POLYGON) |
list
Add Non Network Divides to Aggregated Fabric The refactoring process intentionally drop catchments without a flowpath. In cases where a seamless discritization of the landscape is needed, these area must be reintroduced from the reference dataset.
add_nonnetwork_divides( gpkg = NULL, vpu = NULL, divides = NULL, huc12 = NULL, reference_gpkg = NULL, reference_divides = NULL, verbose = TRUE )
add_nonnetwork_divides( gpkg = NULL, vpu = NULL, divides = NULL, huc12 = NULL, reference_gpkg = NULL, reference_divides = NULL, verbose = TRUE )
gpkg |
a path to a gpkg |
huc12 |
huc12 to COMID crosswalk |
reference_gpkg |
A path to the reference VPU geopackage (see get_hydrofabric(..., type = "reference")) |
verbose |
Should messages be emitted? |
divide |
If gpkg is NULL, then an sf data.frame, otherwise a the layer name. See details. |
gpkg path
This function generates spatial points for non-network nexus locations (coastal and internal) based on the provided divides. It assigns unique identifiers and links them to waterbody identifiers.
add_nonnetwork_nexus_location( divides, coastal_nexus_prefix = "cnx-", internal_nexus_prefix = "inx-", waterbody_prefix = "wb-" )
add_nonnetwork_nexus_location( divides, coastal_nexus_prefix = "cnx-", internal_nexus_prefix = "inx-", waterbody_prefix = "wb-" )
divides |
A spatial data frame (e.g., 'sf' object) containing polygons representing divides. Must include columns 'type', 'divide_id', and 'toid'. |
coastal_nexus_prefix |
A character string to prefix 'divide_id' values for coastal nexus locations. Default is '"cnx-"'. |
internal_nexus_prefix |
A character string to prefix 'divide_id' values for internal nexus locations. Default is '"inx-"'. |
waterbody_prefix |
A character string to prefix 'toid' values for non-network nexus locations. Default is '"wb-"'. |
- For each divide of type 'coastal' or 'internal', the function calculates a representative point using 'st_point_on_surface'. - Prefixes are applied to 'divide_id' and 'toid' values using 'flush_prefix' and 'mutate'. - The output retains only the columns 'id', 'toid', 'type', and geometry.
A spatial data frame (e.g., 'sf' object) containing the non-network nexus locations. The resulting data frame includes the columns: - 'id': Unique identifier for each nexus location (prefixed with 'coastal_nexus_prefix' or 'internal_nexus_prefix'). - 'toid': Linked waterbody identifier (prefixed with 'waterbody_prefix'). - 'type': The type of nexus ('coastal' or 'internal'). - 'geometry': The spatial location of each nexus.
This function adds specified prefixes to the 'id' and 'toid' columns of a topological data frame based on the type of topology and its context (e.g., network or nexus).
add_prefix( topo, hf_prefix = "cat-", nexus_prefix = "nex-", terminal_nexus_prefix = "tnx-", coastal_nexus_prefix = "cnx-", internal_nexus_prefix = "inx-" )
add_prefix( topo, hf_prefix = "cat-", nexus_prefix = "nex-", terminal_nexus_prefix = "tnx-", coastal_nexus_prefix = "cnx-", internal_nexus_prefix = "inx-" )
topo |
A data frame containing topological data. Must include columns 'topo_type', 'type', 'id', and 'toid'. |
hf_prefix |
A character string to prefix 'id' values in rows where 'topo_type == "network"'. Default is '"cat-"'. |
nexus_prefix |
A character string to prefix 'toid' values in rows where 'type' does not match specific cases ('terminal', 'coastal', or 'internal'). Default is '"nex-"'. |
terminal_nexus_prefix |
A character string to prefix 'toid' values where 'type == "terminal"'. Default is '"tnx-"'. |
coastal_nexus_prefix |
A character string to prefix 'toid' values where 'type == "coastal"'. Default is '"cnx-"'. |
internal_nexus_prefix |
A character string to prefix 'toid' values where 'type == "internal"'. Default is '"inx-"'. |
A data frame with updated 'id' and 'toid' values, including appropriate prefixes based on the type of topology and the 'type' column. The resulting data frame contains the columns 'id', 'toid', 'type', and any additional columns with names containing '"vpu"'.
This function takes a vector of area's and length's and returns a grouping vector that enforces the grouping of lengths and areas less then defined thresholds
agg_length_area(l, a, lthres, athres)
agg_length_area(l, a, lthres, athres)
l |
a vector of lengths |
a |
a vector of areas |
lthres |
a minimum length that must be achieved |
athres |
a minimum length that must be achieved |
a vector of length(a) containing grouping indexes
Given a set of ideal catchment sizes, plus the minimum allowable catchment size and segment length, aggregate the network along mainstems.
aggregate_along_mainstems( network_list, ideal_size_sqkm, min_area_sqkm, min_length_km, verbose = TRUE, cache_file = NULL )
aggregate_along_mainstems( network_list, ideal_size_sqkm, min_area_sqkm, min_length_km, verbose = TRUE, cache_file = NULL )
network_list |
a list containing flowline and catchment 'sf' objects |
min_area_sqkm |
The minimum allowable size of the output hydrofabric catchments |
min_length_km |
The minimum allowable length of the output hydrofabric flowlines |
ideal_size |
The ideal size of output hydrofabric catchments |
term_cut |
cutoff integer to define terminal IDs |
a list containing aggregated and validated flowline and catchment 'sf' objects
Aggregates a catchment network according to a set of outlet.
aggregate_network_to_outlets( flowpath, outlets, da_thresh = NA, only_larger = FALSE, post_mortem_file = NA )
aggregate_network_to_outlets( flowpath, outlets, da_thresh = NA, only_larger = FALSE, post_mortem_file = NA )
flowpath |
sf data.frame Flowpaths with ID, toID, LevelPathID, and Hydroseq attributes. |
outlets |
data.frame with "ID" and "type" columns. "ID" must be identifiers from flowpath and divide data.frames. "type" should be "outlet", or "terminal". "outlet" will include the specified ID. "terminal" will be treated as a terminal node with nothing downstream. |
da_thresh |
numeric Defaults to NA. A threshold total drainage area in the units of the TotDASqKM field of the flowpath data.frame. When automatically adding confluences to make the network valid, tributary catchments under this threshold will be lumped with the larger tributaries rather than being added to the set of output catchments. |
only_larger |
boolean Defaults to TRUE. If TRUE when adding confluences to make the network valid, only tributaries larger than the one with an upstream outlet will be added. e.g. if a tributary is required in the model this will add main stems that the tributary contributes to. Note that the NHDPlus treats divergences as part of the main stem, so the da_thresh may still be needed to eliminate small tributary catchments introduced by divergences near confluences. |
post_mortem_file |
rda file to dump environment to in case of error |
This function operates on the catchment network as a node-edge graph. The outlet types are required to ensure that graph searches start from the appropriate nodes and includes the appropriate catchments. Outlets such as gages should be treated as "outlet" outlets. While it may be possible for the algorithm to determine terminal outlets, at this time, it is required that they be specified explicitely as "terminal" outlet types.
The function checks supplied outlets to make sure they connect downstream. Checks verify that the outlet of the levelpath (main stem of a total catchment) of each supplied outlet is in the supplied outlet set. If the outlet of a levelpath is not in the supplied set, it is added along with other catchments that contribute to the same receiving catchment. These checks ensure that all output catchments have one and only one input and output nexus and that all catchments are well-connected.
source(system.file("extdata", "walker_data.R", package = "nhdplusTools")) fline <- dplyr::right_join(dplyr::select(walker_flowline, COMID), nhdplusTools::prepare_nhdplus(walker_flowline, 0, 0, 0, FALSE)) fline <- dplyr::select(fline, ID = COMID, toID = toCOMID, LevelPathID = LevelPathI, Hydroseq) outlets <- data.frame(ID = c(5329357, 5329317, 5329365, 5329303, 5329435, 5329817), type = c("outlet", "outlet", "outlet", "terminal", "outlet", "outlet"), stringsAsFactors = FALSE) aggregated <- aggregate_network_to_outlets(fline, outlets) aggregated <- aggregate_network_to_outlets(fline, outlets) outlets <- dplyr::filter(fline, ID %in% outlets$ID) outlets <- nhdplusTools::get_node(outlets) plot(aggregated$fline_sets$geom, lwd = 3, col = "red") plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE) plot(outlets$geometry, add = TRUE)
source(system.file("extdata", "walker_data.R", package = "nhdplusTools")) fline <- dplyr::right_join(dplyr::select(walker_flowline, COMID), nhdplusTools::prepare_nhdplus(walker_flowline, 0, 0, 0, FALSE)) fline <- dplyr::select(fline, ID = COMID, toID = toCOMID, LevelPathID = LevelPathI, Hydroseq) outlets <- data.frame(ID = c(5329357, 5329317, 5329365, 5329303, 5329435, 5329817), type = c("outlet", "outlet", "outlet", "terminal", "outlet", "outlet"), stringsAsFactors = FALSE) aggregated <- aggregate_network_to_outlets(fline, outlets) aggregated <- aggregate_network_to_outlets(fline, outlets) outlets <- dplyr::filter(fline, ID %in% outlets$ID) outlets <- nhdplusTools::get_node(outlets) plot(aggregated$fline_sets$geom, lwd = 3, col = "red") plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE) plot(outlets$geometry, add = TRUE)
Aggregate Sets by Index Table
aggregate_sets(network_list, index_table)
aggregate_sets(network_list, index_table)
network_list |
a list of flowpaths and catchments |
index_table |
index table to aggregate with |
a list of catchments and flowpaths that have been validated
This function aggregates a network to a desired size distribution while enforcing minimum flowpath legnths and catchment areas. Additionally a set of explicit nexus locations can be provided over which the network cannot be aggregated (see poi_to_outlet)
aggregate_to_distribution( gpkg = NULL, vpu = NULL, flowpath = NULL, divide = NULL, crs = 5070, pois = NULL, ideal_size_sqkm = 10, min_length_km = 1, min_area_sqkm = 3, outfile = NULL, log = TRUE, overwrite = FALSE, cache = FALSE, verbose = TRUE )
aggregate_to_distribution( gpkg = NULL, vpu = NULL, flowpath = NULL, divide = NULL, crs = 5070, pois = NULL, ideal_size_sqkm = 10, min_length_km = 1, min_area_sqkm = 3, outfile = NULL, log = TRUE, overwrite = FALSE, cache = FALSE, verbose = TRUE )
gpkg |
a path to a gpkg |
flowpath |
If gpkg is NULL, then an sf data.frame, otherwise a the layer name. See details. |
divide |
If gpkg is NULL, then an sf data.frame, otherwise a the layer name. See details. |
ideal_size_sqkm |
The ideal size of catchments (default = 10 sqkm) |
min_length_km |
The minimum allowable length of flowpath features (default = 1 km) |
min_area_sqkm |
The minimum allowable area of catchment features (default = 3 sqkm) |
outfile |
of not NULL, where to write the output files |
log |
a filepath to write messages to or Boolean (TRUE = print to console; FALSE = no messages) |
overwrite |
overwrite existing gf file. Default is FALSE |
verbose |
print status updates. Default = TRUE |
outlets |
data.frame with mandatory "ID" column and optional "POI_ID" column. "ID" must be identifiers from flowpath and divide data.frames and POI ID must be unique. |
nexus_locations |
a data.frame with columns specifying the ID, and the nexus type. |
If gpkg is not NULL, divide and flowpath can be left NULL as well. The code attempts to infer the correct layers. The divides layer will be the one including the word "divide" or "catchment" and the flowpath layer will be the one including 'flowpath' or 'flowline'. If no layers, or more then one layer are deemed possible for each input, then the function will stop and ask for explicit names.
if outfile = TRUE, a file path, else a list object
Aggregates catchments according to a set of outlet catchments.
Network aggregation is completed using: See aggregate_network_to_outles
.
aggregate_to_outlets( gpkg = NULL, flowpath = NULL, divide = NULL, outlets = NULL, zero_order = NULL, coastal_cats = NULL, da_thresh = NA, only_larger = FALSE, post_mortem_file = NA, keep = NULL )
aggregate_to_outlets( gpkg = NULL, flowpath = NULL, divide = NULL, outlets = NULL, zero_order = NULL, coastal_cats = NULL, da_thresh = NA, only_larger = FALSE, post_mortem_file = NA, keep = NULL )
flowpath |
sf data.frame Flowpaths as generated by 'refactor_nhdplus' |
divide |
sf data.frame Reconciled catchment divides as generated by 'reconcile_catchment_divides' |
outlets |
data.frame with "ID" and "type" columns. "ID" must be identifiers from flowpath and divide data.frames. "type" should be "outlet", or "terminal". "outlet" will include the specified ID. "terminal" will be treated as a terminal node with nothing downstream. |
zero_order |
list of vectors containing IDs to be aggregated into 0-order catchments. |
coastal_cats |
sf data.frame with coastal catchments to be used with zero order. |
da_thresh |
numeric See |
only_larger |
boolean See |
post_mortem_file |
rda file to dump environment to in case of error |
keep |
logical passed along to |
See aggregate_network_to_outlets
source(system.file("extdata", "walker_data.R", package = "hydrofab")) outlets <- data.frame(ID = c(31, 3, 5, 1, 45, 92), type = c("outlet", "outlet", "outlet", "terminal", "outlet", "outlet"), stringsAsFactors = FALSE) aggregated <- aggregate_to_outlets(flowpath = walker_fline_rec, divide = walker_catchment_rec, outlets = outlets) plot(aggregated$cat_sets$geom, lwd = 3, border = "red") plot(walker_catchment_rec$geom, lwd = 1.5, border = "green", col = NA, add = TRUE) plot(walker_catchment$geom, lwd = 1, add = TRUE) plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE) plot(aggregated$cat_sets$geom, lwd = 3, border = "black") plot(aggregated$fline_sets$geom, lwd = 3, col = "red", add = TRUE) plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE)
source(system.file("extdata", "walker_data.R", package = "hydrofab")) outlets <- data.frame(ID = c(31, 3, 5, 1, 45, 92), type = c("outlet", "outlet", "outlet", "terminal", "outlet", "outlet"), stringsAsFactors = FALSE) aggregated <- aggregate_to_outlets(flowpath = walker_fline_rec, divide = walker_catchment_rec, outlets = outlets) plot(aggregated$cat_sets$geom, lwd = 3, border = "red") plot(walker_catchment_rec$geom, lwd = 1.5, border = "green", col = NA, add = TRUE) plot(walker_catchment$geom, lwd = 1, add = TRUE) plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE) plot(aggregated$cat_sets$geom, lwd = 3, border = "black") plot(aggregated$fline_sets$geom, lwd = 3, col = "red", add = TRUE) plot(walker_flowline$geom, lwd = .7, col = "blue", add = TRUE)
Append a hydrofabric style to a hydrofabric GeoPackage
append_style(gpkg_path, layer_names)
append_style(gpkg_path, layer_names)
gpkg_path |
Path to GeoPackage |
layer_names |
character vector of names to append styles for. These names must be in the package QML directory. |
Update Hydrofabric Identifiers For a given set of hydrofabric geopackages, update the ID and toID values to be globally unique.
assign_global_identifiers( gpkgs = NULL, outfiles = NULL, flowpath_layer = "flowpaths", divide_layer = "divides", network_layer = "network", overwrite = FALSE, term_add = 1e+09, modifications = NULL, verbose = TRUE )
assign_global_identifiers( gpkgs = NULL, outfiles = NULL, flowpath_layer = "flowpaths", divide_layer = "divides", network_layer = "network", overwrite = FALSE, term_add = 1e+09, modifications = NULL, verbose = TRUE )
gpkgs |
a vecotor of file.paths to that define the global network |
outfiles |
a vector of file.paths to write to |
flowpath_layer |
the layer name containing flowpaths |
divide_layer |
the layer name containing divides |
network_layer |
the name of layer containing the hydrologic network |
overwrite |
overwrite existing files? |
term_add |
value to be added to all terminal IDs |
verbose |
emit messages |
a data.frame
Index a Vector by Cumulative Sum
assign_id(x, athres)
assign_id(x, athres)
x |
a vector of values |
athres |
the ideal cumulative size of each group Cumulative sums will get as close to this value without exceeding it |
a vector of length(a)
Identifies small (pathlength or area) headwater catchments and returns a data.frame with the current ID and the feature ID it should collapse into (becomes). Headwaters are segments in which there are no inflows (!ID
build_collapse_table(network_list, min_area_sqkm = 3, min_length_km = 1)
build_collapse_table(network_list, min_area_sqkm = 3, min_length_km = 1)
network_list |
a list containing flowpath and catchment 'sf' objects |
min_area_sqkm |
The minimum allowable size of the output hydrofabric catchments |
min_length_km |
The minimum allowable length of the output hydrofabric flowlines |
a 2 column data.frame with id, becomes
Build a new ID table
build_new_id_table( meta, index, network_layer = "network", term_add = 1e+09, modifications = NULL )
build_new_id_table( meta, index, network_layer = "network", term_add = 1e+09, modifications = NULL )
network_layer |
the name of layer containing the hydrologic network |
gpkgs |
a row of network metadata built with 'network_metadata' |
flowpath_layer |
the layer name containing flowpaths |
divide_layer |
the layer name containing divides |
data.frame
Fixes geometry issues present in catchments derived from DEMs.
These include, but are not limited to disjoint polygon fragments, artifacts
from the DEM used to generate the catchments, and non-valid geometry topologies.
A secondary goal of this functions is to provide a way to reduce the data column
of the catchments by offering a topology preserving simplification
through ms_simplify
.
Generally a "keep" parameter of .9 seems appropriate for the resolution of
the data but can be modified in function
clean_geometry( catchments, flowlines = NULL, fl_ID = NULL, ID = "ID", keep = NULL, crs = 5070, grid = 9e-04, gb = 8, force = FALSE, sys = NULL )
clean_geometry( catchments, flowlines = NULL, fl_ID = NULL, ID = "ID", keep = NULL, crs = 5070, grid = 9e-04, gb = 8, force = FALSE, sys = NULL )
catchments |
catchments geometries to fix |
flowlines |
flowlines geometries to filter largest unit (optional) |
fl_ID |
flowlines unique identifier |
ID |
name of uniquely identifying column |
keep |
proportion of points to retain in geometry simplification
(0-1; default 0.05). See |
crs |
integer or object compatible with sf::st_crs coordinate reference. Should be a projection that supports area-calculations. |
gb |
The amount of heap memory to be allocated when force = TRUE |
force |
should the mapshaper/mapshaper-xl binaries be used directly for simplification? |
sys |
logical should the mapshaper system library be used. If NULL the system library will be used if available. |
sf object
Refactors the NHDPlus flowline network, eliminating short and non-confluence flowlines. The aim of this function is to create flowpaths that describe a network of catchments that combines complex hydrology near confluences into upstream catchments and removes very short flowlines along mainstem flow-paths.
collapse_flowlines( flines, thresh, add_category = FALSE, mainstem_thresh = NULL, exclude_cats = NULL, warn = TRUE )
collapse_flowlines( flines, thresh, add_category = FALSE, mainstem_thresh = NULL, exclude_cats = NULL, warn = TRUE )
flines |
data.frame with COMID, toCOMID, LENGTHKM, Hydroseq, and LevelPathI columns |
thresh |
numeric a length threshold (km). Flowlines shorter than this will be collapsed with up or downstream flowlines. |
add_category |
boolean if combination category is desired in output, set to TRUE |
mainstem_thresh |
numeric threshold for combining inter-confluence mainstems |
exclude_cats |
integer vector of COMIDs to be excluded from collapse modifications. |
warn |
boolean controls whether warning an status messages are printed |
A refactored network with merged up and down flowlines.
The refactor_nhdplus
function implements a complete
workflow using 'collapse_flowlines()'.
This function identifies small (pathlength or area) headwater catchments and collapses them into the existing network until none remain. Headwaters are those segments in which there are no inflows (!ID
collapse_headwaters( network_list, min_area_sqkm = 3, min_length_km = 1, verbose = TRUE, cache_file = NULL )
collapse_headwaters( network_list, min_area_sqkm = 3, min_length_km = 1, verbose = TRUE, cache_file = NULL )
network_list |
a list containing flowpath and catchment 'sf' objects |
min_area_sqkm |
The minimum allowable size of the output hydrofabric catchments |
min_length_km |
The minimum allowable length of the output hydrofabric flowlines |
verbose |
should messages be emitted? |
cache_file |
If not NULL results will be written to a provide path (.gpkg) |
a list containing flowpath and catchment 'sf' objects
This function takes a vector of areas and lengths and returns a index vector that combines them towards an ideal aggregate area (ideal_size_sqkm). While enforcing a minimum area (amin) and length (lmin). Additionally, this function can take a set of indexes to exclude over which the network cannot be aggregated.
cs_group(areas, lengths, exclude_dn, exclude_un, ideal_size_sqkm, amin, lmin)
cs_group(areas, lengths, exclude_dn, exclude_un, ideal_size_sqkm, amin, lmin)
areas |
a vector of areas |
lengths |
a vector of lengths |
exclude_dn |
a vector of equal length to areas and lengths. Any non NA value will be used to enforce an aggregation break on the outflow node of a flowpath |
exclude_un |
a vector of equal length to areas and lengths. Any non NA value will be used to enforce an aggregation break on the inflow node of a flowpath |
ideal_size_sqkm |
a vector of areas |
amin |
a threshold, or target, cumulative size |
lmin |
a threshold, or target, cumulative size |
a vector of length(areas) containing grouping indexes
Identify intersection types and downstream topology
define_touch_id(flowpaths, term_cut = 1e+09)
define_touch_id(flowpaths, term_cut = 1e+09)
flowpaths |
sf LINESTRING |
data.frame with id, type, touches, touches_toID columns
Describe Hydrofabric Describes a hydrofabric in terms of flowpath and catchment count. If they are unequal, FALSE is returned. If equal TRUE is returned. Messages can optionally be emitted.
describe_hydrofabric(network_list, verbose = TRUE)
describe_hydrofabric(network_list, verbose = TRUE)
network_list |
a list containing flowpaths and catchments |
verbose |
should messages be emitted? |
boolean condition
Download Elevation and Derivatives
download_elev(product, out_dir, regions = NULL)
download_elev(product, out_dir, regions = NULL)
product |
character DEM, hydroDEM, or FDRFAC. |
out_dir |
path to directory to store output. |
regions |
character vector of two digit hydrologic |
Download FDR FAC
download_fdr_fac(out_dir, regions = NULL)
download_fdr_fac(out_dir, regions = NULL)
out_dir |
path to directory to store output. |
regions |
character vector of two digit hydrologic |
Remove non-coincident Network Features Remove non-coincident flowlines and catchment pairs from a network list
drop_extra_features(network_list, verbose)
drop_extra_features(network_list, verbose)
network_list |
a list containing flowpaths and catchments |
verbose |
should message be emitted? |
a list containing flowpaths and catchments
Convert MULITLINESTINGS to LINESTRINGS
flowpaths_to_linestrings(flowpaths)
flowpaths_to_linestrings(flowpaths)
flowpaths |
a flowpath 'sf' object |
a 'sf' object
This function removes prefixes from specified columns in a data frame by extracting the numeric portion of the values after the last '-' character.
flush_prefix(input, col) flush_prefix(input, col)
flush_prefix(input, col) flush_prefix(input, col)
input |
A data frame containing the columns to be processed. |
col |
A character vector specifying the names of the columns from which to remove prefixes. |
- The function processes each specified column by removing the prefix up to and including the last '-' character using a regular expression. - The updated columns are converted to numeric values.
data object with updated column
The input data frame with the specified columns updated. The values in these columns are converted to numeric, retaining only the portion after the last '-' character.
Return RPU or VPU boundaries
get_boundaries(type = "vpu")
get_boundaries(type = "vpu")
type |
character. Either "RPU" or "VPU" |
An object of class "sf"
Given a set of outlets, will generate a minimal network by
calling aggregate_network_to_outlets
and adding nhdplus attributes to the result.
If geometry is included with the network, it will be merged and returned.
get_minimal_network(flowpath, outlets)
get_minimal_network(flowpath, outlets)
flowpath |
sf data.frame Flowpaths with ID, toID, LevelPathID, Hydroseq and LENGTHKM and AreaSqKM attributes. |
outlets |
data.frame with "ID" and "type" columns. "ID" must be identifiers from flowpath and divide data.frames. "type" should be "outlet", or "terminal". "outlet" will include the specified ID. "terminal" will be treated as a terminal node with nothing downstream. |
a data.frame (potentially including an sfc list column) with
attributes generated by add_plus_network_attributes
and a list column "set" containing members of each output flowpath.
source(system.file("extdata", "walker_data.R", package = "nhdplusTools")) fline <- walker_flowline outlets <- data.frame(ID = c(5329357, 5329317, 5329365, 5329435, 5329817), type = c("outlet", "outlet", "outlet", "outlet", "outlet")) #' Add toCOMID fline <- nhdplusTools::get_tocomid(fline, add = TRUE) # get attributes set fline <- dplyr::select(fline, ID = comid, toID = tocomid, LevelPathID = levelpathi, hydroseq = hydroseq, AreaSqKM = areasqkm, LENGTHKM = lengthkm) min_net <- get_minimal_network(fline, outlets) plot(sf::st_geometry(fline), col = "blue") plot(sf::st_geometry(min_net), lwd = 2, add = TRUE) plot(sf::st_geometry(nhdplusTools::get_node(min_net)), add = TRUE)
source(system.file("extdata", "walker_data.R", package = "nhdplusTools")) fline <- walker_flowline outlets <- data.frame(ID = c(5329357, 5329317, 5329365, 5329435, 5329817), type = c("outlet", "outlet", "outlet", "outlet", "outlet")) #' Add toCOMID fline <- nhdplusTools::get_tocomid(fline, add = TRUE) # get attributes set fline <- dplyr::select(fline, ID = comid, toID = tocomid, LevelPathID = levelpathi, hydroseq = hydroseq, AreaSqKM = areasqkm, LENGTHKM = lengthkm) min_net <- get_minimal_network(fline, outlets) plot(sf::st_geometry(fline), col = "blue") plot(sf::st_geometry(min_net), lwd = 2, add = TRUE) plot(sf::st_geometry(nhdplusTools::get_node(min_net)), add = TRUE)
Get Row and Column
get_row_col(fdr, start, fac_matrix)
get_row_col(fdr, start, fac_matrix)
fdr |
flow direction grid |
start |
matrix (row, col) |
fac_matrix |
flow accumulation matrix |
Extract nexus locations for Reference POIs
hl_to_outlet( gpkg, type = c("HUC12", "Gages", "TE", "NID", "WBIn", "WBOut"), verbose = TRUE )
hl_to_outlet( gpkg, type = c("HUC12", "Gages", "TE", "NID", "WBIn", "WBOut"), verbose = TRUE )
gpkg |
a reference hydrofabric gpkg |
type |
the type of desired POIs |
verbose |
should messages be emitted? |
data.frame with ID, type columns
Check if a geopackage and layer exists This function checks if a layer exists in a geopackage
layer_exists(gpkg, name)
layer_exists(gpkg, name)
gpkg |
path to geopackage |
name |
name of layer to check |
logical
Convert Refactor Output to HF gpkg This is a temporary function as changes get pushed upstream
make_hf_gpkg_from_refactor(gpkg)
make_hf_gpkg_from_refactor(gpkg)
gpkg |
gpkg file path |
file.path
Convert Reference Output to HF gpkg This is a temporary function as changes get pushed upstream
make_hf_gpkg_from_reference(gpkg)
make_hf_gpkg_from_reference(gpkg)
gpkg |
gpkg file path |
file.path
Convert Target Size Aggregate output to HF gpkg This is a temporary function as changes get pushed upstream
make_hf_gpkg_from_uniform_aggregate(gpkg)
make_hf_gpkg_from_uniform_aggregate(gpkg)
gpkg |
gpkg file path |
file.path
given reconciled flowlines and a set of source outlets, returns a set of outlets with reconciled IDs suitable for use with aggregate_catchments.
map_outlet_ids(source_outlets, reconciled)
map_outlet_ids(source_outlets, reconciled)
source_outlets |
data.frame with COMID and type columns |
reconciled |
data.frame as returned by refactor workflow |
Merges the interior values of a vector if they are less then the provided threshold. Merging will look "up" and "down" the vector and merge into the smaller of the two.
middle_massage(x, index_values, threshold)
middle_massage(x, index_values, threshold)
x |
vector of values |
index_values |
current index values |
threshold |
threshold to evaluate x |
a vector of length(x) containing grouping indexes
Capture Network Metadata This function assumes that files are names *_VPU.gpkg
network_metadata( gpkgs, flowpath_layer = "flowpaths", divide_layer = "divides", network_layer = "network" )
network_metadata( gpkgs, flowpath_layer = "flowpaths", divide_layer = "divides", network_layer = "network" )
gpkgs |
a vector of file.paths to attribute |
flowpath_layer |
the layer name containing flowpaths |
divide_layer |
the layer name containing divides |
network_layer |
the name of layer containing the hydrologic network |
data.frame
pack set
pack_set(x, y = "set")
pack_set(x, y = "set")
x |
data.frame containing "set" list column to be packed |
data.frame containing comma seperated character column
Re-index the edges of vector by threshold Merge the outside edges of a vector if they are less then the provides threshold.
pinch_sides(x, ind, thres)
pinch_sides(x, ind, thres)
x |
vector of values |
ind |
current index values |
thres |
threshold to evaluate x |
a vector of length(x) containing grouping indexes
Prep catchment with FDR/FAC
prep_cat_fdr_fac(cat, fdr, fac)
prep_cat_fdr_fac(cat, fdr, fac)
cat |
catchment (sf object) |
fdr |
flow direction grid |
fac |
flow accumulation grid |
Prep Split Events
prep_split_events(pois, fline, divides, threshold = 25)
prep_split_events(pois, fline, divides, threshold = 25)
pois |
a set of POIs with a poi_id, X and (in 5070) |
divides |
a set of divides geometries (EPSG:5070) |
flines |
a set of flowlines geometries (EPSG:5070) |
theshold |
a percentage (0-100) a POI must be upstream before splitting |
sf POINT object
Prepare Hydrologic Network
prepare_network(network_list)
prepare_network(network_list)
network_list |
a list with flowpath and catchment data |
This function adds an area, length, hydrosequence, streamorder and contributing drainage area metric to the flowpath list element of network_list.
tot_drainage_areasqkm can only be added when there are no NA areas
a list containing flowpath and catchment 'sf' objects
Read Catchments and Flowpaths from Geopackage Convenience function for reading two layers into a list
read_hydrofabric( gpkg = NULL, catchments = NULL, flowpaths = NULL, realization = "all", crs = NULL, verbose = Sys.getenv("hydrofab_verbose") != "false" )
read_hydrofabric( gpkg = NULL, catchments = NULL, flowpaths = NULL, realization = "all", crs = NULL, verbose = Sys.getenv("hydrofab_verbose") != "false" )
gpkg |
path to geopackage |
realization |
what layers to read? Options: "catchemnts", "flowpaths", "all" |
crs |
desired CRS, if NULL they stay as read. If all CRS layers arenot |
catchment_name |
name of catchment layer. If NULL, attempts to find divides layer |
flowpath_name |
name of flowpath layer. If NULL, attempts to find flowpath layer |
vebose |
should message be emitted? |
list
Reconciles catchment divides according to the output of
reconcile_collapsed_flowlines
and refactor_nhdplus
reconcile_catchment_divides( catchment, fline_ref, fline_rec, fdr = NULL, fac = NULL, para = 2, cache = NULL, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, vector_crs = 5070, fix_catchments = TRUE, keep = NULL )
reconcile_catchment_divides( catchment, fline_ref, fline_rec, fdr = NULL, fac = NULL, para = 2, cache = NULL, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, vector_crs = 5070, fix_catchments = TRUE, keep = NULL )
catchment |
sf data.frame NHDPlus Catchment or CatchmentSP layers for included COMIDs |
fline_ref |
sf data.frame flowlines as returned by
|
fline_rec |
sf data.frame flowpaths as returned by
|
fdr |
character path to D8 flow direction |
fac |
character path to flow accumulation |
para |
integer numer of cores to use for parallel execution |
cache |
path .rda to cache incremental outputs |
min_area_m |
minimum area in m^2 to filter out slivers (caution, use with care!!) |
snap_distance_m |
distance in meters to snap SpatRaster generated geometry to polygon geometry |
simplify_tolerance_m |
dTolerance in meters for simplification of grid-cell based polygons |
vector_crs |
integer or object compatible with sf::st_crs coordinate reference. Should be a projection that supports area-calculations. |
fix_catchments |
logical. should catchment geometries be rectified? |
keep |
Only applicable if fix_catchments = TRUE. Defines the proportion
of points to retain in geometry simplification (0-1; default 0.05).
See |
Note that all inputs must be passed in the same projection.
Catchment divides that have been split and collapsed according to input flowpaths
The refactor_nhdplus
function implements a complete
workflow using 'reconcile_collapsed_flowlines()' and can be used in prep
for this function.
Reconciles output of collapse_flowlines giving a unique ID to each new flowpath and providing a mapping to NHDPlus COMIDs.
reconcile_collapsed_flowlines(flines, geom = NULL, id = "COMID")
reconcile_collapsed_flowlines(flines, geom = NULL, id = "COMID")
flines |
data.frame with COMID, toCOMID, LENGTHKM, LevelPathI, Hydroseq, and TotDASqKM columns |
geom |
sf data.frame for flines |
id |
character id collumn name. |
reconciled flowpaths with new ID, toID, LevelPathID, and Hydroseq identifiers. Note that all the identifiers are new integer IDs. LevelPathID and Hydroseq are consistent with the LevelPathID and Hydroseq from the input NHDPlus flowlines.
The refactor_nhdplus
function implements a complete
workflow using 'reconcile_collapsed_flowlines()'.
A wrapper around refactor_nhdplus and reconcile_catchment_divides
refactor( gpkg = NULL, flowpaths = NULL, catchments = NULL, pois = NULL, avoid = NULL, split_flines_meters = 10000, collapse_flines_meters = 1000, collapse_flines_main_meters = 1000, threshold = 25, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, cores = 1, fac = NULL, fdr = NULL, purge_non_dendritic = TRUE, keep = NULL, outfile = NULL )
refactor( gpkg = NULL, flowpaths = NULL, catchments = NULL, pois = NULL, avoid = NULL, split_flines_meters = 10000, collapse_flines_meters = 1000, collapse_flines_main_meters = 1000, threshold = 25, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, cores = 1, fac = NULL, fdr = NULL, purge_non_dendritic = TRUE, keep = NULL, outfile = NULL )
gpkg |
a starting GPKG |
flowpaths |
Reference flowline features |
catchments |
Reference catchment features |
avoid |
integer vector of COMIDs to be excluded from collapse modifications. |
split_flines_meters |
numeric the maximum length flowpath desired in the output. |
collapse_flines_meters |
numeric the minimum length of inter-confluence flowpath desired in the output. |
collapse_flines_main_meters |
numeric the minimum length of between-confluence flowpaths. |
cores |
integer number of cores to use for parallel execution |
fac |
path to flow accumulation grid. If NULL (default) then catchments are NOT reconciled. |
fdr |
path to flow direction grid. If NULL (default) then catchments are NOT reconciled. |
keep |
proportion of points to retain in geometry simplification (0-1; default 0.05). See ms_simplify. If NULL, then no simplification will be executed. |
outfile |
path to geopackage to write refactored_flowlines, and if facfdr != NULL, refactored catchments. |
events |
data.frame containing events |
data to the specified gpkg
A complete network refactor workflow has been packaged into this function. Builds a set of normalized catchment-flowpaths from input flowline features. See details and vignettes for more information.
refactor_nhdplus( nhdplus_flines, split_flines_meters, split_flines_cores, collapse_flines_meters, collapse_flines_main_meters, out_refactored, out_reconciled, three_pass = FALSE, purge_non_dendritic = TRUE, exclude_cats = NULL, events = NULL, warn = TRUE )
refactor_nhdplus( nhdplus_flines, split_flines_meters, split_flines_cores, collapse_flines_meters, collapse_flines_main_meters, out_refactored, out_reconciled, three_pass = FALSE, purge_non_dendritic = TRUE, exclude_cats = NULL, events = NULL, warn = TRUE )
nhdplus_flines |
data.frame raw nhdplus flowline features as derived from the national seamless geodatabase. |
split_flines_meters |
numeric the maximum length flowpath desired in the output. |
split_flines_cores |
numeric the number of processing cores to use while splitting flowlines. |
collapse_flines_meters |
numeric the minimum length of inter-confluence flowpath desired in the output. |
collapse_flines_main_meters |
numeric the minimum length of between-confluence flowpaths. |
out_refactored |
character where to write a geopackage containing the split and collapsed flowlines. |
out_reconciled |
character where to write a geopackage containing the reconciled flowpaths. |
three_pass |
boolean whether to perform a three pass collapse or single pass. |
purge_non_dendritic |
boolean passed on to prepare_nhdplus |
exclude_cats |
integer vector of COMIDs to be excluded from collapse modifications. |
events |
data.frame containing events as generated by nhdplusTools::get_flowline_index() |
warn |
boolean controls whether warning an status messages are printed |
This is a convenient wrapper function that implements three phases
of the network refactor workflow: split, collapse, reconcile. See the
NHDPlus Refactor vignette for details of these three steps by running:
vignette("refactor_nhdplus", package = "hydrofab")
In addition to 'prepare_nhdplus' from the nhdplusTools package, The following three functions are used in the 'refactor_nhdplus' workflow.
source(system.file("extdata", "sample_flines.R", package = "nhdplusTools")) nhdplus_flowlines <- sf::st_zm(sample_flines) refactor_nhdplus(nhdplus_flines = nhdplus_flowlines, split_flines_meters = 2000, split_flines_cores = 2, collapse_flines_meters = 500, collapse_flines_main_meters = 500, out_refactored = "temp.gpkg", out_reconciled = "temp_rec.gpkg", three_pass = TRUE, purge_non_dendritic = FALSE, warn = FALSE) unlink("temp.gpkg") unlink("temp_rec.gpkg")
source(system.file("extdata", "sample_flines.R", package = "nhdplusTools")) nhdplus_flowlines <- sf::st_zm(sample_flines) refactor_nhdplus(nhdplus_flines = nhdplus_flowlines, split_flines_meters = 2000, split_flines_cores = 2, collapse_flines_meters = 500, collapse_flines_main_meters = 500, out_refactored = "temp.gpkg", out_reconciled = "temp_rec.gpkg", three_pass = TRUE, purge_non_dendritic = FALSE, warn = FALSE) unlink("temp.gpkg") unlink("temp_rec.gpkg")
RPU Boundaries Raster Processing Unit boundaries
rpu_boundaries
rpu_boundaries
An object of class "sf"
Return ScienceBase ID for hydrofabric This function checks if a layer exists in a geopackage
sb_id(type)
sb_id(type)
gpkg |
path to geopackage |
name |
name of layer to check |
character
A catchment-divide splitting algorithm that works with a D8 flow direction grid and the output of nhdplus_refactor. See Vignette for examples.
split_catchment_divide( catchment, fline, fdr, fac, lr = FALSE, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, vector_crs = NULL )
split_catchment_divide( catchment, fline, fdr, fac, lr = FALSE, min_area_m = 800, snap_distance_m = 100, simplify_tolerance_m = 40, vector_crs = NULL )
catchment |
sf data.frame with one catchment divide |
fline |
sf data.frame with one or more flowline segments in upstream downstream order. |
fdr |
character path to flow direction that fully covers the catchment |
fac |
character path to flow accumulation that fuller covers the catchment |
lr |
boolean should catchments be split along the left/right bank? |
min_area_m |
minimum area in m^2 to filter out slivers (caution, use with care!!) |
snap_distance_m |
distance in meters to snap SpatRaster generated geometry to polygon geometry |
simplify_tolerance_m |
dTolerance in meters for simplification of grid-cell based polygons |
vector_crs |
any object compatible with sf::st_crs. Used for vector-based calculations in case that fdr projection is not suitable (e.g. lon/lat) – must result in units of meters. |
Split catchment divides as an sfc geometry.
A wrapper for split_lines that works on nhdplus attributes
split_flowlines(flines, max_length = NULL, events = NULL, para = 0, avoid = NA)
split_flowlines(flines, max_length = NULL, events = NULL, para = 0, avoid = NA)
flines |
data.frame with COMID, toCOMID, LENGTHKM and LINESTRING sf column in "meters" projection |
max_length |
maximum segment length to return |
events |
data.frame containing events as generated by nhdplusTools::get_flowline_index() if an 'identifier' attribute is included, it will be passed through in the output table. |
para |
numeric how many threads to use in parallel computation |
avoid |
vector of ids to avoid |
All the flowlines with some split apart. COMIDs are returned as strings with a semantic part number appended. That is .1, .2, ... .10, .11, etc. are appended and must be treated as one would treat a semantic version. .1 is the most upstream and the sequence increases in the downstream direction.
The refactor_nhdplus
function implements a complete
workflow using 'split_flowlines()'.
source(system.file("extdata", "new_hope_data.R", package = "hydrofab")) new_hope_flowline <- dplyr::right_join(dplyr::select(new_hope_flowline, COMID, REACHCODE, FromMeas, ToMeas), suppressWarnings(nhdplusTools::prepare_nhdplus( new_hope_flowline, 0, 0, 0, FALSE, warn = FALSE)), by = "COMID") split <- split_flowlines(suppressWarnings(sf::st_cast(sf::st_transform( new_hope_flowline, 5070), "LINESTRING")), max_length = 2000, events = new_hope_events)
source(system.file("extdata", "new_hope_data.R", package = "hydrofab")) new_hope_flowline <- dplyr::right_join(dplyr::select(new_hope_flowline, COMID, REACHCODE, FromMeas, ToMeas), suppressWarnings(nhdplusTools::prepare_nhdplus( new_hope_flowline, 0, 0, 0, FALSE, warn = FALSE)), by = "COMID") split <- split_flowlines(suppressWarnings(sf::st_cast(sf::st_transform( new_hope_flowline, 5070), "LINESTRING")), max_length = 2000, events = new_hope_events)
Rename simple features layer
st_rename(dsn, layer, new_layer)
st_rename(dsn, layer, new_layer)
dsn |
data source name. Interpretation varies by driver: can be
a filename, a folder, a database name, or a Database Connection
(we officially test support for
|
layer |
layer name. Varies by driver, may be a file name without
extension; for database connection, it is the name of the table. If layer
is missing, the |
new_layer |
new layer name |
dsn
Trace Upstream
trace_upstream(start_point, cat, fdr, fac_matrix, fdr_matrix)
trace_upstream(start_point, cat, fdr, fac_matrix, fdr_matrix)
start_point |
row col index |
cat |
catchment |
fdr |
flow direction grid |
fac_matrix |
flow accumulation matrix |
fdr_matrix |
flow direction matrix |
sfc
Wayyyy faster then either data.table, or sf based line merging
union_linestrings(lines, ID)
union_linestrings(lines, ID)
lines |
lines to merge |
ID |
ID to merge over |
an sf object
Wayyyy faster then either data.table, or sf based line merging
union_linestrings_geos(lines, ID)
union_linestrings_geos(lines, ID)
lines |
lines to merge |
ID |
ID to merge over |
an sf object
This is significantly faster then sf::st_union or summarize
union_polygons(poly, ID)
union_polygons(poly, ID)
poly |
sf POLYGON object |
ID |
the column name over which to union geometries |
sf object
unpack set
unpack_set(x, y = "set")
unpack_set(x, y = "set")
x |
data.frame containing comma separated "set" column to be unpacked |
data.frame containing a list column
Update Network Identifiers Given a data.frame of sf object, the id and toid values are undated based on a provided lookup table (produced with build_new_id_table), and a vpu_topo list if there are cross VPU flows. In the vpu_topo is NULL or has 0 rows, no vpu correction is applied.
update_network_identifiers(x, lookup, term_add = 1e+09, connections = NULL)
update_network_identifiers(x, lookup, term_add = 1e+09, connections = NULL)
x |
a data.frame or sf object with id and/or toid columns |
lookup |
a lookup table of new ID values |
vpu_topo |
a VPU lookup correction table |
data.frame
VPU Boundaries Vector Processing Unit boundaries
vpu_boundaries
vpu_boundaries
An object of class "sf"
Write a hydrofabric gpkg A hydrofabric consists of a flowpath, catchment, and topology layer written to a self contained geopackage
write_hydrofabric(network_list, outfile, verbose = TRUE, enforce_dm = TRUE)
write_hydrofabric(network_list, outfile, verbose = TRUE, enforce_dm = TRUE)
network_list |
a list containing flowpaths and catchments |
outfile |
a file (gpkg) where layers should be written |
verbose |
should messages be emitted? |
catchment_name |
the layer name for divides |
flowpath_name |
the layer name for flowpaths |
file path