A JavaScript sensor web client with graphs and analytics powered by Shiny
JavaScript CSS R HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
R
inst
man
.Rbuildignore
.gitignore
.travis.yml
DESCRIPTION
LICENSE
NAMESPACE
NEWS
README.md
sensorweby.Rproj

README.md

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.

Build Status

OpenHUB

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 GPL-3.0.

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