R integration

The timeseries_client.R file is an API wrapper for AQTS systems for easy consumption in R projects.

Consuming AQUARIUS Time-Series data from R

The R programming environment provides a rich ecosystem for numerical computing and graphic visualization.

Requires:

• an R runtime 4.0-or-greater, any supported platform

Recommended packages

Before consuming any data from AQTS, you'll need to be able issue HTTP requests to the public APIs and serialize data to/from JSON.

Install these packages to enable basic communication with your AQTS server from your R environment.

> install.packages("jsonlite") # Fast JSON parser
> install.packages("httr") # Hadley's nice HTTP requests library

API wrapper methods

Method	Works with	Description
connect( hostname, username, password )	All	Connects to the AQTS app server with the given credentials.
disconnect()	All	Disconnects the session from the app server.
getTimeSeriesUniqueId( timeSeriesIdentifier )	20xx	Gets the uniqueID of the time-series, required for many other methods. For 3.x systems, this method just returns the identifier, since uniqueIDs are a 201x feature.
getLocationIdentifier( timeSeriesIdentifier )	All	Extracts the location identifier from a "Parameter.Label@Location" time-series identifier
getLocationData( locationIdentifier )	All	Gets the location data, including extended-attributes.
getRatings( locationIdentifier, queryFrom, queryTo, inputParameter, outputParameter )	All	Gets all the rating models matching the request filter.
getRatingModelOutputValues( ratingModelIdentifier, inputValues, effectiveTime, applyShifts )	All	Gets the output values of a rating model using specific inputs
getFieldVisits( locationIdentifier, queryFrom, queryTo, activityType )	All	Gets all the field visit data matching the filter.
getTimeSeriesDescriptions( locationIdentifier, parameter, publish, computationIdentifier, computationPeriodIdentifier, extendedFilters )	All	Gets the time-series matching the filter.
getTimeSeriesData( timeSeriesIds, queryFrom, queryTo, outputUnitIds, includeGapMarkers )	2017.2+	Gets the time-aligned data for multiple time-series.
getTimeSeriesCorrectedData( timeSeriesIdentifier, queryFrom, queryTo, getParts, includeGapMarkers )	All	Gets the corrected data for the time-series.
uploadExternalReport( locationDataOrIdentifier, pathToFile, title, deleteDuplicateReports )	2017.3+	Uploads an external report to the given location.
getReportList()	2017.3+	Gets all the generated reports on the system.
deleteReport( reportUniqueId )	2017.3+	Deletes a report from the system.
appendPoints( seriesIdentifierOrUniqueId, points, start, end )	20xx	Queues points to be appended to a basic time-series, returning an appendRequestIdentifier. If start and end are provided, an overwrite append will be performed.
appendReflectedPoints( seriesIdentifierOrUniqueId, points, start, end )	20xx	Queues points to be appended points to a reflected time-series, returning an appendRequestIdentifier.
getAppendStatus( appendRequestIdentifier )	20xx	Gets the status of an append request identifier.
waitForCompletedAppendRequest( appendRequestIdentifier, timeout )	20xx	Waits for an append request to be completed.

Revision History

• 2022-Jun-07 - Added appendPoints(), appendReflectedPoints(), getAppendStatus(), and waitForCompletedAppendRequest() helper methods.
• 2022-Jun-30 - Bugfix for uploadExternalReports()
• 2018-Mar-22 - First stable release for AQTS 20xx and 3.x systems.

Examples

• Example 1 - Plotting stage vs. discharge
• Example 2 - Wind rose plots
• Example 3 - Flood Frequency Analysis curves
• Example 4 - Intensity Duration Frequency plots
• Example 5 - Flow Duration curves
• Example 6 - Appending points

The timeseries_client.R API wrapper

The timeseries_client.R file adds some objects and method to communicate with the public REST APIs of an AQTS system.

Loading the wrapper into your workspace

# Load the wrapper into your workspace
> source("timeseries_client.R")

A timeseries object will be added to your workspace.

Authenticating with AQTS

Authenticate with your AQTS server using the connect method of the timeseries object, passing your AQTS credentials.

# Connects to http://myserver/AQUARIUS as "myuser"
> timeseries$connect("myserver", "myusername", "mypassword")

If your app server is running on a secure connection, just prefix the server name or IP with "https:"

# Connects to https://myserver/AQUARIUS as "myuser"
> timeseries$connect("https://myserver", "myusername", "mypassword")

All subsequent requests to the AQTS server will use the authenticated session.

Disconnecting from AQTS

Your authenticated AQTS session will expire one hour after the last authenticated request made.

Your code can choose to immediately disconnect from AQTS by calling the disconnect method of the timeseries object.

> timeseries$disconnect()
# The next request will fail with 401: Unuathorized
> timeseries$getTimeSeriesUniqueId("Stage.Label@Location")
Error Unauthorized (HTTP 401) ...

Error handling

Any errors contained in the HTTP response will be raised through the stop_for_status() method from the httr package.

Your code can use standard R error handling techniques (like the trycatch() method) to handle errors as you'd like.

Capturing HTTP requests from R using Fiddler

Fiddler is a great tool for capturing HTTP traffic on Windows systems.

You can manually configure your R environment to route its HTTP requests through the Fiddler proxy in order to the traffic in the Fiddler window.

# The following tells R to use the default Fiddler endpoint as its HTTP proxy
> Sys.setenv(http_proxy="http://localhost:8888")

# And this disables the proxy (required if Fiddler is no longer running)
> Sys.setenv(http_proxy="")

As a convenience, when your R session uses the timeseries$connect() method to connect to an AQTS system, the R proxy will automatically be routed through Fiddler if it is running.

Other R platforms like Linux and OS X have similar debugging proxy tools available, and will need to be manually configured using the Sys.setenv() method.

Example 1 - Plotting Stage vs. Discharge

The first step is simply to connect to AQTS and grab a year's worth of data for a stage/discharge pair.

# Connect to AQTS
> timeseries$connect("https://myserver", "admin", "admin")

# Get the time-sligned data for the year 2012 for a discharge and stage time-series
> json = timeseries$getTimeSeriesData(c("Discharge.Working@Location","Stage.Working@Location"),
                                      queryFrom = "2012-01-01T00:00:00Z",
                                      queryTo   = "2013-01-01T00:00:00Z")

Now the points are in R data frames in the json object, so we can simply plot them as an XY plot.

# Plot stage vs. discharge, in logspace, with labeled axis
> plot(json$Points$NumericValue1, json$Points$NumericValue2, log = "xy",
       xlab = json$TimeSeries$Identifier[1],
       ylab = json$TimeSeries$Identifier[2])

And here is the plot, which should match the rating curve for 2012.

Example 6 - Appending points

There are two helper methods in the wrapper for appending points to a time-series:

• timeseries$appendPoints( seriesIdentifierOrUniqueId, points, start, end ) - For appending to basic time-series
• timeseries$appendReflectedPoints( seriesIdentifierOrUniqueId, points, start, end ) - For appending to reflected time-series

The methods are quite similar:

• The seriesIdentifierOrUniqueId parameter can be a text identifier like Stage.Working@Location or a uniqueID like 0123456789abcdef0123456789abcdef.
• The points dataframe parameter, with points$Time and points$Value columns.
• Optional start and end parameters. When specified, then start <= points$Time <= end must be true. All the points must be within the time-range.
• Both methods return a "append request identifier", a text value that can be used with the timeseries$getAppendStatus() or timeseries$waitForCompletedAppendRequest() methods if your integration needs to wait for the queued points to be processed by AQTS.

Most integrations don't actually need to wait for the appended points to be processed.

# Connect to the app server
timeseries$connect("https://myserver", "admin", "admin")

# Load a points CSV into a dataframe
points <- read.csv(file = 'mypoints.csv')

# Append the points to the Stage time series, without waiting for the request to fully processed
timeseries$appendPoints( "Stage.Telemetery@Location", points )