sensorweby

A JavaScript sensor web client with graphs and analytics powered by Shiny. sensorweby is an R extension package building on Shiny and the 52°North JavaScript SOS client.

Installation

The sensorweby package and the required package sensorweb4R are not on CRAN yet, so please download and install the package manually. The first option is using the package devtools, which also works well for your own fork or development versions by other contributors.

devtools::install_github("52North/sensorweb4R")
devtools::install_github("52North/sensorweby")

Alternatively, you can download the source code and install the package from source. For this to work must have both git and R (see documentation here for Windows) on your path. Then run the following commands:

git clone https://github.com/52North/sensorweby
R CMD INSTALL sensorweby

Running

A sensorweby app is very similar to a standard shiny app. So refer to their extensive documentation. This package adds new UI builder functions to generate the JavaScript SensorWebClient UI and a analysis page therein (see ?swcPage, ?swcLeftPanel, ?swcRightPanel and ?swcFullPanel).

It also adds new inputs to obtain the session state, namely the currently selected time interval and timeseries of the JavaScript client (see ?swcTimeseriesInput, ?swcIntervalInput, ?swcTimeBeginInput and ?swcTimeEndInput).

Using these functions you easily can enhance the JavaScript client using the analytical power of R.

Example

This ui.R creates the complete client and adds a Analytics page. This page contains a single plotOutput and two sensorweby inputs:

library(shiny)
library(sensorweby)

shinyUI(
    swcPage(
        caption = c(en = "Time Plot"),
        title = "Sensorweby",
        swcIntervalInput("time"),
        swcTimeseriesInput("series"),
        swcFullPanel(plotOutput("plot", width="100%", height="100%"))
    )
)

The accompanying server.R takes the two reactive inputs and creates the plot output using sensorweb4R to request and openair to plot the data:

library(sensorweby)
library(sensorweb4R)
library(openair)
library(lubridate)

shinyServer(function(input, output, session) {
    output$plot <- renderPlot({

        validate(
            need(length(input$series) > 0, 'No Timeseries selected'),
            need(input$time, "No timespan selected")
        )
        data <- getData(input$series, timespan = input$time)
        times <- unique(sort(do.call(c, lapply(data, time))))
        values <- lapply(data, function(x) value(x)[match(times, time(x))])
        names(values) <- id(input$series)
        values$date <- times
        df <- as.data.frame(values)

        validate(need(dim(df)[1] > 0, "No data available"))

        timePlot(df, pollutant = id(input$series),
                 name.pol = label(input$series),
                 plot.type = "h", smooth = TRUE,
                 ci = TRUE, ylab=c())
    })
})

To close the client interrupt R, usually by hitting Esc or Ctrl + C.

For more information about running Shiny apps on the server see the Shiny documentation.

User Documentation

The package provides examples and you can build the function reference. The package does not provide demos or a Vignette (yet).

Examples

The package ships with various example applications. To run an example, install and load the package (see above), then execute one of the following calls to run the respective example. There might be more examples as subdirectories in inst/examples, just give them a try by running sensorweby::runExample("<name of the subdirectory>").

Basic

A simple example of a plot generated by R. This example does not integrate with the map and chart view in any way. To view the plot click on the "Analysis" button in the top right menu. Then you can select one of the available pollutants in a drop down menu on the righ hand side.

sensorweby::runExample("basic")

Pollution Plot

Example for a wind rose pollution plot powered by openair. Select an station which provides wind data on the map, then switch to the analysis page to see a wind rose/pollution rose.

sensorweby::runExample("pollutionPlot")

Advanced Timeseries Plot

Plot the currently select time series with an advanced plotting function from the package openair (openair::timePlot). Select any phenomenon and time series from the map and specify the time span of interest. Then click on the "Analysis" button to see the same data plotted by R.

sensorweby::runExample("timePlot")

Reference manual

When installed from source or GitHub, run the command Rd2pdf on the regular command line from the parent directory of the package. This will create the reference manual, which describes all functions in the package:

R CMD Rd2pdf sensorweby

Configuration

The JavaScript client can be configured by placing a www/settings.json file inside the app directory. For configuration options refer to the documentation of the client.

Logging

To change the logging threshold prepend this to your server.R:

flog.threshold(DEBUG)

To redirect the logging output to a file prepend this to your server.R:

flog.appender(appender.file("/var/log/shiny-server/sensorweby.log"))

Input Functions

Begin Time Input

swcTimeBeginInput adds a new reactive input that contains the currently selected start time (as a POSIXct) of the JavaScript SensorWebClient. Returns a HTML input tag.

Parameter	Description
id	the id of the input

Example

swcTimeBeginInput('begin')

End Time Input

swcTimeEndInput adds a new reactive input that contains the currently selected end time (as a POSIXct) of the JavaScript SensorWebClient. Returns a HTML input tag.

Parameter	Description
id	the id of the input

Example

swcTimeEndInput('end')

Time Interval Input

swcIntervalInput adds a new reactive input that contains the currently selected timespan (as a lubridate::interval) of the JavaScript SensorWebClient. Returns a HTML input tag.

Parameter	Description
id	the id of the input

Example

swcIntervalInput('time')

Timeseries Input

swcTimeseriesInput adds a new reactive input that contains the currently selected time series of the JavaScript SensorWebClient (as a sensorweb4R::Timeseries. Returns a HTML input tag.

Parameter	Description
id	the id of the input

Example

swcTimeseriesInput('series')

Interface Builder Functions

I18N Definition

swcI18N adds a new I18N value to the JavaScript SensorWebClient. Returns a HTML script tag setting the value.

Parameter	Description
lang	the language identifier
key	the message key
value	the message value

Example

swcI18N('eng', 'button_label', 'OK')

Left Panel Definition

swcLeftPanel creates the left panel of the analysis view of the JavaScript SensorWebClient. Returns a HTML div tag for the left panel.

Parameter	Description
...	inherited from shiny::tags$div

Example

swcLeftPanel(
    plotOutput("output", width="100%", height="100%")
)

Right Panel Definition

swcLeftPanel creates the right panel of the analysis view of the JavaScript SensorWebClient. Returns a HTML div tag for the right panel.

Parameter	Description
header	the header of the right panel
...	inherited from shiny::tags$div

Example

swcRightPanel(
    header="Parameters",
    selectInput(
        "pollutant",
        label="Pollutant",
        choices = c("NOX", "NO2", "O3", "PM10", "SO2", "CO", "PM25"),
        selected = "NOX"
    ),
    swcTimeBeginInput("begin"),
    swcTimeEndInput("end"),
    swcTimeseriesInput("series")
)

Full Panel Definition

swcFullPanel creates a panel spanning the complete analysis view of the JavaScript SensorWebClient. Returns a HTML div tag for the panel.

Parameter	Description
...	inherited from shiny::tags$div

Example

swcFullPanel(
    plotOutput("output", width="100%", height="100%")
)

JavaScript SensorWebClient Page Definition

swcPage creates a new page containing the JavaScript SensorWebClient. Returns a HTML html tag containing the client.

Parameter	Description
title	the title of the page
author	the HTML meta tag author
description	the HTML meta tag description
debug	indicates if the client should be run in debug mode
...	inherited from shiny::tags$div

Example

swcPage(
    swcLeftPanel(...),
    swcRightPanel(...)
)

Developer Documentation

Change and test code

require(devtools)

# do your developments...

# install the package or build & reload in RStudio
devtools::install() # when workdir is directory /sensorweby

# load the package
require(sensorweby)

# test...

Updating the JavaScript Sensor Web Client

To install the latest tag of the 52°North JavaScript Sensor Web Client just run:

#require("devtools")
#devtools::install_github('cscheid/rgithub')
#require("github")

# http://stackoverflow.com/questions/15347233/ssl-certificate-failed-for-twitter-in-r
# Set SSL certs globally
#options(RCurlOptions = list(cainfo = system.file("CurlSSL", "cacert.pem", package = "RCurl")))

require("sensorweby")
installSensorWebClient()

To install your own fork:

installSensorWebClient(owner = 'myusername', version = 'mybranch')

Both commands require the packages RCurl and github to be installed. Also, Maven has to be found in your PATH.

Contact / Support

Please direct support questions to the 52°North Sensor Web Community mailing list/forum: http://sensorweb.forum.52north.org/ (and read the guidelines beforehand).

Add an issue/comment on the GitHub repository if you found a bug or want to collaborate on new features.

License

This R extension package is licensed under Apache License 2.

Documentation (namely the vignettes) are published under CC BY 4.0.