Assemble an SSN object from an LSN — ssn

Create an SSN (spatial stream network) object from a Landscape Network (LSN).

ssn_assemble(
  edges,
  lsn_path = NULL,
  obs_sites = NULL,
  preds_list = NULL,
  ssn_path,
  import = TRUE,
  check = TRUE,
  afv_col = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

edges: An sf object with LINESTING geometry created using lines_to_lsn (see Details).
lsn_path: Local pathname to a directory in character format specifying where relationships.csv resides, which is created using link{lines_to_lsn}.
obs_sites: Optional. A single sf object with POINT geometry created using link{sites_to_lsn} that represents the observation locations (i.e. where data were collected). Default = NULL (see Details).
preds_list: Optional. A list of one or more sf objects representing prediction sites.
ssn_path: Pathname to an output directory where output files will be stored. A .ssn extension will be added if it is not included.
import: Logical indicating whether the output files should be returned as an SSN object. Defaults to TRUE.
check: Logical indicating whether the validity of the SSN should be checked using [ssn_check] when both import = TRUE and verbose = TRUE. Default = TRUE.
afv_col: Character vector containing the names of the additive function value columns that will be checked when check = TRUE. Columns must be present in edges, obs_sites and preds_list, if all are included. Default is NULL.
overwrite: Logical. If TRUE and ssn_path already exists, the contents of ssn_path will be overwritten. Defaults to FALSE.
verbose: Logical. Indicates whether messages about the function progress and object validity check (when check = TRUE should be printed to the console. Defaults to TRUE.

Value

The components of an SSN object are written to ssn_path (see Details). When import = TRUE, the function also returns an object of class SSN. If check = TRUE and verbose = TRUE, the validity of the returned SSN

object is checked using [ssn_check] and results are printed to the console.

Details

The SSNbler package is used to generate the spatial, topological, and attribute information needed to fit spatial stream-network models using the 'SSN2' package. The ssn_assemble function will often be the final step in the 'SSNbler' data-processing workflow and it is important that the previous processing steps have been followed. Prior to running ssn_assemble, the edges must be processed using link{lines_to_lsn}, link{updist_edges}, and link{afv_edges}. The obs_sites and prediction site datasets in preds_list must be processed with link{sites_to_lsn}, link{updist_sites}, and link{afv_sites}. In addition, the edges, obs_sites, and all of the sf objects in preds_list must be part of the same LSN.

The obs_sites and preds_list are optional arguments, with the Default = NULL. If obs_sites = NULL, an SSN object will be returned with NA stored in ssn.object$obs and a warning returned that ssn.object$obs is required for fitting spatial statistical models in 'SSN2'.

ssn_assemble stores the output locally in ssn_path. If ssn_path does not include the .ssn extension, it is added before the new directory is created. This directory contains:

edges.gpkg: edges in GeoPackage format. A new network identifier, netID, is added that is unique to each subnetwork.
sites.gpkg: observed sites in GeoPackage format (if present). Three new ID columns are added that are unique to the measurement (pid), the location (locID), and the network (netID).
prediction datasets in GeoPackage format (if present). The prediction sites also contain pid, locID, and netID. The naming convention is taken from the names provided in preds_list.
netID.dat files for each distinct network, which store the binaryID values for line segments in edges.

A more detailed description of the .ssn directory and its contents is provided in Peterson and Ver Hoef (2014).

Examples

# Get temporary directory, where the example LSN will be stored
# locally.
temp_dir <- tempdir()
# Build the LSN. When working with your own data, lsn_path will be
# a local folder of your choice rather than a temporary directory.
edges<- lines_to_lsn(
   streams = MF_streams,
   lsn_path = temp_dir,
   snap_tolerance = 1,
   check_topology = FALSE,
   overwrite = TRUE,
   verbose = FALSE
)

# Incorporate observed sites, MF_obs, into LSN
obs<- sites_to_lsn(
   sites = MF_obs,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 100,
   overwrite = TRUE,
   verbose = FALSE
)

# Incorporate prediction dataset, MF_preds, into LSN
preds<- sites_to_lsn(sites = MF_preds,
   edges = edges,
   save_local = FALSE,
   snap_tolerance = 1,
   overwrite = TRUE,
   verbose = FALSE
)

# Calculate the AFV for the edges using
# a column representing watershed area (h2oAreaKm2).
edges<- afv_edges(
   edges=edges,
   infl_col = "h2oAreaKm2",
   segpi_col = "areaPI",
   lsn_path = temp_dir,
   afv_col = "afvArea",
   overwrite = TRUE,
   save_local = FALSE
)

# Calculate the AFV for observed sites (obs) and prediction
# dataset, preds.
site.list<- afv_sites(
   sites = list(obs = obs,
                preds = preds),
   edges=edges,
   afv_col = "afvArea",
   save_local = FALSE,
   overwrite = TRUE
)

# Calculate upstream distance for edges
edges<- updist_edges(
   edges = edges,
   lsn_path = temp_dir,
   calc_length = TRUE,
   length_col = "Length",
   overwrite = TRUE,
   save_local = FALSE,
   verbose = FALSE
)

# Calculate upstream distance for observed sites (obs) and one
# prediction dataset (preds)
site.list<- updist_sites(
   sites = site.list,
   edges = edges,
   length_col= "Length",
   lsn_path = temp_dir,
   save_local = FALSE,
   overwrite = TRUE
)

# Assemble SSN object
ssn.obj<- ssn_assemble(
   edges = edges,
   lsn_path = temp_dir,
   obs_sites = site.list[["obs"]],
   preds_list = site.list[c("preds")],
   ssn_path = paste0(temp_dir, "/example.ssn"),
   import = TRUE,
   overwrite = TRUE
)
#> 
#> Checking inputs
#> 
#> C:\Users\mdumelle\AppData\Local\Temp\RtmpUFiNJq/example.ssn created.
#> 
#> Creating binaryID.db
#> Adding NetID and netgeom to edges 
#> 
#> pid, locID, netID, and netgeom added to ...
#> 
#> obs_sites
#> 
#> preds
#> 
#> Saving files to C:\Users\mdumelle\AppData\Local\Temp\RtmpUFiNJq/example.ssn
#> 
#> Creating SSN object
#> 
#> Checking the SSN object
#> 
#> 
#> SSN object is valid: TRUE

# Summarise SSN object
summary(ssn.obj)
#> Object of class SSN
#> 
#> Object includes observations on 26 variables across 45 sites within the bounding box
#>     xmin     ymin     xmax     ymax 
#> -1531385  2521181 -1498448  2540274 
#> 
#> Object also includes 1 set of prediction points with 43 locations
#> 
#> Variable names are (found using ssn_names(object)):
#> $obs
#>  [1] "rid"        "pid"        "STREAMNAME" "COMID"      "AREAWTMAP" 
#>  [6] "SLOPE"      "ELEV_DEM"   "Source"     "Summer_mn"  "MaxOver20" 
#> [11] "C16"        "C20"        "C24"        "FlowCMS"    "AirMEANc"  
#> [16] "AirMWMTc"   "rcaAreaKm2" "h2oAreaKm2" "ratio"      "snapdist"  
#> [21] "afvArea"    "upDist"     "locID"      "netID"      "geometry"  
#> [26] "netgeom"   
#> 
#> $preds
#>  [1] "rid"        "pid"        "COMID"      "AREAWTMAP"  "SLOPE"     
#>  [6] "ELEV_DEM"   "FlowCMS"    "AirMEANc"   "AirMWMTc"   "rcaAreaKm2"
#> [11] "h2oAreaKm2" "ratio"      "snapdist"   "afvArea"    "upDist"    
#> [16] "locID"      "netID"      "geometry"   "netgeom"   
#>