rubyvis 0.1.7 → 0.2.0

data/lib/rubyvis/color/colors.rb

@@ -1,14 +1,61 @@
 module Rubyvis
+  #
+  # :section: colors/Ramp.js
+  
+  
+  # Returns a linear color ramp from the specified <tt>start</tt> color to the
+  # specified <tt>end</tt> color. The color arguments may be specified either as
+  # <tt>string</tt>s or as Rubyvis::Color. This is equivalent to:
+  #
+  # <pre>    pv.Scale.linear().domain(0, 1).range(...)</pre>  
+  def self.ramp(*arguments)
+    start, _end, dummy = arguments
+    scale = Rubyvis.Scale.linear
+    scale.range(*arguments)
+    scale
+  end
+  
+  # :section: colors/Colors.js
+  
   # Alias for Rubyvis::Colors
   def self.Colors
     Rubyvis::Colors
   end
+  
+  # Returns a new categorical color encoding using the specified colors.  The
+  # arguments to this method are an array of colors; see Rubyvis.color(). For
+  # example, to create a categorical color encoding using the <tt>species</tt>
+  # attribute:
+  #
+  # <pre>Rubyvis.colors("red", "green", "blue").by(lambda{|d| d.species})</pre>
+  #
+  # The result of this expression can be used as a fill- or stroke-style
+  # property. This assumes that the data's <tt>species</tt> attribute is a
+  # string.
+  #
   def self.colors(*args)
     scale=Rubyvis::Scale.ordinal
     scale.range(*args)
     scale
   end
+  
+  # A collection of standard color palettes for categorical encoding.
   module Colors
+    
+    # Returns a new 10-color scheme. The arguments to this constructor are
+    # optional, and equivalent to calling Rubyvis::Scale::Ordinal.domain. The
+    # following colors are used:
+    #
+    # <div style="background:#1f77b4;">#1f77b4</div>
+    # <div style="background:#ff7f0e;">#ff7f0e</div>
+    # <div style="background:#2ca02c;">#2ca02c</div>
+    # <div style="background:#d62728;">#d62728</div>
+    # <div style="background:#9467bd;">#9467bd</div>
+    # <div style="background:#8c564b;">#8c564b</div>
+    # <div style="background:#e377c2;">#e377c2</div>
+    # <div style="background:#7f7f7f;">#7f7f7f</div>
+    # <div style="background:#bcbd22;">#bcbd22</div>
+    # <div style="background:#17becf;">#17becf</div>
     def self.category10(*arguments)
       scale = Rubyvis.colors(
       "#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
@@ -16,6 +63,30 @@ module Rubyvis
       scale.domain(*arguments) if arguments.size>0
       scale
     end
+    
+    # Returns a new alternative 19-color scheme. The arguments to this constructor
+    # are optional, and equivalent to calling
+    # Rubyvis::Scale::Ordinal.domain. The following colors are used:
+    #
+    # <div style="background:#9c9ede;">#9c9ede</div>
+    # <div style="background:#7375b5;">#7375b5</div>
+    # <div style="background:#4a5584;">#4a5584</div>
+    # <div style="background:#cedb9c;">#cedb9c</div>
+    # <div style="background:#b5cf6b;">#b5cf6b</div>
+    # <div style="background:#8ca252;">#8ca252</div>
+    # <div style="background:#637939;">#637939</div>
+    # <div style="background:#e7cb94;">#e7cb94</div>
+    # <div style="background:#e7ba52;">#e7ba52</div>
+    # <div style="background:#bd9e39;">#bd9e39</div>
+    # <div style="background:#8c6d31;">#8c6d31</div>
+    # <div style="background:#e7969c;">#e7969c</div>
+    # <div style="background:#d6616b;">#d6616b</div>
+    # <div style="background:#ad494a;">#ad494a</div>
+    # <div style="background:#843c39;">#843c39</div>
+    # <div style="background:#de9ed6;">#de9ed6</div>
+    # <div style="background:#ce6dbd;">#ce6dbd</div>
+    # <div style="background:#a55194;">#a55194</div>
+    # <div style="background:#7b4173;">#7b4173</div>
     def self.category19(*arguments)
       scale = Rubyvis.colors(
       "#9c9ede", "#7375b5", "#4a5584", "#cedb9c", "#b5cf6b",
@@ -25,6 +96,33 @@ module Rubyvis
       scale.domain(*arguments) if arguments.size>0
       scale
     end
+    
+
+    # Returns a new 20-color scheme. The arguments to this constructor are
+    # optional, and equivalent to calling Rubyvis::Scale::Ordinal.domain. The
+    # following colors are used:
+    #
+    # <div style="background:#1f77b4;">#1f77b4</div>
+    # <div style="background:#aec7e8;">#aec7e8</div>
+    # <div style="background:#ff7f0e;">#ff7f0e</div>
+    # <div style="background:#ffbb78;">#ffbb78</div>
+    # <div style="background:#2ca02c;">#2ca02c</div>
+    # <div style="background:#98df8a;">#98df8a</div>
+    # <div style="background:#d62728;">#d62728</div>
+    # <div style="background:#ff9896;">#ff9896</div>
+    # <div style="background:#9467bd;">#9467bd</div>
+    # <div style="background:#c5b0d5;">#c5b0d5</div>
+    # <div style="background:#8c564b;">#8c564b</div>
+    # <div style="background:#c49c94;">#c49c94</div>
+    # <div style="background:#e377c2;">#e377c2</div>
+    # <div style="background:#f7b6d2;">#f7b6d2</div>
+    # <div style="background:#7f7f7f;">#7f7f7f</div>
+    # <div style="background:#c7c7c7;">#c7c7c7</div>
+    # <div style="background:#bcbd22;">#bcbd22</div>
+    # <div style="background:#dbdb8d;">#dbdb8d</div>
+    # <div style="background:#17becf;">#17becf</div>
+    # <div style="background:#9edae5;">#9edae5</div>
+
     def self.category20(*arguments)
       scale = Rubyvis.colors(
       "#1f77b4", "#aec7e8", "#ff7f0e", "#ffbb78", "#2ca02c",

data/lib/rubyvis/layout/stack.rb

@@ -1,225 +1,300 @@
 module Rubyvis
   class Layout
-  def self.Stack
-    Rubyvis::Layout::Stack
-  end
-  class Stack < Rubyvis::Layout
-    @properties=Panel.properties.dup    
-    
-    attr_accessor :_x, :_y, :_values, :prop
-    attr_accessor_dsl :orient,:offset, :order, :layers
-    def self.defaults
-      Stack.new.extend(Layout.defaults).orient("bottom-left").offset("zero").layers([[]])
-    end
-    def initialize
-      super
-      @none=lambda {nil}
-      @prop = {"t"=> @none, "l"=> @none, "r"=> @none, "b"=> @none, "w"=> @none, "h"=> @none}
-      @values=nil
-      @_x=lambda {return 0}
-      @_y=lambda {return 0}
-      @_values=Rubyvis.identity
-    end
-    def x(f)
-      @_x=Rubyvis.functor(f)
-      return self
-    end
-    def y(f)
-      @_y=Rubyvis.functor(f)
-      return self
+    # Alias for Rubyvis::Layout::Stack 
+    def self.Stack
+      Rubyvis::Layout::Stack
     end
-    def values(f=nil)
-      if f.nil?
-        @values
-      else
-        @_values=Rubyvis.functor(f)
-        return self
-      end
-    end
-    
     
-    def proxy(name)
-      that=self
-      return lambda {
-        a=that.prop[name].js_call(self, self.parent.index, self.index);
-        puts "proxy(#{name}): #{a}" if $DEBUG
-        a
-      }
-    end
-    
-    def build_implied(s)
-      # puts "Build stack" if $DEBUG
-      panel_build_implied(s)
-      data = s.layers
-      n = data.size
-      m = nil
-      orient = s.orient
-      if orient =~/^(top|bottom)\b/
-        horizontal=true
-      else
-        horizontal=false
+    # Implements a layout for stacked visualizations, ranging from simple
+    # stacked bar charts to more elaborate "streamgraphs" composed of stacked
+    # areas. Stack layouts uses length as a visual encoding, as opposed to
+    # position, as the layers do not share an aligned axis.
+    #
+    # <p>Marks can be stacked vertically or horizontally. For example,
+    #
+    #   vis.add(Rubyvis::Layout::Stack)
+    #     .layers([[1, 1.2, 1.7, 1.5, 1.7],
+    #              [.5, 1, .8, 1.1, 1.3],
+    #              [.2, .5, .8, .9, 1]])
+    #     .x(lambda { index * 35})
+    #     .y(lambda {|d| d * 40})
+    #   .layer.add(Rubyvis::Area)
+    #
+    # specifies a vertically-stacked area chart, using the default "bottom-left"
+    # orientation with "zero" offset. This visualization can be easily changed into
+    # a streamgraph using the "wiggle" offset, which attempts to minimize change in
+    # slope weighted by layer thickness. See the offset property for more
+    # supported streamgraph algorithms.
+    #
+    # <p>In the simplest case, the layer data can be specified as a two-dimensional
+    # array of numbers. The <tt>x</tt> and <tt>y</tt> psuedo-properties are used to
+    # define the thickness of each layer at the given position, respectively; in
+    # the above example of the "bottom-left" orientation, the <tt>x</tt> and
+    # <tt>y</tt> psuedo-properties are equivalent to the <tt>left</tt> and
+    # <tt>height</tt> properties that you might use if you implemented a stacked
+    # area by hand.
+    #
+    # <p>The advantage of using the stack layout is that the baseline, i.e., the
+    # <tt>bottom</tt> property is computed automatically using the specified offset
+    # algorithm. In addition, the order of layers can be computed using a built-in
+    # algorithm via the <tt>order</tt> property.
+    #
+    # <p>With the exception of the "expand" <tt>offset</tt>, the stack layout does
+    # not perform any automatic scaling of data; the values returned from
+    # <tt>x</tt> and <tt>y</tt> specify pixel sizes. To simplify scaling math, use
+    # this layout in conjunction with Rubyvis::Scale.linea} or similar.
+    #
+    # <p>In other cases, the <tt>values</tt> psuedo-property can be used to define
+    # the data more flexibly. As with a typical panel &amp; area, the
+    # <tt>layers</tt> property corresponds to the data in the enclosing panel,
+    # while the <tt>values</tt> psuedo-property corresponds to the data for the
+    # area within the panel. For example, given an array of data values:
+    #
+    #   crimea = [
+    #   { date: "4/1854", wounds: 0, other: 110, disease: 110 },
+    #   { date: "5/1854", wounds: 0, other: 95, disease: 105 },
+    #   { date: "6/1854", wounds: 0, other: 40, disease: 95 },
+    #   ...
+    #
+    # and a corresponding array of series names:
+    #
+    #   causes = [:wounds, :other, :disease]
+    #
+    # Separate layers can be defined for each cause like so:
+    #
+    #   vis.add(pv.Layout.Stack)
+    #     .layers(causes)
+    #     .values(crimea)
+    #     .x(lambda {|d| x.scale(d[:date]})
+    #     .y(lambda {|d,dp| y.scale(d[dp])})
+    #   .layer.add(pv.Area)
+    #
+    # As with the panel &amp; area case, the datum that is passed to the
+    # psuedo-properties <tt>x</tt> and <tt>y</tt> are the values (an element in
+    # <tt>crimea</tt>); the second argument is the layer data (a string in
+    # <tt>causes</tt>). Additional arguments specify the data of enclosing panels, if any.
+    class Stack < Rubyvis::Layout
+      @properties=Panel.properties.dup    
+      
+      attr_accessor :_x, :_y, :_values, :prop
+      attr_accessor_dsl :orient,:offset, :order, :layers
+      def self.defaults
+        Stack.new.extend(Layout.defaults).orient("bottom-left").offset("zero").layers([[]])
       end
-      h = self.parent.send(horizontal ? "height" : "width")
-      x = []
-      y = []
-      dy = []
       
-      #
-      # Iterate over the data, evaluating the values, x and y functions. The
-      # context in which the x and y psuedo-properties are evaluated is a
-      # pseudo-mark that is a grandchild of this layout.
-      #
-      stack = Rubyvis::Mark.stack
+      # Constructs a new, empty stack layout. Layouts are not typically constructed
+      # directly; instead, they are added to an existing panel via
+      # Rubyvis::Mark.add
+      def initialize
+        super
+        @none=lambda {nil}
+        @prop = {"t"=> @none, "l"=> @none, "r"=> @none, "b"=> @none, "w"=> @none, "h"=> @none}
+        @values=nil
+        @_x=lambda {return 0}
+        @_y=lambda {return 0}
+        @_values=Rubyvis.identity
+      end
+      def x(f)
+        @_x=Rubyvis.functor(f)
+        return self
+      end
+      def y(f)
+        @_y=Rubyvis.functor(f)
+        return self
+      end
+      def values(f=nil)
+        if f.nil?
+          @values
+        else
+          @_values=Rubyvis.functor(f)
+          return self
+        end
+      end
       
-      o = OpenStruct.new({:parent=> OpenStruct.new({:parent=> self})})
-      stack.unshift(nil)
-      values = []
-      n.times {|i|
-      dy[i] = []
-      y[i] = []
-      o.parent.index = i
-      stack[0] = data[i]
-      values[i] = self._values.js_apply(o.parent, stack);
-      m = values[i].size if (i==0) 
-      stack.unshift(nil)
-      m.times {|j|
-        stack[0] = values[i][j]
-        o.index = j
-        x[j] = self._x.js_apply(o, stack) if i==0
-        dy[i][j] = self._y.js_apply(o, stack)
-      }
-      stack.shift()
-      }
-      stack.shift()
       
-      # order
-      _index=nil
-      case (s.order) 
-      when "inside-out" 
-        max  = dy.map {|v| Rubyvis.max.index(v) }
-        map  = pv.range(n).sort {|a,b| return max[a] - max[b]}
-        sums = dy.map {|v| Rubyvis.sum(v)}
-        top = 0
-        bottom = 0
-        tops = []
-        bottoms = []
-        n.times {|i|
-          j = map[i]
-          if (top < bottom) 
-            top += sums[j];
-            tops.push(j);
-          else
-            bottom += sums[j];
-            bottoms.push(j);
-          end
+      def proxy(name)
+        that=self
+        return lambda {
+          a=that.prop[name].js_call(self, self.parent.index, self.index);
+          puts "proxy(#{name}): #{a}" if $DEBUG
+          a
         }
-        _index = bottoms.reverse+tops
-        
-      when "reverse"
-        _index = Rubyvis.range(n - 1, -1, -1)
-      else
-        _index = Rubyvis.range(n)
       end
       
-      #/* offset */
-      case (s.offset) 
-      when "silohouette"
+      def build_implied(s)
+        # puts "Build stack" if $DEBUG
+        panel_build_implied(s)
+        data = s.layers
+        n = data.size
+        m = nil
+        orient = s.orient
+        if orient =~/^(top|bottom)\b/
+          horizontal=true
+        else
+          horizontal=false
+        end
+        h = self.parent.send(horizontal ? "height" : "width")
+        x = []
+        y = []
+        dy = []
+        
+        #
+        # Iterate over the data, evaluating the values, x and y functions. The
+        # context in which the x and y psuedo-properties are evaluated is a
+        # pseudo-mark that is a grandchild of this layout.
+        #
+        stack = Rubyvis::Mark.stack
+        
+        o = OpenStruct.new({:parent=> OpenStruct.new({:parent=> self})})
+        stack.unshift(nil)
+        values = []
+        n.times {|i|
+        dy[i] = []
+        y[i] = []
+        o.parent.index = i
+        stack[0] = data[i]
+        values[i] = self._values.js_apply(o.parent, stack);
+        m = values[i].size if (i==0) 
+        stack.unshift(nil)
         m.times {|j|
-          o = 0;
-          n.times {|i| 
-            o += dy[i][j]
-          }
-          y[_index[0]][j] = (h - o) / 2.0;
+          stack[0] = values[i][j]
+          o.index = j
+          x[j] = self._x.js_apply(o, stack) if i==0
+          dy[i][j] = self._y.js_apply(o, stack)
         }
-      
-      when "wiggle"
-        o = 0;
-        n.times {|i|  o += dy[i][0] }
-        
-        y[_index[0]][0] = o = (h - o) / 2.0
+        stack.shift()
+        }
+        stack.shift()
         
-        (1...m).each  {|j|
-          s1 = 0
-          s2 = 0
-          dx = x[j] - x[j - 1]
-          n.times {|i| s1 += dy[i][j]}
+        # order
+        _index=nil
+        case (s.order) 
+        when "inside-out" 
+          max  = dy.map {|v| Rubyvis.max.index(v) }
+          map  = pv.range(n).sort {|a,b| return max[a] - max[b]}
+          sums = dy.map {|v| Rubyvis.sum(v)}
+          top = 0
+          bottom = 0
+          tops = []
+          bottoms = []
           n.times {|i|
-            
-            s3 = (dy[_index[i]][j] - dy[_index[i]][j - 1]) / (2.0 * dx)
-            i.times {|k|
-              s3 += (dy[_index[k]][j] - dy[_index[k]][j - 1]) / dx.to_f
+            j = map[i]
+            if (top < bottom) 
+              top += sums[j];
+              tops.push(j);
+            else
+              bottom += sums[j];
+              bottoms.push(j);
+            end
+          }
+          _index = bottoms.reverse+tops
+          
+        when "reverse"
+          _index = Rubyvis.range(n - 1, -1, -1)
+        else
+          _index = Rubyvis.range(n)
+        end
+        
+        #/* offset */
+        case (s.offset) 
+        when "silohouette"
+          m.times {|j|
+            o = 0;
+            n.times {|i| 
+              o += dy[i][j]
             }
-            s2 += s3 * dy[_index[i]][j]
+            y[_index[0]][j] = (h - o) / 2.0;
           }
-          o -= (s1!=0) ? s2 / s1.to_f * dx : 0
-          y[_index[0]][j] = o
+        
+        when "wiggle"
+          o = 0;
+          n.times {|i|  o += dy[i][0] }
           
-        }
-      when "expand"
+          y[_index[0]][0] = o = (h - o) / 2.0
+          
+          (1...m).each  {|j|
+            s1 = 0
+            s2 = 0
+            dx = x[j] - x[j - 1]
+            n.times {|i| s1 += dy[i][j]}
+            n.times {|i|
+              
+              s3 = (dy[_index[i]][j] - dy[_index[i]][j - 1]) / (2.0 * dx)
+              i.times {|k|
+                s3 += (dy[_index[k]][j] - dy[_index[k]][j - 1]) / dx.to_f
+              }
+              s2 += s3 * dy[_index[i]][j]
+            }
+            o -= (s1!=0) ? s2 / s1.to_f * dx : 0
+            y[_index[0]][j] = o
+            
+          }
+        when "expand"
+          m.times {|j|
+            y[_index[0]][j] = 0
+            
+            k = 0
+            n.times {|i|k += dy[i][j]}
+            if (k!=0) 
+              k = h / k.to_f
+              n.times {|i| dy[i][j] *= k}
+            else 
+              k = h / n.to_f
+              n.times { dy[i][j] = k}
+            end
+          }
+        else
+          m.times {|j| y[_index[0]][j] = 0}
+        end
+        
+        # Propagate the offset to the other series. */
         m.times {|j|
-          y[_index[0]][j] = 0
+        o = y[_index[0]][j]
+        (1...n).each {|i|
           
-          k = 0
-          n.times {|i|k += dy[i][j]}
-          if (k!=0) 
-            k = h / k.to_f
-            n.times {|i| dy[i][j] *= k}
-          else 
-            k = h / n.to_f
-            n.times { dy[i][j] = k}
-          end
+          o += dy[_index[i - 1]][j]
+          y[_index[i]][j] = o
         }
-      else
-        m.times {|j| y[_index[0]][j] = 0}
+        }
+        
+        # /* Find the property definitions for dynamic substitution. */
+        
+        i = orient.index("-")
+        pdy = horizontal ? "h" : "w"
+        px = i < 0 ? (horizontal ? "l" : "b") : orient[i + 1,1]
+        py = orient[0,1]
+        
+        @values=values
+        
+        @prop.each {|k,v|
+          @prop[k]=@none
+        }
+        # puts "stack: x:#{px}, y:#{py}, dy:#{pdy}" if $DEBUG
+        @prop[px] =lambda {|i1,j| x[j]}
+        @prop[py] =lambda {|i1,j| y[i1][j]}
+        @prop[pdy]=lambda {|i1,j| dy[i1][j]}  
       end
       
-      # Propagate the offset to the other series. */
-      m.times {|j|
-      o = y[_index[0]][j]
-      (1...n).each {|i|
+      def layer
+        that=self
+        value = Rubyvis::Mark.new().data(lambda { that.values[self.parent.index] }).top(proxy("t")).left(proxy("l")).right(proxy("r")).
+          bottom(proxy("b")).
+        width(proxy("w")).
+        height(proxy("h"))
         
-        o += dy[_index[i - 1]][j]
-        y[_index[i]][j] = o
-      }
-      }
-      
-      # /* Find the property definitions for dynamic substitution. */
-      
-      i = orient.index("-")
-      pdy = horizontal ? "h" : "w"
-      px = i < 0 ? (horizontal ? "l" : "b") : orient[i + 1,1]
-      py = orient[0,1]
-      
-      @values=values
-      
-      @prop.each {|k,v|
-        @prop[k]=@none
-      }
-      # puts "stack: x:#{px}, y:#{py}, dy:#{pdy}" if $DEBUG
-      @prop[px] =lambda {|i1,j| x[j]}
-      @prop[py] =lambda {|i1,j| y[i1][j]}
-      @prop[pdy]=lambda {|i1,j| dy[i1][j]}  
-    end
-    
-    def layer
-      that=self
-      value = Rubyvis::Mark.new().data(lambda { that.values[self.parent.index] }).top(proxy("t")).left(proxy("l")).right(proxy("r")).
-        bottom(proxy("b")).
-      width(proxy("w")).
-      height(proxy("h"))
-      
-      class << value
-        def that=(v)
-          @that = v
-        end
-        def add(type)
-          that  = @that
-          that.add( Rubyvis.Panel ).data(lambda { that.layers() }).add(type).extend( self )
+        class << value # :nodoc:
+          def that=(v)
+            @that = v
+          end
+          def add(type)
+            that  = @that
+            that.add( Rubyvis.Panel ).data(lambda { that.layers() }).add(type).extend( self )
+          end
         end
+        
+        value.that=self
+        return value
       end
-      value.that=self
-      return value
     end
   end
-  end
 end