tricle 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ae60bb0e6e671d65f0c1901458bdb6a2a8ea730
-  data.tar.gz: 4714ec2150c42c605587d3cea5fd05382a60f4ab
+  metadata.gz: 1e1bf9319ba25a271eaae97c379e62f2f6a6b68e
+  data.tar.gz: 4a515d52060d25dcae9a4f6c00c41786bf930b10
 SHA512:
-  metadata.gz: b0b2c91ada726e91f976c1cb5ed6c421c9a8a8e4a8d6f633f599bd644e71aa80af59157835cbad37ad844952abe3d60a59e5fe272d1a92c672133d44d871e9c1
-  data.tar.gz: 365357668547fc809ace7212a7d2a9931850b8d69d97f0d85b7e0713b23c205cddcbee6ecb96596c92ae1caba151ba5786441594dc8492e26c279e41df122f5a
+  metadata.gz: bc6c048e313464575809c42d0dfd56857893be868834de9b8fc3c411c05dcfe813401cd60589ba4f9a65c0d7a7cf810486a5b542a2ece34857f102cec507d040
+  data.tar.gz: 204151436a1410c2b7138dd1480f929e733a8260b4c6b1a97dc893ad6c3f3dd46f8a62ebbd7e15fa3743b608bab95c56c34e9566be0a858802205684229bdc98

data/.gitignore

@@ -15,3 +15,4 @@ spec/reports
 test/tmp
 test/version_tmp
 tmp
+gemfiles/*.lock

data/.travis.yml

@@ -2,3 +2,6 @@ language: ruby
 rvm:
   - 1.9.3
   - 2.0.0
+gemfile:
+  - gemfiles/rails_3.gemfile
+  - gemfiles/rails_4.gemfile

data/Appraisals

@@ -0,0 +1,9 @@
+appraise "rails-3" do
+  gem 'actionmailer', '3.2.19'
+  gem 'activesupport', '3.2.19'
+end
+
+appraise "rails-4" do
+  gem 'actionmailer', '4.1.5'
+  gem 'activesupport', '4.1.5'
+end

data/CONTRIBUTING.md

@@ -17,7 +17,6 @@ bundle exec guard
 To see a live preview with dummy data:
 
 ```bash
-gem install shotgun
-shotgun
-open http://localhost:9393/test_mailer.html
+bundle exec rake tricle:preview
+open http://localhost:8080
 ```

data/Gemfile

@@ -1,4 +1,16 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in tricle.gemspec
 gemspec
+
+group :development, :test do
+  gem 'appraisal'
+  gem 'bundler'
+  gem 'byebug', platforms: :mri_20
+  gem 'guard', '~> 2.6'
+  gem 'guard-rspec'
+  gem 'rake'
+  gem 'rspec', '~> 3.0'
+  gem 'ruby_gntp'
+  gem 'shotgun'
+  gem 'timecop', '~> 0.7'
+end

data/Guardfile

@@ -1,6 +1,6 @@
 notification :gntp
 
-guard :rspec, all_on_start: true do
+guard :rspec, cmd: 'bundle exec rspec', all_on_start: true do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/}) { 'spec' }
   watch('spec/spec_helper.rb') { 'spec' }

data/README.md

@@ -1,4 +1,4 @@
-# Tricle [![Build Status](https://travis-ci.org/artsy/tricle.png?branch=master)](https://travis-ci.org/artsy/tricle) [![Code Climate](https://codeclimate.com/github/artsy/tricle.png)](https://codeclimate.com/github/artsy/tricle)
+# Tricle [![Build Status](https://travis-ci.org/afeld/tricle.png?branch=master)](https://travis-ci.org/afeld/tricle) [![Code Climate](https://codeclimate.com/github/afeld/tricle.png)](https://codeclimate.com/github/afeld/tricle)
 
 Automated metrics reporting via email.  It's datastore-agnostic, so you can query SQL, MongoDB, external APIs, etc. to generate the stats you need.  See [here](https://github.com/afeld/tricle-afeld) for an example implementation ([live demo](http://tricle.afeld.me/weekly_metrics)).
 
@@ -12,7 +12,7 @@ This gem can be used within an existing project (e.g. a Rails app), or standalon
 
 ```ruby
 # Gemfile
-gem 'tricle', '~> 0.1.0'
+gem 'tricle', '~> 0.2.0'
 
 # Rakefile
 require 'tricle/tasks'
@@ -51,14 +51,15 @@ class MyMetric < Tricle::Metric
     # ...
   end
 
-  # Retrieve the cumulative value for this metric.
+  # Optional: Retrieve the cumulative value for this metric. If not defined,
+  # the total won't be displayed in the mailer.
   #
   # @return [Fixnum] the grand total
   def total
     # ...
   end
 
-  # Optional: only necessary if using `list` for this Metric within your Mailer.
+  # Optional: Only necessary if using `list` for this Metric within your Mailer.
   #
   # @param start_at [Time]
   # @param end_at [Time] non-inclusive
@@ -73,11 +74,11 @@ end
 ActiveRecord example:
 
 ```ruby
-# metrics/new_users.rb
+# app/metrics/new_users.rb
 class NewUsers < Tricle::Metric
 
   def size_for_range(start_at, end_at)
-    self.size_for_range(start_at, end_at).size
+    self.items_for_range(start_at, end_at).count
   end
 
   def total
@@ -85,16 +86,12 @@ class NewUsers < Tricle::Metric
   end
 
   def items_for_range(start_at, end_at)
-    self.size_for_range(start_at, end_at)
+    self.users.where('created_at >= ? AND created_at < ?', start_at, end_at)
   end
 
 
   private
 
-  def size_for_range(start_at, end_at)
-    self.users.where('created_at >= ? AND created_at < ?', start_at, end_at)
-  end
-
   # You can add whatever helper methods in that class that you need.
   def users
     # non-deleted Users
@@ -104,6 +101,24 @@ class NewUsers < Tricle::Metric
 end
 ```
 
+If you would like finer-grain optimization, the methods included from the [`Aggregation`](lib/tricle/arregation.rb) mixin can be overridden.
+
+#### "Lower is better" metrics
+
+By default, Tricle highlights numbers that increased in green, and those that decreased in red. If you have a metric where a *lower* number is considered better, you'll want to override the `#better` method so Tricle highlights your cells properly:
+
+```ruby
+class LowerIsBetterMetric < Tricle::Metric
+  def better
+    :lower
+  end
+
+  ...
+end
+```
+
+You can also return `:none`, and none of your cells for that metric will be highlighted green or red.
+
 ### Mailers
 
 Mailers specify how a particular set of Metrics should be sent.  You can define one or multiple, to send different metrics to different groups of people.
@@ -143,7 +158,7 @@ end
 e.g.
 
 ```ruby
-# mailers/weekly_insights.rb
+# app/mailers/weekly_insights.rb
 class WeeklyInsights < Tricle::Mailer
 
   default(
@@ -199,6 +214,12 @@ To send all Tricle emails, run
 rake tricle:emails:send
 ```
 
+To set a speficic time zone, use the `TZ` environment variable (see the list [here](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)).
+
+```bash
+TZ=UTC rake tricle:emails:send
+```
+
 ### Cron Setup
 
 TODO

data/gemfiles/rails_3.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionmailer", "3.2.19"
+gem "activesupport", "3.2.19"
+
+group :development, :test do
+  gem "appraisal"
+  gem "bundler"
+  gem "byebug", :platforms => :mri_20
+  gem "guard", "~> 2.6"
+  gem "guard-rspec"
+  gem "rake"
+  gem "rspec", "~> 3.0"
+  gem "ruby_gntp"
+  gem "shotgun"
+  gem "timecop", "~> 0.7"
+end
+
+gemspec :path => "../"

data/gemfiles/rails_4.gemfile

@@ -0,0 +1,21 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "actionmailer", "4.1.5"
+gem "activesupport", "4.1.5"
+
+group :development, :test do
+  gem "appraisal"
+  gem "bundler"
+  gem "byebug", :platforms => :mri_20
+  gem "guard", "~> 2.6"
+  gem "guard-rspec"
+  gem "rake"
+  gem "rspec", "~> 3.0"
+  gem "ruby_gntp"
+  gem "shotgun"
+  gem "timecop", "~> 0.7"
+end
+
+gemspec :path => "../"

data/lib/tricle/aggregation.rb

@@ -0,0 +1,46 @@
+require 'active_support/concern'
+
+module Tricle
+  module Aggregation
+    extend ActiveSupport::Concern
+
+    included do
+      attr_reader :now
+
+      def initialize
+        # TODO allow Time to be passed in so it can be frozen
+        @now = Time.now
+      end
+    end
+
+    def days_ago(n)
+      start_at = self.now.beginning_of_day.ago(n.days)
+      end_at = start_at + 1.day
+      self.size_for_range(start_at, end_at)
+    end
+
+    def yesterday
+      self.days_ago(1)
+    end
+
+    def weeks_ago(n)
+      start_at = self.now.beginning_of_week.weeks_ago(n)
+      end_at = start_at + 7.days
+      self.size_for_range(start_at, end_at)
+    end
+
+    def last_week
+      self.weeks_ago(1)
+    end
+
+    def weeks_average(past_num_weeks)
+      weeks_range = 1..past_num_weeks
+      total = weeks_range.reduce(0){|sum, n| sum + self.weeks_ago(n) }
+      total.to_f / past_num_weeks
+    end
+
+    def week_average_this_quarter
+      self.weeks_average(13)
+    end
+  end
+end

data/lib/tricle/email_helper.rb

@@ -4,31 +4,56 @@ require 'active_support/core_ext/numeric/time'
 module Tricle
   module EmailHelper
     def weeks_ago(n)
-      Date.today.beginning_of_week.weeks_ago(n)
+      Date.today.beginning_of_week.ago(n.weeks)
     end
 
     def format_date(date)
       date.strftime('%-m/%-d/%y')
     end
 
+    def format_number(number)
+      number_with_delimiter((number.abs >= 100 ? number.round : sig_figs(number)))
+    end
+
     def number_with_delimiter(number)
       # from http://stackoverflow.com/a/11466770/358804
-      number.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse
+      integer, decimal = number.to_s.split(".")
+      [integer.to_s.reverse.gsub(/(\d{3})(?=\d)/, '\\1,').reverse, decimal].compact.join('.')
+    end
+
+    def sig_figs(number, num_sig_figs = 3)
+      # http://six-impossible.blogspot.com/2011/05/significant-digits-in-ruby-float.html
+      f = sprintf("%.#{num_sig_figs - 1}e", number).to_f
+      i = f.to_i # avoid
+      i == f && i.to_s.size > num_sig_figs ? i : f
     end
 
     def percent_change(new_val, old_val)
-      if old_val == 0
+      if old_val == new_val
+        'No change'
+      elsif old_val == 0
         new_val >= 0 ? '+' : '-'
       else
         fraction = (new_val - old_val) / old_val.to_f
-        sprintf('%+.1f%', fraction * 100.0)
+        (fraction >= 0 ? '+' : '').concat("#{sig_figs(fraction * 100.0)}%")
+      end
+    end
+
+    def percent_change_class(new_val, old_val, better)
+      case better
+      when :higher
+        (new_val >= old_val) ? 'good' : 'bad'
+      when :lower
+        (new_val >= old_val) ? 'bad' : 'good'
+      else
+        ''
       end
     end
 
-    def percent_change_cell(new_val, old_val)
-      cls = (new_val >= old_val) ? 'positive' : 'negative'
+    def percent_change_cell(new_val, old_val, better)
+      cls = self.percent_change_class(new_val, old_val, better)
       pct_str = percent_change(new_val, old_val)
-      old_val_str = number_with_delimiter(old_val.round)
+      old_val_str = format_number(old_val)
       %[<td class="#{cls}"><div>#{pct_str}</div><div>#{old_val_str}</div></td>].html_safe
     end
 

data/lib/tricle/metric.rb

@@ -1,9 +1,16 @@
 require 'active_support/core_ext/date/calculations'
 require 'active_support/core_ext/numeric/time'
 require_relative 'abstract_method_error'
+require_relative 'aggregation'
 
 module Tricle
   class Metric
+    include Aggregation
+
+    def better
+      :higher
+    end
+
     def title
       self.class.name.titleize
     end
@@ -12,12 +19,12 @@ module Tricle
       self.items_for_range(start_at, end_at).size
     end
 
-    def total
+    def items_for_range(start_at, end_at)
       raise Tricle::AbstractMethodError.new
     end
 
-    def items_for_range(start_at, end_at)
-      raise Tricle::AbstractMethodError.new
+    def total?
+      self.respond_to?(:total)
     end
   end
 end

data/lib/tricle/presenters/group.rb

@@ -1,19 +1,17 @@
-require_relative 'metric'
 require_relative 'section'
 
 module Tricle
   module Presenters
     class Group < Section
-      attr_reader :metric_presenters, :title
+      attr_reader :metrics, :title
 
       def initialize(title=nil)
         @title = title
-        @metric_presenters = []
+        @metrics = []
       end
 
       def add_metric(klass)
-        presenter = Tricle::Presenters::Metric.new(klass)
-        self.metric_presenters << presenter
+        self.metrics << klass.new
       end
     end
   end

data/lib/tricle/templates/email.css

@@ -36,12 +36,12 @@ td div:first-child {
   font-size: 20px;
 }
 
-.positive {
+.good {
   background-color: #e4ffea;
   color: green;
 }
 
-.negative {
+.bad {
   background-color: #ffe3e4;
   color: #c21717;
 }

data/lib/tricle/templates/email.html.erb

@@ -27,15 +27,17 @@
               <%= quarter_dates_cell %>
             </th>
           </tr>
-          <% section.metric_presenters.each do |metric| %>
+          <% section.metrics.each do |metric| %>
             <tr>
               <th class="metric-title"><%= metric.title %></th>
               <td>
-                <div><%= number_with_delimiter(metric.last_week) %></div>
-                <div><%= number_with_delimiter(metric.total) %> (total)</div>
+                <div><%= format_number(metric.last_week) %></div>
+                <% if metric.total? %>
+                  <div><%= format_number(metric.total) %> (total)</div>
+                <% end %>
               </td>
-              <%= percent_change_cell(metric.last_week, metric.weeks_ago(2)) %>
-              <%= percent_change_cell(metric.last_week, metric.week_average_this_quarter) %>
+              <%= percent_change_cell(metric.last_week, metric.weeks_ago(2), metric.better) %>
+              <%= percent_change_cell(metric.last_week, metric.week_average_this_quarter, metric.better) %>
             </tr>
           <% end %>
         <% end %>

data/lib/tricle/version.rb

@@ -1,3 +1,3 @@
 module Tricle
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end