ADLongwell-usgs-waterdata 0.0.1

data/History.txt

@@ -0,0 +1 @@
+0.0.1 - Welcomed into the world, screaming and crying.

data/License.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2008 Aaron Longwell, Chris Tenbrink
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,12 @@
+History.txt
+init.rb
+Manifest.txt
+License.txt
+README.txt
+Rakefile
+lib/usgs.rb
+lib/usgs/gauge.rb
+lib/usgs/water_data.rb
+spec/gauge_spec.rb
+spec/spec_helper.rb
+spec/waterdata_spec.rb

data/README.txt

@@ -0,0 +1,3 @@
+README.txt
+
+The usgs-waterdata library is a tool for obtaining real-time and statistical river flow data from the United States Geological Survey's National Water Information System. It will fetch a list of all rivers for which gauge data exists along with the gauges on that river. For a particular gauge, the library will obtain the latest flow, the mean flow on all days for which data exists, and long-term statistical flow data.

data/Rakefile

@@ -0,0 +1,12 @@
+# -*- ruby -*-
+
+require 'rubygems'
+require 'hoe'
+require './lib/usgs.rb'
+
+Hoe.new('usgs-waterdata', USGS::VERSION) do |p|
+  # p.rubyforge_name = 'usgs-waterdata' # if different than lowercase project name
+  # p.developer('FIX', 'FIX@example.com')
+end
+
+# vim: syntax=Ruby

data/init.rb

@@ -0,0 +1 @@
+# Placeholder

data/lib/usgs.rb

@@ -0,0 +1,7 @@
+$:.unshift File.dirname(__FILE__)
+require 'usgs/water_data'
+require 'usgs/gauge'
+
+module USGS
+  VERSION = '0.0.1'
+end

data/lib/usgs/gauge.rb

@@ -0,0 +1,149 @@
+module USGS
+
+  require 'open-uri'
+  require 'date'
+
+  class Gauge
+
+    attr_reader :site_number
+
+    def initialize( site_number )
+      @site_number = site_number
+    end
+
+    # Determine the most recent instantaneous flow in CFS for this guage
+    def latest_flow
+      url = "http://waterdata.usgs.gov/nwis/uv?cb_00060=on&format=rdb&period=1&site_no=#{@site_number}"
+      flow = 0
+      open(url).each do |line|
+        next if line =~ /^#/
+        next if line =~ /^5/
+        next if line =~ /^agency/
+
+        fields = line.split(/\t/)
+        flow = fields[3]
+      end
+      flow
+    end
+
+    # todo: use lambda (or a similar construct) to minimize repetitive code
+
+    # Returns a 2-dimensional array of the statistical mean flows for this
+    # gauge on days for which data exists, sorted by date.
+    def get_statistical_mean_flows
+      populate_statistical_data if @statistical_mean_flows.nil? or @statistical_mean_flows.empty?
+      @statistical_mean_flows
+    end
+
+    # Returns a 2-dimensional array of the statistical median flows for this
+    # gauge on days for which data exists, sorted by date.
+    def get_statistical_median_flows
+      populate_statistical_data if @statistical_median_flows.nil? or @statistical_median_flows.empty?
+      @statistical_median_flows
+    end
+    
+    # Returns a 2-dimensional array of the statistical 80th percentile flows for this
+    # gauge on days for which data exists, sorted by date.
+    def get_statistical_percentile80_flows
+      populate_statistical_data if @statistical_percentile80_flows.nil? or @statistical_percentile80_flows.empty?
+      @statistical_percentile80_flows
+    end
+    
+    # Returns a 2-dimensional array of the statistical 20th percentile flows for this
+    # gauge on days for which data exists, sorted by date.
+    def get_statistical_percentile20_flows
+      populate_statistical_data if @statistical_percentile20_flows.nil? or @statistical_percentile20_flows.empty?
+      @statistical_percentile20_flows
+    end
+
+    # Returns a 2-dimensional array of the daily mean flows for this
+    # gauge on days for which data exists, sorted by date.
+    def get_daily_mean_flows
+      populate_daily_data if @daily_mean_flows.nil? or @daily_mean_flows.empty?
+      @daily_mean_flows
+    end
+
+    private
+
+    # Populate daily data for a gauge from the USGS site
+    def populate_daily_data
+      url = "http://waterdata.usgs.gov/nwis/dv?site_no=#{@site_number}&cb_00060=on&begin_date=1880-01-01&format=rdb"
+      mean_flows_hash = {}  
+      open(url).each do |line|
+        next if line =~ /^#/
+        next if line =~ /^5/
+        next if line =~ /^agency/
+         
+        field_array = line.split(/\t/)
+        date_array = field_array[2].split('-')
+        date = Date.new(date_array[0].to_i, date_array[1].to_i, date_array[2].to_i)
+        mean = field_array[3]
+        mean_flows_hash[date] = mean
+      end
+      @daily_mean_flows = mean_flows_hash.sort
+    end
+
+    # Populate statistical data for a gauge from the USGS site
+    def populate_statistical_data
+      url = "http://waterdata.usgs.gov/id/nwis/dvstat/?site_no=#{@site_number}&por_#{@site_number}_2=1155369,00060,2,0000-01-01,9999-01-01&start_dt=0000-01-01&end_dt=9999-01-01&format=rdb&date_format=YYYY-MM-DD"
+
+      field_map = { 
+        'agency' => 0, 
+        'site' => 1, 
+        'parameter' => 2, 
+        'dd_nu' => 3, 
+        'month_nu' => 4, 
+        'day_nu' => 5, 
+        'begin_yr' => 6, 
+        'end_yr' => 7, 
+        'count_nu' => 8, 
+        'max_va_yr' => 9, 
+        'max_va' => 10, 
+        'min_va_yr' => 11,
+        'min_va' => 12,
+        'mean_va' => 13,
+        'p05_va' => 14,      # 05 percentile of daily mean values for this day.
+        'p10_va' => 15,      # 10 percentile of daily mean values for this day.
+        'p20_va' => 16,      # 20 percentile of daily mean values for this day.
+        'p25_va' => 17,      # 25 percentile of daily mean values for this day.
+        'p50_va' => 18,      # 50 percentile (median) of daily mean values for this day.
+        'p75_va' => 19,      # 75 percentile of daily mean values for this day.
+        'p80_va' => 20,      # 80 percentile of daily mean values for this day.
+        'p90_va' => 21,      # 90 percentile of daily mean values for this day.
+        'p95_va' => 22       # 95 percentile of daily mean values for this day.
+      }
+      
+      mean_flows_hash = {}
+      median_flows_hash = {}
+      percentile20_flows_hash = {}
+      percentile80_flows_hash = {}
+      open(url).each do |line|
+        next if line =~ /^#/
+        next if line =~ /^5/
+        next if line =~ /^agency/
+        next if line =~ /^\s/
+
+        field_array = line.split(/\t/)
+        month = field_array[field_map['month_nu']]
+        day = field_array[field_map['day_nu']]
+        mean = field_array[field_map['mean_va']]
+        median = field_array[field_map['p50_va']]
+        percentile20 = field_array[field_map['p20_va']]
+        percentile80 = field_array[field_map['p80_va']]
+
+        d = Date.new(1500, month.to_i, day.to_i)
+        mean_flows_hash[d] = mean
+        median_flows_hash[d] = median
+        percentile20_flows_hash[d] = percentile20
+        percentile80_flows_hash[d] = percentile80
+      end
+
+      @statistical_mean_flows = mean_flows_hash.sort
+      @statistical_median_flows = median_flows_hash.sort
+      @statistical_percentile20_flows = percentile20_flows_hash.sort
+      @statistical_percentile80_flows = percentile80_flows_hash.sort
+    end
+  end
+end
+
+

data/lib/usgs/water_data.rb

@@ -0,0 +1,66 @@
+module USGS
+  class WaterData
+
+    class << self
+
+      def us_rivers
+        states = %w{al ar az ca co ct dc de fl ga hi ia id il in ks ky la ma md me mi mn mo ms mt nc nd ne nh nj nm nv ny oh ok or pa ri sc sd tn tx ut va vt wa wi wv wy}
+        state_rivers = {}
+        states.each do |state|
+          STDOUT.write("#{state} ") # REMOVE THIS REMOVE THIS REMOVE THIS
+          STDOUT.flush
+          state_rivers[state] = rivers_in_state(state)
+        end
+        state_rivers
+      end
+
+
+      def rivers_in_state(st)
+        require 'open-uri'
+
+        url = "http://waterdata.usgs.gov/#{st}/nwis/current/?type=flow&format=rdb"
+        rivers = {}
+
+        open(url).each do |line|
+          next if line =~ /^#/
+          next if line =~ /^5/
+          next if line =~ /^agency/
+
+          fields = line.split(/\t/)
+          station_name = fields[2]
+          name_parts = station_name.split(/\b([A-Z]+ OF|ABV|AT|NR|NEAR|DS OF|US OF|ABOVE|BELOW|BEL|BL|BLW|AB|ABV)\b/i)
+          river_name = clean_river_name(name_parts[0])
+
+          rivers[river_name] ||= []
+          rivers[river_name] << fields[1]
+        end
+
+        rivers
+      end
+
+
+      # Given a river name from the USGS site, a clean and 
+      # normalized river name is returned.
+      #
+      def clean_river_name(river_name)
+        val = river_name.strip.downcase.gsub(/\b('?[a-z])/) { $1.capitalize }
+        val.gsub!(/d'?\s*alene/i, "d'Alene")
+        val.gsub!(/[^A-Za-z' ]/, '')
+        val.gsub!(/\bSf\b/, 'South Fork')
+        val.gsub!(/\bMf\b/, 'Middle Fork')
+        val.gsub!(/\bNf\b/, 'North Fork')
+        val.gsub!(/\bDiv\b/, 'Diversion')
+        val.gsub!(/\bCrk?\b/, 'Creek')
+        val.gsub!(/\bC\b/, 'Creek')
+        val.gsub!(/\bR\b/, 'River')
+        val.gsub!(/\bBra?(nch)?\b/, 'Branch')
+        val.gsub!(/\bRvr\b/, 'River')
+        val.gsub!(/\bTrib\b/, 'Tributary')
+        val.gsub!(/\bSprngs\b/, 'Springs')
+        val
+      end
+
+    end
+    
+  end
+end

data/spec/gauge_spec.rb

@@ -0,0 +1,51 @@
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
+
+describe USGS::Gauge do
+
+  it 'should get mean flow data for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    mean_flow = gauge.get_statistical_mean_flows
+    mean_flow.each do |record|
+      puts "Mean flow for the Selway River on #{record[0].strftime("%d %b")} is #{record[1]} CFS"
+    end
+  end
+
+  it 'should get median flow data for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    median_flow = gauge.get_statistical_median_flows
+    median_flow.each do |record|
+      puts "Median flow for the Selway River on #{record[0].strftime("%d %b")} is #{record[1]} CFS"
+    end
+  end
+
+  it 'should get 80th percentile flow data for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    percentile80_flow = gauge.get_statistical_percentile80_flows
+    percentile80_flow.each do |record|
+      puts "80th percentile flow for the Selway River on #{record[0].strftime("%d %b")} is #{record[1]} CFS"
+    end
+  end
+
+  it 'should get 20th percentile flow data for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    percentile20_flow = gauge.get_statistical_percentile20_flows
+    percentile20_flow.each do |record|
+      puts "20th percentile flow for the Selway River on #{record[0].strftime("%d %b")} is #{record[1]} CFS"
+    end
+  end
+
+  it 'should get daily mean flows for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    daily_mean_flows = gauge.get_daily_mean_flows
+    daily_mean_flows.each do |record|
+      puts "Daily mean flow for the Selway River on #{record[0].strftime("%d %b %Y")} is #{record[1]} CFS"
+    end
+  end
+
+  it 'should get the current flow for a river' do
+    gauge = USGS::Gauge.new(13336500)
+    puts "Latest flow for the Selway River is #{gauge.latest_flow} CFS"
+  end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,2 @@
+require 'spec'
+require File.dirname(__FILE__) + '/../lib/usgs'

data/spec/waterdata_spec.rb

@@ -0,0 +1,15 @@
+require File.expand_path(File.dirname(__FILE__) + "/spec_helper")
+
+describe USGS::WaterData do
+
+  it 'should retrieve data' do
+    USGS::WaterData.us_rivers.each do |state, rivers|
+      puts "#{state}"
+      puts '-' * 60
+      rivers.each do |river_name, gauge_ids|
+        puts " * #{river_name} => #{gauge_ids.join(', ')}"
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification 
+name: ADLongwell-usgs-waterdata
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Aaron Longwell
+- Chris Tenbrink
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-10-16 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: A library for obtaining statistical and real-time flows from the Unite States Geological Survey's National Water Information System
+email: ctenbrink@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- History.txt
+- Manifest.txt
+- README.txt
+files: 
+- History.txt
+- init.rb
+- Manifest.txt
+- License.txt
+- README.txt
+- Rakefile
+- lib/usgs.rb
+- lib/usgs/gauge.rb
+- lib/usgs/water_data.rb
+has_rdoc: true
+homepage: http://github.com/ADLongwell/usgs-waterdata
+post_install_message: 
+rdoc_options: 
+- --main
+- README.txt
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Library for obtaining river flow data.
+test_files: 
+- spec/gauge_spec.rb
+- spec/spec_helper.rb
+- spec/waterdata_spec.rb