Import SSN object

Source: R/ssn_import.R

This function reads spatial data from a .ssn folder and creates an SSN object.

ssn_import(path, include_obs = TRUE, predpts = NULL, overwrite = FALSE)

Arguments

path

Filepath to the .ssn directory. See details.

include_obs

default = TRUE. Logical indicating whether observed sites should be included in the SSN object.

predpts

Vector of prediction site dataset names found within the .ssn folder. See details.

overwrite

default = FALSE. If TRUE, overwrite existing binaryID.db files and netgeom column(s) if it exists in the edges, observed sites (if include_obs = TRUE), and prediction site datasets (if they exist).

Value

ssn_import returns an object of class SSN, which is a list with four elements containing:

  • edges: An sf data.frame containing the stream network, with an additional 'netgeom' column.

  • obs: An sf data.frame containing observed site locations, with an additional 'netgeom' column. NA if include_obs = FALSE.

  • preds: A list of sf data.frames containing prediction site locations. An empty list is returned if predpts is not provided.

  • path: The local filepath for the .ssn directory associated with the SSN object.

Details

The ssn_import function imports spatial data (shapefile or GeoPackage format) from a .ssn folder generated using the SSNbler package function SSNbler::lsn_to_ssn. The .ssn folder contains all of the spatial, topological and attribute data needed to fit a spatial statistical stream network model to streams data. This includes:

  • An edges dataset with LINESTRING geometry representing the stream network.

  • A sites dataset with POINT geometry where observed data were collected on the stream network.

  • Prediction sites dataset(s) representing locations where predictions will be made.

  • netID.dat file(s) for each distinct network, which stores the topological relationships of the line features in edges.

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

The ssn_import imports the edges, observed sites (optional), and prediction sites (optional) as sf data.frame objects. A new column named 'netgeom' is created to store important data representing topological relationships in a spatial stream network model. These data are stored in character format, which is less likely to be inadvertantly changed by users. See create_netgeom for a more detailed description of the format and contents of 'netgeom'.

The information contained in the netID text files is imported into an SQLite database, binaryID.db, which is stored in the .ssn directory. This information is used internally by ssn_create_distmat, ssn_lm and ssn_glm to calculate the data necessary to fit a spatial statistical model to stream network data. If overwrite = TRUE (overwrite = FALSE is the default) and a binaryID.db file already exists within the .ssn directory, it will be overwriten when the SSN object is created.

At a minimum, an SSN object must always contain streams, which are referred to as edges. The SSN object would also typically contain a set of observed sites, where measurements have been collected. Only one observed dataset is permitted in an SSN object. When include_obs=FALSE, an SSN object is created without observations. This option provides flexibility for users who would like to simulate data on a set of artifical sites on an existing stream network. Note that observation sites must be included in the SSN object in order to fit models using ssn_lm or ssn_glm. The SSN object may contain multiple sets of prediction points (or none), which are stored as separate datasets in the .ssn directory. If predpts is a named vector, the names of the preds list in the SSN object correspond to the vector names. Otherwise, they are set to the basename of the prediction site dataset file(s) specified in predpts. The ssn_import_predpts function allows users to import additional sets of prediction sites to a an existing SSN object.

References

Peterson, E., and Ver Hoef, J.M. (2014) STARS: An ArcGIS toolset used to calculate the spatial information needed to fit spatial statistical stream network models to stream network data. Journal of Statistical Software 56(2), 1--17.

Examples

## Create local temporary copy of MiddleFork04.ssn found in
# SSN2/lsndata folder. Only necessary for this example.
copy_lsn_to_temp()

## Import SSN object with no prediction sites
mf04 <- ssn_import(paste0(tempdir(), "/MiddleFork04.ssn"),
  overwrite = TRUE
)

## Import SSN object with 3 sets of prediction sites
mf04p <- ssn_import(paste0(tempdir(), "/MiddleFork04.ssn"),
  predpts = c(
    "pred1km",
    "CapeHorn"
  ),
  overwrite = TRUE
)