knmi 0.2.0 → 0.3.0

data/README.mkdn

@@ -0,0 +1,193 @@
+knmi
+====
+
+Ruby API to access Royal Netherlands Meteorological Institute daily climate data
+Access climatological data as provided by the Royal Netherlands Meteorological Institute through the http get forms for daily and hourly data
+
+* http://www.knmi.nl/climatology/daily_data/getdata_day.cgi
+* http://www.knmi.nl/klimatologie/uurgegevens/getdata_uur.cgi
+
+This gem was constructed using information from the KNMI climate data pages here.
+
+* Hourly data (Dutch) - http://www.knmi.nl/klimatologie/uurgegevens/scriptxs-nl.html#uur
+* Daily data (English) - http://www.knmi.nl/climatology/daily_data/scriptxs-en.html
+* Select Data with a form, listed below are links to metadata about each station http://www.knmi.nl/climatology/daily_data/selection.cgi
+
+Installation
+------------
+	gem install httparty
+	gem install geokit
+	
+	gem install knmi
+
+Example Usage
+-------------
+
+# Quick Script
+
+  require 'knmi'
+
+  station = KNMI.station_by_id(235)
+  parameter = KNMI.parameters(period = "daily", params = nil, categories = ["TEMP", "WIND"])
+  starts = Time.utc(2010, 6, 28) # 2010 April 28th
+  ends = Time.utc(2010, 6, 29) # 2010 April 29th
+  request = KNMI.get_data(station, parameter, starts, ends)
+  data = KNMI::Calculations.convert(request.data)
+
+# Elaborated Script
+
+  require 'knmi'
+
+  # Get station object by station ID
+  station = KNMI.station_by_id(235)
+
+  station
+  #=> #<KNMI::Station:0x0000010133c938> # A struct object
+
+  # Available Instance Variables
+  station.instance_variables
+  #=> [:@id, :@name, :@elevation, :@photo, :@map, :@web, :@instrumentation, :@coordinates]
+  station.id
+  #=> 235
+  station.name
+  #=>"De kooy"
+  station.coordinates
+  #=> 52.924,4.785
+
+
+  # Get parameter object at the time interval you wish to use "hourly" or "daily"
+  # Params can be a single term or an array of terms such as "TG" or ["TG", TX]
+  # Categories can be a single term or an array of terms such as "WIND" or ["WIND", "TEMP"]
+  parameters = KNMI.parameters(period = "daily", params = nil, categories = ["TEMP", "WIND"])
+
+  parameters # returns an array of parameter objects
+  #=> [#<KNMI::Parameters:0x000001011387e0 @parameter="TX", @category="TEMP", @description="Maximum Temperature", @validate="n.integer?", @conversion="n / 10", @units="C", @period="daily">]
+
+  # Available Instance Variables
+  parameters[0].instance_variables
+  #=>[:@parameter, :@category, :@description, :@validate, :@conversion, :@units, :@period]
+
+  parameters[0].parameter
+  #=> "TX"
+
+
+  # Define Time period of interest
+  starts = Time.utc(2010, 6, 28) 	# 2010 April 28th
+  ends = Time.utc(2010, 7, 01) 		# 2010 April 29th
+
+  # Get Data using previously retrieved objects
+  request = KNMI.get_data(station, parameters, starts, ends)
+
+  # Available Instance Variables
+  request.instance_variables
+  #=> [:@query, :@data]
+
+  request.query
+  #=>["stns=235", "vars=TX", "start=20100628", "end=20100629"]
+
+  request.data
+  #=>[{:STN=>"235", :YYYYMMDD=>"20100628", :TX=>"263"}, {:STN=>"235", :YYYYMMDD=>"20100629", :TX=>"225"}]
+
+  request.data[0]
+  #=>{:STN=>"235", :YYYYMMDD=>"20100628", :TX=>"263"}
+
+
+  # Convert data from storage format to operating format
+  data = KNMI.convert(parameters, request)
+
+Available Parameters
+--------------------
+All available recorded parameters can be found in the file .data/data_key.yml 
+This file contains the parameter name, category, description, a script to validate the data, a script to convert the data to to appropriate units, units, and the appropriate period.
+
+Daily Data
+----------
+|Parameter|Category|Description|
+|:--------|:-------|:----------|
+|YYYYMMDD |        | Time Stamp|
+|DDVEC    |WIND    | Wind Direction |
+|FHVEC    |WIND    | Vector Mean Wind Speed|
+|FG   |WIND    | Daily Mean Wind Speed|
+|FHX    |WIND    | Maximum Hourly Mean Windspeed|
+|FHXH   |WIND    | Hourly Division  at Which Maximum Wind Speed Was Measured|
+|FHN    |WIND    | Minimum Hourly Mean Windspeed|
+|FHNH   |WIND    | Hourly Division  at Which Minimum Wind Speed Was Measured|
+|FXX    |WIND    | Maximum Instantaneous Wind Speed|
+|FXXH   |WIND    | Hourly Division  at Which Maximum Instantaneous Wind Speed Was Measured|
+|TG   |TEMP    | Daily Mean Temperature|
+|TN   |TEMP    | Minimum Temperature|
+|TNH    |TEMP    | Hourly Division in Which Minimum Temperature Was Measured|
+|TX   |TEMP    | Maximum Temperature|
+|TXH    |TEMP    | Hourly Division in Which Maximum Temperature Was Measured|
+|T10N   |TEMP    | Minimum Temperature at 10 Cm Above Surface|
+|T10NH    |TEMP    | Six Hourly Division at Which Minimum Temperature at 10 Cm Above Surface Was Measured|
+|SQ   |RADT    | Sunshine Duration|
+|SP   |RADT    | Percent of Maximum Sunshine Duration|
+|Q    |RADT    | Global Radiation|
+|DR   |PRCP    | Precipitation Duration|
+|RH   |PRCP    | Daily Precipitation|
+|RHX    |PRCP    | Maximum Hourly Precipitation|
+|RHXH   |PRCP    | Hourly Division in Which Maximum Hourly Precipitation Was Measured|
+|EV24   |ATMS    | Potential Evapotranspiration|
+|PG   |ATMS    | Daily Mean Sea Level Pressure|
+|PX   |ATMS    | Maximum Hourly Sea Level Pressure|
+|PXH    |ATMS    | Hourly Division on Which Maximum Hourly Sea Level Pressure Was Measured|
+|PN   |ATMS    | Minimum Hourly Sea Level Pressure|
+|PNH    |ATMS    | Hourly Division in Which Minimum Hourly Sea Level Pressure Was Measured|
+|VVN    |VISB    | Minimum Visibility|
+|VVNH   |VISB    | Hourly Division in Which Minimum Visibility Was Measured|
+|VVX    |VISB    | Maximum Visibility|
+|VVXH   |VISB    | Hourly Division in Which Maximum Visibility Was Measured|
+|NG   |VISB    | Mean Daily Cloud Cover|
+|UG   |ATMS    | Daily Mean Relative Humidity|
+|UX   |ATMS    | Maximum Relative Humidity|
+|UXH    |ATMS    | Hourly Division in Which Maximum Relative Humidity Was Measured|
+|UN   |ATMS    | Minimum Relative Humidity|
+|UNH    |ATMS    | Hourly Division in Which Minimum Relative Humidity Was Measured|
+
+Hourly Data
+-----------
+|Parameter|Category|Description|
+|:--------|:-------|:----------|
+|YYYYMMDD |        | Time Stamp|
+|HH       |	       |Hour |
+|DD   |WIND    | Mean wind direction during the 10-minute period preceding the time of observation|
+|FH   |WIND    | Hourly mean wind speed|
+|FF   |WIND    | Mean wind speed|
+|FX   |WIND    | Maximum wind gust|
+|T    |TEMP    | Air Temperature at 1.5 m|
+|T10N   |TEMP    | Minimum Air Temperature at 10 cm in the preceding 6 hours|
+|TD   |TEMP    | Dew Point Temperature|
+|SQ   |RDTN    | Sunshine Duration|
+|Q    |RDTN    | Golbal Radiation|
+|DR   |PRCP    | Precipitation Duration|
+|RH   |PRCP    | Precipitation|
+|P    |ATMS    | Air Pressure|
+|VV   |VISB    | Visibility|
+|N    |VISB    | Cloud Cover|
+|U    |ATMS    | Relative Humidity|
+|M    |WTHR    | Fog|
+|R    |WTHR    | Rainfall|
+|S    |WTHR    | Snow|
+|O    |WTHR    | Thunder|
+|Y    |WTHR    | Ice|
+|WW   |WTHR    | Weather Code|
+
+TODO
+----
+
+Write unit tests for lib/calculations/calculations.rb
+                    
+Please Note the license included in the header source header
+---------------------------------------------------------------
+	# DEZE GEGEVENS MOGEN VRIJ WORDEN GEBRUIKT MITS DE VOLGENDE BRONVERMELDING WORDT GEGEVEN:
+	# KONINKLIJK NEDERLANDS METEOROLOGISCH INSTITUUT (KNMI)
+	#
+	# THESE DATA CAN BE USED FREELY PROVIDED THAT THE FOLLOWING SOURCE IS ACKNOWLEDGED:
+	# ROYAL NETHERLANDS METEOROLOGICAL INSTITUTE
+
+Copyright
+---------
+
+Copyright (c) 2011 Patrick Galvin Schmitz p.schmitz@gmail.com. See LICENSE.txt for
+further details.

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/knmi.gemspec

@@ -5,24 +5,23 @@
 
 Gem::Specification.new do |s|
   s.name = %q{knmi}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["bullfight"]
-  s.date = %q{2011-05-17}
+  s.date = %q{2011-05-19}
   s.description = %q{A set of methods to query the KNMI HTTP get form for daily climate data and select a variety of measured parameters, from available stations, in a json style array of hashes, and if necessary convert to csv.}
   s.email = %q{p.schmitz@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.mkdn"
   ]
   s.files = [
-    ".DS_Store",
     ".document",
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.mkdn",
     "Rakefile",
     "VERSION",
     "data/current_stations.yml",
@@ -30,12 +29,13 @@ Gem::Specification.new do |s|
     "data/data_key.yml",
     "data/hourly_data_key.yml",
     "knmi.gemspec",
-    "lib/.DS_Store",
     "lib/knmi.rb",
+    "lib/knmi/calculations.rb",
     "lib/knmi/httpservice.rb",
     "lib/knmi/parameters.rb",
     "lib/knmi/station.rb",
     "test/helper.rb",
+    "test/test_calculations.rb",
     "test/test_httpservice.rb",
     "test/test_knmi.rb",
     "test/test_parameters.rb",
@@ -48,6 +48,7 @@ Gem::Specification.new do |s|
   s.summary = %q{Ruby API to access daily climate data from the Royal Netherlands Meteorological Institute}
   s.test_files = [
     "test/helper.rb",
+    "test/test_calculations.rb",
     "test/test_httpservice.rb",
     "test/test_knmi.rb",
     "test/test_parameters.rb",

data/lib/knmi.rb

@@ -8,41 +8,79 @@ rescue LoadError => e
   end
 end
 
-%w(station parameters httpservice).each { |file| require File.join(File.dirname(__FILE__), 'knmi', file) }
+%w(station parameters httpservice calculations).each { |file| require File.join(File.dirname(__FILE__), 'knmi', file) }
 
 module KNMI
 
   class << self
     
-    #
     # Get nearest station by lat lng
-    # KNMI.station_by_location(52.165, 4.419) #=> #<KNMI::Station:0x0000010134e7f0>
+    #
+    # @param lat [Numeric] - latitude e.g. 52.165
+    # @param lng [Numeric] - longitude e.g. 52.165
+    # @param [Array] [] - [lat, lng] e.g. [52.165, 4,419] *eqivalent to (lat, lng)*
+    # @param [GeoKit::LatLng] - Geokit object e.g. GeoKit::LatLng.new(52.165, 4.419) *eqivalent to (lat, lng)*
+    # @return [KNMI::Station] - Object with details about the station nearest to the requested lat/lng
+    #
+    # @example Get nearest station by lat, lng
+    #   KNMI.station_by_location(52.165, 52.165)
+    #
+    # @example Get nearest station by [lat, lng]
+    #   KNMI.station_by_location([52.165, 52.165])
+    #
+    # @example Get nearest station with GeoKit object
+    #   KNMI.station_by_location(GeoKit::LatLng.new(52.165, 4.419))
+    #
     def station_by_location(lat, lng)
       Station.closest_to(lat, lng)
     end
     
-    #
     # Get station object by station ID
-    # KNMI.station_by_id(210) #=> #<KNMI::Station:0x000001016b9b38>
+    #
+    # @param station_id [String, Numeric] - number of station of interest, station_ids can be found in 
+    # @return [KNMI::Station] - Object with details about the requested station
+    #
+    # @example Get station by ID
+    #   KNMI.station_by_id(210)
+    #
     def station_by_id(station_id)
       Station.find(station_id)
     end
     
+    # Get an array of parameter objects
     #
-    # Generate array of unique daily or hourly parameter objects
     # All details in daily_data_key.yml and hourly_data_key.yml
-    # inputs 
-    # period = "daily" or "hourly" 
-    # params =  
-    # categories =
-    
-    def parameters(period, params = "", categories = "")
-      if params.blank? and categories.blank?
+    # @param [string] period - "daily" or "hourly"
+    # @param [Array<string>] params - array of parameters e.g ["TX", "TG"]
+    # @param [Array<string>] categories - array of categories e.g. ["WIND", "TEMP"]
+    # @return [Array<KNMI::Parameters>] - array of KNMI::Parameters objects
+    #
+    # @example Get daily station data and a single parameter
+    #   KNMI.parameters("daily", "TX")
+    #
+    # @example Get hourly station data and a multiple parameters
+    #   KNMI.parameters("hourly", ["TX", "TG"])
+    #
+    # @example Get hourly station data and a multiple categories
+    #   KNMI.parameters("daily", nil, ["WIND", "TEMP"])
+    #
+    def parameters(period, params = nil, categories = nil)
+      if params.nil? and categories.nil?
+        
         list = Parameters.all(period)
-      else
-        list = []
+      
+      elsif categories.nil?
         
+        # Parameters by name
+        list = []
+        params = unique_params(params, list) #ensure params are unique to list 
+        list << Parameters.find(period, params)        
+        list.flatten!
+        list.compact!
+      else 
+
         # Parameters by category
+        list = []
         list << Parameters.category(period, categories)
         list.flatten!
         
@@ -55,17 +93,42 @@ module KNMI
       return list
     end
         
+    # Retrieve climate data from a weather station
+    #
+    # @param station [KNMI::Station] - station object retrieved with KNMI.station_by_id() or KNMI.station_by_location()
+    # @param parameters [Array<KNMI::Parameters>] - parameters object retrieved with KNMI.parameters()
+    # @param starts [Time] - Time object e.g. Time.utc(2010, 6, 28)
+    # @param ends [Time] - Time object e.g. Time.utc(2010, 6, 29)
+    # @param seasonal [Boolean]
     #
-    # Input a station object from KNMI.station_by_id or KNMI.station_by_location
-    # and a parameter hash of objects from # KNMI.Parameters
-    # return 
-    def get_data(station_object, parameter_object, start_at = nil, end_at = nil, seasonal = false)
-      if parameter_object[0].period == "daily"
-        HttpService.get_daily(station_object, parameter_object, start_at, end_at, seasonal)
-      elsif parameter_object[0].period == "hourly"
-        HttpService.get_hourly(station_object, parameter_object, start_at, end_at, seasonal)
+    # @return [KNMI::HttpService]
+    def get_data(station, parameters, starts = nil, ends = nil, seasonal = false)
+      
+      if parameters[0].period == "daily"        
+        HttpService.get_daily(station, parameters, starts, ends, seasonal)
+        
+      elsif parameters[0].period == "hourly"        
+        HttpService.get_hourly(station, parameters, starts, ends, seasonal)
+        
       end
     end
+    
+    # Input data request object and return array of hashes converted from storage to operable units.
+    #
+    # @param parameters [KNMI::Stations] - Parameters object
+    # @param request [KNMI:HttpService] - Data object from HttpRequest
+    #
+    # @return [Hash] - Hash containing climate data in operable units
+    def convert(parameters, request)
+      
+      if parameters[0].period == "daily"        
+        KNMI::Calculations.convert_daily(request.data)
+        
+      elsif parameters[0].period == "hourly"
+        KNMI::Calculations.convert_hourly(request.data)
+        
+      end    
+    end
 
     
     private

data/lib/knmi/calculations.rb

@@ -0,0 +1,185 @@
+module KNMI
+  class Calculations
+    class << self
+   
+      # Converts Daily KNMI.get_data().data from storage to operable units
+      #
+      # @param [Array<Hash>] array - in storage format (integers)
+      # @return [Array<Hash>] - in operable format (Float, Integer, Time)
+      def convert_daily(array)
+        x = []
+        
+        array.each_with_index do |a, index|
+          x[index] = {}
+          x[index][:stn] = a
+          a.each_pair { |key,value| x[index].merge!( {key => converts_daily(key, value)} ) }
+        
+        end
+        
+        return x          
+      end
+      
+      # Converts Hourly KNMI.get_data().data from storage to operable units
+      #
+      # @param [Array<Hash>] array - Array of hashes, in storage format (integers)
+      # @return [Array<Hash>] - Array of hashes, in operable format (Float, Integer, Time)      
+      def convert_hourly(array)
+        x = []
+        
+        array.each_with_index do |a, index|
+          x[index] = {}
+          a.each_pair { |key,value| x[index].merge!( {key => converts_daily(key, value)} ) }
+          x[index][:Time] = x[index][:YYYYMMDD] + x[index][:HH]
+          
+        end
+        
+        return x
+      end
+          
+      private
+      
+      def converts_daily( key, n )
+        if key == :STN
+          n                  
+        elsif [:FHVEC, :FG, :FHX, :FHN, :FXX, :TG, :TN, :TX, :T10N, :RH, :EV24, :PG, :PX, :PN].include?(key)
+
+          n.integer? ? n.to_f / 10 : nil
+
+        elsif [:FHXH, :FHNH, :FXXH, :TNH, :TXH, :RHXH, :PXH, :PNH, :VVNH, :VVXH, :UXH, :UNH].include?(key)
+
+          (1..24).include?(n) ? n : nil
+
+        elsif [:SP, :UG, :UX, :UN].include?(key)
+
+          (0..100).include?(n) ? n : nil
+
+        elsif [:RHX].include?(key)
+
+          n = n.integer? ? n : nil
+          return n == -1 ? 0.05 : n.to_f / 10
+          
+        elsif [:Q].include?(key)
+          
+          n.integer? ? n : nil
+
+        elsif [:DR].include?(key)
+
+          (0..6).include?(n) ? (n.to_f / 10) * 60 : nil
+
+        elsif [:DDVEC].include?(key)
+
+          (0..360).include?(n) ? n : nil
+
+        elsif [:SQ].include?(key)
+
+          n = (-1..6).include?(n) ? n : nil
+          return n == -1 ? 0.05 : (n.to_f / 10) * 60
+
+        elsif [:T10NH].include?(key)
+
+          (6..24).step(6).include?(n) ? n : nil
+
+        elsif [:NG].include?(key)
+
+          (0..9).include?(n) ? n : nil
+
+        elsif [:YYYYMMDD].include?(key)
+
+          Time.utc(
+            year = n.to_s[(0..3)],
+            month = n.to_s[(4..5)],
+            day = n.to_s[(6..7)]
+          )
+
+        elsif [:VVN, :VVX].include?(key)
+
+          if n == 0 
+            '< 100 meters'
+          elsif (1..49).include?(n)
+            (n * 100).to_s + '-' + ((n+1) * 100).to_s + ' meters'
+          elsif n == 50
+            '5-6 kilometers'
+          elsif (56..79).include?(n)
+            (n - 50).to_s + '-' + (n - 49).to_s + ' kilometers'
+          elsif (80..88).include?(n)
+            (n - 50).to_s + '-' + (n - 45).to_s + ' kilometers'
+          elsif n == 89
+            '> 70 kilometers'
+          end
+
+        end
+      end
+      
+      
+      def converts_hourly( key, n )
+        if key == :STN
+          
+          n
+          
+        elsif [:FH, :FF, :FX, :T, :T10N, :TD, :RH, :P].include?(key)
+          
+          n.integer? ? n.to_f / 10 : nil
+        
+        elsif [:M, :R, :S, :O, :Y].include?(key)
+          
+          (0..1).include?(n) ? n : nil
+          
+        elsif key == :SQ
+          
+          (-1..240).include?(n) ? n : nil
+          return n == -1 ? 0.05 : (n / 10) * 60
+          
+        elsif key == :U
+          
+          (0..100).include?(n) ? n : nil
+          
+        elsif key == :DR
+          
+          (0..240).include?(n) ?  (n / 10) * 60 : nil
+          
+        elsif key == :DD
+          
+          (0..360).to_a.push(990).include?(n) ? n : nil
+        
+        elsif key == :N
+          
+          (0..9).include?(n) ? n : nil
+          
+        elsif key == :WW
+          
+          (0..99).include?(n) ? n : nil
+          
+        elsif key == :HH
+          
+          (1..24).include?(n) ? n : nil
+          
+        elsif [:YYYYMMDD].include?(key)
+
+          Time.utc(
+            year = n.to_s[(0..3)],
+            month = n.to_s[(4..5)],
+            day = n.to_s[(6..7)]
+          )
+
+        elsif [:VVN, :VVX].include?(key)
+
+          if n == 0 
+            '< 100 meters'
+          elsif (1..49).include?(n)
+            (n * 100).to_s + '-' + ((n+1) * 100).to_s + ' meters'
+          elsif n == 50
+            '5-6 kilometers'
+          elsif (56..79).include?(n)
+            (n - 50).to_s + '-' + (n - 49).to_s + ' kilometers'
+          elsif (80..88).include?(n)
+            (n - 50).to_s + '-' + (n - 45).to_s + ' kilometers'
+          elsif n == 89
+            '> 70 kilometers'
+          end
+
+        end
+      end
+      
+    end
+  end
+end

data/lib/knmi/httpservice.rb

@@ -5,25 +5,43 @@ module KNMI
     
     class << self
       
-      def get_daily(station_object, parameter_object, start_at = nil, end_at = nil, seasonal = false)
+      # Requests Daily data
+      #
+      # @param station_object [KNMI::Station] - Station Object
+      # @param parameter_object [KNMI::Parameters] - Parameter Object
+      # @param starts [Time] - Time Object
+      # @param ends [Time] - Time Object
+      # @param seasonal [Boolean]
+      # @return [KNMI::HttpService]
+      #
+      def get_daily(station_object, parameters_object, starts = nil, ends = nil, seasonal = false)
         # select YYYYMMDD (drops hour term)
-        query = [station(station_object),  parameters(parameter_object), 
-                 start_date(start_at)[0..13], end_date(end_at)[0..11],
+        query = [station(station_object),  parameters(parameters_object), 
+                 start_date(starts)[0..13], end_date(ends)[0..11],
                  seasonal(seasonal)].compact
         result = get('http://www.knmi.nl/climatology/daily_data/getdata_day.cgi', { :query => "#{query * "&"}" } )
         
-        data = parse(station_object, parameter_object, result)
+        data = parse(station_object, parameters_object, result)
         
         return new({"query" => query, "data" => data})
       end
-  
-      def get_hourly(station_object, parameter_object, start_at = nil, end_at = nil, seasonal = false)
-        query = [station(station_object),  parameters(parameter_object), 
-                 start_date(start_at), end_date(end_at),
+      
+      # Requests Hourly data
+      #
+      # @param station_object [KNMI::Station] - Station Object
+      # @param parameter_object [KNMI::Parameters] - Parameter Object
+      # @param starts [Time] - Time Object
+      # @param ends [Time] - Time Object
+      # @param seasonal [Boolean]
+      # @return [KNMI::HttpService]
+      #
+      def get_hourly(station_object, parameters_object, starts = nil, ends = nil, seasonal = false)
+        query = [station(station_object),  parameters(parameters_object), 
+                 start_date(starts), end_date(ends),
                  seasonal(seasonal)].compact
         result = get('http://www.knmi.nl/klimatologie/uurgegevens/getdata_uur.cgi', { :query => "#{query * "&"}" } )
         
-        data = parse(station_object, parameter_object, result)
+        data = parse(station_object, parameters_object, result)
         
         return new({"query" => query, "data" => data})
       end
@@ -98,7 +116,7 @@ module KNMI
         # Parse into array and then hash with var name
         data = CSV.parse(data, {:skip_blanks => true})
         header = data.shift.map {|i| i.to_s.intern }
-        string_data = data.map {|row| row.map {|cell| cell.to_s } }
+        string_data = data.map {|row| row.map {|cell| cell.to_i } }
         data = string_data.map {|row| Hash[*header.zip(row).flatten] }
       
         return data
@@ -106,14 +124,21 @@ module KNMI
     
     end
   
-    #
     # Returns query string used in HTTP get request
-    # KNMI::HttpService.get_daily(210) #=> @ query =>[ "stns=210", "vars=ALL", "start=2011051500", "end=2011051613"]
+    #
+    # @return [Array<string>] - array of strings which contains the components used in the HTTP request
+    #
+    # @example
+    #   KNMI::HttpService.get_daily(station, parameter).query
+    #   =>[ "stns=210", "vars=ALL", "start=2011051500", "end=2011051613"]
     attr_reader :query
   
-    #
     # Parsed HTTP request
-    # Array of Hashes     
+    #
+    # @return [Array<Hash>] - array of hashes which contains climate data in storage(integer) format
+    # @example
+    #   KNMI::HttpService.get_daily(station, parameter).data
+    #   =>[{:STN=>"235", :YYYYMMDD=>"20100628", :TX=>"263"}, {:STN=>"235", :YYYYMMDD=>"20100629", :TX=>"225"}]
     attr_reader :data
   
     def initialize(properties)

data/lib/knmi/parameters.rb

@@ -3,11 +3,16 @@ module KNMI
     class << self
       attr_writer :keys_file
       
+      # Retrieve Parameter Object by named parameter
       #
-      # Retrieve information about Parameter can be string or array
+      # @param period [String] - "daily" or "hourly"
+      # @param parameter [Array, String] - Array of strings or string of parameter name
+      # @return [Array<KNMI::Parameters>] - array of parameter objects
+      #
+      # @example
+      #   KNMI::Parameter.find(period = "daily", "TA")  
+      #   KNMI::Parameter.find(period = "daily", ["TG", "TX"])
       #
-      # KNMI::Parameter.find(period = "daily", "TA")  #=> KNMI::Parameter object for TG (Daily Max temperature)
-      # KNMI::Parameter.find(period = "daily", ["TG", "TX"])  #=> KNMI::Parameter array of objects TG (Daily Mean temperature) and TX (Daily Max Temperature)
       def find(period, parameter)
         parameter = [parameter].flatten
         
@@ -19,12 +24,16 @@ module KNMI
         return list
       end     
       
+      # Retrieve Parameter Object by named parameter
+      #
+      # @param period [String] - "daily" or "hourly"
+      # @param category [Array, String] - Array of strings or string of category name
+      # @return [Array<KNMI::Parameters>] - array of parameter objects
       #
-      # Retrieve each parameter within a category
-      # an Array of structs
+      # @example
+      #   KNMI.Parameter.category(period = "daily, ""WIND")
+      #   KNMI.Parameter.category(period = "daily, ["WIND", "TEMP"])
       #
-      # KNMI.Parameter.category(period = "daily, ""WIND") #=> [#<Parameter:0x00000100b433f8 @parameter="SQ", @category="RADT", @description="Sunshine Duration", @validate="(-1..6).include?(n)", @conversion="n == -1 ? 0.05 : (n / 10) * 60", @units="minutes">, #<Daily:0x00000100b43290 @parameter="SP", @category="RADT", @description="Percent of Maximum Sunshine Duration", @validate="(0..100).include?(n)", @conversion=nil, @units="%">, #<Daily:0x00000100b43128 @parameter="Q", @category="RADT", @description="Global Radiation", @validate="n.integer?", @conversion=nil, @units="J/cm^2">]
-      # KNMI.Parameter.category(period = "daily, ["WIND", "TEMP"]) 
       def category(period, category)        
         category = [category].flatten
         
@@ -36,9 +45,10 @@ module KNMI
         return list.flatten!
       end
       
-      #
       # Retrieve all Parameters
-      # an Array of structs
+      # @param period [String] - "daily" or "hourly"
+      # @return [Array<KNMI::Parameters>] - array of parameter objects
+      #
       def all(period)      
         list = []
         list << keys.select { |k| k.period == period }
@@ -61,25 +71,25 @@ module KNMI
       
     end
     
-    # Paramter shortname
+    # @return [String] - Paramter shortname
     attr_reader :parameter
     
-    # Categories grouping parameters
+    # @return [String] - Categories grouping parameters
     attr_reader :category
     
-    # Description of parameter
+    # @return [String] - Description of parameter
     attr_reader :description 
     
-    # Code to validate data as accurate
+    # @return [String] - example code to validate data as accurate
     attr_reader :validate
     
-    # Code to convert data into appropriate format/units
+    # @return [String] - example code to convert data into appropriate format/units for operation
     attr_reader :conversion
     
-    # Unit of converted format
+    # @return [String] - Unit of converted format
     attr_reader :units 
     
-    # Time Period
+    # @return [String] - Time Period "daily" or "hourly"
     attr_reader :period
     
     def initialize(properties)
@@ -88,6 +98,7 @@ module KNMI
       end
     end
     
+    # @return [Hash] - Hash containing important details about parameters object
     def detail
       {:parameter => @parameter, :category => @category, 
        :description => @description, :validate => @validate, 

data/lib/knmi/station.rb

@@ -1,23 +1,35 @@
 module KNMI
   class Station
     class <<self
-      attr_writer :stations_file #:nodoc:
+      attr_writer :stations_file
 
+      # Retrieve station object by id
       #
-      # Retrieve information about a station given a station ID
+      # @param id [Numeric, String] - Station id
+      # @return [KNMI::Station]
+      #
+      # @example Retrieve Station object for Valkenburg
+      #   KNMI::Station.find(210)
       #
-      #   KNMI::Station.find(210)  #=> KNMI::Station object for Valkenburg
       def find(id)
         stations.find { |station| station.id == id }
       end
 
-      # 
       # Find the station closest to a given location. Can accept arguments in any of the following
       # three forms (all are equivalent):
       #
+      # @param *args [String, Array, Geokit::LatLLng]
+      # @return [KNMI::Station] - Object with details about the station nearest to the requested lat/lng
+      #
+      # @example Retrieve Station by lat, lng
       #   KNMI::Station.closest_to(52.165, 4.419)
+      #
+      # @example Retrieve Station by [lat, lng]  
       #   KNMI::Station.closest_to([52.165, 4.419])
+      #
+      # @example Retrieve Station with GeoKit object
       #   KNMI::Station.closest_to(GeoKit::LatLng.new(52.165, 4.419))
+      #
       def closest_to(*args)
         if args.length == 1
           if args.first.respond_to?(:distance_to)
@@ -59,31 +71,32 @@ module KNMI
         @stations_file ||= File.join(File.dirname(__FILE__), '..', '..', 'data', 'current_stations.yml')
       end
     end
-
-    # GeoKit::LatLng containing the station's coordinates
+    
+    # @return [GeoKit::LatLng] - object containing the station's coordinates
     attr_reader :coordinates
 
-    # Station ID (e.g., 210)
+    # @return [String] - Station ID (e.g., 210)
     attr_reader :id
 
-    # Station name (e.g., "Valkenburg")
+    # @return [String] - Station name (e.g., "Valkenburg")
     attr_reader :name
     
-    # Station Elevation
+    # @return [String] - Station Elevation
     attr_reader :elevation
     alias_method :elev, :elevation
     alias_method :altitude, :elevation
     alias_method :alt, :elevation
     
-    # Link to Station Photo
+    # @return [String] - Link to Station Photo {http://www.knmi.nl/klimatologie/metadata/210_valkenburg_big.jpg Station 210 - Valkenburg Station Photo}
     attr_reader :photo
     
-    # Link to map of station location
+    # @return [String] - Link to map of station location {http://www.knmi.nl/klimatologie/metadata/stn_210.gif Station 210 - Valkenburg Station Map}
     attr_reader :map
     
-    # Link to Metadata page listing
+    # @return [String] - Link to Metadata page listing http://www.knmi.nl/klimatologie/metadata/valkenburg.html {Station 210 - Valkenburg Station MetaData page}
     attr_reader :web
     
+    # @return [Hash<Array>] - Hash containing arrays with detail about historical and current instrumentation at station
     attr_reader :instrumentation
 
     def initialize(properties)
@@ -93,19 +106,21 @@ module KNMI
       @coordinates = GeoKit::LatLng.new(properties['lat'], properties['lng'])
     end
     
-    # Latitude of station
+    # @return [Float] - Latitude of station
     def latitude
       @coordinates.lat
     end
     alias_method :lat, :latitude
 
-    # Longitude of station
+    # @return [Float] - Longitude of station
     def longitude
       @coordinates.lng
     end
     alias_method :lng, :longitude
     alias_method :lon, :longitude
     
+    
+    # @return [Hash] - contains a has with detail about the station
     def detail
       {:id => @id, :name => @name, :elev => @elevation, :lat => latitude, :lng => longitude}    
     end

data/test/test_calculations.rb

@@ -0,0 +1,5 @@
+require 'helper'
+
+class TestCalculations < KNMI::TestCase
+  # TODO
+end

data/test/test_httpservice.rb

@@ -20,7 +20,7 @@ class TestHttpService < KNMI::TestCase
     end
     
     should "have result" do
-      assert_equal @response.data, [{:STN=>"235", :YYYYMMDD=>"20100628", :TX=>"263"}, {:STN=>"235", :YYYYMMDD=>"20100629", :TX=>"225"}]
+      assert_equal @response.data, [{:STN=>235, :YYYYMMDD=>20100628, :TX=>263}, {:STN=>235, :YYYYMMDD=>20100629, :TX=>225}]
     end    
   end
   
@@ -43,10 +43,10 @@ class TestHttpService < KNMI::TestCase
     end
     
     should "have result" do
-      assert_equal @response.data, [
-        {:STN=>"235", :YYYYMMDD=>"20100427", :HH=>"1", :T=>"88"},
-        {:STN=>"235", :YYYYMMDD=>"20100427", :HH=>"2", :T=>"79"},
-        {:STN=>"235", :YYYYMMDD=>"20100427", :HH=>"3", :T=>"73"} ]
+      assert_equal @response.data, [          
+        {:STN=>235, :YYYYMMDD=>20100427, :HH=>1, :T=>88},
+        {:STN=>235, :YYYYMMDD=>20100427, :HH=>2, :T=>79},
+        {:STN=>235, :YYYYMMDD=>20100427, :HH=>3, :T=>73} ]
     end
   end
 

data/test/test_knmi.rb

@@ -122,26 +122,46 @@ class TestKNMI < KNMI::TestCase
   
   context "get data over daily timestep" do
     setup do
-      station = KNMI.station_by_location(52.165, 4.419)
-      params = KNMI.parameters(period = "daily", "TX")
-      start_at = Time.utc(2010, 6, 28)
-      end_at = Time.utc(2010, 6, 29)
-      @response = KNMI.get_data(station, params, start_at, end_at)
+      @station = KNMI.station_by_location(52.165, 4.419).freeze
+      @params = KNMI.parameters(period = "daily", "TX").freeze
+      @starts = Time.utc(2010, 6, 28)
+      @ends = Time.utc(2010, 6, 29)
+      @request = KNMI.get_data(@station, @params, @starts, @ends)
+      @data = KNMI.convert(@params, @request)
     end
     
     should "have HTTParty::Response class" do
-      assert_equal @response.class, KNMI::HttpService
+      assert_equal @request.class, KNMI::HttpService
     end
     
-    should "have query" do
-      assert_equal @response.query, ["stns=210", "vars=TX", "start=20100628", "end=20100629"]
+    should "request should have query" do
+      assert_equal @request.query, ["stns=210", "vars=TX", "start=20100628", "end=20100629"]
     end
     
-    should "have result" do
-      assert_equal @response.data, [
-        {:STN=>"210", :YYYYMMDD=>"20100628", :TX=>"268"},
-        {:STN=>"210", :YYYYMMDD=>"20100629", :TX=>"239"}]
-    end    
+    should "request should have result" do
+      assert_equal @request.data, [{:STN=>210, :YYYYMMDD=>20100628, :TX=>268},
+                                   {:STN=>210, :YYYYMMDD=>20100629, :TX=>239}]
+    end 
+    
+    should "data should have class array" do 
+      assert_equal @data.class, Array
+    end
+    
+    should "data[0] should have class Hash" do 
+      assert_equal @data[0].class, Hash
+    end
+    
+    should "data[0] should have station" do 
+      assert_equal @data[0][:STN], 210
+    end
+    
+    should "data[0] should have result" do 
+      assert_equal @data[0][:TX], 26.8
+    end
+    
+    should "data[0] should have time class" do 
+      assert_equal @data[0][:YYYYMMDD].class, Time
+    end
   end
   
 end

metadata

@@ -2,7 +2,7 @@
 name: knmi
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - bullfight
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-05-17 00:00:00 Z
+date: 2011-05-19 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: httparty
@@ -119,14 +119,13 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE.txt
-- README.rdoc
+- README.mkdn
 files: 
-- .DS_Store
 - .document
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.rdoc
+- README.mkdn
 - Rakefile
 - VERSION
 - data/current_stations.yml
@@ -134,12 +133,13 @@ files:
 - data/data_key.yml
 - data/hourly_data_key.yml
 - knmi.gemspec
-- lib/.DS_Store
 - lib/knmi.rb
+- lib/knmi/calculations.rb
 - lib/knmi/httpservice.rb
 - lib/knmi/parameters.rb
 - lib/knmi/station.rb
 - test/helper.rb
+- test/test_calculations.rb
 - test/test_httpservice.rb
 - test/test_knmi.rb
 - test/test_parameters.rb
@@ -157,7 +157,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 1440179461476455421
+      hash: 3402158507789262008
       segments: 
       - 0
       version: "0"
@@ -176,6 +176,7 @@ specification_version: 3
 summary: Ruby API to access daily climate data from the Royal Netherlands Meteorological Institute
 test_files: 
 - test/helper.rb
+- test/test_calculations.rb
 - test/test_httpservice.rb
 - test/test_knmi.rb
 - test/test_parameters.rb

data/README.rdoc

@@ -1,132 +0,0 @@
-= knmi
-
-Ruby API to access Royal Netherlands Meteorological Institute daily climate data
-
-Access climatological data as provided by the Royal Netherlands Meteorological Institute through the http get forms for daily and hourly data
-	http://www.knmi.nl/climatology/daily_data/getdata_day.cgi
-	http://www.knmi.nl/klimatologie/uurgegevens/getdata_uur.cgi
-	
-Details 
-* Hourly data (Dutch) - http://www.knmi.nl/klimatologie/uurgegevens/scriptxs-nl.html#uur
-* Daily data (English) - http://www.knmi.nl/climatology/daily_data/scriptxs-en.html
-* Select Data with a form, listed below are links to metadata about each station http://www.knmi.nl/climatology/daily_data/selection.cgi
-
-
-= Installation
-	gem install httparty
-	gem install geokit
-	
-	gem install knmi
-	
-= Dependancies
-* "httparty", "~> 0.7.7"
-* "geokit", "~> 1.5.0"
-
-= Example Usage
-	# Get station object by station ID
-	station = KNMI.station_by_id(235)
-	
-	# Get parameter object at the time interval you wish to use "hourly" or "daily"
-	# Params can be a single term or an array of terms such as "TG" or ["TG", TX]
-	# Categories can be a single term or an array of terms such as "WIND" or ["WIND", "TEMP"]
-    
-	parameter = KNMI.parameters(period = "daily", params = "TX", categories = "")
-    
-	# Define Time period of interest
-	start_at = Time.utc(2010, 6, 28) 	# 2010 April 28th
-    end_at = Time.utc(2010, 6, 29) 		# 2010 April 29th
-    
-	# Get Data using previously retrieved objects
-	data = KNMI.get_data(station, parameter, start_at, end_at)
-
-= TODO
-* function validate data at each time step using associated parameterobject.validate
-* function to convert data at each time step using associated parameterobject.conversion
-
-= Available Data
-All available recorded parameters can be found in the file
-	.data/data_key.yml 
-
-= Daily Data
-	Parameter   Category	Description
-	YYYYMMDD				Time Stamp
-	DDVEC		WIND		Wind Direction 
-	FHVEC		WIND		Vector Mean Wind Speed
-	FG			WIND		Daily Mean Wind Speed
-	FHX	   		WIND		Maximum Hourly Mean Windspeed
-	FHXH   		WIND		Hourly Division  at Which Maximum Wind Speed Was Measured
-	FHN			WIND		Minimum Hourly Mean Windspeed
-	FHNH		WIND		Hourly Division  at Which Minimum Wind Speed Was Measured
-	FXX			WIND		Maximum Instantaneous Wind Speed
-	FXXH		WIND		Hourly Division  at Which Maximum Instantaneous Wind Speed Was Measured
-	TG			TEMP		Daily Mean Temperature
-	TN			TEMP		Minimum Temperature
-	TNH			TEMP		Hourly Division in Which Minimum Temperature Was Measured
-	TX			TEMP		Maximum Temperature
-	TXH			TEMP		Hourly Division in Which Maximum Temperature Was Measured
-	T10N		TEMP		Minimum Temperature at 10 Cm Above Surface
-	T10NH		TEMP		Six Hourly Division at Which Minimum Temperature at 10 Cm Above Surface Was Measured
-	SQ			RADT		Sunshine Duration
-	SP			RADT		Percent of Maximum Sunshine Duration
-	Q			RADT		Global Radiation
-	DR			PRCP		Precipitation Duration
-	RH			PRCP		Daily Precipitation
-	RHX			PRCP		Maximum Hourly Precipitation
-	RHXH		PRCP		Hourly Division in Which Maximum Hourly Precipitation Was Measured
-	EV24		ATMS		Potential Evapotranspiration
-	PG			ATMS		Daily Mean Sea Level Pressure
-	PX			ATMS		Maximum Hourly Sea Level Pressure
-	PXH			ATMS		Hourly Division on Which Maximum Hourly Sea Level Pressure Was Measured
-	PN			ATMS		Minimum Hourly Sea Level Pressure
-	PNH			ATMS		Hourly Division in Which Minimum Hourly Sea Level Pressure Was Measured
-	VVN			VISB		Minimum Visibility
-	VVNH		VISB		Hourly Division in Which Minimum Visibility Was Measured
-	VVX			VISB		Maximum Visibility
-	VVXH		VISB		Hourly Division in Which Maximum Visibility Was Measured
-	NG			VISB		Mean Daily Cloud Cover
-	UG			ATMS		Daily Mean Relative Humidity
-	UX			ATMS		Maximum Relative Humidity
-	UXH			ATMS		Hourly Division in Which Maximum Relative Humidity Was Measured
-	UN			ATMS		Minimum Relative Humidity
-	UNH			ATMS		Hourly Division in Which Minimum Relative Humidity Was Measured
-
-= Hourly Data
-	Parameter	Category	Description
-	YYYYMMDD				Time Stamp
-	HH			Hour
-	DD			WIND		Mean wind direction during the 10-minute period preceding the time of observation
-	FH			WIND		Hourly mean wind speed
-	FF			WIND		Mean wind speed
-	FX			WIND		Maximum wind gust
-	T			TEMP		Air Temperature at 1.5 m
-	T10N		TEMP		Minimum Air Temperature at 10 cm in the preceding 6 hours
-	TD			TEMP		Dew Point Temperature
-	SQ			RDTN		Sunshine Duration
-	Q			RDTN		Golbal Radiation
-	DR			PRCP		Precipitation Duration
-	RH			PRCP		Precipitation
-	P			ATMS		Air Pressure
-	VV			VISB		Visibility
-	N			VISB		Cloud Cover
-	U			ATMS		Relative Humidity
-	M			WTHR		Fog
-	R			WTHR		Rainfall
-	S			WTHR		Snow
-	O			WTHR		Thunder
-	Y			WTHR		Ice
-	WW			WTHR		Weather Code
-
-                    
-= Please Note the disclaimer included in the header source header
-	# DEZE GEGEVENS MOGEN VRIJ WORDEN GEBRUIKT MITS DE VOLGENDE BRONVERMELDING WORDT GEGEVEN:
-	# KONINKLIJK NEDERLANDS METEOROLOGISCH INSTITUUT (KNMI)
-	#
-	# THESE DATA CAN BE USED FREELY PROVIDED THAT THE FOLLOWING SOURCE IS ACKNOWLEDGED:
-	# ROYAL NETHERLANDS METEOROLOGICAL INSTITUTE
-
-
-== Copyright
-
-Copyright (c) 2011 Patrick Galvin Schmitz p.schmitz@gmail.com. See LICENSE.txt for
-further details.
-