diff --git a/README.md b/README.md
index ee6af7a..b8a69a4 100644
--- a/README.md
+++ b/README.md
@@ -3,13 +3,13 @@
[](https://www.mathworks.com/matlabcentral/fileexchange/74065-ocean-networks-canada-api-client-library)
This library facilitates access to scientific data hosted by [Ocean Networks Canada](https://oceannetworks.ca) through the
-[Oceans 2.0 API](https://wiki.oceannetworks.ca/display/O2A/Oceans+2.0+API+Home) public web services.
+[Oceans 3.0 API](https://wiki.oceannetworks.ca/display/O2A/Oceans+3.0+API+Home) public web services.
This repository is synchronized to the [MATLAB ONC API Client Add-On](https://www.mathworks.com/matlabcentral/fileexchange/74065-ocean-networks-canada-api-client-library) which can be installed from the MATLAB Add-on explorer (please search for the "onc" Add-on).
## Documentation
-For complete documentation and examples, visit https://wiki.oceannetworks.ca/display/O2A/Client+Libraries
+For complete documentation and examples, visit [ONC File Exchange](https://www.mathworks.com/matlabcentral/fileexchange/74065-ocean-networks-canada-api-client-library)
## Maintainers
diff --git a/doc/AddOn.png b/doc/AddOn.png
new file mode 100644
index 0000000..c6ac1c2
Binary files /dev/null and b/doc/AddOn.png differ
diff --git a/doc/ExampleLinks.html b/doc/ExampleLinks.html
new file mode 100644
index 0000000..7f13fa9
--- /dev/null
+++ b/doc/ExampleLinks.html
@@ -0,0 +1,84 @@
+
+
+
+ Ocean Networks Canada API Client Library
+
+
Example/LiveScript Links
+
Contents
+
These links will only work when you open this page in MATLAB's 'doc' viewer.
+
\ No newline at end of file
diff --git a/doc/GettingStarted.html b/doc/GettingStarted.html
new file mode 100644
index 0000000..4545544
--- /dev/null
+++ b/doc/GettingStarted.html
@@ -0,0 +1,1260 @@
+
+
+
+ Getting Started
+
+
+
Getting Started
+
Contents
+
To navigate directly to a specific part of the documentation (use the internal links), right-click on the section you're interested and select "Open" or "Open in New Tab".
For more information about creating an Onc object, see ONC Class
+
+
+
Note
+
+
It's important to check that you are using the latest version. Outdated version may results in bugs.
+
When you run Onc() to create an Onc object, it will run a version check and prints out version outdated warning if fails. How to update to latest version.
+
+
+
+
General Tutorial - 1. Searching with discovery services
+
Check sections in the left panel for full documentation, source code and examples on each service.
+
To download data from Ocean Networks Canada's database (Oceans 3.0) , you need to specify the type of data you are interested in
+ and where in particular (i.e. location, from specific instrument (device)) it originates from.
+ In the Oceans 3.0 API, there are a unique codes that identify every location, device, property, data product type, etc.
+ You include these codes in a group of filters to retrieve the information you're interested in.
+ The Oceans 3.0 API Discovery services allow you to explore the hierarchy of ONC's database to obtain the codes required for your filters
+ to obtain the information/data you are interested in (they work like a "search" function).
+
+
The example below uses the getLocations method, which is querying the locations database tables that include "Bullseye" in
+ their name (i.e. "Clayoquot Slope Bullseye Vent"). It returns a list with all locations that match the search filters provided.
+
Using ONC library
+
% 1. Define your filter parameter
+params = {'locationName', 'Bullseye'};
+% 2. Call methods in the onc library
+onc.getLocations(params)
+
+ ans = struct with fields:
+ deployments: 38
+ locationName: 'Bullseye'
+ depth: 1.2569e+03
+ bbox: [1x1 struct]
+ description: ' Bullseye is a location at Clayoquot Slope, where gas hydrates, seafloor cold seeps, and hydrate dynamics are observed.'
+ hasDeviceData: 1
+ lon: -126.8480
+ locationCode: 'NC89'
+ hasPropertyData: 0
+ lat: 48.6706
+ dataSearchURL: 'https://data.oceannetworks.ca/DataSearch?location=NC89'
+
+
Each entry of this list contains more meta data information for that location, e.g. the locationName, the geographical coordinates and depth,
+ a description field and the URL for Oceans 3.0 Data Search tool. The parameter locationCode contains the string "NC89", which is needed for the next steps.
+
1.1 What device categories are available here at the location NC89?
+
Using ONC library
+
% 1. Define your filter parameter
+params = {'locationCode', 'NC89'};
+% 2. Call methods in the onc library
+onc.getDeviceCategories(params)
+ ' Acoustic Doppler Current Profilers are hydroacoustic instruments, similar to sonars. ADCPs measure current speed and direction at multiple predetermined depths simultaneously. ADCPs use the Doppler effect of sound waves that are scattered by particles in seawater over a depth range.'
+
+
+
+
+ 2
+
+
+ 1×1 struct
+
+
+ 'Acoustic Doppler Current Profiler 75 kHz '
+
+
+ 'ADCP75KHZ'
+
+
+ 'Acoustic Doppler Current Profiler 75 kHz'
+
+
+ 1
+
+
' Acoustic Doppler Current Profilers (ADCP) are hydroacoustic instruments, similar to sonars. ADCPs measure current speed and direction at multiple predetermined depths simultaneously. ADCPs use the Doppler effect of sound waves that are scattered by particles in seawater over a depth range.'
+
3
1×1 struct
+
'Broadband Seismometer'
+
'BBS'
+
'Broadband Seismometer'
+
1
+
' Broadband Seismometers measure seismic waves over a broad frequency range depending on the device (e.g. 0.00278 Hz - 250 Hz). A broadband seismometer facilitates measurement of seismic events in the widest frequency band possible.'
+
4
1×1 struct
+
'Bottom Pressure Recorder'
+
'BPR'
+
'Bottom Pressure Recorder'
+
1
+
' Bottom Pressure Recorders (BPR) are instruments that can detect small changes in pressure on the seafloor. '
+
5
1×1 struct
+
'Controlled Source Electromagnetic Method'
+
'CSEM'
+
'Controlled Source Electromagnetic Method'
+
1
+
' The Controlled Source Electromagnetic Method (CSEM) measures sub-surface resistivity structure through the measurement of the electromegnetic fields resulting from stimulation by a towed source.'
+
6
1×1 struct
+
'Conductivity Temperature (and Depth Sensor)'
+
'CTD'
+
'Conductivity Temperature Depth'
+
1
+
' Conductivity Temperature Depth (CTD) is an instrument package that contains sensors for measuring the conductivity, temperature, and pressure of seawater. Salinity, sound velocity, depth and density are variables that can be derived from sensor measurements. CTDs can carry additional instruments and sensors such as oxygen sensors, turbidity sensors and fluorometers.'
+
7
1×1 struct
+
'Current Meter'
+
'CURRENTMETER'
+
'Current Meter'
+
1
+
' Acoustic Current Meters (ACM) measure current speed and direction, using the Doppler Effect. Aquadopp current meters have a sensor head that contains 3 acoustic transducers, a tilt sensor, a temperature sensor and a pressure sensor. The instrument transmits a short pulse of sound, and then listens to its echo to measure the change in pitch or frequency. The change in pitch can determine the velocity of the current.'
+
8
1×1 struct
+
'Gravimeter'
+
'GRAVIMETER'
+
'Gravimeter'
+
1
+
' Gravimeters (or gravity meters) measure the gravity field of the Earth with such a resolution that they can detect very small changes in the underlying or surrounding structures.'
+
9
1×1 struct
+
'Junction Box'
+
'JB'
+
'Junction Box'
+
1
+
' Junction Boxes supply power and communications to deployed instruments. Junction boxes have a number of serial and ethernet ports, including 400V ethernet ports that enable connections to other junction boxes and high-voltage instruments. Junction boxes can convert high voltages to lower voltages (15V, 24V or 48V) required by many instruments.'
+
10
1×1 struct
+
'Oxygen Sensor'
+
'OXYSENSOR'
+
'Oxygen Sensor'
+
1
+
' Oxygen sensors measure dissolved oxygen concentration in seawater.'
+
11
1×1 struct
+
'Pan Tilt Lights'
+
'PTL'
+
'Pan Tilt Lights'
+
1
+
' Pan Tilt Lights are used for cameras and allow remotely controlled operations such as changing the camera's field of view and illuminating the subject matter.'
+
12
1×1 struct
+
'Tiltmeter'
+
'TILTMTR'
+
'Tiltmeter'
+
1
+
' A tiltmeter is a sensitive inclinometer designed to measure very small changes from the vertical level, either on the ground or in structures.'
+
13
1×1 struct
+
'Video Camera'
+
'VIDEOCAM'
+
'Video Camera'
+
1
+
' Video cameras record video of characteristics of the surrounding environments and can be deployed on fixed and mobile platforms.'
+
+
+
1.2 What properties are available for the device category CTD at this location NC89?
+
Using ONC library
+
% 1. Define your filter parameter
+params = {'locationCode', 'NC89', ...
+ 'deviceCategoryCode', 'CTD'};
+% 2. Call methods in the onc library
+onc.getProperties(params)
+
If the row of the data is above 100,000, not all the data will be returned. The rest of the data can be queried based on the next key in the response.
+
+
If you use onc library.
getDirectRawByLocation supports a boolean allPages parameter. When set to True, it will try to retrieve all the pages.
+
If you use MATLAB's HTTP library.
You have to manually query the next pages until the next key in the response json is None, and concatenate all the data together.
+
+
+
Using ONC library
+
% 1. Define your filter parameter with a longer date range (2 days of data)
+paramsLongerRange = {'locationCode', 'NC89', ...
+ 'deviceCategoryCode', 'CTD', ...
+ 'dateFrom', '2020-06-20T00:00:00.000Z', ...
+ 'dateTo', '2020-06-22T00:00:00.000Z', ...
+ };
+% 2. Call methods in the onc library
+result = onc.getDirectRawByLocation(paramsLongerRange, 'allPages', true)
+struct2table(result.data)
+
+
+
Data size is greater than the row limit and will be downloaded in multiple pages.
+ Estimated approx. 1 pages
+ Estimated approx. 5.79 seconds to complete
+
+ (100000 samples) Downloading page 2...
+ (172796 samples) Completed in 2.25 seconds.
A faster way to download data products and processed data files that are available in Oceans 3.0 (if it suits your needs) is to leverage how ONC scripts
+auto-generate and archive data products of different types at set time intervals. You can directly download these data product files from our files archive, as long as you know their unique filename.
+
In the following example, we get the list of archived files available for a camera (deviceCategoryCode: VIDEOCAM) at Ridley Island (locationCode: RISS) for 5-minute timerange.
Once we have the file names, you can use the method "getFile()" to download individual files:
+
Using ONC library
+
% 1. Call methods in the onc library with the filename. The file is downloaded in the output folder.
+onc.getFile('AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg', 'overwrite', true)
+
+
Downloading file "AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg"...
+ [==================================================] 100%
+ File was downloaded to "AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg"
% 1. Define your filter parameter with the filename
+params.filename = 'AXISQ6044PTZACCC8E334C53_20161201T000001.000Z.jpg';
+params.token = 'YOUR TOKEN HERE'; % or readToken
+% 2. Define your base url for this query
+url_location = 'https://data.oceannetworks.ca/api/archivefile/download';
+request = matlab.net.http.RequestMessage;
+uri = matlab.net.URI(url_location);
+uri.Query = matlab.net.QueryParameter(params);
+
+% 3. prepare MATLAB request options
+options = matlab.net.http.HTTPOptions();
+options.ConnectTimeout = 120;
+
+% 4. send request
+result = request.send(uri,options);
+% 5. Save the file
+% f = fopen(fullPath, 'w','n','ISO-8859-1');
+% if f ~= -1
+% fwrite(f, char(dataToWrite));
+% end
+
+
2.4 Downloading data products
+
Other than using Oceans 3.0 Data Search, we can request the ONC server to generate a data product. This is done through the data product delivery services methods.
+
+
Hint
+
This service should ONLY be used when the requested files are not already provided using the ArchiveFiles services (see 2.3 above).
+ The data product delivery services will re-generate files using ONC's web machines and this process can often take very long time to generate these results.
+ If you request data files for very long-time ranges and large file sizes, ONCs system will sometimes slow down and stall and requires some manual actions.
+
We therefore encourage you to check other services before requesting data through this service. If you are unsure what to use feel free to contact u.
+
+
This process will require three steps before you will be able to see the downloaded data product on your computer:
+
+
+
Request the data.
+
Run the Request.
+
Download the data.
+
+
+
The following example downloads two PNG files with plots for 30 minutes of data from a CTD (find them in the "output" folder beside this jupyter notebook).
+ The filter includes codes for location, deviceCategory, and dataProduct, as well as the file extension and a time interval.
+ They also include a couple of filters to configure this specific data product type (starting with the "dpo_" prefix) which can be obtained from the Data Product Options documentation. You can download more than 120 different types of data products including audio & video.
+
Using ONC library
+
ONCs library contains all three steps (methods) in one call. So this is the preferred library to use over the requests library.
citations: [1×1 struct]
+ disclaimer: 'Software Developers are implementing estimates of processing times and file sizes for data requests. These are extremely rough to begin with, but bear with us. We expect these estimates will gradually improve.'
+ dpRequestId: 18690550
+ estimatedFileSize: '185 kB'
+estimatedProcessingTime: '20 s'
+ messages: []
+ queryPids: 25848930
+ queryURL: 'https://data.oceannetworks.ca/api/dataProductDelivery/request?locationCode=NC89&deviceCategoryCode=CTD&dataProductCode=TSSP&extension=png&dateFrom=2017-01-19T00:00:00.000Z&dateTo=2017-01-19T00:30:00.000Z&token=YOUR_TOKEN&dpo_resample=none&dpo_resample=none&dpo_qualityControl=1'
+
+
+
+%% requests continued
+% Run the request
+% Note: you have to execute this cell multiple times until the return shows the "status": "complete"
+% Note: Depending on your request, you can have more than one file ('fileCount').
+% You will need to individually download these files by using the index parameter.
+url_run = 'https://data.oceannetworks.ca/api/dataProductDelivery/run';
+
+requestID = requestResponse.Body.Data.dpRequestId;
+params_run = struct();
+params_run.dpRequestId = requestID;
+params_run.token = readToken;
+
+request = matlab.net.http.RequestMessage;
+uri = matlab.net.URI(url_run);
+uri.Query = matlab.net.QueryParameter(params_run);
+runResponse = request.send(uri,options);
+result = runResponse.Body.Data
+
%% requests continued
+% Find the RunID for the next step
+runId = response(1).dpRunId
+
+
runId = 40531302
+
+
%% requests continued
+% 3. Download the data
+url_download = 'https://data.oceannetworks.ca/api/dataProductDelivery/download';
+params_download = struct();
+params_download.dpRunId = runId;
+params_download.token = readToken;
+params_download.index = '1';
+request = matlab.net.http.RequestMessage;
+uri = matlab.net.URI(url_download);
+uri.Query = matlab.net.QueryParameter(params_download);
+
+% Start - Rerun this part until the response code is 200.
+downloadResponse = request.send(uri,options);
+result = downloadResponse.Body.Data
+responseCode = double(downloadResponse.StatusCode)
+% End - Rerun this part until the response code is 200.
+
+% %downloadResponse.Headers has field Content-Disposition,
+% %and Content-Disposition has the format "attachement; filename=XXX.png"
+% contentDisposition = char(downloadResponse.Header.getFields('Content-Disposition').Value);
+% filename = contentDisposition(23:end);
+% imwrite(downloadResponse.Body.Data, filename);
+% %Use other download functions if content type is not png/jpg
+
+
result = struct with fields:
message: 'Running'
+ status: 'running'
+
+
responseCode = 202
+
+
+
Another option to get the data
+
Obtain your downloads from your user FTP directory (More -> User Directory) in Oceans 3.0. Navigate to the folder that contains the runId: You will see the files in this folder.
+
\ No newline at end of file
diff --git a/doc/Info.html b/doc/Info.html
new file mode 100644
index 0000000..24d3200
--- /dev/null
+++ b/doc/Info.html
@@ -0,0 +1,158 @@
+
+
+
+ Ocean Networks Canada API Client Library
+
+
Ocean Networks Canada API Client Library
+
This library serves as a toolbox to access ONC Web Services which allows users to discover and retrieve Ocean Networks Canada's 12+ years of oceanographic data in raw, text, image, audio, video or any other format available. This codebase provides a class that wraps web service calls, complex workflows, and business logic so that users can download data with a single line of code.
+
Check left panel for more documentation and code examples. You can also find code examples under Examples section from here
+
Introduction to ONC Web Services/API
+
What are ONC Web Services?
+
A group of public web services that can be used to explore and download ONC data.
The ONC class provides a wrapper for Oceans 3.0 API requests. All the client library’s functionality is provided as methods of this class. Create an ONC object to access this library’s functionalities.
+
Parameters:
+
* token ([char]) - The ONC API token, which could be retrieved at https://data.oceannetworks.ca/Profile once logged in.
+ * production (logical, optional, default = True) - Whether the ONC Production server URL is used for service requests.
+ True: Use the production server.
+ False: Use the internal ONC test server (reserved for ONC staff IP addresses).
+ * showInfo (logical, optional, default = false) - Whether verbose script messages are displayed, such as request url and processing time information.
+ True: Print all information and debug messages (intended for debugging).
+ False: Only print information messages.
+ * outPath ([char], optional, default = 'output') - Output path for downloaded files. The directory will be created if it does not exist during the download.
+ * timeout (int, optional, default = 60) - Number of seconds before a request to the API is canceled
+
For detailed information and usage examples, run doc command or visit MATLAB's help browser https://www.mathworks.com/help/matlab/ then find Ocean Networks Canada API Client under supplemental software
+
Source code:
+
function this = Onc(token, varargin)
+ p = inputParser;
+ addRequired(p, 'token', @ischar);
+ addOptional(p, 'production', true, @islogical);
+ addOptional(p, 'showInfo', false, @islogical);
+ addOptional(p, 'outPath', 'output', @ischar);
+ addOptional(p, 'timeout', 60, @isnumeric);
+ parse(p, token, varargin{:});
+
+ this.token = strtrim(p.Results.token);
+ this.production = p.Results.production;
+ this.showInfo = p.Results.showInfo;
+ this.timeout = p.Results.timeout;
+
+ % sanitize outPath
+ opath = strtrim(p.Results.outPath);
+ if strlength(opath) > 0
+ opath = strrep(opath, '\', '/');
+ if opath(end) == '/'
+ opath = opath(1:end-1);
+ end
+ end
+ this.outPath = opath;
+
+ if not(this.production)
+ this.baseUrl = 'https://qa.oceannetworks.ca/';
+ end
+
+ %If a search tree file exists, load it. If not, generate and save one
+ [source_path,~,~] = fileparts(which('Onc.m'));
+ tree_path = fullfile(source_path,'onc_tree.mat');
+ if ~exist(tree_path,'file')
+ fprintf('\n Loading ONC search tree. Accessible with onc.tree \n');
+ tree = util.extract_tree(this);
+ save(tree_path, 'tree')
+ elseif exist(tree_path,'file')
+ %Check if it's more than a week old. If so, update it:
+ dir_files = dir(source_path);
+ filenames = {dir_files(:).name};
+ [~,idx] = ismember('onc_tree.mat',filenames);
+ treeFileDate = dir_files(idx).datenum;
+ if now - treeFileDate > 7
+ fprintf('\n Updating ONC search tree. Accessible with onc.tree \n');
+ tree = util.extract_tree(this);
+ save(tree_path, 'tree')
+ end
+ end
+ temp = load(tree_path);
+ this.tree = temp.tree;
+ %These codes can then be used for input to onc.getDevices by
+ %providing the locationCodes
+end
+
+
\ No newline at end of file
diff --git a/doc/OncArchive.html b/doc/OncArchive.html
new file mode 100644
index 0000000..755db51
--- /dev/null
+++ b/doc/OncArchive.html
@@ -0,0 +1,432 @@
+
+
+
+
+ OncArchive
+
+
+
ONC Archive Files methods
+
Contents
+
To navigate directly to a specific part of the documentation (use the internal links), right-click on the section you're interested and select "Open" or "Open in New Tab".
Contains the functionality that wraps API archivefile services To be inherited by the Onc class These methods allow users to directly download previously generated data product files from our archive.
+
ONC systems auto-generate and archive files of different types at set time intervals. These archived files can be downloaded without waiting for a generation process to finish (potentially faster than Data product download methods).
+
+
Note
+
Archived files have a unique filename (e.g. “NAXYS_HYD_007_20091231T235919.476Z-spect.png”) that includes the device code (“NAXYS_HYD_007”) and the UTC date-time when the data in the file started being measured (“20091231T235919.476Z”). The filename might contain additional information.
+
+
+
+
Caution
+
Due to security regulations, some very recent files (e.g. hydrophone.wav files in the last hour) might not be made immediately available.
+
+
GetListByLocation(filters, allPages)
+
Get a list of files for a given location and device category filtered by other optional parameters.
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional, default = false) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
Output:
+
+
array of structs - File list obtained
+
+
+
The API endpoint is /archivefile/location.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
+
Get a list of files for a given device filtered by other optional parameters.
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional, default = false) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
Output:
+
+
array of structs - File list obtaine
+
+
The API endpoint is /archivefile/location.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
Downloads all archive files that match the filters Uses geListByDevice or getListByLocation to get a file list, then getFile's everything.
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional, default = false) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
overwrite(logical, optional) - When true, downloaded files will overwrite any file with the same filename, otherwise(default) file will be skipped
+
+
Output:
+
+
struct - Information on the results of the operation, with 'downloadResults' for each file downloaded and general 'stats
+
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
\ No newline at end of file
diff --git a/doc/OncDelivery.html b/doc/OncDelivery.html
new file mode 100644
index 0000000..11743e4
--- /dev/null
+++ b/doc/OncDelivery.html
@@ -0,0 +1,466 @@
+
+
+
+
+ OncDelivery
+
+
+
ONC Delivery methods
Contents
+
To navigate directly to a specific part of the documentation (use the internal links), right-click on the section you're interested and select "Open" or "Open in New Tab".
Functionality that wraps the API data product delivery services. To be inherited by the Onc class Data product download methods allow you to request and download more than 120 different types of ONC data products, with granular control over what data to obtain, from where, and in what time frame. They are comparable to the download functionality from ONC’s Data Search tool. Examples of usage include:
+
+
+
Downloading PNG plots of sensor readings in a device
+
Downloading sensor readings as .mat files, text files, or in commercial manufacturer formats
+
Downloading compressed or raw audio files from hydrophones
+
+
+
+
Note
+
If the data product requested doesn’t exist in our archive, it will be generated by our servers before your download starts.
function [response, info] = cancelDataProduct(this, dpRequestId)
+ url = sprintf('%sapi/dataProductDelivery', this.baseUrl);
+ filters = struct('method', 'cancel', 'token', this.token, 'dpRequestId', dpRequestId);
+ [response, info] = this.doRequest(url, filters);
+ if isfield(response, 'status') && strcmp(response.status, 'cancelled') && info.status == 200
+ fprintf("The data product with request id %d and run id %d has been successfully cancelled.\n", dpRequestId, response.dpRunId);
+ else
+ fprintf("Failed to cancel the data Product.\n");
+ end
+end
+
+
\ No newline at end of file
diff --git a/doc/OncDiscovery.html b/doc/OncDiscovery.html
new file mode 100644
index 0000000..a3234ba
--- /dev/null
+++ b/doc/OncDiscovery.html
@@ -0,0 +1,459 @@
+
+
+
+
+ OncDiscovery
+
+
+
+
+
ONC Discovery methods
Contents
+
To navigate directly to a specific part of the documentation (use the internal links), right-click on the section you're interested and select "Open" or "Open in New Tab".
Contains the functionality that wraps the API discovery services To be inherited by the Onc class Discovery methods can be used to search for available locations, deployments, device categories, devices, properties, and data products. They support numerous filters and might resemble an "advanced search” function for ONC data sources.
+
Use discovery methods to:
+
+
+
Obtain the identification codes required to use other API services.
+
Obtain the identification codes required to use other API services.
+
Explore what's available in a certain location or device.
+
Obtain the deployment dates for a device.
+
List available data products for download in a particular device or location.
+
+
+
+
+
Note
+
+
Locations can contain other locations.
+
"Cambridge bay" may contain separate children locations for its underwater network and shore station.
+
Locations can contain device categories, which contain devices, which contain properties.
+
Searches can be performed without considering the hierarchy mentioned above.
+
You can search for locations with data on a specific property or search for all properties in a specific location.
+
+
+
+
GetLocations(filters)
+
Obtain a filtered list of locations
+
Input: filters(cell array, optional) - Describes the data origin
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all locations available if None. Supported parameters are:
function r = getLocations(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'locations');
+end
+
+
GetLocationHierarchy(filters)
+
Obtain a location tree
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: struct - Location tree
+
The API endpoint is /locations/tree.
+
Return a hierarchical representation of the ONC Search Tree Nodes. The Search Tree is used in Oceans 3.0 to organize instruments and variables by location so that users can easily drill down by place name or mobile platform name to find the instruments or properties they are interested in.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all locations available if None. Supported parameters are:
function r = getLocationHierarchy(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'locations', 'method', 'getTree');
+end
+
+
+
GetDeployments(filters)
+
Obtain an array of device deployments.
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: array of structs - Deployments found
+
The API endpoint is /deployments.
+
Return all deployments defined in Oceans 3.0 which meet the filter criteria, where a deployment is the installation of a device at a location. The deployments service assists in knowing when and where specific types of data are available.
+The primary purpose for the deployments service is to find the dates and locations of deployments and use the dateFrom and dateTo datetimes when requesting a data product using the dataProductDelivery web service.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return a tree of all available locations available if None. Supported parameters are:
function r = getDeployments(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'deployments');
+end
+
+
GetDevices(filters)
+
Obtain a filtered list of devices
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: array of structs - Devices found
+
The API endpoint is /devices.
+
Return all the devices defined in Oceans 3.0 that meet a set of filter criteria.
+ Devices are instruments that have one or more sensors that observe a property or phenomenon with a goal of producing an
+ estimate of the value of a property. Devices are uniquely identified by a device code and can be deployed at multiple
+ locations during their lifespan. The primary purpose of the devices service is to find devices that have the data you are interested in
+ and use the deviceCode when requesting a data product using the dataProductDelivery web service.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all devices available if None. Supported parameters are:
function r = getDevices(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'devices');
+end
+
+
+
GetDeviceCategories(filters)
+
Obtain a filtered list of device categories
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: array of structs - Device categories found
+
The API endpoint is /deviceCategories.
+
Return all device categories defined in Oceans 3.0 that meet a filter criteria. A Device Category represents an instrument type
+classification such as CTD (Conductivity, Temperature & Depth Instrument) or BPR (Bottom Pressure Recorder).
+Devices from a category can record data for one or more properties (variables). The primary purpose of this service is to find
+device categories that have the data you want to access; the service provides the
+deviceCategoryCode you can use when requesting a data product via the dataProductDelivery web service.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all device categories available if None. Supported parameters are:
function r = getDeviceCategories(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'deviceCategories');
+end
+
+
GetProperties(filters)
+
Obtain a filtered list of properties
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: array of structs - Properties found
+
The API endpoint is /properties.
+
Return all properties defined in Oceans 3.0 that meet a filter criteria. Properties are observable phenomena (aka, variables) are the
+ common names given to sensor types (i.e., oxygen, pressure, temperature, etc).
+ The primary purpose of this service is to find the available properties of the data you want to access;
+ the service provides the propertyCode that you can use to request a data product via the dataProductDelivery web service.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all properties available if None. Supported parameters are:
function r = getProperties(this, varargin)
+ filters = this.getFilters(varargin);
+ r = this.discoveryRequest(filters, 'properties');
+end
+
+
GetDataProducts(filters)
+
Obtain a list of available data products for the filters
+
Input: filters(cell array, optional) - Describes the data origin
+
Output: array of structs - Data products found
+
The API endpoint is /dataProducts.
+
Return all data products defined in Oceans 3.0 that meet a filter criteria. Data Products are downloadable representations of ONC
+ observational data, provided in formats that can be easily ingested by analytical or visualization software. The primary purpose of this
+ service is to identify which data products and formats (file extensions) are available for the locations, devices, device categories or
+ properties of interest. Use the dataProductCode and extension when requesting a data product via the dataProductDelivery web service.
Parameters: filters(cell array, optional) - Query string parameters in the API request. Return all data products available if None. Supported parameters are:
\ No newline at end of file
diff --git a/doc/OncRealTime.html b/doc/OncRealTime.html
new file mode 100644
index 0000000..57dc933
--- /dev/null
+++ b/doc/OncRealTime.html
@@ -0,0 +1,306 @@
+
+
+
+
+ OncRealTime
+
+
+
ONC Real-time data methods
+
Contents
+
To navigate directly to a specific part of the documentation (use the internal links), right-click on the section you're interested and select "Open" or "Open in New Tab".
Contains the functionality that wraps API real-time services. To be inherited by the Onc class Near real-time (as fast as they get into our database) data access methods allow the extraction of sensor data as time-series, either as processed scalar data with Quality Assurance and Control flags (QAQC) or directly as raw data obtained from the device in its specific output format. In contrast to the Data product download methods, this data can be downloaded directly without waiting for any kind of generation process.
+
Common use cases include:
+
+
+
Plotting time series from properties in a specific time frame or in “near real-time”
+
Quickly obtaining the latest reading from a particular sensor
+
Obtaining raw unprocessed data from our instruments (data might require processing to be readable)
+
+
+
+
Note
+
+
The methods getDirectByLocation() and getDirectRawByLocation() obtain data readings from a location no matter what device it came from (hence the need to specify a device category code instead of a single device code). You might want to obtain data by location instead of by device, as individual devices are often replaced/repositioned.
+
Each request to our API can return a maximum of 100,000 samples; larger data requests must be downloaded as a sequence of pages. Use the allPages parameter to automatically download all pages required for your requested time frame.
+
+
+
GetDirectByLocation(filters, allPages)
+
Obtains scalar data from a location, from the source described by the filters
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
+
Output:
array of structs - Scalar data obtained for all sensors found
+
The API endpoint is /scalardata/location.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
function r = getDirectByLocation(this, filters, varargin)
+ [allPages] = util.param(varargin, 'allPages', false);
+ r = this.getDirectAllPages(filters, 'scalardata', 'getByLocation', allPages);
+end
+
+
GetDirectByDevice(filters, allPages)
+
Obtains scalar data from a device, as described by the filters
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
+
Output:
+
+
array of structs - Scalar data obtained for all sensors found
+
+
+
The API endpoint is /scalardata/device.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
+
function r = getDirectByDevice(this, filters, varargin)
+ [allPages] = util.param(varargin, 'allPages', false);
+ r = this.getDirectAllPages(filters, 'scalardata', 'getByDevice', allPages);
+end
+
+
GetDirectRawByLocation(filters, allPages)
+
Obtains raw data from a location, from the source described by the filters
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
Output:
+
+
array of structs - Raw data obtained for all sensors found
+
+
The API endpoint is /rawdata/location.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
+
function r = getDirectRawByLocation(this, filters, varargin)
+ [allPages] = util.param(varargin, 'allPages', false);
+ r = this.getDirectAllPages(filters, 'rawdata', 'getByLocation', allPages);
+end
+
+
GetDirectRawByDevice(filters, allPages)
+
Obtains raw data from a device, as described by the filters
+
Input:
+
+
filters(struct) - Describes the data origin
+
allPages(logical, optional) - When true, if the data requested is too large to fit a single API resquest, keep downloading data pages until we gather all data
+
+
+
Output:
+
+
array of structs - Raw data obtained for all sensors found
+
+
+
The API endpoint is /rawdata/device.
+
Parameters in filter: Query string parameters in the API request. Supported parameters are:
+
+
\ No newline at end of file
diff --git a/doc/UpdateInstruction.html b/doc/UpdateInstruction.html
new file mode 100644
index 0000000..50f3601
--- /dev/null
+++ b/doc/UpdateInstruction.html
@@ -0,0 +1,151 @@
+
+
+
+ How to update to latest version
+
+
How to update to latest version
+
When using Ocean Networks Canada API Client Library, you may get a warning about outdated version. Follow the following instruction to update to latest version.
1. Select Manage Add-Ons under Add-Ons from the HOME menu.
+
+
2. Select updates at the top, new releases of installed libraries will show below. Click update to the right of Ocean Networks Canada API Client Library.
+
+
Copyright 2024, ONC Data Team.
+
diff --git a/doc/UserDirectory.png b/doc/UserDirectory.png
new file mode 100644
index 0000000..efb1033
Binary files /dev/null and b/doc/UserDirectory.png differ
diff --git a/doc/helptoc.xml b/doc/helptoc.xml
new file mode 100644
index 0000000..4b52eb6
--- /dev/null
+++ b/doc/helptoc.xml
@@ -0,0 +1,28 @@
+
+
+
+ ONC Toolbox
+
+ How to use
+ Getting Started with this library
+ Onc class
+
+
+ Discovery Service
+
+
+ Delivery Service
+
+
+ Archive Service
+
+
+ Near Real Time Service
+
+
+ Examples/Live Scripts
+
+ How to update to latest version
+
+
+
\ No newline at end of file
diff --git a/doc/update.png b/doc/update.png
new file mode 100644
index 0000000..4d23447
Binary files /dev/null and b/doc/update.png differ
diff --git a/info.xml b/info.xml
new file mode 100644
index 0000000..3442751
--- /dev/null
+++ b/info.xml
@@ -0,0 +1,23 @@
+
+
+
+
+
+
+
+ 2022b
+
+ ONC
+
+
+ toolbox
+
+
+
+
+ doc
+
+
+
+
\ No newline at end of file
diff --git a/onc/examples/OncArchive.mlx b/onc/examples/OncArchive.mlx
new file mode 100644
index 0000000..9153fba
Binary files /dev/null and b/onc/examples/OncArchive.mlx differ
diff --git a/onc/examples/OncDeliveryDataProducts.mlx b/onc/examples/OncDeliveryDataProducts.mlx
new file mode 100644
index 0000000..9b8ffe6
Binary files /dev/null and b/onc/examples/OncDeliveryDataProducts.mlx differ
diff --git a/onc/examples/OncDiscoveryDataProducts.mlx b/onc/examples/OncDiscoveryDataProducts.mlx
new file mode 100644
index 0000000..a0de425
Binary files /dev/null and b/onc/examples/OncDiscoveryDataProducts.mlx differ
diff --git a/onc/examples/OncDiscoveryDeployments.mlx b/onc/examples/OncDiscoveryDeployments.mlx
new file mode 100644
index 0000000..21364f7
Binary files /dev/null and b/onc/examples/OncDiscoveryDeployments.mlx differ
diff --git a/onc/examples/OncDiscoveryDeviceCategories.mlx b/onc/examples/OncDiscoveryDeviceCategories.mlx
new file mode 100644
index 0000000..861e33a
Binary files /dev/null and b/onc/examples/OncDiscoveryDeviceCategories.mlx differ
diff --git a/onc/examples/OncDiscoveryDevices.mlx b/onc/examples/OncDiscoveryDevices.mlx
new file mode 100644
index 0000000..878d9aa
Binary files /dev/null and b/onc/examples/OncDiscoveryDevices.mlx differ
diff --git a/onc/examples/OncDiscoveryLocations.mlx b/onc/examples/OncDiscoveryLocations.mlx
new file mode 100644
index 0000000..e18f764
Binary files /dev/null and b/onc/examples/OncDiscoveryLocations.mlx differ
diff --git a/onc/examples/OncDiscoveryProperties.mlx b/onc/examples/OncDiscoveryProperties.mlx
new file mode 100644
index 0000000..9eeca64
Binary files /dev/null and b/onc/examples/OncDiscoveryProperties.mlx differ
diff --git a/onc/examples/OncRealTime.mlx b/onc/examples/OncRealTime.mlx
new file mode 100644
index 0000000..fa9c453
Binary files /dev/null and b/onc/examples/OncRealTime.mlx differ
+
+
+