Module: Cdss::Telemetry

Includes:
Utils
Included in:
Client
Defined in:
lib/cdss/telemetry.rb

Overview

Provides methods for accessing telemetry station data from the CDSS API.

This module includes functionality for retrieving telemetry stations and their associated time series data.

Instance Method Summary collapse

Methods included from Utils

#batch_dates, #build_query, #fetch_paginated_data, #format_date, #format_query_param, #parse_timestamp, #safe_float, #safe_integer

Instance Method Details

#get_telemetry_stations(aoi: nil, radius: nil, abbrev: nil, county: nil, division: nil, gnis_id: nil, usgs_id: nil, water_district: nil, wdid: nil) ⇒ Array<Station>

Fetches telemetry stations based on various filtering criteria.

Examples:

Fetch stations in Denver county

get_telemetry_stations(county: 'Denver')

Fetch stations within 10 miles of a point

get_telemetry_stations(aoi: { latitude: 39.7392, longitude: -104.9903 }, radius: 10)

Parameters:

  • aoi (Hash, Array, nil) (defaults to: nil) —

    Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys. If array, must contain [longitude, latitude].

  • radius (Integer, nil) (defaults to: nil) —

    Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.

  • abbrev (String, nil) (defaults to: nil) —

    Station abbreviation to filter by.

  • county (String, nil) (defaults to: nil) —

    County name to filter stations.

  • division (Integer, nil) (defaults to: nil) —

    Water division number to filter stations.

  • gnis_id (String, nil) (defaults to: nil) —

    GNIS ID to filter by.

  • usgs_id (String, nil) (defaults to: nil) —

    USGS station ID to filter by.

  • water_district (Integer, nil) (defaults to: nil) —

    Water district number to filter by.

  • wdid (String, nil) (defaults to: nil) —

    WDID to filter by.

Returns:

  • (Array<Station>) —

    Array of matching telemetry station objects.

Raises:

  • (ArgumentError) —

    If aoi parameter is provided but invalid.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/cdss/telemetry.rb', line 29

def get_telemetry_stations(aoi: nil, radius: nil, abbrev: nil, county: nil, division: nil, gnis_id: nil,
                           usgs_id: nil, water_district: nil, wdid: nil)
  query = {
    format: "json",
    dateFormat: "spaceSepToSeconds",
    includeThirdParty: true,
    abbrev: abbrev,
    county: county,
    division: division,
    gnisId: gnis_id,
    usgsStationId: usgs_id,
    waterDistrict: water_district,
    wdid: wdid
  }

  if aoi
    if aoi.is_a?(Hash) && aoi[:latitude] && aoi[:longitude]
      query.merge!(longitude: aoi[:longitude], latitude: aoi[:latitude])
    elsif aoi.is_a?(Array) && aoi.count == 2
      query.merge!(longitude: aoi[0], latitude: aoi[1])
    else
      raise ArgumentError, "Invalid 'aoi' parameter"
    end
    query[:radius] = radius || 20
    query[:units] = "miles"
  end

  fetch_paginated_data(
    endpoint: "/telemetrystations/telemetrystation/",
    query: query
  ) { |data| Parser.parse_stations(data) }
end

#get_telemetry_ts(abbrev:, parameter: "DISCHRG", start_date: nil, end_date: nil, timescale: "day", include_third_party: true) ⇒ Array<Reading>

Fetches telemetry time series data for specified stations.

Examples:

Fetch daily discharge data for a station

get_telemetry_ts(abbrev: 'PLACHECO', parameter: 'DISCHRG', start_date: Date.new(2023, 1, 1))

Parameters:

  • abbrev (String) —

    Station abbreviation.

  • parameter (String, nil) (defaults to: "DISCHRG") —

    Telemetry parameter to retrieve. Defaults to ‘DISCHRG’.

  • start_date (Date, nil) (defaults to: nil) —

    Start date for time series data.

  • end_date (Date, nil) (defaults to: nil) —

    End date for time series data.

  • timescale (String, nil) (defaults to: "day") —

    Time interval for data. Valid values: ‘day’, ‘hour’, ‘raw’.

  • include_third_party (Boolean) (defaults to: true) —

    Whether to include third-party data. Defaults to true.

Returns:

  • (Array<Reading>) —

    Array of time series reading objects.

Raises:

  • (ArgumentError) —

    If an invalid timescale is provided.



74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/cdss/telemetry.rb', line 74

def get_telemetry_ts(abbrev:, parameter: "DISCHRG", start_date: nil, end_date: nil, timescale: "day",
                     include_third_party: true)
  timescales = %w[day hour raw]
  unless timescales.include?(timescale)
    raise ArgumentError, "Invalid 'timescale' argument: '#{timescale}'. Valid values are: #{timescales.join(', ')}"
  end

  query = {
    format: "json",
    dateFormat: "spaceSepToSeconds",
    abbrev: abbrev,
    parameter: parameter,
    includeThirdParty: include_third_party.to_s
  }

  query[:startDate] = start_date&.strftime("%m-%d-%Y") if start_date
  query[:endDate] = end_date&.strftime("%m-%d-%Y") if end_date

  fetch_paginated_data(
    endpoint: "/telemetrystations/telemetrytimeseries#{timescale}/",
    query: query
  ) { |data| Parser.parse_readings(data, timescale: timescale.to_sym) }
end