knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
sos4R
includes a collection of convenience functions which wrap the complex SOS interface with its specific terms (e.g. FOI, procedure).
The wrapper function use more generic terms easily accessible for all users, especially without a strong knowledge of the OGC standards of the Sensor Web Enablement (see "OGC SWE and SOS" vignette for details).
In general, these functions always return an object of class data.frame
, even if the result is only a list, in which case the data.frame
has one column.
library("sos4R") mySos <- SOS(url = "https://climate-sos.niwa.co.nz/", binding = "KVP", useDCPs = FALSE, version = "2.0.0") maxOutputRowsPerExample <- 5 maxOutputColumnsPerExample <- 3
A minimal Shiny app demonstrating the convenience functions is included in the package. Run it with
shiny::runApp(appDir = file.path(path.package("sos4R"), "shiny"))
The function phenomena(..)
provides information about observed phenomena, time periods of data, and sites observing these phenomena.
phenomena <- phenomena(sos = mySos) str(phenomena)
phenomena[1:maxOutputRowsPerExample,]
The retrieved data can be extended to the time intervals and site identifier for which data is available. The next example shows the overall temporal availability of the phenomena in the SOS instance:
phenomena(sos = mySos, includeTemporalBBox = TRUE)[1:maxOutputRowsPerExample,]
This example shows at which site the phenomena are available:
phenomena(sos = mySos, includeSiteId = TRUE)[1:maxOutputRowsPerExample,]
You can also add both temporal extent and sites:
phenomena(sos = mySos, includeTemporalBBox = TRUE, includeSiteId = TRUE)[1:maxOutputRowsPerExample,]
The function sites(..)
provides information about sites where observations are performed, including metadata about the sites (e.g. location).
The returned object is a SpatialPointsDataFrame
.
sites <- sites(sos = mySos) sites[1:maxOutputRowsPerExample,]
To see all sites, even the ones without any data, use the empty
parameter.
sites_with_empty <- sites(sos = mySos, empty = TRUE) sites_with_empty[1:maxOutputRowsPerExample,]
You can retrieve additional metadata about the phenomena and the time period for which data is available.
Including temporal extent implies inclusion of phenomena.
In the next chunks the object is coerced to a date.frame
to get a tabular view.
sites_with_phenomena <- sites(sos = mySos, includePhenomena = TRUE) sites_with_phenomena[1:maxOutputRowsPerExample, 1:maxOutputColumnsPerExample]
The next section show how to retrieve spatial information about the sites and temporal information about the available phenomena:
sites_with_temporal_bbox <- sites(sos = mySos, includePhenomena = TRUE, includeTemporalBBox = TRUE) tail(sites_with_temporal_bbox, n = 3)[,1:maxOutputColumnsPerExample]
The following chunk shows how to get a better representation:
str(tail(sites_with_temporal_bbox, n = 3)[,1:maxOutputColumnsPerExample])
You can filter sites using phenomena and temporal extent.
Note: When creating time objects from strings, as.POSIXct(..)
by default recognises the local timezone and creates a time object in UTC.
sites_filtered_by_phenomena <- sites(sos = mySos, phenomena = phenomena[3,]) nrow(sites_filtered_by_phenomena@data) str(sites_filtered_by_phenomena)
Use the parameter includeTemporalBBox
for including additional metadata:
sites_filtered_by_phenomena_with_metadata <- sites(sos = mySos, phenomena = phenomena[3,], includePhenomena = TRUE, includeTemporalBBox = TRUE) str(sites_filtered_by_phenomena_with_metadata)
# under development - no github issue atm #sites_filtered_by_time <- sites(sos = mySos, begin = parsedate::parse_iso_8601("1904-01-01"), end = parsedate::parse_iso_8601("1905-12-31")) #nrow(sites_filtered_by_time@data) #str(sites_filtered_by_time)
The SpatialPointsDataFrame
allows access to coordinates with coordinate reference system (CRS).
sp::coordinates(sites)[1:maxOutputRowsPerExample,]
sites@proj4string
sp::bbox(sites)
This object can be directly used as input for various mapping libraries, e.g. mapview
.
suppressPackageStartupMessages(library("mapview")) mapview(sites, legend = FALSE, col.regions = "blue")
The function siteList(..)
provides information about observed phenomena at sites and the time periods when data is available.
siteList <- siteList(sos = mySos) str(siteList)
You can extend the information returned with these parameters:
empty
to also show sites without dataincludePhenomena
to add phenomena to the table (boolean)includeTemporalBBox
to also show the time when data is available (boolean)siteList_with_empty <- siteList(sos = mySos, empty = TRUE) siteList_with_empty[1:maxOutputRowsPerExample,]
# under development - https://github.com/52North/sos4R/issues/90 #siteListe_with_metadata <- siteList(sos = mySos, includePhenomena = TRUE, includeTemporalBBox = TRUE) #siteListe_with_metadata[1:maxOutputRowsPerExample,]
You can filter the results with these parameters:
phenomena
is a vector of phenomena which must be measured at the sitesbegin
and end
define a time interval (date and time class objects) for which some data must be available (sites may have data outside the given interval)Note: When creating time objects from strings, as.POSIXct(..)
by default recognises the local timezone and creates a time object in UTC.
siteList_filtered_by_time_and_phenomenon <- siteList(sos = mySos, phenomena = phenomena$phenomenon[1:2], begin = as.POSIXct("1950-01-01"), end = as.POSIXct("1960-12-31") ) siteList_filtered_by_time_and_phenomenon
The function getData(..)
retrieves the actual data and returns them in ready-to-use data structures from the spacetime
package.
The returned data can be limited by thematical, spatial, and temporal filters. Thematical filtering (phenomena) support the values of the previous functions as inputs. Spatial filters are either sites, or a bounding box. Temporal filter is a time period during which observations are made.
Note: When creating time objects from strings, as.POSIXct(..)
by default recognises the local timezone and creates a time object in UTC.
observationData <- getData(sos = mySos, phenomena = phenomena[18,1], sites = siteList[1,1], begin = parsedate::parse_iso_8601("1970-01-01T12:00:00+12:00"), end = parsedate::parse_iso_8601("2000-01-02T12:00:00+12:00") ) str(observationData)
Get an overview of the data using the summary
function:
summary(observationData)
Plot received data as time series:
suppressPackageStartupMessages(library(xts)) ts1056 <- xts(observationData[observationData$siteID == '1056',3], observationData[observationData$siteID == '1056',"timestamp"]) names(ts1056) <- "#1056" plot(x = ts1056, main = "Monthly: Extreme max. Temp. (°C)", yaxis.right = FALSE, legend.loc = 'topleft')
The next example gets data for two phenomena a site.
# TO BE IMPLEMENTED: merge different observation types - see https://github.com/52North/sos4R/issues/96#issuecomment-493424151 observationData <- getData(sos = mySos, phenomena = phenomena$phenomenon[1:2], sites = siteList$siteID[c(1,58)], begin = parsedate::parse_iso_8601("1994-12-31T12:00:00+12:00"), end = parsedate::parse_iso_8601("1995-12-31T12:00:00+12:00") ) str(observationData)
You can also retrieve data for phenomena from multiple sites.
multipleSites <- siteList$siteID[1:2] observationData <- getData(sos = mySos, phenomena = phenomena[18, 1], sites = multipleSites, begin = parsedate::parse_iso_8601("1997-01-01T12:00:00+12:00"), end = parsedate::parse_iso_8601("2000-01-02T12:00:00+12:00") ) ts1056 <- xts(observationData[observationData$siteID == '1056', 3], observationData[observationData$siteID == '1056',"timestamp"]) names(ts1056) <- "Station#1056" ts11234 <- xts(observationData[observationData$siteID == '11234', 3], observationData[observationData$siteID == '11234',"timestamp"]) names(ts11234) <- "Station#11234" plot(x = na.fill(merge(ts1056, ts11234), list(NA, "extend", NA)), main = "Monthly: Extreme max. Temp. (°C)", yaxis.right = FALSE, legend.loc = 'topleft')
Map of the according sites:
sites_of_timeseries <- sites[sites$siteID == "1056" | sites$siteID == "11234",] mapview(sites_of_timeseries, legend = FALSE, col.regions = "blue")
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.