pippa 0.1.0 → 0.2.1

data/README.md

@@ -1,5 +1,7 @@
 # Pippa
 
+[![Gem Version](https://badge.fury.io/rb/pippa.png)](http://badge.fury.io/rb/pippa)
+
 Pippa - a Ruby gem for producing simple map graphics overlain with
 geocoded dots of given area. Dot coordinates are in screen pixels,
 latitude/longitude, or US zipcode.

data/lib/pippa.rb

@@ -9,6 +9,7 @@ require 'pippa/version'
 require 'RMagick'
 require 'csv'
 
+# The Pippa API.
 module Pippa
 
   # Return a list of the valid map names.
@@ -16,6 +17,53 @@ module Pippa
     Map.info[:map].keys
   end
 
+  # Compress the zipcode CSV file to something that loads quicker.
+  #
+  # This gem is packaged with compressed zipcode table that only works
+  # if your ruby has compatible a +Marshal+ version. If loading fails,
+  # it will attempt to rewrite the table in a compatible format, but if
+  # you don't have write permission in the gem store, that will
+  # consistently fail. You can use this call with +sudo∂ irb+ to
+  # write a compatible table.
+  def self.compress_zipcodes
+    dump_zips.size
+  end
+
+  # Return a hash mapping zip codes to CSV records of zip code data.
+  # NB: The file is big, so this takes a while to return the first time called.
+  #
+  # +CSV::Row+ struct format (see also http://ruby-doc.org/stdlib-1.9.2/libdoc/csv/rdoc/CSV/Row.html):
+  #
+  #     #<CSV::Row
+  #       zipcode:"97475"
+  #       zip_code_type:"PO BOX"
+  #       city:"SPRINGFIELD"
+  #       state:"OR"
+  #       location_type:"PRIMARY"
+  #       lat:44.05
+  #       long:-123.02
+  #       location:"NA-US-OR-SPRINGFIELD"
+  #       decommisioned:"false"
+  #       tax_returns_filed:nil
+  #       estimated_population:nil
+  #       total_wages:nil>
+  #
+  # See http://federalgovernmentzipcodes.us for more information on the zipcode data.
+  def self.zips
+    @@zips ||= zips_from_file
+  end
+
+  # Run the profiler and record results. (For development.)
+  def self.profile
+    require 'ruby-prof'
+    RubyProf.start
+    Map.write_zipcode_maps
+    result = RubyProf.stop
+    File.open('profile.htm', 'w') do |f|
+      RubyProf::GraphHtmlPrinter.new(result).print(f)
+    end
+  end
+
   # An image-based map class that can be overlain with dots
   # of given area and location given by pixel coordinates, lat/lon,
   # or zipcode (courtesy of http://federalgovernmentzipcodes.us).
@@ -160,6 +208,7 @@ module Pippa
     def add_at_lat_lon(lat, lon, area = 0)
       add_dot(*lat_lon_to_xy(lat, lon), area)
     end
+    alias_method :add_dot_at_lat_lon, :add_at_lat_lon
 
     # Add a dot on the map at given 5-digit zip code.
     #
@@ -176,33 +225,10 @@ module Pippa
     #    map.add_at_zip('10996', 100)
     #    map.write_png('map.png')
     def add_at_zip(zip, area = 0)
-      data = Map.zips[zip]
-      add_at_lat_lon(data[:lat], data[:long], area) if data
-    end
-
-    # Return a hash mapping zip codes to CSV records of zip code data.
-    # NB: The file is big, so this takes a while to return the first time called.
-    #
-    # +CSV::Row+ struct format (see also http://ruby-doc.org/stdlib-1.9.2/libdoc/csv/rdoc/CSV/Row.html):
-    #
-    #     #<CSV::Row
-    #       zipcode:"97475"
-    #       zip_code_type:"PO BOX"
-    #       city:"SPRINGFIELD"
-    #       state:"OR"
-    #       location_type:"PRIMARY"
-    #       lat:44.05
-    #       long:-123.02
-    #       location:"NA-US-OR-SPRINGFIELD"
-    #       decommisioned:"false"
-    #       tax_returns_filed:nil
-    #       estimated_population:nil
-    #       total_wages:nil>
-    #
-    # See http://federalgovernmentzipcodes.us for more information on the zipcode data.
-    def self.zips
-      @@zips ||= zips_from_file
+      data = Pippa.zips[zip]
+      add_at_lat_lon(data[:lat], data[:lon], area) if data
     end
+    alias_method :add_dot_at_zip, :add_at_zip
 
     # Force rendering of all dots added so far onto the map.
     # Then forget them so they're never rendered again.
@@ -299,7 +325,7 @@ module Pippa
     def self.zipcode_map
       generator = Random.new(42) # Force same on every run for testing.
       m = Map.new('USA')
-      zips.each_key.each do |zip|
+      Pippa.zips.each_key.each do |zip|
         m.add_at_zip(zip, generator.rand(4) ** 2)
       end
       m.fill = 'red'
@@ -316,17 +342,6 @@ module Pippa
       m.write_jpg('spec/data/zipcodes.jpg')
     end
 
-    # Run the profiler and record results.
-    def self.profile
-      require 'ruby-prof'
-      RubyProf.start
-      write_zipcode_maps
-      result = RubyProf.stop
-      File.open('profile.htm', 'w') do |f|
-        RubyProf::GraphHtmlPrinter.new(result).print(f)
-      end
-    end
-
     private
 
     #:nodoc:
@@ -411,36 +426,65 @@ module Pippa
         data
       end
     end
+  end
 
-    # Read CSV file of zipcode data.  Much more than we need.
-    # TODO: Develop quicker-loading version of the data file.
-    # Format:
-    #     "Zipcode","ZipCodeType","City","State","LocationType","Lat","Long",
-    #     "Location","Decommisioned","TaxReturnsFiled","EstimatedPopulation","TotalWages"
-    def self.zips_from_file
-      CSV::HeaderConverters[:underscore_symbol] = lambda do |s|
-        t = s.gsub(/::/, '/')
-        t.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
-        t.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
-        t.tr!("-", "_")
-        t.downcase!
-        t.to_sym
-      end
-      CSV::Converters[:custom] = lambda do |s, info|
-        begin
-          [:lat, :long].include?(info.header) ? Float(s) : s
-        rescue
-          s
-        end
-      end
-      zips = {}
-      CSV.foreach("#{File.dirname(__FILE__)}/pippa/maps/_zipcodes.csv",
-                  :headers => :first_row,
-                  :header_converters => :underscore_symbol,
-                  :converters => :custom) do |row|
-        zips[row[:zipcode]] = row if row[:lat] && row[:long]
+  private
+
+  ZIPCODE_CSV_FILE_PATH = "#{File.dirname(__FILE__)}/pippa/maps/_zipcodes.csv" # :nodoc:
+
+  # Read zipcode data from unaltered CSV file.
+  def self.zips_from_csv
+    CSV::HeaderConverters[:underscore_symbol] = lambda do |s|
+      t = s.gsub(/::/, '/')
+      t.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+      t.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+      t.tr!("-", "_")
+      t.downcase!
+      t.to_sym
+    end
+    CSV::Converters[:custom] = lambda do |s, info|
+      begin
+        [:lat, :long].include?(info.header) ? Float(s) : s
+      rescue
+        s
       end
-      zips
     end
+    zips = {}
+    CSV.foreach(ZIPCODE_CSV_FILE_PATH,
+                :headers => :first_row,
+                :header_converters => :underscore_symbol,
+                :converters => :custom) do |row|
+      zips[row[:zipcode]] = row if row[:lat] && row[:long]
+    end
+    zips
+  end
+
+  ZIPCODE_DUMP_FILE_PATH = "#{File.dirname(__FILE__)}/pippa/maps/_zipcodes.dmp" # :nodoc:
+
+  # Use native Ruby facility to create a quick-loading, compatible version of CSV zipcode data.
+  def self.dump_zips
+    hash = {}
+    zips_from_csv.each do |zip, row|
+      hash[zip] = { :lat => row[:lat], :lon => row[:long] }
+    end
+    File.open(ZIPCODE_DUMP_FILE_PATH, 'wb') {|f| Marshal.dump(hash, f) }
+    hash
+  rescue
+    hash
+  end
+
+  # Read a previously created dump of the zipcode database.
+  def self.zips_from_dump
+    File.open(ZIPCODE_DUMP_FILE_PATH, 'rb') {|f| Marshal.load(f) }
+  end
+
+  # Read zipcode data. Tries compressed form first and then CSV.
+  # Format:
+  #     "Zipcode","ZipCodeType","City","State","LocationType","Lat","Long",
+  #     "Location","Decommisioned","TaxReturnsFiled","EstimatedPopulation","TotalWages"
+  def self.zips_from_file
+    zips_from_dump
+  rescue
+    dump_zips
   end
 end

data/lib/pippa/version.rb

@@ -1,4 +1,5 @@
+# Bundler auto-generated mixin for gem version.
 module Pippa
   # Current version of Pippa
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/pippa.gemspec

@@ -8,14 +8,21 @@ Gem::Specification.new do |spec|
   spec.version       = Pippa::VERSION
   spec.authors       = ["Gene Ressler"]
   spec.email         = ["gene.ressler@gmail.com"]
-  spec.description   = %q{Draw dots on maps by lat/lon or zip code.}
-  spec.summary       = %q{Port of the plot-latlon utility from CAIDA (http://www.caida.org).}
+
+  spec.summary       = %q{Reimplements some parts of the plot-latlon utility from CAIDA (http://www.caida.org).}
+  spec.description   =
+%q{Draw dots on maps by lat/lon or zip code. Includes a library of 30 map backgrounds,
+and associated geocoding configuration data, and a table of US zip codes with their
+approximate centroids as latitude and longitude. Exposes the ImageMagick image and
+coordinate conversions so that overlaying labels, lines, and other features on dots
+is possible. Renders as a blob suitable for e.g. Rails send_data as an img tag src
+and writes files in any supported ImageMagick graphic format.}
+
   spec.homepage      = "https://github.com/gene-ressler/pippa/wiki"
-  spec.license       = "GPLv3"
+  spec.licenses      = ["GPL-3.0", "RUC"]
 
-  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.files         = `git ls-files`.split($/)
+  spec.test_files    = spec.files.grep(%r{^spec/})
   spec.require_paths = ["lib"]
 
   # Make work on earlier versions, but this is where testing has been performed.

data/spec/lib/map_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 
+# Test functions of the Pippa::Map API lightly.  Much more possible here.
 describe Pippa::Map do
 
   let(:map) { Pippa::Map.zipcode_map }
@@ -19,10 +20,6 @@ describe Pippa::Map do
     i[:projection].size.should == 4
   end
 
-  it 'should have right number of zipcodes' do
-    Pippa::Map.zips.size.should == 41874
-  end
-
   # Here I'm assuming timestamp metadata chunk always has same size.
   # PNG docs are encouraging on this:
   # http://www.libpng.org/pub/png/book/chapter11.html#png.ch11.div.2

data/spec/lib/pippa_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 
+# Test the Pippa API. Much more work possible here.
 describe Pippa do
 
   it 'should report version' do
@@ -10,4 +11,8 @@ describe Pippa do
     Pippa.map_names.size.should be == 30
   end
 
+  it 'should have right number of zipcodes' do
+    Pippa.zips.size.should == 41874
+  end
+
 end

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: pippa
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
+  prerelease: 
 platform: ruby
 authors:
 - Gene Ressler
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-12-29 00:00:00.000000000 Z
+date: 2013-12-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -20,6 +22,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -27,6 +30,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -34,6 +38,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -41,6 +46,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -48,6 +54,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -55,6 +62,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-prof
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -62,6 +70,7 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -69,6 +78,7 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rmagick
   requirement: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -76,11 +86,23 @@ dependencies:
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
+    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.13'
-description: Draw dots on maps by lat/lon or zip code.
+description: ! 'Draw dots on maps by lat/lon or zip code. Includes a library of 30
+  map backgrounds,
+
+  and associated geocoding configuration data, and a table of US zip codes with their
+
+  approximate centroids as latitude and longitude. Exposes the ImageMagick image and
+
+  coordinate conversions so that overlaying labels, lines, and other features on dots
+
+  is possible. Renders as a blob suitable for e.g. Rails send_data as an img tag src
+
+  and writes files in any supported ImageMagick graphic format.'
 email:
 - gene.ressler@gmail.com
 executables: []
@@ -123,6 +145,7 @@ files:
 - lib/pippa/maps/World50-new.png
 - lib/pippa/maps/_info
 - lib/pippa/maps/_zipcodes.csv
+- lib/pippa/maps/_zipcodes.dmp
 - lib/pippa/version.rb
 - pippa.gemspec
 - spec/data/zipcodes.jpg
@@ -132,28 +155,30 @@ files:
 - spec/spec_helper.rb
 homepage: https://github.com/gene-ressler/pippa/wiki
 licenses:
-- GPLv3
-metadata: {}
+- GPL-3.0
+- RUC
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 1.8.23
 signing_key: 
-specification_version: 4
-summary: Port of the plot-latlon utility from CAIDA (http://www.caida.org).
+specification_version: 3
+summary: Reimplements some parts of the plot-latlon utility from CAIDA (http://www.caida.org).
 test_files:
 - spec/data/zipcodes.jpg
 - spec/data/zipcodes.png

checksums.yaml

@@ -1,15 +0,0 @@
----
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    ZDg5YjUzMzdjYjMwZTBhZjFhZTlmZDM5OWM5MzgxMzYxNmU0YTdkZA==
-  data.tar.gz: !binary |-
-    NDc1MzEzMTc3MmZkMjRjN2IzMmNlZjM1MzYwZmU4OTlmZDA4NzllYw==
-!binary "U0hBNTEy":
-  metadata.gz: !binary |-
-    MmY3YTFjMDRmNzMyZjUxNjIwMzU5NTIyY2I5ZjhjYWUyZWE5ZTJkZDg3Yjg5
-    ZDY5YThmZmYyNDAwY2JiZjMyZmJkZGE5MjQ1YzRkOGZiZjMxZTk0ZWI3NTBk
-    ZmY3ZTRhOGI4NTI5NTBjZWNlNDEzNDg4Y2E4MGU2NGMyNGJmZmQ=
-  data.tar.gz: !binary |-
-    Y2ZhM2E3YjhmNTUxYmJlNDE2YWQxNTA5YWE3YjgzNzk3MzliYTUzMmI3ZGMw
-    ZTE0M2ZiOGQwOWJiZDJlNjBhN2VjZjRhYzBjZDk1Yzk1YWU1ODFkMTllZDJh
-    NDQxZTgwYWE0MDlmNzBkNDFhZDAyZWM2MDI3Y2U2ZWJjOTQ1NTE=