weather_judge 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a7cc48f83c00173d4ac5eb1d72ccb336b8ea206
-  data.tar.gz: 25131c80b1435c676367b06be003f62bbb5c950b
+  metadata.gz: b16a105944c44f8c8570ceecaf92d4bce60d87e9
+  data.tar.gz: 2083d9db3e5990d7a1c7ef7f9e7a604310f917b8
 SHA512:
-  metadata.gz: 131fdfde7a5ad13aa8478df225e564f1a661147d224d215b6d71010033287d38dac31fc1cc9216405fd9f90d8a2a1c4de8041d01b63a745f37cdba92532a3aca
-  data.tar.gz: de6e5d2dd793f317d9b645867c1b669d9051e28ea564d240ed85769818be15663c2d3924ddbaa28f71bb16bb240f50cc663a7819221669028b057fafebda8c89
+  metadata.gz: 69ee399124f40a141c80f6accbda48b3e2fc48196d213e67c1dc039c9fbe9facc4ccb2a10be3c2d0cb06271ba9011c7dea2d1dc9eaaf555920c3a87885957773
+  data.tar.gz: 5fed51dce6328ed31f0086c73cbb1b41556cd32c613d49a64593026ea7929eb5dfee2f6cf963cc287cabf717776077fac24c902f7d212fe676c5c44c45f4750c

data/README.md

@@ -2,18 +2,26 @@
 
 This gem retrieves weather forecasting data from Forecast.IO via [forecast-ruby](https://github.com/darkskyapp/forecast-ruby) 
 using longitude and latitude and returns an overall score. The following criteria are used to judge
-the quality of weather. The total score is up to 100. 
+the quality of weather. The maximum score you can get is 100. 
 
 - Temperature
 - Sky Cover
 - Wind speed
-- Change of Rain
+- Chance of Rain
 
 Currently it only evaluates today's data but I plan on adding an ability to take a specified date. This is 
-more of a proof of concept at this point. Since there are four criteria at the moment, each of them holds
-up to 25 points. Optimal weather is considered as a day with comfortable temperature, less than 15 mph wind, 
+more of a proof of concept at this point. Since there are four criteria, each criteria can be given
+up to 25 points. By default, optimal weather is considered as a day with comfortable temperature (67-77F), less than 15 mph wind, 
 low chance of rain, and low sky cover.
 
+## Why I Developed This Gem
+
+I currently live in Portland, OR, USA, where we have access to great outdoors. You can easily drive to the 
+coast (Pacific Ocean) or the mountains (Cascade Range) within a few hours. Consequently, we have 
+micro-climates and the weather can vary depending on where you are. I like to hike a lot, so I need 
+to know where would be the best place to go for a day trip easily. I plan to use this gem for an app
+that will rank specified locations to help me decide where to go on the day of the trip. 
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -31,21 +39,54 @@ Or install it yourself as:
     $ gem install weather_judge
 
 ## Usage
-`WeatherJudge` returns overall weather score, and scores of weather aspect. 
+`WeatherJudge` takes longitude and latitude as input and then returns an overall weather score, and scores of weather aspect via `WeatherData` class.
 
 Please see [Forecast IO's documentation](https://developer.forecast.io/) for creating an api key. 
 
+To configure you can do:
+
+```ruby
+WeatherJudge.configure do |configuration|
+  configuration.forecast_io_api_key = `(your api key here)`
+  configuration.max_cloud_cover = 0.60  
+  configuration.max_percent_rain = 0.30
+  configuration.max_wind_speed = 22
+  configuration.ideal_temp_range = { min: 50, max: 80}
+  configuration.temp_range_delta = 10
+end
+```
+
+or 
+
 ```ruby
-WeatherJudge.forecast_io_api_key = '(your api key here)'
-data = WeatherJudge.run(44, -122)
+WeatherJudge.forecast_io_api_key = `(your api key here)`
+WeatherJudge.max_cloud_cover = 0.60
+# and so forth
+```
+
+More details on configuration
+ - `max_cloud_cover`: Maximum cloud cover you are willing to tolerate. A decimal number between 0 to 1
+ - `max_percent_rain`: Maximum change of rain you are willing to tolerate. A decimal number between 0 to 1
+ - `max_wind_speed`: Maximum wind speed you are willing to tolerate. Default is 15 mph.
+ - `ideal_temp_range`: Ideal temperature range in fahrenheit expressed in hash
+ - `temp_range_delta`: The delta for slightly less than ideal temperate range in fahrenheit
+
+To run, you need to pass in a valid coordinates.
+
+```ruby
+data = WeatherJudge.run(44.123, -122.123)
 # => Returns `WeatherData` object
 
 data.total_location_score
-# => returns a score of 0 - 100
+# => returns a score of up to 100
 ```
 
-Available methods for `WeatherData`
-- `raw_data`
+List of available methods for `WeatherData`
+- `raw_data` returns forecast data in `Hashie` (More info on Hashie [here](https://github.com/intridea/hashie)) . Example:
+  ```
+  => #<Hashie::Mash apparentTemperatureMax=85.83 apparentTemperatureMaxTime=1472702400 apparentTemperatureMin=79.79 apparentTemperatureMinTime=1472734800 cloudCover=0.17 dewPoint=70.42 humidity=0.72 icon="partly-cloudy-night" moonPhase=0.99 ozone=280.5 precipIntensity=0.001 precipIntensityMax=0.0025 precipIntensityMaxTime=1472677200 precipProbability=0.07 precipType="rain" pressure=1009.95 summary="Partly cloudy in the morning." sunriseTime=1472673538 sunsetTime=1472719928 temperatureMax=81.76 temperatureMaxTime=1472702400 temperatureMin=79.79 temperatureMinTime=1472734800 time=1472652000 windBearing=186 windSpeed=4.09>
+
+  ```
 - `total_location_score`
 - `cloud_cover_score`
 - `wind_score`
@@ -64,11 +105,11 @@ update the version number in `version.rb`, and then run `bundle exec rake releas
 git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Future Plans/Disclaimer
-The current state of this gem is more of a proof of concept. This gem was originally developed to be
-used in my personal project for ranking overall weather of different locations, but feel free to use 
-it for any purpose. This gem will be evolving in the near future. A couple of obvious future plans are:
- - Add ability to change preferred weather aspects for scoring
+This gem was originally developed to be used in my personal project for ranking overall weather of 
+different locations, but feel free to use it for any other purpose. This gem will be evolving in the 
+near future. A few of obvious future plans are:
  - Add ability to specify a date for retrieving scored data
+ - Other weather criteria to evaluate
 
 ## Contributing
  

data/lib/weather_judge/configuration.rb

@@ -1,9 +1,40 @@
 module WeatherJudge
   module Configuration
-    attr_writer :forecast_io_api_key
+    attr_writer :forecast_io_api_key, :max_cloud_cover, :max_percent_rain, :max_wind_speed,
+                :ideal_temp_range, :temp_range_delta
+
+    # For configuring WeatherJudge with block style
+    def configure
+      yield self
+    end
 
     def forecast_io_api_key
       @forecast_io_api_key
     end
+
+    # Maximum cloud cover you are willing to tolerate
+    def max_cloud_cover
+      @max_cloud_cover
+    end
+
+    # Maximum change of rain you are willing to tolerate
+    def max_percent_rain
+      @max_percent_rain
+    end
+
+    # Maximum wind speed you are willing to tolerate. Default is 15mph.
+    def max_wind_speed
+      @max_wind_speed || 15
+    end
+
+    # Ideal temperature range in fahrenheit expressed in hash
+    def ideal_temp_range
+      @ideal_temp_range || { min: 67, max: 77 }
+    end
+
+    # The delta for slightly less than ideal temperate range in fahrenheit
+    def temp_range_delta
+      @temp_range_delta || 10
+    end
   end
 end

data/lib/weather_judge/version.rb

@@ -1,3 +1,3 @@
 module WeatherJudge
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/weather_judge/weather_data.rb

@@ -1,3 +1,6 @@
+require 'bigdecimal'
+require 'bigdecimal/util'
+
 # Calculates score for 4 different weather aspects: sky cover,
 # chance of rain, wind, and temperature
 
@@ -21,19 +24,17 @@ module WeatherJudge
     end
 
     def cloud_cover_score
-      @forecast_today.cloudCover * SCORE_WEIGHT
+      score_from_decimal_data(WeatherJudge.max_cloud_cover, @forecast_today.cloudCover)
     end
 
     def percent_rain_score
-      @forecast_today.precipProbability * SCORE_WEIGHT
+      score_from_decimal_data(WeatherJudge.max_percent_rain, @forecast_today.precipProbability)
     end
 
     def wind_score
       wind_speed = @forecast_today.windSpeed
-      max_wind_speed = 15.to_f
-      if wind_speed == 0
-        SCORE_WEIGHT
-      elsif wind_speed < max_wind_speed
+      max_wind_speed = WeatherJudge.max_wind_speed.to_f
+      if wind_speed < max_wind_speed
         ((max_wind_speed - wind_speed) / max_wind_speed) * SCORE_WEIGHT
       else
         0
@@ -41,15 +42,35 @@ module WeatherJudge
     end
 
     def temperature_score
-      max_temperature = @forecast_today.temperatureMax
+      high_today = @forecast_today.temperatureMax
+      min_ideal_temp = WeatherJudge.ideal_temp_range[:min]
+      max_ideal_temp = WeatherJudge.ideal_temp_range[:max]
+      delta = WeatherJudge.temp_range_delta
 
-      if max_temperature > 67 && max_temperature < 77
+      if high_today > min_ideal_temp && high_today < max_ideal_temp
         SCORE_WEIGHT
-      elsif max_temperature > 55 && max_temperature < 67 || max_temperature > 77 && max_temperature < 85
+      elsif high_today > min_ideal_temp - delta && high_today < min_ideal_temp ||
+          high_today > max_ideal_temp && high_today < max_ideal_temp + delta
         SCORE_WEIGHT.to_f / 2
       else
         SCORE_WEIGHT.to_f / 4
       end
     end
+
+    private
+
+    # Calculates weather quality from decimal data, with an assumption that larger the
+    # data value the worse. E.g. (80% cloud cover returns smaller score than 50% cloud cover.)
+    def score_from_decimal_data(max_allowed, data)
+      if !max_allowed.nil?
+        if data < max_allowed
+          (((max_allowed.to_d - data) / max_allowed) * SCORE_WEIGHT).to_f
+        else
+          0
+        end
+      else
+        ((1.to_d - data) * SCORE_WEIGHT).to_f
+      end
+    end
   end
 end

data/lib/weather_judge.rb

@@ -10,11 +10,26 @@ module WeatherJudge
 
     # Retrieves WeatherData object for today's forecast given latitude and longitude.
     def run(latitude, longitude)
+      validate_coordinates(latitude, longitude)
+
       ForecastIO.api_key = WeatherJudge.forecast_io_api_key
       forecast = ForecastIO.forecast(latitude, longitude, params: { exclude: 'hourly,minutely,alerts,flags'})
+
+      if forecast.nil?
+        raise StandardError.new("Unable to obtain forecast! Check your network connectivity and API key")
+      end
+
       @forecast_today = forecast.daily.data.first
 
       WeatherData.new(@forecast_today)
     end
+
+    private
+
+    def validate_coordinates(latitude, longitude)
+      unless latitude >= -90 && latitude <= 90 && longitude >= -180 && longitude <= 180
+        raise ArgumentError.new("Invalid coordinates!")
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: weather_judge
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Makoto Scott-Hinkle
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-29 00:00:00.000000000 Z
+date: 2016-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler