refine-ruby 0.2.4 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 23013da310f5a03e05cbc6cc3152567257b64184
-  data.tar.gz: fd29dd48c328ef841812d4bc983575bf51d94136
+  metadata.gz: dda04c11eafc58372e17a09a56aa0e59649daeaf
+  data.tar.gz: 860aac69f2bcb486052094b5d43dc2756014ee64
 SHA512:
-  metadata.gz: 621bb2bd7aa876aabe148f6214c602328b832ae09b2f35b9e0388cbdc4602cab81a9e8b2b849ac3ec8ed660679091fde2b582d0f319e9e470eb8643083d89f8a
-  data.tar.gz: 1646755790ba2c42cfe03c39f4dda3e259754758c6a3b0f9f498d4333b26c09f59520d6e800b16d3f978cd556b8d1bbabdd011a0c2fc1394f127ddeae7c64f57
+  metadata.gz: 9492f07c6120b6328f258f2f9872e2bdc113b3504e7eb0b090961beb5611f1e95487a4c32af80e05d5c7c59df1047722b84c475f69e4924183b890177c05f871
+  data.tar.gz: 1d3cb1338180a42932f347d67a7a4a7e38d332fd33abd4f0fa645243b503aa0f95f68bbf949ace956151987c3742e8d3a974aaa3c797bdb1f66b0da9a8e750a3

data/README.textile

@@ -8,7 +8,9 @@ h2. Install
 
 @gem install refine-ruby@
 
-h2. Example
+h2. Use Cases
+
+h3. Apply Operations / Export Operations
 
 Given that you have the following raw data:
 
@@ -21,42 +23,42 @@ Given that you have the following raw data:
   </code>
 </pre>
 
-Google Refine lets you clean up the data and export your operation history as a JSON instruction set. Here is an example that extracts the year from the above dates:
+Refine Ruby lets you clean up the data and export your operation history as a JSON instruction set. Here is an example that extracts the year from the above dates:
 
 <pre>
-<code>
-  [
-    {
-      "op": "core/text-transform",
-      "description": "Text transform on cells in column Date using expression grel:value.toDate()",
-      "engineConfig": {
-        "facets": [],
-        "mode": "row-based"
-      },
-      "columnName": "Date",
-      "expression": "grel:value.toDate()",
-      "onError": "set-to-blank",
-      "repeat": false,
-      "repeatCount": 10
-    },
-    {
-      "op": "core/text-transform",
-      "description": "Text transform on cells in column Date using expression grel:value.datePart(\"year\")+1",
-      "engineConfig": {
-        "facets": [],
-        "mode": "row-based"
+  <code>
+    [
+      {
+        "op": "core/text-transform",
+        "description": "Text transform on cells in column Date using expression grel:value.toDate()",
+        "engineConfig": {
+          "facets": [],
+          "mode": "row-based"
+        },
+        "columnName": "Date",
+        "expression": "grel:value.toDate()",
+        "onError": "set-to-blank",
+        "repeat": false,
+        "repeatCount": 10
       },
-      "columnName": "Date",
-      "expression": "grel:value.datePart(\"year\")",
-      "onError": "set-to-blank",
-      "repeat": false,
-      "repeatCount": 10
-    }
-  ]
-</code>
+      {
+        "op": "core/text-transform",
+        "description": "Text transform on cells in column Date using expression grel:value.datePart(\"year\")+1",
+        "engineConfig": {
+          "facets": [],
+          "mode": "row-based"
+        },
+        "columnName": "Date",
+        "expression": "grel:value.datePart(\"year\")",
+        "onError": "set-to-blank",
+        "repeat": false,
+        "repeatCount": 10
+      }
+    ]
+  </code>
 </pre>
 
-You can use this gem to apply the operation set to the raw data from ruby. You will need to have Google Refine running on your local computer, or specify an external address (see source):
+You can use this gem to apply the operation set to the raw data from ruby. You will need to have OpenRefine running on your local computer, or specify an external address (see source):
 
 <pre>
   <code>
@@ -64,7 +66,6 @@ You can use this gem to apply the operation set to the raw data from ruby. You w
     prj = Refine.new('project_name' => 'date cleanup', 'file_name' => 'dates.txt')
     prj.apply_operations('operations.json')
     puts prj.export_rows('csv')
-    prj.delete_project
   </code>
 </pre>
 
@@ -79,6 +80,60 @@ Which outputs:
   </code>
 </pre>
 
+h3. Link to Facets
+
+Continuing on the project above - assuming 'project_id' = 1594197247031.
+Link to facets generates a link to the facets set up. The method can take an array of hashes, with the keys as the column name and the optional values: 'sort', 'invert', and a '<GREL expression>'.
+
+<pre>
+  <code>
+  require 'refine'
+    prj = Refine.new('project_id' => 1594197247031)
+    prj.link_to_facets('Date' => ['invert', 'isNonBlank(value)'])
+  </code>
+</pre>
+
+Which outputs:
+
+<pre>
+ "http://127.0.0.1:3333/project?project=1594197247031&ui=%7B%22facets%22%3A%5B%7B%22c%22%3A%7B%22columnName%22%3A%22Date%22%2C%22expression%22%3A%22value%22%2C%22name%22%3A%22Date%22%2C%22invert%22%3Atrue%7D%2C%22o%22%3A%7B%22sort%22%3A%22name%22%7D%7D%5D%7D"
+</pre>
+
+Screenshot:
+
+!/img/link_to_facets_screenshot.png!
+
+
+h3. Compute Facet
+
+Compute facet returns a JSON object with meta info on the output of the column based on the GREL expression provided. The method can take an array of hashes with the keys as the column name and the optional values: 'sort', 'invert', and a '<GREL expression>'.
+<pre>
+  <code>
+      prj = Refine.new('project_id' => 1594197247031)
+      prj.compute_facet('Date' => ['value'])
+  </code>
+</pre>
+
+Which outputs:
+
+<pre>
+[
+  {
+    "columnName"=>"Date",
+    "name"=>"Date",
+    "expression"=>"value",
+    "choices"=>[
+        {"value"=>2002, "label"=>"2002", "count"=>1, "selected"=>false},
+        {"value"=>2001, "label"=>"2001", "count"=>1, "selected"=>false},
+        {"value"=>2010, "label"=>"2010", "count"=>1, "selected"=>false}
+    ]
+  }
+]
+</pre>
+
+
+See test_refine.rb to see all the optional arguments for link_to_facets, and compute_facet methods.
+
 h2. Copyright
 
 Copyright (c) 2018 David Huynh, Max Ogden & Distill Analytics Inc.

data/Rakefile

@@ -1,8 +1,33 @@
 require 'bundler/gem_tasks'
 require 'rake/testtask'
 
-Rake::TestTask.new do |t|
+require 'pry'
+def make_minitest_options(args)
+  args ||= {}
+  options = []
+  options << "--name=#{Shellwords.escape(args[:name])} -v" if args.has_key?(:name)
+  options.join(" ")
+end
+
+Rake::TestTask.new do |t,args|
   t.pattern = "test/test_*.rb"
 end
 
+namespace :test do
+  desc "Run just one test based on the name"
+  task :named, [:name] do |t, args|
+
+    test_options = make_minitest_options(args)
+
+    task_name = "test with opts: #{test_options}"
+
+    Rake::TestTask.new(task_name) do |test_task|
+      test_task.pattern = "test/test_*.rb"
+      test_task.options =  test_options
+    end
+
+    Rake::Task[task_name].execute
+  end
+end
+
 task default: :test

data/lib/refine.rb

@@ -138,26 +138,24 @@ class Refine
         }
       end
 
-      json_facet = JSON::dump(facets: [formatted.first])
+      json_facet = JSON::dump(facets: formatted)
 
       openrefine_response = compute_facets("engine" => json_facet)
 
-      facet_response = openrefine_response.fetch("facets").first
+      openrefine_response.fetch("facets").map do |facet|
 
+        if facet.key?("choices")
 
+          choices_hash = facet.fetch("choices").map do |h|
+            Hash[%w(value label count selected).zip([h["v"]["v"], h["v"]["l"], h["c"], h["s"]])]
+          end
 
-      if facet_response.key?("choices")
+          Hash[%w(columnName name expression choices).zip([facet.fetch("columnName"), facet.fetch("name"), facet.fetch("expression"), choices_hash])]
+        elsif facet.key?("error")
 
-        choice_hash = facet_response.fetch("choices").map do |h|
-          Hash[%w(value label count selection).zip([h["v"]["v"], h["v"]["l"], h["c"], h["s"]])]
+          Hash[%w(columnName name expression error).zip([facet.fetch("columnName"), facet.fetch("name"), facet.fetch("expression"), facet.fetch("error")])]
         end
 
-        response = choice_hash.inject({}) do |hash, choice|
-          hash.merge(choice["value"] => choice["count"])
-        end
-
-      else
-      response = "Error: " + facet_response.fetch("error")
       end
 
     end

data/lib/refine/version.rb

@@ -1,3 +1,3 @@
 class Refine
-  VERSION = "0.2.4"
+  VERSION = "0.3.0"
 end

data/test/examples_of_usage.rb

@@ -1,17 +1,17 @@
 ### NOTE: The internal client-server protocol used by OpenRefine is not yet maintained as a stable external API, subject to change. ###
 ### Therefore, plase indicate changes you notice to kittelmann@sub.uni-goettingen.de ###
 ### Some examples require cURL http://curl.haxx.se ###
-### It is assumed that examples are run from the 'test' directory. Otherwise paths need to be adjusted. 
+### It is assumed that examples are run from the 'test' directory. Otherwise paths need to be adjusted.
 load '../lib/refine.rb'
 
 ##########################
 ### create initial project
 ##########################
-prj = Refine.new({ 'project_name' => 'date_cleanup', 'file_name' => 'dates.csv' })
+prj = Refine.new({ 'project_name' => 'date_cleanup', 'file_name' => 'dates.csv', 'throws_exceptions'=> false })
 
 
 ##########################
-### create another project 
+### create another project
 ##########################
 prj.create_project( 'date_cleanup', 'dates.txt' )                          # return value = project id, example: 1484090391100
 
@@ -21,6 +21,15 @@ prj.create_project( 'date_cleanup', 'dates.txt' )                          # ret
 ################
 prj.apply_operations( 'operations.json' )                                  # return value = status code, example: {'code'=>'ok'}
 
+######################
+### link to facet(s) already set up
+######################
+prj.link_to_facets("Date"=>["isNonBlank(value)"])                          # return value = a link to the facet(s) (method can take multiple facet arguments)
+
+######################
+### compute facet(s)
+######################
+prj.compute_facet({"Date"=>["value"]}, {"Date"=>["isNonBlank(value)"]})    # return value = the computed facets as an array of hashes
 
 ######################
 ### extract operations
@@ -39,8 +48,8 @@ end
 ###############
 ### export data
 ###############
-prj.export_rows                                                              # return value = exported data as tsv 
-prj.export_rows( {'format'=>'tsv'} )                                         # return value = exported data as tsv   
+prj.export_rows                                                              # return value = exported data as tsv
+prj.export_rows( {'format'=>'tsv'} )                                         # return value = exported data as tsv
 prj.export_rows( {'format'=>'csv'} )                                         # return value = exported data as csv
 
 ### export data in custom table format
@@ -106,4 +115,4 @@ prj.get_all_project_metadata                                                 # r
 ##################
 ### delete project
 ##################
-prj.delete_project                                                           # return value = status, e.g. ok
+prj.delete_project                                                           # return value = status, e.g. ok

data/test/operations.json

@@ -25,4 +25,4 @@
         "repeat": false,
         "repeatCount": 10
     }
-]
+]

data/test/test_refine.rb

@@ -6,7 +6,7 @@ require_relative '../lib/refine.rb'
 describe Refine do
 
   before do
-    @refine_project = Refine.new({ "project_name" => 'date_cleanup', "file_name" => './test/dates.txt' })
+    @refine_project = Refine.new({ "project_name" => 'date_cleanup', "file_name" => './test/dates.txt'})
   end
 
   describe "error handling" do
@@ -105,7 +105,7 @@ describe Refine do
 
       assert !params['ui'].nil?
 
-      facet_spec = JSON::parse(URI::decode(params['ui']))
+      facet_spec = JSON::parse(CGI::unescape(params['ui']))
       assert_equal 1, facet_spec.fetch("facets").length
 
       assert_equal "Date", facet_spec.fetch("facets").first.fetch("c").fetch("columnName")
@@ -199,18 +199,72 @@ describe Refine do
 
     describe "compute_facets" do
       it "Request responds with error due to non existent column" do
-        response = @refine_project.compute_facet({"transcript_fiscal_year"=> ["isNonBlank(value)"]})
-        assert_equal("Error: No column named transcript_fiscal_year", response)
+        response = @refine_project.compute_facet({"Column 1"=> ["value"]}, {"transcript_fiscal_year"=> ["isNonBlank(value)"]})
+        _(response).must_equal ([{
+              "columnName" => "Column 1",
+              "name" => "Column 1",
+              "expression" => "value",
+              "choices" => [
+                {"value" => "7 December 2001",
+                 "label" => "7 December 2001",
+                 "count" => 1 ,
+                 "selected" => false},
+                 {"value" => "Date",
+                  "label" => "Date",
+                  "count" => 1 ,
+                  "selected" => false},
+                 {"value" => "July 1 2002",
+                  "label" => "July 1 2002",
+                  "count" => 1,
+                  "selected" => false},
+                {"value" => "10/20/10",
+                 "label" => "10/20/10",
+                 "count" => 1 ,
+                 "selected" => false}
+              ]
+            },{
+              "columnName" => "transcript_fiscal_year",
+              "name" => "transcript_fiscal_year",
+              "expression" => "isNonBlank(value)",
+              "error" => "No column named transcript_fiscal_year"
+              }])
       end
 
-      it "Request executes expression and sends response with the results" do
-        response = @refine_project.compute_facet({"Column 1"=> ["isNonBlank(value)"]})
-        assert_equal({true=>4}, response)
+      it "Request executes expression and cleans up the choices response formatting" do
+        response = @refine_project.compute_facet({"Column 1"=> ["value"]})
+        _(response).must_equal([{
+          "columnName" => "Column 1",
+          "name" => "Column 1",
+          "expression" => "value",
+          "choices" => [
+            {"value" => "7 December 2001",
+             "label" => "7 December 2001",
+             "count" => 1 ,
+             "selected" => false},
+             {"value" => "Date",
+              "label" => "Date",
+              "count" => 1 ,
+              "selected" => false},
+             {"value" => "July 1 2002",
+              "label" => "July 1 2002",
+              "count" => 1,
+              "selected" => false},
+            {"value" => "10/20/10",
+             "label" => "10/20/10",
+             "count" => 1 ,
+             "selected" => false}
+          ]
+        }])
       end
 
       it "Request with faulty expression" do
         response = @refine_project.compute_facet({"Column 1"=> ["iBlank(value)"]})
-        assert_equal("Error: Parsing error at offset 6: Unknown function or control named iBlank", response)
+        _(response).must_equal([{
+            "columnName"=>"Column 1",
+            "name"=>"Column 1",
+            "expression"=>"iBlank(value)",
+            "error"=>"Parsing error at offset 6: Unknown function or control named iBlank"
+          }])
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: refine-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Caleb Buxton
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-15 00:00:00.000000000 Z
+date: 2018-05-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -129,6 +129,7 @@ files:
 - README.textile
 - Rakefile
 - bin/console
+- img/link_to_facets_screenshot.png
 - lib/refine.rb
 - lib/refine/version.rb
 - refine-ruby.gemspec