onc-1.0.mltbx

Resolve unhandled exception with invalid parameters.

Resolved naming inconsistencies.

Added getDeployments() function.

Updated QA url from http://qaweb2.neptune.uvic.ca to https://qa.oceannetworks.ca.

Updated production url to https.

Updated orderDataProduct() function to handle estimatedProcessingTime string format

Updated downloadDataProduct() function to throttle calls using onc.callsPerSecond when downloadResultsOnly=true

Indicates whether the ONC Production server URL is used for service requests.

• Default is true.
• false is intended for internal ONC testing only.
• All non-ONC users must use true or leave blank. Non-ONC user IP addresses are blocked from accessing the Oceans 2.0 QA server.

Indicates whether verbose script messages, such as request URL and processing time information, are displayed.

• Default is false.
• True is intended for script debugging.

The path that downloaded files are saved to.

• Default is 'c:/Temp'.
• Full path will be created if it does not already exist.

The web service request timeout in seconds

• Default is 60

A comma separated list of one or more filter criteria, used to return an exclusive set of location elements from the ONC locations endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• If excluded, all locations are returned.
• Valid filters:
  • locationCode, locationName, deviceCategoryCode, deviceCode, propertyCode, dataProductCode, deploymentBegin, deploymentEnd, includeChildren
• See locations Discovery Service for more information on filter usage.

struct('locationCode','BACAX')

or

{'locationCode','BACAX'}

location[].deployments

locationName: "Axis (POD 1)"

depth: 75

description: "Depth: 985 m Latitude: 48.3167 Longitude: -126.0501 Type: Stationary platform 

               Description: Canyon axis: benthic processes, biodiversity, sediment dynamics."

hasDeviceData: "true"

locationCode: "BACAX"

hasPropertyData: "true"

dataSearchURL: "https://data.oceannetworks.ca/DataSearch?location=BACAX"

A comma separated list of one or more filter criteria, used to return an exclusive set of device elements from the ONC devices endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.

• If excluded, all devices are returned.
• Valid filters
  • deviceCode, deviceName, locationCode, deviceCategoryCode, propertyCode, dataProductCode, deploymentBegin, deploymentEnd
• See devices Discovery Service for more information on filter usage.

struct('deviceCode','NORTEKADCP9917')

or

{'deviceCode','NORTEKADCP9917'}

[]

cvTerm: [1×1 struct]

device: [1×1 struct]

uri: 'http://vocab.nerc.ac.uk/collection/L22/current/TOOL0888/'

vocabulary: 'SeaVoX Device Catalogue'

dataRating: [2×1 struct]

The starting datetime for a data rating.

• Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• datetime is represented in Coordinated Universal Time (UTC). 

dateFrom: '2008-11-01T00:00:00.000Z'

The ending datetime for a data rating.

• If None, the data rating was still in affect when the request was made.
• Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• datetime is represented in Coordinated Universal Time (UTC).

dateTo: '2010-05-27T19:27:04.000Z'

samplePeriod: 1

sampleSize: 1

deviceCode: 'BC_POD1_AD2M'

deviceId: 11302

A comma separated list of one or more filter criteria, used to return an exclusive set of deployment elements from the ONC deployments endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.

• If excluded, all deployments are returned.
• Valid filters
  • locationCode, deviceCode,deviceCategoryCode, propertyCode, begin, end.
• See devices Discovery Service for more information on filter usage.

{'deviceCode':'NORTEKADCP9917'}

deviceCode: "SBECTD19p6813"

The beginning datetime of the deployment.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• DateTime is represented in Coordinated Universal Time (UTC).

begin: '2010-07-27T00:00:00.000Z'

The ending datetime of the deployment.

• If the deployment is current, the value is null.

Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• DateTime is represented in Coordinated Universal Time (UTC).

end: '2016-08-01T00:00:00.000Z'

deployment[].hasDeviceData

hasDeviceData: 1

The latitude of the device deployment.

A comma separated list of one or more filter criteria, used to return an exclusive set of deviceCategory elements from the ONC deviceCategories endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• If excluded, all device categories are returned.
• Valid filters
  • deviceCategoryCode, deviceCategoryName, description, locationCode, propertyCode.
• See deviceCategories Discovery Service for more information on filter usage.

struct('deviceCategoryCode','HYDROPHONE')

or

{'deviceCategoryCode','HYDROPHONE'}

cvTerm: [1×1 struct]

deviceCategory: [1×1 struct]

uri: 'http://vocab.nerc.ac.uk/collection/L05/current/130/'

vocabulary: 'SeaDataNet device categories'

description: 'Conductivity Temperature (and Depth Sensor)'

deviceCategoryCode: 'CTD'

deviceCategoryName: 'CTD'

hasDeviceData: 'true'

longDescription: ' Conductivity Temperature Depth (CTD) is an abbreviated 
                   name for an instrument package that contains sensors for
                   measuring the conductivity, temperature, and pressure of
                   seawater. Salinity, sound velocity, and density are variables
                   derived from sensor measurements. CTDs can carry additional
                   instruments and sensors such as oxygen sensors, turbidity
                   sensors and fluorometers. '

A comma separated list of one or more filter criteria, used to return an exclusive set of properties elements from the ONC properties endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• If excluded, all properties are returned.
• Valid filters
  • propertyCode, propertyName, description, locationCode, deviceCategoryCode, deviceCode.
• See properties Discovery Service for more information on filter usage.

struct('propertyCode','seawatertemperature')

or

{'propertyCode','seawatertemperature'}

cvTerm: [1×1 struct]

property: []

uom: [1×1 struct]

uri: 'http://vocab.nerc.ac.uk/collection/P06/current/UPDB/'

vocabulary: 'BODC data storage units'

description: 'Pressure'

hasDeviceData: 'true'

hasPropertyData: 'true'

propertyCode: 'pressure'

propertyName: 'Pressure'

uom: 'decibar'

A comma separated list of one or more filter criteria, used to return an exclusive set of data product & extension elements from the ONC dataProducts endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• If excluded, all data products are returned.
• Valid filters
  •  dataProductCode, extension, locationCode, deviceCategoryCode, deviceCode, propertyCode.
• See dataProducts Discovery Service for more information on filter usage.

struct('dataProductCode','TSSD', ...
       'extension','json')
or
{'dataProductCode','TSSD', ...
 'extension','json'}

[]

dataProductCode: 'TSSD'

dataProductName: 'Time Series Scalar Data'

extension: 'json'

hasDeviceData: 1

hasPropertyData: 1

helpDocument: 'https://wiki.oceannetworks.ca/display/DP/1'

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• Required filters
  
  • For Site Device data request include locationCode and deviceCategoryCode.
  • For Primary Sensor level data request include locationCode and propertyCode.
  • For Sensor Level data request include locationCode, deviceCategoryCode and propertyCode.
  • For Device (all properties) data request use deviceCode.
  • For Device Property data request use deviceCode and deviceCategoryCode.
  • Include begin and end (a date range).
  • Include dataProductCode, extension and appropriate data product options.
• See locations Discovery Service, devices Discovery Service, deviceCategories Discovery Service, properties Discovery Service and dataProducts Discovery Service for available parameters (filters).

struct('locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'begin','2016-07-27T00:00:00.000Z',...
'end','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0)

or

{'locationCode','BACAX',...
'deviceCategoryCode','ADCP2MHZ',...
'dataProductCode','TSSD',...
'extension','csv',...
'begin','2016-07-27T00:00:00.000Z',...
'end','2016-08-01T00:00:00.000Z',...
'dpo_qualityControl',1,...
'dpo_resample','none',...
'dpo_dataGaps',0}

The number of times to retry the service before the function aborts.

• If excluded, the default of 100 is used.

Indicates whether the files will be downloaded or if only the URL to the file will be returned.

• false - Files are downloaded to the ONC class outPath property location.
• true - Files will not be downloaded. The download URLs are available from the url property for each downloadResult in downloadResults in the returned struct.
• If excluded, the default of false is used.

Indicates whether the metadata file associated with the data product request will be downloaded.

• false - Metadata file is not downloaded.
• true - Metadata file is downloaded.
• If excluded, the default of false is used.

The status of the download process at the request. Possible values are:

• "running" - The data product request is running on the Task server.
• "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
• "error" - An error, preventing the task execution or download from completing successfully, has occurred.

struct or array

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• Required filters
  
  • For Site Device data request include locationCode and deviceCategoryCode.
  • For Primary Sensor level data request include locationCode and propertyCode.
  • For Sensor Level data request include locationCode, deviceCategoryCode and propertyCode.
  • For Device (all properties) data request use deviceCode.
  • For Device Property data request use deviceCode and deviceCategoryCode.
  • Include begin and end (a date range).
  • Include dataProductCode, extension and appropriate data product options.
• See locations Discovery Service, devices Discovery Service, deviceCategories Discovery Service, properties Discovery Service and dataProducts Discovery Service for available parameters (filters).

struct('locationCode','BACAX',...
       'deviceCategoryCode','ADCP2MHZ',...
       'dataProductCode','TSSD',...
       'extension','csv',...
       'begin','2016-07-27T00:00:00.000Z',...
       'end','2016-08-01T00:00:00.000Z',...
       'dpo_qualityControl',1,...
       'dpo_resample','none',...
       'dpo_dataGaps',0)

or

{'locationCode','BACAX', ...
 'deviceCategoryCode','ADCP2MHZ', ...
 'dataProductCode','TSSD', ...
 'extension','csv', ...
 'begin','2016-07-27T00:00:00.000Z', ...
 'end','2016-08-01T00:00:00.000Z', ...
 'dpo_qualityControl',1, ...
 'dpo_resample','none', ...
 'dpo_dataGaps',0}

dpRequestId: 2046404

downloadTimes: {1x3 cell}

              10Mbps: 7.076623

              50Mbps: 1.4153247

              150Mbps: 0.47177488

A dataProductDelivery dpRequestId, which is returned by the dataProductDelivery service request method, or as the 'dpRequestId' property in the dpRequest returned by the requestDataProduct() method.

2046404

A dataProductDelivery dpRunId, which is returned by the dataProductDelivery service run method, or as the dpRunId property in the list returned by the runDataProduct() method.

4629218

The actual or estimated file count, which is returned from the dataProductDelivery request method.

• If there is no estimated file count, use 0.
• If excluded, the default of 0 is used.

The estimated time in seconds, to run the request on the task machine.

• Used to determine how often the dataProductDelivery service is called to determine whether the task processing is complete.
• Estimated processing time is provided by the dataProductDelivery request method.

The number of times to retry the service before the function aborts.

• If excluded, the default of 100 is used.

Determines whether the files will be downloaded or if only the URL to the file will be returned.

• false - Files are downloaded to the ONC class outPath property location.
• true - Files will not be downloaded. The download URLs are available from the url property for each downloadResult in downloadResults in the returned struct.
• If excluded, the default of false is used.

Indicates whether the metadata file associated with the data product request will be downloaded.

• false - Metadata file is not downloaded.
• true - Metadata file is downloaded.
• If excluded, the default of false is used.

true

The status of the download process at the request. Possible values are:

• "running" - The data product request is running on the Task server.
• "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
• "error" - An error, preventing the task execution or download from completing successfully, has occurred.

A comma separated list of filter criteria parameters, used to request data as a data product from the ONC dataProductDelivery endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• Required filters
  
  • For Site Device data request include locationCode and deviceCategoryCode.
  • For Primary Sensor level data request include locationCode and propertyCode.
  • For Sensor Level data request include locationCode, deviceCategoryCode and propertyCode.
  • For Device (all properties) data request use deviceCode.
  • For Device Property data request use deviceCode and deviceCategoryCode.
  • Include begin and end (a date range).
  • Include dataProductCode, extension and appropriate data product options.
• See locations Discovery Service, devices Discovery Service, deviceCategories Discovery Service, properties Discovery Service and dataProducts Discovery Service for available parameters (filters).

struct('locationCode','BACAX',...
       'deviceCategoryCode','ADCP2MHZ',...
       'dataProductCode','TSSD',...
       'extension','csv',...
       'begin','2016-07-27T00:00:00.000Z',...
       'end','2016-08-01T00:00:00.000Z',...
       'dpo_qualityControl',1,...
       'dpo_resample','none',...
       'dpo_dataGaps',0)

or

{'locationCode','BACAX', ...
 'deviceCategoryCode','ADCP2MHZ', ...
 'dataProductCode','TSSD', ...
 'extension','csv', ...
 'begin','2016-07-27T00:00:00.000Z', ...
 'end','2016-08-01T00:00:00.000Z', ...
 'dpo_qualityControl',1, ...
 'dpo_resample','none', ...
 'dpo_dataGaps',0}

The number of times to retry the service before the function aborts.

• If excluded, the default of 100 is used.

The URL to be downloaded.

https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>

&dpRunId=<YOUR_RUN_ID_HERE>&index=<YOUR_INDEX_HERE>

The full path of the file download destination.

• If excluded, the file name from the content disposition in the header is used, along with the onc class object outPath to create a full file name path.

The status of the download process at the request. Possible values are:

• "running" - The data product request is running on the Task server.
• "complete" - The data product request Task has completed and file has been downloaded or URL has been returned.
• "error" - An error, preventing the task execution or download from completing successfully, has occurred.

The URL to a JSON data product delivery result.

https://data.oceannetworks.ca/api/dataProductDelivery?method=download&token=<YOUR_TOKEN_HERE>&dpRunId=<YOUR_RUN_ID_HERE>&index=<YOUR_INDEX_HERE>

A comma separated list of filter criteria parameters, used to request data and metadata from the scalardata endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• Filters must include locationCode and deviceCategoryCode.
• Filters can optionally Include begin and end (a date range).
• See locations Discovery Service and deviceCategories Discovery Service  for more information on filter usage.

struct('locationCode','TWDP', ...

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z'}

The encoding of the response output.

• Object - Data are a list of structures with sampleTime, value and qaqcFlag for a given sensor.
• Array - Data have 3 arrays for a given sensor. Array of sampleTime, array of values and array of qaqcFlags.
• If excluded, the default 'Object' is used.

The amount of metadata detail included in the response output.

• Minimum - Provides only basic property information. Response includes serviceMetadata structure only.
• Full - Provides all property information. Response includes both metadata and serviceMetadata structures.
• If excluded, the default 'Minimum' is used.

The maximum number of rows of scalar data that will be returned for each sensor.

• Maximum is 100,000.
• If excluded, the default 100,000 is used.

The recorded time of the observation.

• Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• datetime is represented in Coordinated Universal Time (UTC).

struct

or

cell array

A comma separated list of filter criteria parameters, used to request data and metadata from the rawdata endpoint.

• A list of filter/value pairs in the following format struct('<filter_1>','<value_1>','<filter_2>','<value_2>',...) or {'<filter_1>','<value_1>','<filter_2>','<value_2>',...}.
• Filters must include locationCode and deviceCategoryCode.
• Filters can optionally Include begin and end (a date range).
• See locations Discovery Service and deviceCategories Discovery Service  for more information on filter usage.

struct('locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z')

or

{'locationCode','TWDP', ...
'deviceCategoryCode','TSG', ...
'begin','2016-09-01T00:00:00.000Z', ...
'end','2016-09-01T08:00:00.000Z'}

The maximum number of rows of raw data that will be returned

• Maximum is 100,000.
• If excluded, the default 100,000 is used.

The recorded time of the observation.

• Date Time format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'.

• datetime is represented in Coordinated Universal Time (UTC).

Whether more data are available within the range of the request. For example if 1,000 records are returned (because the rowLimit=1000), but there chould be 200,000 rows as defined by the filter criteria.

• 0 = False
• 1 = True