Helper that appends a list item to a list of lists

Description

Helper that appends a list item to a list of lists

Usage

.appendList(li = list(), item = list())

Arguments

Value

The modified list

Given a runId, polls the "download" method to count the number of files available Uses HTTP HEAD to avoid downloading the files

Description

Given a runId, polls the "download" method to count the number of files available Uses HTTP HEAD to avoid downloading the files

Usage

.countFilesInProduct(self, runId = 0)

Arguments

Value

(numeric) Number of files available for download

Discovery Request encapsulates a request to a discovery service

Description

Discovery Request encapsulates a request to a discovery service

Usage

.discoveryRequest(self, filters = list(), service = "", method = "get")

Arguments

Value

(named list) Parsed response obtained

Generic request wrapper for making simple web service requests Will return parsed results, even if they are an error description sent by the API Will stop() if the request fails into an error different from 400

Description

Generic request wrapper for making simple web service requests Will return parsed results, even if they are an error description sent by the API Will stop() if the request fails into an error different from 400

Usage

.doRequest(
  self,
  url = "",
  filters = list(),
  getInfo = FALSE,
  rawResponse = FALSE
)

Arguments

Value

(list) The parsed response

Public wrapper that lets a user download data products manually with a runId Can optionally return just the download links

Description

Public wrapper that lets a user download data products manually with a runId Can optionally return just the download links

Usage

.downloadDataProduct(
  self,
  runId = 0,
  maxRetries = 0,
  downloadResultsOnly = FALSE,
  includeMetadataFile = TRUE,
  overwrite = FALSE
)

Arguments

Value

(list) A list of results (one named list for each file) with information on the operation outcome

Download all data product files for provided run id

Description

Download all data product files for provided run id

Usage

.downloadProductFiles(
  self,
  runId = 0,
  getMetadata = TRUE,
  maxRetries = 0,
  overwrite = TRUE,
  fileCount = 0
)

Arguments

Value

a list of named lists, with the results for each file

Sets a poll period adequate to the estimated processing time Longer processing times require longer poll periods to avoid going over maxRetries

Description

Sets a poll period adequate to the estimated processing time Longer processing times require longer poll periods to avoid going over maxRetries

Usage

.estimatePollPeriod(self, response)

Arguments

Value

(numeric) suggested time between server polls (seconds)

Filter file list results to only those where the filename ends with the extension If extension is empty no change will be made

Description

Filter file list results to only those where the filename ends with the extension If extension is empty no change will be made

Usage

.filterByExtension(self, results = list(), extension = "")

Arguments

Value

Filtered list

Returns a string URL for a base url and a named list of parameters

Description

Returns a string URL for a base url and a named list of parameters

Usage

.filters2url(url, params)

Arguments

Value

Full URL

Returns a formatted time duration string representation of a duration in seconds

Description

Returns a formatted time duration string representation of a duration in seconds

Usage

.formatDuration(secs = 0)

Arguments

Value

(character) A readable string for this time duration

Aggregates individual download results obtained in .orderDataProduct() into a list of formatted results to return, and a named list with general stats of the operation

Description

Aggregates individual download results obtained in .orderDataProduct() into a list of formatted results to return, and a named list with general stats of the operation

Usage

.formatResult(self, fileList = list(), runInfo = list())

Arguments

Value

A named list with "downloadResults" (list of download results) and "stats" (general stats for the full operation)

Returns a formatted file size string representation

Description

Returns a formatted file size string representation

Usage

.formatSize(size = 0)

Arguments

Value

(character) a readable string for this file size

Format date as ISO8601 UTC

Description

Helper that returns an ISO8601 string for the provided date string Most date formats are supported, as explained in: https://github.com/eddelbuettel/anytime A value of "now" returns the current UTC date & time Depends on the local system clock

Usage

.formatUtc(self, dateString = "now")

Arguments

Value

(character) Date string

Request a list of data products that matches the filters provided

Description

Request a list of data products that matches the filters provided

Usage

.getDataProducts(self, filters = list())

Arguments

Value

   (named list) A list of data products found, or an error description if any

Request a list of deployments that matches the filters provided

Description

Request a list of deployments that matches the filters provided

Usage

.getDeployments(self, filters = list())

Arguments

Value

   (named list) A list of deployments found, or an error description if any

Request a list of device categories that matches the filters provided

Description

Request a list of device categories that matches the filters provided

Usage

.getDeviceCategories(self, filters = list())

Arguments

Value

   (named list) A list of device categories found, or an error description if any

Request a list of devices that matches the filters provided

Description

Request a list of devices that matches the filters provided

Usage

.getDevices(self, filters = list())

Arguments

Value

   (named list) A list of devices found, or an error description if any

Generic method to download and concatenate all pages of data Keeps downloading all scalar or raw data pages until finished Automatically translates sensorCategoryCodes to a string if a list is provided

Description

Generic method to download and concatenate all pages of data Keeps downloading all scalar or raw data pages until finished Automatically translates sensorCategoryCodes to a string if a list is provided

Usage

.getDirectAllPages(
  self,
  filters = list(),
  service = "",
  method = "",
  allPages = FALSE
)

Arguments

Value

A single response in the expected format, with all data pages concatenated

Obtains scalar data from a device, as described by the filters

Description

Obtains scalar data from a device, as described by the filters

Usage

.getDirectByDevice(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) Scalar data obtained for all sensors found

Obtains scalar data from a location, from the source described by the filters

Description

Obtains scalar data from a location, from the source described by the filters

Usage

.getDirectByLocation(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) Scalar data obtained for all sensors found

Downloads all archive files that match the filters Internally will use geListByDevice or getListByLocation and getFile all files

Description

Downloads all archive files that match the filters Internally will use geListByDevice or getListByLocation and getFile all files

Usage

.getDirectFiles(self, filters = list(), overwrite = FALSE, allPages = FALSE)

Arguments

Value

(named list) Information on the results of the operation, with "downloadResults" for each file downloaded and general "stats"

Obtains raw data from a device, as described by the filters

Description

Obtains raw data from a device, as described by the filters

Usage

.getDirectRawByDevice(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) Raw data obtained for all sensors found

Obtains raw data from a location, from the source described by the filters

Description

Obtains raw data from a location, from the source described by the filters

Usage

.getDirectRawByLocation(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) Raw data obtained for all sensors found

Given a filename, returns an archivefile absolute download URL

Description

Given a filename, returns an archivefile absolute download URL

Usage

.getDownloadUrl(self, filename = "")

Arguments

Value

(character) download URL

Download the archive file with filename

Description

Download the archive file with filename

Usage

.getFile(self, filename = "", overwrite = FALSE)

Arguments

Value

(named list) Information on the download result

A generic wrapper for getListByLocation() and getListByDevice()

Description

A generic wrapper for getListByLocation() and getListByDevice()

Usage

.getList(self, filters = list(), by = "location", allPages = FALSE)

Arguments

Value

(named list) Information on the list of files obtained

Get a list of files available in Oceans 2.0 Archiving System for a given device code. The list of filenames can be filtered by time range. filtered by others optional parameters.

Description

Get a list of files available in Oceans 2.0 Archiving System for a given device code. The list of filenames can be filtered by time range. filtered by others optional parameters.

Usage

.getListByDevice(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) file list obtained

Get a list of files for a given location code and device category code, and filtered by others optional parameters.

Description

Get a list of files for a given location code and device category code, and filtered by others optional parameters.

Usage

.getListByLocation(self, filters = list(), allPages = FALSE)

Arguments

Value

(named list) file list obtained

Request a hierarchical tree list of locations that matches the filters provided

Description

Request a hierarchical tree list of locations that matches the filters provided

Usage

.getLocationHierarchy(self, filters = list())

Arguments

Value

   (named list) A list of locations found, or an error description if any
           Locations include lists of children locations recursively

Request a list of locations that matches the filters provided

Description

Request a list of locations that matches the filters provided

Usage

.getLocations(self, filters = list())

Arguments

Value

   (named list) A list of locations found, or an error description if any

Request a list of properties that matches the filters provided

Description

Request a list of properties that matches the filters provided

Usage

.getProperties(self, filters = list())

Arguments

Value

   (named list) A list of properties found, or an error description if any

Returns a list of information lists for each file available for download Returned rows will have the same structure as those returned by DataProductFile$getInfo()

Description

Returns a list of information lists for each file available for download Returned rows will have the same structure as those returned by DataProductFile$getInfo()

Usage

.infoForProductFiles(self, dpRunId = 0, fileCount = 0, getMetadata = FALSE)

Arguments

Value

a list of named lists, with the results for each file

R helper: Returns the last element of a list

Description

R helper: Returns the last element of a list

Usage

.lastItem(collection)

Arguments

Value

The last element of the list

Prints message to console only when showInfo is true

Description

Prints message to console only when showInfo is true

Usage

.log(self, msg = "")

Arguments

Request, run and download a data product as described by the filters

Description

Request, run and download a data product as described by the filters

Usage

.orderDataProduct(
  self,
  filters = list(),
  maxRetries = 0,
  downloadResultsOnly = FALSE,
  metadata = TRUE,
  overwrite = FALSE
)

Arguments

Value

(list) A list of results (one named list for each file) with information on the operation outcome

Creates directory if it does not exist Supports directory paths with or without filenames

Description

Creates directory if it does not exist Supports directory paths with or without filenames

Usage

.prepareDirectory(filepath = "")

Arguments

Value

(logical) TRUE if the directory was created or already exists

Pretty prints a complex hierarchy of lists

Description

Pretty prints a complex hierarchy of lists

Usage

.prettyPrint(item, name = "", level = 0, comma = FALSE, file = "")

Arguments

Helper for printing a JSON named list to the console Can alternatively print the output to a text file at filePath

Description

Helper for printing a JSON named list to the console Can alternatively print the output to a text file at filePath

Usage

.print(self, obj, filePath = "")

Arguments

Print Error Response Message

Description

Prints the information from a API error response to the console as a formatted error message

Usage

.printErrorMessage(response)

Arguments

Prints a formatted representation of the total time and size downloaded after the product order finishes

Description

Prints a formatted representation of the total time and size downloaded after the product order finishes

Usage

.printProductOrderStats(self, fileList = list(), runInfo = list())

Arguments

Prints the response after a data product request The request response format might differ depending on the product origin as it can be "assembled" on the fly, or reused from existing products

Description

Prints the response after a data product request The request response format might differ depending on the product origin as it can be "assembled" on the fly, or reused from existing products

Usage

.printProductRequest(self, response)

Arguments

Request a data product generation described by the filters

Description

Request a data product generation described by the filters

Usage

.requestDataProduct(self, filters = list())

Arguments

Value

Parsed httr response

Response has failed

Description

Returns TRUE if the response is a 401 JSON error description provided by the API

Usage

.respFailed(response)

Arguments

Value

(logical)

Run a data product generation request

Description

Run a data product generation request

Usage

.runDataProduct(self, dpRequestId = 0, waitComplete = FALSE)

Arguments

Value

(named list) information of the run process, or error object

For all rows in data, enforce that fields expected to have bool values are logical values (fixes API issues with booleans returned as strings)

Description

For all rows in data, enforce that fields expected to have bool values are logical values (fixes API issues with booleans returned as strings)

Usage

.sanitizeBooleans(self, data = list())

Arguments

Value

(list) The modified data

Saves the file downloaded in the response object, in the outPath, with filename

Description

Saves the file downloaded in the response object, in the outPath, with filename

Usage

.saveAsFile(response, filePath = "", fileName = "", overwrite = FALSE)

Arguments

Value

(numeric) Result code from 0: done, -1: error, -2: fileExists

Returns the absolute url for a given ONC API service

Description

Returns the absolute url for a given ONC API service

Usage

.serviceUrl(self, service = "")

Arguments

Value

(character) Service's URL

DataProductFile class

Description

Encapsulates the download of a single data product file, and the handling of the server polling and error codes.

Arguments

Value

(integer) the final response's HTTP status code Return the file name from the response

(string) The filename as obtained from the headers Return information on this download's outcome

(list) A named list with information on the download result Sets this object's status to 200 (complete) Used by onc_delivery methods

Fields

.filters

The list of filters to pass to the download API method

.retries

Total count of HTTP requests made by this object

.status

Last request's HTTP status code

.downloaded

TRUE if the file was downloaded from the API

.baseUrl

Same as in the Onc class

.downloadUrl

URL that downloads this file

.fileName

Filename of the file if downloaded & saved

.fileSize

Size in bytes of the file if downloaded & saved

.runningTime

Total time spent running (sec)

.downloadingTime

Total time spend downloading (sec) Class initializer

MultiPage

Description

API multiple page helper. Handles the download of data in multiple pages Used by real-time and archivefile services

Arguments

Value

: Response with concatenated data for all pages obtained Do a page request

Wraps the _doRequest method Performs additional processing of the response for certain services

(list) A named list with: "response" (httr response) and "duration" (secs) Concatenate data

Concatenates the data results from nextResponse into response Compatible with the row structure of scalardata, rowdata and archivefiles

(named list) Modified original response Estimate pages

Estimates the number of pages this request will require to download, from the first page's response and its duration

(int) Estimated number of pages Response Time Span

Determines the timespan covered by the data in the response

    (int)        page duration in seconds

Fields

showInfo

As provided by the Onc class

timeout

As provided by the Onc class Class initializer Get all pages

Obtains all data pages for a query with the filters Multiple pages will be downloaded in sequence until completed Each new page gets concatenated to the previous one (limited to RAM)

Onc Class

Description

Provides convenient & easy access to Ocean Networks Canada's data. For detailed information and usage examples, visit our official Documentation.

Arguments

Fields

token

character. User token

showInfo

logical. Print verbose debug comments

timeout

numeric. Number of seconds before a request to the API is canceled

baseUrl

character. Base URL for API requests

outPath

character. Output path for downloaded files

Class initializer

Methods

downloadDataProduct( runId = 0, maxRetries = 0, downloadResultsOnly = FALSE, includeMetadataFile = TRUE, overwrite = FALSE )

Manually download a data product after it was requested and run

formatUtc(dateString = "now")

Formats the provided date string to meet ISO8601

getDataProducts(filters = list())

Returns a filtered list of data products

getDeployments(filters = list())

Returns a filtered list of deployments

getDeviceCategories(filters = list())

Returns a filtered list of device categories

getDevices(filters = list())

Returns a filtered list of devices

getDirectByDevice(filters = list(), allPages = FALSE)

Obtain scalar data readings from a device

getDirectByLocation(filters = list(), allPages = FALSE)

Obtain scalar data readings from a device category in a location

getDirectFiles(filters = list(), overwrite = FALSE, allPages = FALSE)

Download a list of archived files that match the filters provided

getDirectRawByDevice(filters = list(), allPages = FALSE)

Obtain raw data readings from a device

getDirectRawByLocation(filters = list(), allPages = FALSE)

Obtain raw data readings from a device category in a location

getFile(filename = "", overwrite = FALSE)

Download a file with the given filename

getListByDevice(filters = list(), allPages = FALSE)

Get a list of archived files for a device

getListByLocation(filters = list(), allPages = FALSE)

Get a list of archived files for a device category in a location

getLocationHierarchy(filters = list())

Returns a filtered locations tree

getLocations(filters = list())

Returns a filtered list of locations

getProperties(filters = list())

Returns a filtered list of properties

orderDataProduct( filters = list(), maxRetries = 0, downloadResultsOnly = FALSE, includeMetadataFile = TRUE, overwrite = FALSE )

Request, run and download a data product

print(data, filename = "")

Prints a named list in a format easier to read

requestDataProduct(filters = list())

Manually Request a data product

runDataProduct(dpRequestId = 0, waitComplete = FALSE)

Manually run a data product request