grapht 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: e6bffdc5a59f292991c12f400d7bf92513c50aca
+  data.tar.gz: a0059941f096ba157c90d29cc32e16f1b6370861
+SHA512:
+  metadata.gz: d5a1db3b4f08a414f1d8b8c1399fe2c89cbe475db450d06a7b137528b1985ee0053d4029c3a22685a58d450899e34e124325ba136dfb8b4e8890e46ab3ab5d73
+  data.tar.gz: 8f79d9688f7f91370d5f4a5f8f0306230919d2957fc30c7e9cf9d5e67af3dd40be9f492d5075d297822df290e836911e9a9d930080113560b02e79ef96152fea

data/.gitignore

@@ -0,0 +1,20 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+.DS_Store
+profiles/

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--warnings
+--require spec_helper

data/Gemfile

@@ -0,0 +1,6 @@
+source  'https://rubygems.org'
+ruby    '2.0.0'
+
+group :test do
+  gem 'rspec'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Trade Informatics Inc.
+
+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/README.md

@@ -0,0 +1,267 @@
+<img src='http://upload.wikimedia.org/wikipedia/commons/thumb/1/15/Graft_182_%28PSF%29.png/320px-Graft_182_%28PSF%29.png' style='width: 320px; margin: 0 auto; display: block;'/>
+
+# Grapht
+
+Grapht is a server-side graphing library built on [PhantomJS](https://github.com/ariya/phantomjs/wiki)
+and utilizing [D3.js](http://d3js.org/).  Grapht provides a CLI for simple Bash scripting.
+It also profides a light-weight [Ruby](https://www.ruby-lang.org/en/)
+API to make service-level integration simple.
+
+### Why was Grapht built on PhantomJS?
+
+- PhantomJS allows us to leverage [D3.js](http://d3js.org/), a best-of-breed data visualization library
+authored by the formidable data visualization expert, Mike Bostock.  [D3.js](http://d3js.org/) is a
+battlefield tested library.
+- Using PhantomJS allows us to reuse existing data visualization logic, originally
+authored for our client-side application. This means we get consistent visualizations
+across the various layers of our stack, and we minimize developer effort.
+
+### How well does Grapht perform?
+
+While PhantomJS is able to run Javascript extremely fast, it has a slow startup
+time.  When measured on a 2.4GHz Intel Core i7 laptop, with 16GB of DDR3 RAM, the
+benchmarks<sup>†</sup> are as follows (_averaged over 10 runs_):
+
+<table style='width: 100%;'>
+  <thead>
+    <tr>
+      <th>Bytes-In</th>
+      <th>Average, Real Time <small style='color:gray; font-weight:lighter;'>( Seconds )</small></th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>1,323</td>
+      <td>1.559</td>
+    </tr>
+    <tr>
+      <td>13,527</td>
+      <td>1.675</td>
+    </tr>
+    <tr>
+      <td>135,252</td>
+      <td>1.715</td>
+    </tr>
+  </tbody>
+</table>
+
+<div style='width: 320px; margin: 0 auto;'>
+  <img src='http://i.imgur.com/NyhWdxx.jpg'/>
+  <p>
+    <small style='color:gray;'><em>time (sec.) / bytes</em></small>
+  </p>
+</div>
+
+Note that even when incrementing the amount of data-in by an order of magnitude,
+time increases minimally (_roughly √n_).  From this, we can infer a start-up time of ~1.5 seconds,
+for PhantomJS, on the aforementioned hardware.
+
+<sup>†</sup> _All measurements were collected using the following command: `time -p bin/grapht bar-horizontal < data/bar_data.json > /dev/null`_
+
+## CLI
+
+### Overview
+Grapht provides a CLI, accessed using the `bin/grapht` command.  The basic invocation
+requires one argument specifying the desired graph type, and a JSON string provided
+via `STDIN`.  For example, if we want a **horizontal bar graph**:
+
+    bin/grapht bar-horizontal < ~/my-data.json
+
+The result will be a string of **svg** markup:
+
+    <svg width="200" height="200">
+      <rect class="bar" x="0" y="13" width="0" height="50"></rect>
+      <rect class="bar" x="0" y="75" width="200" height="50"></rect>
+      <rect class="bar" x="0" y="137" width="150" height="50"></rect>
+      <g class="x axis" transform="translate(0,200)">
+        <g class="tick" style="opacity: 1; " transform="translate(0,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">20</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(20,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">22</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(40,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">24</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(60.00000000000001,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">26</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(80,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">28</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(100,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">30</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(120.00000000000001,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">32</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(140,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">34</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(160,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">36</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(180,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">38</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(200,0)">
+          <line y2="-200" x2="0"></line>
+          <text y="3" x="0" dy=".71em" style="text-anchor: middle; ">40</text>
+        </g>
+        <path class="domain" d="M0,-200V0H200V-200"></path>
+      </g>
+      <g class="y axis">
+        <g class="tick" style="opacity: 1; " transform="translate(0,38)">
+          <line x2="6" y2="0"></line>
+          <text x="9" y="0" dy=".32em" style="text-anchor: start; ">foo</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(0,100)">
+          <line x2="6" y2="0"></line>
+          <text x="9" y="0" dy=".32em" style="text-anchor: start; ">bar</text>
+        </g>
+        <g class="tick" style="opacity: 1; " transform="translate(0,162)">
+          <line x2="6" y2="0"></line>
+          <text x="9" y="0" dy=".32em" style="text-anchor: start; ">baz</text>
+        </g>
+        <path class="domain" d="M6,0H0V200H6"></path>
+      </g>
+    </svg>
+
+### Usage
+
+    bin/grapht GRAPH_TYPE [options] < JSON_INPUT
+
+### Options
+
+Currently supported flags:
+
+<table style='width: 100%;'>
+  <thead>
+    <tr>
+      <th>Flag</th>
+      <th>Description</th>
+      <th>Allowable Values</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>-f</code></td>
+      <td>Specifies an output format for the generated graph.</td>
+      <td><code>png|jpg|gif|pdf</code></td>
+    </tr>
+  </tbody>
+</table>
+
+## Ruby API
+
+To generate the same **horizontal bar graph** generated in the CLI
+section--using the Ruby API--we can do the following:
+
+    json   = "[{ \"name\": \"foo\", \"value\": 20 },{ \"name\": \"bar\", \"value\": 40 },{ \"name\": \"baz\", \"value\": 35 }]"
+    type   = Grapht::Type::BAR_HORIZONTAL
+    graph  = Grapht::Shell.exec type, json
+
+## Supported Graphs
+
+Grapht is extensible, allowing users to create new graph definitions using
+Javascript and [D3.js](http://d3js.org).  However, Grapht provides a handful
+of graph definitions out of the box:
+
+- Horizontal Bar Graph
+- Vertical Bar Graph
+- Line Graph
+- Pie Graph
+
+### User Defined Graph Definitions
+
+Users may create their own graph definitions with Grapht.  To do this, we first
+have to register a location where the new graph definitions will reside.  This
+is done simply by setting the `EXT_GRAPHT_DEFINITIONS_HOME` environment variable.
+For example, if we have our custom definitions stored in
+`~/Development/my_project/my_graph_defs`, we set our environment variable to this
+path:
+
+    export EXT_GRAPHT_DEFINITIONS_HOME=~/Development/my_project/my_graph_defs
+    bin/grapht my-scatterplot < ~/my-data.json
+
+In the example above, we supply the name of our new graph definition
+(`my-scatterplot`) to the Grapht CLI.  Grapht will first look in
+`EXT_GRAPHT_DEFINITIONS_HOME` for the file `my-scatterplot.js`.  If it's not
+found, it will check its own internal set of graph definitions.  If it is found,
+Grapht will load the new definition.
+
+##### Creating Your First Graph Definition
+
+All graph definitions must comply with a short set of rules:
+
+- They must be wrapped within a function that takes a single data argument.
+- They must generate one, and only one root DOM node.
+
+Here's an example of a valid graph definition:
+
+    function(data) {    // <- our wrapper fuction
+      var width  = 200,
+          height = 200;
+
+      // our single root node added to document.body
+      var svg = d3.select("body").append("svg")
+                                 .attr("width", width)
+                                 .attr("height", height);
+
+      // a bunch of D3 operations on svg...
+    }
+
+## Error Handling
+
+Grapht will raise an error in the following scenarios:
+
+- When any of its dependencies cannot be found.  _Currently, Grapht
+depends upon the D3.js and JSON2 javascript libraries.  These dependencies
+can be found in Grapht's `vendor` directory._
+- When an unknown graph type is supplied to Grapht
+- When malformed JSON is supplied to Grapht
+- When PhantomJS raises an internal error
+
+When using Grapht's CLI, all errors are printed to `STDERR` and Grapht exits
+with an exit-code of `1`.
+
+When accessing Grapht's features through the Ruby API, all errors are presented
+as instances of `Grapht::Shell::Error`.  The error messages, in this case, are
+consistent with the errors messages raised from the CLI.
+
+## Rails Integration
+
+While Rails integration is not scripted by the Grapht library, it is quite
+simple to integrate.  The following steps are all that is required for integration:
+
+- Add the following to your `Gemfile`:
+    <pre>gem 'grapht', git: 'https://github.com/ibpinc/grapht.git'</pre>
+- In the Rails `app` directory, create a directory named `graph-definitions`
+- Create the file `config/initializers/grapht.rb`.  In the file add the following:
+    <pre>ENV['EXT_GRAPHT_DEFINITIONS_HOME'] =
+    Rails.root.join('app/graph-definitions')</pre>
+- Place all user-defined graph definitions in the `app/graph-definitions`
+
+## Contributing
+
+1. Fork it (http://github.com/ibpinc/grapht/fork)
+2. Create your feature branch `git checkout -b my-new-feature`
+3. Commit your changes `git commit -am 'Add some feature'`
+4. Push to the branch `git push origin my-new-feature`
+5. Create a new pull request
+
+## License
+
+Copyright (c) 2014 Trade Informatics, Inc
+
+[MIT License](https://github.com/ibpinc/grapht/blob/master/LICENSE.txt)

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/grapht

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+script="${BASH_SOURCE%/*}/../script/grapht.coffee"
+
+phantom_version=`phantomjs -v`
+if [ $? -ne 0 ]; then
+  echo "could not find phantomjs!"
+  exit 1
+fi
+
+if [ "$#" -ge 1 ]; then
+  phantomjs $script $@ < /dev/stdin
+else
+  echo "ERROR:"
+  echo "-- grapht was called with unknown arguments:"
+  echo "-- grapht requires an initial argument, specifying the graph type."
+  exit 1
+fi

data/example-data/bar_data.json

@@ -0,0 +1,5 @@
+[
+  { "name": "foo",   "value": 20 },
+  { "name": "bar",   "value": 40 },
+  { "name": "baz",   "value": 35 }
+]

data/example-data/donut_data.json

@@ -0,0 +1,5 @@
+[
+  { "name": "foo",   "value": 20 },
+  { "name": "bar",   "value": 40 },
+  { "name": "baz",   "value": 35 }
+]

data/example-data/grapht_performance_line_data.json

@@ -0,0 +1,7 @@
+{
+  "perf": [
+    { "x":  1323,   "y": 1.559 },
+    { "x":  13527,  "y": 1.675 },
+    { "x":  135252, "y": 1.715 }
+  ]
+}

data/example-data/line_data.json

@@ -0,0 +1,16 @@
+{
+  "london": [
+    { "x": 0,  "y": 10 },
+    { "x": 10, "y": 0 },
+    { "x": 20, "y": 20 },
+    { "x": 30, "y": 40 },
+    { "x": 40, "y": 60 }
+  ],
+  "paris": [
+    { "x": 0,  "y": 80 },
+    { "x": 10, "y": 60 },
+    { "x": 20, "y": 40 },
+    { "x": 30, "y": 20 },
+    { "x": 40, "y": 0 }
+  ]
+}

data/grapht.gemspec

@@ -0,0 +1,24 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'grapht/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "grapht"
+  spec.version       = Grapht::VERSION
+  spec.authors       = ["Tim Lowrimore"]
+  spec.email         = ["tim@plia.com"]
+  spec.description   = %q{Grapht is a server-side graphing library built on PhantomJS and utilizing D3.js. Grapht provides a CLI for simple Bash scripting. It also profides a light-weight Ruby API to make service-level integration simple.}
+  spec.summary       = %q{Grapht is a server-side graphing library built on PhantomJS and utilizing D3.js.}
+  spec.homepage      = "https://github.com/ibpinc/grapht"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+end

data/lib/graph-definitions/bar-horizontal.js

@@ -0,0 +1,90 @@
+function(data) {
+  var margin     = { top: 50, right: 20, bottom: 30, left: 40 },
+      width      = 400,
+      height     = 400,
+      svgWidth   = width + margin.right + margin.left,
+      svgHeight  = height + margin.top + margin.bottom;
+
+  var svg = d3.select("body").append("svg")
+             .style("fill", "none")
+             .attr("width", svgWidth)
+             .attr("height", svgHeight)
+             .attr('viewBox', "0 -10 " +svgWidth+ " " +svgHeight+ "")
+            .append('g')
+              .attr('transform', 'translate(' +margin.left+ ',' +margin.top+ ')')
+              .style("fill", "none");
+
+  var paddedExtent = function(data, pad) {
+    return [
+      d3.min(data, function(d) { return d.value-pad; }),
+      d3.max(data, function(d) { return d.value+pad; })
+    ]
+  }
+
+  // Axis Scales
+  var x = d3.scale
+          .linear()
+          .domain(paddedExtent(data, 1))
+          .range([0, width])
+          .nice();
+
+  var y = d3.scale
+          .ordinal()
+          .domain(data.map(function(d) { return d.name; }))
+          .rangeRoundBands([0, height], 0.2);
+
+  // Axes
+  var xAxis = d3.svg
+              .axis()
+              .scale(x)
+              .orient('bottom')
+              .tickSize(-height);
+
+  var yAxis = d3.svg
+              .axis()
+              .scale(y)
+              .orient('right')
+              .ticks(data.length);
+
+  svg.selectAll('.bar')
+      .data(data)
+    .enter().append('rect')
+      .attr('class',    'bar')
+      .style('fill',    '#428bca')
+      .attr('opacity',  '0.3')
+      .attr('x',        0)
+      .attr('y',        function(d) { return y(d.name); })
+      .attr('width',    function(d) { return x(d.value); })
+      .attr('height',   y.rangeBand());
+
+  svg.selectAll('.text')
+    .attr('font-family', 'Arial')
+    .selectAll('label')
+      .attr('fill-opacity', '0.3')
+
+  var xAxisElement = svg.append('g')
+                     .attr('class',      'x axis')
+                     .style("fill", "none")
+                     .attr('transform',  "translate(0," +height+ ")")
+                     .call(xAxis);
+
+  var yAxisElement = svg.append('g')
+                     .attr('class', 'y axis')
+                     .style("fill", "none")
+                     .call(yAxis);
+
+  xAxisElement.selectAll('line')
+    .style('fill', 'none')
+    .attr('stroke', 'black')
+    .attr('stroke-width', '1px')
+    .attr('stroke-opacity', 0.1)
+    .attr('shape-rendering', 'geometricPrecision');
+
+  xAxisElement.selectAll('text')
+    .style('fill', '#333333')
+    .attr('font-family', 'Arial');
+
+  yAxisElement.selectAll('text')
+    .style('fill', '#333333')
+    .attr('font-family', 'Arial');
+}