cdss-ruby 0.1.0

data/lib/cdss/parser.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Cdss
+  # The Parser class handles parsing of response data from the CDSS API into domain objects.
+  # It delegates the actual parsing work to specialized parser modules for each data type.
+  class Parser
+    class << self
+      # Parses station data from the API response.
+      #
+      # @param response [Hash] The API response containing station data.
+      # @return [Array<Station>] Array of Station objects representing telemetry or surface water stations.
+      # @example Parse stations from API response
+      #   stations = Parser.parse_stations(response_data)
+      def parse_stations(response)
+        Parsers::StationParser.parse_stations(response)
+      end
+
+      # Parses time series readings from the API response.
+      #
+      # @param response [Hash] The API response containing reading data.
+      # @param timescale [Symbol] The timescale of the readings (:day, :month, :year, :raw, :hour).
+      # @return [Array<Reading>] Array of Reading objects with time series data.
+      # @raise [ArgumentError] If an invalid timescale is provided.
+      # @example Parse daily readings
+      #   readings = Parser.parse_readings(response_data, timescale: :day)
+      def parse_readings(response, timescale:)
+        Parsers::ReadingParser.parse_readings(response, timescale: timescale)
+      end
+
+      # Parses well data from the API response.
+      #
+      # @param response [Hash] The API response containing well data.
+      # @return [Array<Well>] Array of Well objects with basic well information.
+      # @example Parse wells from response
+      #   wells = Parser.parse_wells(response_data)
+      def parse_wells(response)
+        Parsers::WellParser.parse_wells(response)
+      end
+
+      # Parses well measurement data from the API response.
+      #
+      # @param response [Hash] The API response containing well measurement data.
+      # @return [Array<Reading>] Array of Reading objects containing well measurements.
+      # @example Parse well measurements
+      #   measurements = Parser.parse_well_measurements(response_data)
+      def parse_well_measurements(response)
+        Parsers::WellParser.parse_well_measurements(response)
+      end
+
+      # Parses geophysical well data from the API response.
+      #
+      # @param response [Hash] The API response containing geophysical well data.
+      # @return [Array<Well>] Array of Well objects with geophysical well information.
+      # @example Parse geophysical wells
+      #   geo_wells = Parser.parse_geophysical_wells(response_data)
+      def parse_geophysical_wells(response)
+        Parsers::WellParser.parse_geophysical_wells(response)
+      end
+
+      # Parses geophysical log pick data from the API response.
+      #
+      # @param response [Hash] The API response containing log pick data.
+      # @return [Array<Reading>] Array of Reading objects containing log pick information.
+      # @example Parse log picks for a well
+      #   picks = Parser.parse_log_picks(response_data)
+      def parse_log_picks(response)
+        Parsers::WellParser.parse_log_picks(response)
+      end
+
+      # Parses water rights data from the API response.
+      #
+      # @param response [Hash] The API response containing water rights data.
+      # @param type [Symbol] The type of water rights data to parse (:net_amount or :transaction).
+      # @return [Array<WaterRight>] Array of WaterRight objects.
+      # @raise [ArgumentError] If an invalid water rights type is provided.
+      # @example Parse net amounts
+      #   rights = Parser.parse_water_rights(response_data, type: :net_amount)
+      # @example Parse transactions
+      #   transactions = Parser.parse_water_rights(response_data, type: :transaction)
+      def parse_water_rights(response, type:)
+        Parsers::WaterRightsParser.parse_water_rights(response, type: type)
+      end
+
+      # Parses climate station data from the API response.
+      #
+      # @param response [Hash] The API response containing climate station data.
+      # @return [Array<ClimateStation>] Array of climate station objects.
+      def parse_climate_stations(response)
+        Parsers::ClimateParser.parse_climate_stations(response)
+      end
+
+      # Parses climate reading data from the API response.
+      #
+      # @param response [Hash] The API response containing climate readings.
+      # @param type [Symbol] The type of climate reading (:frost_dates, :daily, or :monthly).
+      # @return [Array<Reading>] Array of climate reading objects.
+      # @raise [ArgumentError] If an invalid reading type is provided.
+      def parse_climate_readings(response, type:)
+        Parsers::ClimateParser.parse_climate_readings(response, type: type)
+      end
+
+      # Parses administrative calls data from the API response.
+      #
+      # @param response [Hash] The API response containing administrative calls data.
+      # @return [Array<AdminCall>] Array of administrative call objects.
+      # @example Parse admin calls from response
+      #   calls = Parser.parse_admin_calls(response_data)
+      def parse_admin_calls(response)
+        Parsers::AdminCallsParser.parse_admin_calls(response)
+      end
+
+      # Parses call analysis data from the API response.
+      #
+      # @param response [Hash] The API response containing call analysis data.
+      # @param type [Symbol] The type of analysis (:wdid or :gnis).
+      # @return [Array<CallAnalysis>] Array of call analysis objects.
+      # @raise [ArgumentError] If an invalid analysis type is provided.
+      def parse_call_analyses(response, type:)
+        Parsers::AnalysisParser.parse_call_analyses(response, type: type)
+      end
+
+      # Parses source route framework data from the API response.
+      #
+      # @param response [Hash] The API response containing source route data.
+      # @return [Array<SourceRoute>] Array of source route objects.
+      def parse_source_routes(response)
+        Parsers::AnalysisParser.parse_source_routes(response)
+      end
+
+      # Parses route analysis data from the API response.
+      #
+      # @param response [Hash] The API response containing route analysis data.
+      # @return [Array<RouteAnalysis>] Array of route analysis objects.
+      def parse_route_analyses(response)
+        Parsers::AnalysisParser.parse_route_analyses(response)
+      end
+
+      # Parses structure data from the API response.
+      #
+      # @param response [Hash] The API response containing structure data.
+      # @return [Array<Cdss::Models::Structure>] Array of structure objects.
+      def parse_structures(response)
+        Parsers::StructuresParser.parse_structures(response)
+      end
+
+      # Parses diversion record data from the API response.
+      #
+      # @param response [Hash] The API response containing diversion record data.
+      # @param type [Symbol] The type of record (:day, :month, :year, or :stage_volume).
+      # @return [Array<Cdss::Models::DiversionRecord>] Array of diversion record objects.
+      def parse_diversion_records(response, type:)
+        Parsers::StructuresParser.parse_diversion_records(response, type: type)
+      end
+
+      # Parses water class data from the API response.
+      #
+      # @param response [Hash] The API response containing water class data.
+      # @return [Array<Cdss::Models::WaterClass>] Array of water class objects.
+      def parse_water_classes(response)
+        Parsers::StructuresParser.parse_water_classes(response)
+      end
+
+      # Parses reference table data from the API response.
+      #
+      # @param response [Hash] The API response containing reference table data.
+      # @return [Array<Cdss::Models::ReferenceTable>] Array of reference table objects.
+      def parse_reference_table(response)
+        Parsers::ReferenceTablesParser.parse_reference_table(response)
+      end
+    end
+  end
+end

data/lib/cdss/parsers/admin_calls_parser.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module AdminCallsParser
+      extend BaseParser
+      class << self
+        def parse_admin_calls(response)
+          parse_collection(response) { |data| build_call(data) }
+        end
+
+        private
+
+        def build_call(data)
+          Cdss::Models::AdminCall.new(
+            call_number: data["callNumber"]&.to_i,
+            call_type: data["callType"],
+            date_time_set: parse_timestamp(data["dateTimeSet"]),
+            date_time_released: parse_timestamp(data["dateTimeReleased"]),
+            water_source_name: data["waterSourceName"],
+            location_wdid: data["locationWdid"],
+            location_wdid_streammile: data["locationWdidStreammile"]&.to_f,
+            location_structure_name: data["locationStructureName"],
+            priority_wdid: data["priorityWdid"],
+            priority_structure_name: data["priorityStructureName"],
+            priority_admin_number: data["priorityAdminNumber"]&.to_f,
+            priority_order_number: data["priorityOrderNumber"]&.to_i,
+            priority_date: parse_timestamp(data["priorityDate"]),
+            priority_number: data["priorityNumber"]&.to_i,
+            bounding_wdid: data["boundingWdid"],
+            bounding_structure_name: data["boundingStructureName"],
+            set_comments: data["setComments"],
+            release_comment: data["releaseComment"],
+            division: data["division"]&.to_i,
+            location_structure_latitude: data["locationStructureLatitude"]&.to_f,
+            location_structure_longitude: data["locationStructureLongitude"]&.to_f,
+            bounding_structure_latitude: data["boundingStructureLatitude"]&.to_f,
+            bounding_structure_longitude: data["boundingStructureLongitude"]&.to_f,
+            modified: parse_timestamp(data["modified"]),
+            more_information: data["moreInformation"],
+            metadata: {}
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/analysis_parser.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module AnalysisParser
+      class << self
+        def parse_call_analyses(response, type:)
+          parse_collection(response) do |data|
+            params = build_call_analysis_params(data, type)
+            Cdss::Models::CallAnalysis.new(**params)
+          end
+        end
+
+        def parse_source_routes(response)
+          parse_collection(response) do |data|
+            params = build_source_route_params(data)
+            Cdss::Models::SourceRoute.new(**params)
+          end
+        end
+
+        def parse_route_analyses(response)
+          parse_collection(response) do |data|
+            params = build_route_analysis_params(data)
+            Cdss::Models::RouteAnalysis.new(**params)
+          end
+        end
+
+        private
+
+        def parse_collection(response, &block)
+          return [] unless response && response["ResultList"]
+
+          response["ResultList"].map(&block)
+        end
+
+        def parse_timestamp(value)
+          return nil if value.nil? || value.to_s.empty?
+
+          DateTime.parse(value)
+        rescue StandardError
+          nil
+        end
+
+        def safe_float(value)
+          Float(value)
+        rescue StandardError
+          nil
+        end
+
+        def safe_integer(value)
+          Integer(value)
+        rescue StandardError
+          nil
+        end
+
+        def build_call_analysis_params(data, _type)
+          return {} unless data
+
+          {
+            analysis_date: parse_timestamp(data["analysisDate"]),
+            wdid: data["analysisWdid"],
+            admin_number: safe_float(data["analysisWrAdminNo"]),
+            percent_time_out_of_priority: safe_float(data["analysisOutOfPriorityPercentOfDay"]),
+            downstream_call_wdid: data["locationWdid"],
+            downstream_call_right: data["priorityStructure"],
+            downstream_call_stream_mile: safe_float(data["locationWdidStreamMile"]),
+            downstream_call_admin_number: safe_float(data["priorityAdminNo"]),
+            downstream_call_decreed_amount: nil,
+            downstream_call_decreed_unit: nil,
+            downstream_call_appropriation_date: parse_timestamp(data["priorityDate"]),
+            downstream_call_status: data["callType"],
+            modified: parse_timestamp(data["dateTimeSet"]),
+            metadata: {
+              division: safe_integer(data["division"]),
+              date_time_released: parse_timestamp(data["dateTimeReleased"]),
+              water_source_name: data["waterSourceName"],
+              location_structure: data["locationStructure"],
+              priority_order_no: safe_integer(data["priorityOrderNo"]),
+              priority_no: data["priorityNo"],
+              bounding_wdid: data["boundingWdid"],
+              bounding_structure_name: data["boundingStructureName"],
+              set_comments: data["setComments"],
+              release_comment: data["releaseComment"]
+            }
+          }.compact
+        end
+
+        def build_source_route_params(data)
+          return {} unless data
+
+          {
+            gnis_id: data["gnisId"],
+            gnis_name: data["gnisName"],
+            division: safe_integer(data["division"]),
+            water_district: safe_integer(data["waterDistrict"]),
+            stream_length: safe_float(data["streamLength"]),
+            tributary_to_level: safe_integer(data["tributaryToLevel"]),
+            tributary_to_gnis_id: data["TributaryToGnisId"],
+            tributary_gnis_name: data["tribGnisName"],
+            tributary_to_stream_mile: safe_float(data["tributaryToStreamMile"]),
+            metadata: {}
+          }.compact
+        end
+
+        def build_route_analysis_params(data)
+          return {} unless data
+
+          {
+            wdid: data["wdid"],
+            structure_name: data["structureName"],
+            stream_mile: safe_float(data["streamMile"]),
+            structure_type: data["structureType"],
+            decreed_amount: safe_float(data["decreedAmount"]),
+            decreed_unit: data["decreedUnit"],
+            appropriation_date: parse_timestamp(data["appropriationDate"]),
+            admin_number: safe_float(data["adminNo"]),
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          }.compact
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/base_parser.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module BaseParser
+      include Utils
+      def parse_collection(response, &block)
+        return [] unless response["ResultList"]
+
+        if block_given?
+          response["ResultList"].map(&block)
+        else
+          response["ResultList"].map { |data| build_resource(data) }
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/climate_parser.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module ClimateParser
+      extend BaseParser
+
+      class << self
+        def parse_climate_stations(response)
+          parse_collection(response) { |data| build_station(data) }
+        end
+
+        def parse_climate_readings(response, type:)
+          parse_collection(response) { |data| build_reading(data, type) }
+        end
+
+        private
+
+        def build_station(data)
+          Cdss::Models::ClimateStation.new(
+            station_number: data["stationNum"],
+            station_name: data["stationName"],
+            site_id: data["siteId"],
+            division: data["division"]&.to_i,
+            water_district: data["waterDistrict"]&.to_i,
+            county: data["county"],
+            state: data["state"],
+            latitude: data["latitude"]&.to_f,
+            longitude: data["longitude"]&.to_f,
+            utm_x: data["utmX"]&.to_f,
+            utm_y: data["utmY"]&.to_f,
+            elevation: data["elevation"]&.to_f,
+            data_source: data["dataSource"],
+            start_date: parse_timestamp(data["startDate"]),
+            end_date: parse_timestamp(data["endDate"]),
+            modified: parse_timestamp(data["modified"]),
+            more_information: data["moreInformation"],
+            parameter_types: data["parameterTypes"],
+            metadata: {}
+          )
+        end
+
+        def build_reading(data, type)
+          base_params = {
+            station_number: data["stationNum"],
+            site_id: data["siteId"],
+            parameter: data["measType"],
+            data_source: data["dataSource"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          }
+
+          case type
+          when :frost_dates
+            base_params.merge!(
+              cal_year: data["calYear"]&.to_i,
+              spring_frost_date: parse_timestamp(data["springFrostDate"]),
+              fall_frost_date: parse_timestamp(data["fallFrostDate"]),
+              frost_date_28f_spring: parse_timestamp(data["l28s"]),
+              frost_date_28f_fall: parse_timestamp(data["f28s"]),
+              frost_date_32f_spring: parse_timestamp(data["l32s"]),
+              frost_date_32f_fall: parse_timestamp(data["f32f"])
+            )
+          when :daily
+            base_params.merge!(
+              meas_date: parse_timestamp(data["measDate"]),
+              value: data["value"]&.to_f,
+              flag: data["flag"],
+              units: data["units"]
+            )
+          when :monthly
+            base_params.merge!(
+              cal_year: data["calYear"]&.to_i,
+              cal_month: data["calMonth"]&.to_i,
+              value: data["value"]&.to_f,
+              flag: data["flag"],
+              units: data["units"]
+            )
+          end
+
+          Cdss::Models::Reading.new(**base_params)
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/reading_parser.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module ReadingParser
+      extend BaseParser
+
+      class << self
+        def parse_readings(response, timescale:)
+          parse_collection(response) { |data| build_reading(data, timescale) }
+        end
+
+        private
+
+        def build_reading(data, timescale)
+          params = build_base_params(data)
+          add_timescale_params(params, data, timescale)
+          Cdss::Models::Reading.new(**params)
+        end
+
+        def build_base_params(data)
+          {
+            station_num: data["stationNum"],
+            abbrev: data["abbrev"],
+            parameter: data["parameter"],
+            usgs_site_id: data["usgsSiteId"],
+            meas_type: data["measType"],
+            meas_unit: data["measUnit"],
+            meas_count: safe_integer(data["measCount"]),
+            meas_value: safe_float(data["measValue"]),
+            meas_date: parse_timestamp(data["measDate"]),
+            meas_date_time: parse_timestamp(data["measDateTime"]),
+            data_source: data["dataSource"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          }
+        end
+
+        def add_timescale_params(params, data, timescale)
+          case timescale
+          when :day then add_day_params(params, data)
+          when :month then add_month_params(params, data)
+          when :year, :water_year then add_year_params(params, data)
+          when :raw, :hour then add_raw_params(params, data)
+          else
+            raise ArgumentError, "Invalid timescale: #{timescale}"
+          end
+        end
+
+        def add_day_params(params, data)
+          params[:value] = safe_float(data["value"])
+          params[:flags] = {
+            flagA: data["flagA"],
+            flagB: data["flagB"],
+            flagC: data["flagC"],
+            flagD: data["flagD"]
+          }
+        end
+
+        def add_month_params(params, data)
+          params.merge!(
+            cal_year: safe_integer(data["calYear"]),
+            cal_month_num: safe_integer(data["calMonNum"]),
+            min_q_cfs: safe_float(data["minQCfs"]),
+            max_q_cfs: safe_float(data["maxQCfs"]),
+            avg_q_cfs: safe_float(data["avgQCfs"]),
+            total_q_af: safe_float(data["totalQAf"])
+          )
+        end
+
+        def add_year_params(params, data)
+          params.merge!(
+            water_year: safe_integer(data["waterYear"]),
+            min_q_cfs: safe_float(data["minQCfs"]),
+            max_q_cfs: safe_float(data["maxQCfs"]),
+            avg_q_cfs: safe_float(data["avgQCfs"]),
+            total_q_af: safe_float(data["totalQAf"])
+          )
+        end
+
+        def add_raw_params(params, data)
+          params[:flags] = {
+            flagA: data["flagA"],
+            flagB: data["flagB"]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/reference_tables_parser.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module ReferenceTablesParser
+      extend BaseParser
+
+      class << self
+        def parse_reference_table(response)
+          parse_collection(response) { |data| build_reference(data) }
+        end
+
+        private
+
+        def build_reference(data)
+          Models::ReferenceTable.new(
+            name: data["name"],
+            code: data["code"],
+            description: data["description"],
+            division: safe_integer(data["division"]),
+            water_district: safe_integer(data["waterDistrict"]),
+            water_district_name: data["waterDistrictName"],
+            division_name: data["divisionName"],
+            county: data["county"],
+            management_district: data["managementDistrict"],
+            management_district_name: data["managementDistrictName"],
+            designated_basin: data["designatedBasin"],
+            designated_basin_name: data["designatedBasinName"],
+            parameter: data["parameter"] || data["measType"],
+            flag: data["flag"],
+            flag_column: data["flagColumn"],
+            divrectype: data["divRecType"],
+            div_rec_type_long: data["divRecTypeLong"],
+            additional_info: data["additionalInfo"],
+            data_source: data["dataSource"],
+            publication_name: data["publicationName"],
+            action_name: data["actionName"],
+            action_descr: data["actionDescr"],
+            ciu_code: data["ciuCode"],
+            ciu_code_long: data["ciuCodeLong"],
+            obs_code: data["obsCode"],
+            obs_code_long: data["obsCodeLong"],
+            obs_descr: data["obsDescr"],
+            start_iyr: safe_integer(data["startIyr"]),
+            end_iyr: safe_integer(data["endIyr"]),
+            not_used_code: data["notUsedCode"],
+            not_used_code_descr: data["notUsedCodeDescr"],
+            submission_type: data["submissionType"],
+            metadata: {}
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/station_parser.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module StationParser
+      extend BaseParser
+
+      class << self
+        def parse_stations(response)
+          parse_collection(response)
+        end
+
+        private
+
+        def build_resource(data)
+          Cdss::Models::Station.new(
+            station_num: data["stationNum"],
+            abbrev: data["abbrev"],
+            usgs_site_id: data["usgsSiteId"],
+            name: data["stationName"],
+            agency: data["dataSource"],
+            latitude: data["latitude"],
+            longitude: data["longitude"],
+            division: data["division"],
+            water_district: data["waterDistrict"],
+            county: data["county"],
+            state: data["state"],
+            utm_x: data["utmX"],
+            utm_y: data["utmY"],
+            location_accuracy: data["locationAccuracy"],
+            start_date: parse_timestamp(data["startDate"]),
+            end_date: parse_timestamp(data["endDate"]),
+            modified: parse_timestamp(data["modified"]),
+            more_information: data["moreInformation"],
+            meas_unit: data["measUnit"],
+            metadata: {}
+          )
+        end
+      end
+    end
+  end
+end