rp_clustering-rgeo-activerecord 0.0.2 → 0.0.3

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MmJmOWM2NjZhMmMzODM1M2EyZDhkNjUyMzJjOGU1M2NlZTQ5N2IzOQ==
+    MzliYTdiMDQyNjMxZmQ3NGM4NGQyNTZmMjgwYmY4NDUyMTk0NGFiYQ==
   data.tar.gz: !binary |-
-    NjZlZjdkMWNhNGYwOTdiMDU4YTdlNTIzODA2OGFmMDNhYjUyOTdkYg==
+    YTRmZWE4M2Q5NDhkZDE0NWYwOTEyYzRkYzk5MDU3ZmVmZDVlMDk2Mg==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    Y2I1NTBjYzEyMTZmN2FjYTlmMDhjZDFlNGMxYjM0NWQxOTQ0ODUxMTYxMjBl
-    YmI4MTgyNzAzYzhiMTYzZDFlYzAwZTgxNWQ2ZTJkN2RkNjg2NmYzN2M2ZWJh
-    ODIyYTE0OTM0NzFlMzJkNTZhM2MxODc0ODZiOTNkNWFlYTNiYWU=
+    ODEwOGZjNWVmZDg3ODFkNTU5YjZlODQ0OGM5NjlkZTU2NTNkZWU5Mjg3NGIy
+    YzcxOWY5OGJjMzg4ZjJmODhhZWNkNDM2MjIzMGU0NTk4ZmM1NDE0MDdjNWYz
+    NTAwMjllZTRjMTY1MzRjNjI3NWUyZDQ3ODUxNjFiMGU5MjBhYTk=
   data.tar.gz: !binary |-
-    NWFlODJlYWQ1Mzg2MjRmNTVlYzM0NTk0YmI3ZTQwMmY3MTlhNjE4NGVlNzQx
-    YTZmZGJkMWFkOGVkM2Y5M2I4YzVlZDhhNDhiMjdhOGM4ZTEwNDdmNzUzYzEx
-    ZDI2NDgyNTFjZmNjZTc5MjMyNDFlNTI2NjIxZjAxZDBjOWY4YzE=
+    NzQ1OTU4MWE4MDM3OWJkNTJkYWI0ZWQ2ZTkxN2Q1NTBhNjU1NWJmYTFiNWRm
+    NWRlMjUyN2I1NjExZjJiOWVhZTY1MjllZmQ0ZmViN2E4MmZhMjViOWQzMzFh
+    ODAzMzZlNjA3OGQ0ZWQ1YzczOTg1OTMwZjFkZjU2ZmM3MTNhYzM=

data/README.md

@@ -1,5 +1,7 @@
 # RPClustering::RGeo::ActiveRecord
 
+[![Code Climate](https://codeclimate.com/github/robertpyke/rp_clustering-rgeo-activerecord.png)](https://codeclimate.com/github/robertpyke/rp_clustering-rgeo-activerecord)
+
 A RGeo PostGIS extension to provide Active Record (Model) clustering functionality.
 
 The intention is that this Gem will eventually provide abstracted methods for
@@ -8,7 +10,7 @@ both "on the fly" clustering, as well as cached clustering (including associated
 This Gem is currently in early development, so expect changes. On this note, if you'd like a specific clustering
 algorithm or feature added, please ask.
 
-If you find a problem with this Gem, please don't hesitate to raise an [issue](https://github.com/robertpyke/rp_clustering-rgeo-activerecord/issues).
+If you find a problem with this Gem, please don't hesitate to [raise an issue](https://github.com/robertpyke/rp_clustering-rgeo-activerecord/issues).
 
 ## Installation
 
@@ -32,6 +34,98 @@ Or install it yourself as:
 
 ## Usage
 
+### Added in Version 0.0.3
+
+This version allows for the "on the fly" use of a ST_SnapToGrid clustering function.
+The function is added to ActiveRecord::Base (Models). The function is:
+
+```ruby
+
+# Cluster using the PostGIS function ST_SnapToGrid
+# -------------------------------------------------
+#
+# attr_to_cluster is the name of attribute to be clustered (a symbol).
+# The attribute should be geometry attribute.
+#
+# Use the options Hash to define what cluster properties you would
+# like returned.
+#
+# Options:
+#
+# [:grid_size] if set, will be used to create the cluster. The clustering
+#     works rougly like this; all geometries within 'grid_size'
+#     will be pulled together to form a single cluster. For a detailed
+#     explanation, please see the PostGIS docs for ST_SnapToGrid.
+#
+#     If no +:grid_size+ is given, clusters will consist of all 'equal'
+#     geometries. E.g. all points at the same 
+#     position (x,y) will be pulled together to form a single cluster.
+#     This is actually just a Group By of your +attr_to_cluster+.
+#
+# [:cluster_geometry_count] if set to true, the query will select, for
+#     each cluster, the number of geometries in the cluster.
+#
+# [:cluster_geometry_count_as] the name to select the
+#     cluster_geometry_count as, defaults to "cluster_geometry_count".
+#
+# [:cluster_centroid] if set to true, the query will select, for
+#     each cluster, the cluster centroid. The cluster_centroid returned
+#     will be a WKT string.
+#
+# [:cluster_centroid_as] the name to select the 
+#     cluster_centroid as, defaults to "cluster_centroid".
+#
+# [:cluster_minimum_bounding_circle] if set to true, the query will select,
+#     for each cluster, the minimum bouding circle. The cluster_minimum_bounding_circle
+#     will be a WKT string.
+#
+# [:cluster_minimum_bounding_circle_as] the name to select the
+#     cluster_minimum_bounding_circle as, defaults to "cluster_minimum_bounding_circle"
+#
+# Note: Using the options hash, you must 'select' at least one attribute,
+# else this method will rase an ArgumentError.
+
+cluster_by_st_snap_to_grid(attr_to_cluster, options={})
+
+```
+
+e.g.
+
+```ruby
+
+
+@layer = Layer.find(params[:id])
+
+cluster_result = @layer.cluster_by_st_snap_to_grid(
+  :geometry, # the column to cluster
+  grid_size: 0.01,
+  cluster_geometry_count: true,
+  cluster_centroid: true
+)
+
+features = []
+cluster_result.each do |cluster|
+  geom_feature = Layer.rgeo_factory_for_column(:geometry).parse_wkt(cluster.cluster_centroid)
+  feature = RGeo::GeoJSON::Feature.new(geom_feature, nil, { cluster_size: cluster.cluster_geometry_count.to_i })
+
+  features << feature
+end
+
+feature_collection = RGeo::GeoJSON::FeatureCollection.new(features)
+RGeo::GeoJSON.encode(feature_collection)
+
+# BOOM! You just made some GeoJSON which is ready to be displayed on a map.
+# You've also embedded the cluster_size in the GeoJSON, so you can do some
+# fancy client side interaction based on cluster size. For example, you could
+# make outliers (small clusters) bright red, or you could vary the size of the
+# cluster centroid based on the size of cluster.
+#
+# Ideally, you could vary your +grid_size+ based on the user's view port.
+# For example, you could set it to fixed values based on the user's zoom level.
+# You could dynamically generate it based on some fraction of the user's view port bbox.
+
+```
+
 ### Added in Version 0.0.1
 
 This version allows for hand-coded low-level clustering via the Arel interface.
@@ -40,37 +134,37 @@ e.g.
 
 ```ruby
 
-    # Get the Arel handle for the model
+# Get the Arel handle for the model
 
-    arel_table = MyModel.arel_table
+arel_table = MyModel.arel_table
 
-    # Our cluster grid size.
-    # Smaller grid_size means more clusters.
-    # Larger grid_size means less clusters (cluster covers a larger area).
-    # See http://www.postgis.org/docs/ST_SnapToGrid.html for more info.
+# Our cluster grid size.
+# Smaller grid_size means more clusters.
+# Larger grid_size means less clusters (cluster covers a larger area).
+# See http://www.postgis.org/docs/ST_SnapToGrid.html for more info.
 
-    grid_size = 0.1
+grid_size = 0.1
 
-    # Cluster against our model's :latlon attribute with a grid size of '0.1'.
-    # Return the centroid of each cluster as "cluster_centroid".
+# Cluster against our model's :latlon attribute with a grid size of '0.1'.
+# Return the centroid of each cluster as "cluster_centroid".
 
-    query = MyModel.select(
-      arel_table.st_astext(
-        arel_table.st_centroid(arel_table.st_collect(arel_table[:latlon]))
-      ).as("cluster_centroid")
-    ).group(arel_table[:latlon].st_snaptogrid(grid_size))
+query = MyModel.select(
+  arel_table.st_astext(
+    arel_table.st_centroid(arel_table.st_collect(arel_table[:latlon]))
+  ).as("cluster_centroid")
+).group(arel_table[:latlon].st_snaptogrid(grid_size))
 
-    # Iterate over our clusters
-    query.all.each do |cluster|
+# Iterate over our clusters
+query.all.each do |cluster|
 
-      # print the cluster_centroid (a point) as WKT
-      puts cluster["cluster_centroid"]
+  # print the cluster_centroid (a point) as WKT
+  puts cluster["cluster_centroid"]
 
-      # convert the WKT into a RGeo Geometry (a point)
-      geographic_factory.parse_wkt(cluster["cluster_centroid")
+  # convert the WKT into a RGeo Geometry (a point)
+  geographic_factory.parse_wkt(cluster["cluster_centroid")
 
-      # ...
-    end
+  # ...
+end
 
 ```
 

data/lib/rp_clustering-rgeo-activerecord.rb

@@ -1,4 +1,5 @@
 require "rp_clustering-rgeo-activerecord/version"
+require "rp_clustering-rgeo-activerecord/active_record_base_spatial_expressions"
 require "rp_clustering-rgeo-activerecord/arel_attribute_spatial_expressions"
 require "rp_clustering-rgeo-activerecord/arel_table_spatial_expressions"
 
@@ -8,12 +9,22 @@ module RPClustering
 
     module ActiveRecord
 
+      # Spatial Expressions to be attached directly to ActiveRecord::Base
+
+      module BaseSpatialExpressions
+      end
+
+      # Attach our Spatial Expression methods onto the ActiveRecord::Base class (as class methods).
+      class ::ActiveRecord::Base
+        include ::RPClustering::RGeo::ActiveRecord::BaseSpatialExpressions
+      end
+
       # Spatial Expressions to be attached directly to Arel Attributes (DB columns)
 
       module ArelAttributeSpatialExpressions
       end
 
-      # Attach our Spatial Expression methods onto the Arel::Attribute class.
+      # Attach our Spatial Expression methods onto the Arel::Attribute class (as instance methods).
       #
       # i.e. As stated in the RGeo::ActiveRecord docs.. Allow chaining of spatial expressions from attributes
 
@@ -26,7 +37,7 @@ module RPClustering
       module ArelTableSpatialExpressions
       end
 
-      # Attach our Spatial Expression methods onto the Arel::Table class.
+      # Attach our Spatial Expression methods onto the Arel::Table class (as instance methods).
 
       ::Arel::Table.class_eval do
         include ::RPClustering::RGeo::ActiveRecord::ArelTableSpatialExpressions

data/lib/rp_clustering-rgeo-activerecord/active_record_base_spatial_expressions.rb

@@ -0,0 +1,154 @@
+# Author: Robert Pyke
+
+module RPClustering
+
+  module RGeo
+
+    module ActiveRecord
+
+      module BaseSpatialExpressions
+
+        # Use ActiveSupport::Concern to seperate our
+        # class and instance methods for inclusion into ActiveRecord::Base
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+
+          # Cluster using the PostGIS function ST_SnapToGrid
+          # -------------------------------------------------
+          #
+          # attr_to_cluster is the name of attribute to be clustered (a symbol).
+          # The attribute should be geometry attribute.
+          #
+          # Use the options Hash to define what cluster properties you would
+          # like returned.
+          #
+          # Options:
+          #
+          # [:grid_size] if set, will be used to create the cluster. The clustering
+          #     works rougly like this; all geometries within 'grid_size'
+          #     will be pulled together to form a single cluster. For a detailed
+          #     explanation, please see the PostGIS docs for ST_SnapToGrid.
+          #
+          #     If no +:grid_size+ is given, clusters will consist of all 'equal'
+          #     geometries. E.g. all points at the same 
+          #     position (x,y) will be pulled together to form a single cluster.
+          #     This is actually just a Group By of your +attr_to_cluster+.
+          #
+          # [:cluster_geometry_count] if set to true, the query will select, for
+          #     each cluster, the number of geometries in the cluster.
+          #
+          # [:cluster_geometry_count_as] the name to select the
+          #     cluster_geometry_count as, defaults to "cluster_geometry_count".
+          #
+          # [:cluster_centroid] if set to true, the query will select, for
+          #     each cluster, the cluster centroid. The cluster_centroid returned
+          #     will be a WKT string.
+          #
+          # [:cluster_centroid_as] the name to select the 
+          #     cluster_centroid as, defaults to "cluster_centroid".
+          #
+          # [:cluster_minimum_bounding_circle] if set to true, the query will select,
+          #     for each cluster, the minimum bouding circle. The cluster_minimum_bounding_circle
+          #     will be a WKT string.
+          #
+          # [:cluster_minimum_bounding_circle_as] the name to select the
+          #     cluster_minimum_bounding_circle as, defaults to "cluster_minimum_bounding_circle"
+          #
+          # Note: Using the options hash, you must 'select' at least one attribute,
+          # else this method will raise an ArgumentError.
+          #
+
+          def cluster_by_st_snap_to_grid(attr_to_cluster, options={})
+            raise ArgumentError, "Invalid cluster_by_st_snap_to_grid options provided" unless _are_cluster_options_valid?(options)
+
+            grid_size = options[:grid_size]
+
+            arel_table = self.arel_table
+            arel_attr  = arel_table[attr_to_cluster]
+
+            q = self
+
+            # Get the cluster geometry count (if asked to)
+            if options[:cluster_geometry_count]
+              cluster_geometry_count_as = options[:cluster_geometry_count_as] || "cluster_geometry_count"
+              q = q._select_cluster_geometry_count(attr_to_cluster, cluster_geometry_count_as)
+            end
+
+            if options[:cluster_centroid]
+              cluster_centroid_as = options[:cluster_centroid_as] || "cluster_centroid"
+              q = q._select_cluster_centroid_as_wkt(attr_to_cluster, cluster_centroid_as)
+            end
+
+            if options[:cluster_minimum_bounding_circle]
+              cluster_minimum_bounding_circle_as = options[:cluster_minimum_bounding_circle_as] || "cluster_minimum_bounding_circle"
+              q = q._select_cluster_minimum_bounding_circle_as_wkt(attr_to_cluster, cluster_minimum_bounding_circle_as)
+            end
+
+            if grid_size
+              q = q.group(arel_attr.st_snaptogrid(grid_size))
+            else
+              q = q.group(arel_attr)
+            end
+
+            q
+          end
+
+          # Ensure the user is selecting something, and that
+          # the grid size is either nil, or is a valid integer
+
+          def _are_cluster_options_valid?(options)
+            selecting_something = (
+              options[:cluster_geometry_count] or
+              options[:cluster_centroid] or
+              options[:cluster_minimum_bounding_circle]
+            )
+
+            grid_size_valid = (
+              options[:grid_size].nil? or 
+              ( options[:grid_size].is_a? Numeric and options[:grid_size] >= 0 )
+            )
+
+            valid = selecting_something and grid_size_valid
+          end
+
+          # Select the cluster geometry count 
+
+          def _select_cluster_geometry_count(attr_to_cluster, as)
+            arel_table = self.arel_table
+            arel_attr  = arel_table[attr_to_cluster]
+
+            select(arel_attr.count().as(as))
+          end
+
+          # Select the cluster centroid as WKT.
+
+          def _select_cluster_centroid_as_wkt(attr_to_cluster, as)
+            arel_table = self.arel_table
+            arel_attr  = arel_table[attr_to_cluster]
+
+            select(
+              arel_table.st_astext(
+                arel_attr.st_collect
+              ).as(as)
+            )
+          end
+
+          # Select the cluster minimum bounding circle as WKT.
+
+          def _select_cluster_minimum_bounding_circle_as_wkt(attr_to_cluster, as)
+            arel_table = self.arel_table
+            arel_attr  = arel_table[attr_to_cluster]
+
+            select(
+              arel_table.st_astext(
+                arel_table.st_minimumboundingcircle(arel_attr.st_collect)
+              ).as(as)
+            )
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/rp_clustering-rgeo-activerecord/arel_attribute_spatial_expressions.rb

@@ -67,17 +67,16 @@ module RPClustering
 
         def st_minimumboundingcircle(num_segs=nil)
           args = [self]
+          spatial_flags = [true, true]
+
           if num_segs
             args << num_segs.to_s
-
-            ::RGeo::ActiveRecord::SpatialNamedFunction.new(
-              'ST_MinimumBoundingCircle', args, [true, true, false]
-            )
-          else
-            ::RGeo::ActiveRecord::SpatialNamedFunction.new(
-              'ST_MinimumBoundingCircle', args, [true, true]
-            )
+            spatial_flags << false
           end
+
+          ::RGeo::ActiveRecord::SpatialNamedFunction.new(
+            'ST_MinimumBoundingCircle', args, spatial_flags
+          )
         end
 
       end

data/lib/rp_clustering-rgeo-activerecord/arel_table_spatial_expressions.rb

@@ -83,17 +83,16 @@ module RPClustering
 
         def st_minimumboundingcircle(g, num_segs=nil)
           args = [g]
+          spatial_flags = [true, true]
+
           if num_segs
             args << num_segs.to_s
-
-            ::RGeo::ActiveRecord::SpatialNamedFunction.new(
-              'ST_MinimumBoundingCircle', args, [true, true, false]
-            )
-          else
-            ::RGeo::ActiveRecord::SpatialNamedFunction.new(
-              'ST_MinimumBoundingCircle', args, [true, true]
-            )
+            spatial_flags << false
           end
+
+          ::RGeo::ActiveRecord::SpatialNamedFunction.new(
+            'ST_MinimumBoundingCircle', args, spatial_flags
+          )
         end
 
       end

data/lib/rp_clustering-rgeo-activerecord/version.rb

@@ -1,7 +1,7 @@
 module RPClustering
   module RGeo
     module ActiveRecord
-      VERSION = "0.0.2"
+      VERSION = "0.0.3"
     end
   end
 end

data/test/test_clustering.rb

@@ -0,0 +1,110 @@
+require 'test/unit'
+require 'rgeo/active_record/adapter_test_helper'
+require 'rp_clustering-rgeo-activerecord'
+require 'squeel'
+
+module RPClustering
+  module RGeo
+    module ActiveRecord
+      module Tests
+        class MyUnitTest < Test::Unit::TestCase  # :nodoc:
+
+          # Use the RGEO active record adapter test helper
+
+          DATABASE_CONFIG_PATH = ::File.dirname(__FILE__)+'/database.yml'
+          OVERRIDE_DATABASE_CONFIG_PATH = ::File.dirname(__FILE__)+'/database_local.yml'
+          include ::RGeo::ActiveRecord::AdapterTestHelper
+
+
+          define_test_methods do
+
+            def populate_ar_class(content_)
+              klass_ = create_ar_class
+              case content_
+              when :latlon_point
+                klass_.connection.create_table(:spatial_test) do |t_|
+                  t_.column 'latlon', :point, :srid => 4326
+                end
+              end
+              klass_
+            end
+
+            def test_cluster_by_st_snap_to_grid_exists
+              arel_klass = populate_ar_class(:latlon_point)
+              assert(
+                arel_klass.methods.include?(:cluster_by_st_snap_to_grid),
+                "ActiveRecord::Base should now have a cluster_by_st_snap_to_grid function. " +
+                "Found:\n#{arel_klass.methods.sort}"
+              )
+            end
+
+            def test_cluster_by_st_snap_to_grid_should_exception_with_invalid_options
+              arel_klass = populate_ar_class(:latlon_point)
+
+              assert_raise(ArgumentError) do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size: 10)
+              end
+
+              assert_raise(ArgumentError) do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size:  -12, cluster_geometry_count: true)
+              end
+
+              assert_raise(ArgumentError) do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size:  "2", cluster_geometry_count: true)
+              end
+
+              assert_nothing_thrown do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size:  2, cluster_geometry_count: true)
+              end
+
+              assert_nothing_thrown do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size:  2, cluster_centroid: true)
+              end
+
+              assert_nothing_thrown do
+                res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size:  2, cluster_minimum_bounding_circle: true)
+              end
+
+            end
+
+            def test_clustering_with_a_sufficiently_large_grid_size_reduces_count
+              arel_klass = populate_ar_class(:latlon_point)
+
+              points_generated = 0
+              (-5..5).each do |lng|
+                (-5..5).each do |lat|
+                  obj = arel_klass.new
+                  obj.latlon = @geographic_factory.point(lng, lat)
+                  obj.save!
+                  points_generated+=1
+                end
+              end
+
+              res = arel_klass.cluster_by_st_snap_to_grid(:latlon, grid_size: 5, cluster_geometry_count: true)
+              clusters = res.all
+              total_clusters = clusters.count()
+
+              points_found_in_clusters = 0
+
+              res.all.each do |cluster|
+                points_found_in_clusters += cluster["cluster_geometry_count"].to_i
+              end
+
+              assert_equal(points_generated, points_found_in_clusters,
+                "The sum of the size of our clusters should equal the number of points in the table"
+              )
+
+              # We should have less clusters than we have points
+              assert(total_clusters < points_generated, "we should have less clusters than we have points")
+
+              # We should have more than 1 cluster with this size grid
+              assert(total_clusters > 1, "we should have more than 1 cluster with this grid size")
+            end
+
+          end
+
+        end
+      end
+    end
+  end
+end

data/test/test_unit.rb

@@ -141,6 +141,7 @@ module RPClustering
             end
 
           end
+
         end
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rp_clustering-rgeo-activerecord
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Robert Pyke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-02-28 00:00:00.000000000 Z
+date: 2013-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -178,11 +178,13 @@ files:
 - README.md
 - Rakefile
 - lib/rp_clustering-rgeo-activerecord.rb
+- lib/rp_clustering-rgeo-activerecord/active_record_base_spatial_expressions.rb
 - lib/rp_clustering-rgeo-activerecord/arel_attribute_spatial_expressions.rb
 - lib/rp_clustering-rgeo-activerecord/arel_table_spatial_expressions.rb
 - lib/rp_clustering-rgeo-activerecord/version.rb
 - rp_clustering-rgeo-activerecord.gemspec
 - test/database.yml
+- test/test_clustering.rb
 - test/test_unit.rb
 homepage: https://github.com/robertpyke/rp_clustering-rgeo-activerecord
 licenses:
@@ -210,4 +212,6 @@ specification_version: 4
 summary: RGeo PostGIS extension to provide clustering functionality
 test_files:
 - test/database.yml
+- test/test_clustering.rb
 - test/test_unit.rb
+has_rdoc: