spatial_stats 0.1.1 → 0.2.1

data/lib/spatial_stats/narray_ext.rb

@@ -3,7 +3,19 @@
 require 'numo/narray'
 
 module Numo
+  ##
+  # Extension to Numo::NArray base class.
   class NArray
+    ##
+    # For a 2-D NArray, transform the non-zero values so that the sum of each
+    # row is 1.
+    #
+    # @ example
+    #
+    #   Numo::DFloat [[0, 1, 1], [1, 1, 1]].row_standardized
+    #   Numo::DFloat [[0, 0.5, 0.5], [0.33333, 0.33333, 0.33333]]
+    #
+    # @return [Numo::NArray]
     def row_standardized
       # every row will sum up to 1, or if they are all 0, do nothing
       standardized = each_over_axis.map do |row|
@@ -20,6 +32,21 @@ module Numo
       self.class.cast(standardized)
     end
 
+    ##
+    # For a 2-D, n x n NArray, if the trace is 0, add an n x n eye matrix to the matrix
+    # and return the result.
+    #
+    # @ example
+    #
+    #   Numo::DFloat [[0, 1, 0], [1, 0, 1], [0, 1, 0]].windowed
+    #   Numo::DFloat [[1, 1, 0], [1, 1, 1], [0, 1, 1]]
+    #
+    # @ example
+    #   # Input will be equivalent to output in this case
+    #   Numo::DFloat [[1, 1, 0], [1, 0, 1], [0, 1, 0]].windowed
+    #   Numo::DFloat [[1, 1, 0], [1, 0, 1], [0, 1, 0]]
+    #
+    # @return [Numo::NArray]
     def windowed
       # in windowed calculations, the diagonal is set to 1
       # if trace (sum of diag) is 0, add it, else return input

data/lib/spatial_stats/queries.rb

@@ -2,3 +2,9 @@
 
 require 'spatial_stats/queries/variables'
 require 'spatial_stats/queries/weights'
+
+module SpatialStats
+  # The Queries module contains the ActiveRecord/PostGIS interface for the gem.
+  module Queries
+  end
+end

data/lib/spatial_stats/queries/variables.rb

@@ -2,10 +2,23 @@
 
 module SpatialStats
   module Queries
+    ##
+    # Variables includes a method to query a field from a given scope and
+    # keep it in a consistent order with how weights are queried.
     module Variables
-      # Module to query for the desired variable from the given scope
-      # and include the primary keys so that the weights matrix
-      # will know that its keys will match up with the variables.
+      ##
+      # Query the given field for a scope and order by primary key
+      #
+      # @example
+      #   scope = County.all
+      #   field = :avg_income
+      #   SpatialStats::Queries::Variables.query_field(scope, field)
+      #   # => [30023, 23400, 57800, ...]
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] field you want to query from the scope
+      #
+      # @return [Array]
       def self.query_field(scope, field)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(field)

data/lib/spatial_stats/queries/weights.rb

@@ -2,14 +2,31 @@
 
 module SpatialStats
   module Queries
-    # This provides PostGIS queries for calculating weights/neighbors
-    # of spatial data sets
+    ##
+    # Weights includes methods for querying a scope using PostGIS sql methods
+    # to determine neighbors and weights based on different weighting
+    # schemes/formulas.
     module Weights
-      def self.idw_knn(scope, column, n, alpha)
+      ##
+      # Compute inverse distance weighted, k nearest neighbors weights
+      # for a given scope and geometry.
+      #
+      # Combines knn and idw weightings. Each observation will have
+      # k neighbors, but the weights will be calculated by 1/(d**alpha).
+      #
+      # Only works for geometry types that implement ST_Distance.
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      # @param [Integer] k neighbors to find
+      # @param [Integer] alpha number used in inverse calculations (usually 1 or 2)
+      #
+      # @return [Hash]
+      def self.idw_knn(scope, column, k, alpha = 1)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(column)
         primary_key = klass.quoted_primary_key
-        neighbors = klass.find_by_sql([<<-SQL, scope: scope, n: n])
+        neighbors = klass.find_by_sql([<<-SQL, scope: scope, k: k])
           WITH scope as (:scope)
           SELECT neighbors.*
           FROM scope AS a
@@ -19,7 +36,7 @@ module SpatialStats
             FROM scope as b
             WHERE a.#{primary_key} <> b.#{primary_key}
             ORDER BY a.#{column} <-> b.#{column}
-            LIMIT :n
+            LIMIT :k
           ) AS neighbors
         SQL
 
@@ -41,6 +58,21 @@ module SpatialStats
         end
       end
 
+      ##
+      # Compute inverse distance weighted, band limited weights
+      # for a given scope and geometry.
+      #
+      # Combines distance_band and idw weightings. Each observation will have
+      # neighbers in the bandwidth, but the weights will be calculated by 1/(d**alpha).
+      #
+      # Only works for geometry types that implement ST_Distance and ST_DWithin.
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      # @param [Numeric] bandwidth to find neighbors in
+      # @param [Integer] alpha number used in inverse calculations (usually 1 or 2)
+      #
+      # @return [Hash]
       def self.idw_band(scope, column, bandwidth, alpha = 1)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(column)
@@ -75,11 +107,19 @@ module SpatialStats
         end
       end
 
-      def self.knn(scope, column, n)
+      ##
+      # Compute k nearest neighbor weights for a given scope.
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      # @param [Integer] k neighbors to find
+      #
+      # @return [Hash]
+      def self.knn(scope, column, k)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(column)
         primary_key = klass.quoted_primary_key
-        klass.find_by_sql([<<-SQL, scope: scope, n: n])
+        klass.find_by_sql([<<-SQL, scope: scope, k: k])
           WITH scope as (:scope)
           SELECT neighbors.*
           FROM scope AS a
@@ -88,11 +128,21 @@ module SpatialStats
             FROM scope as b
             WHERE a.#{primary_key} <> b.#{primary_key}
             ORDER BY a.#{column} <-> b.#{column}
-            LIMIT :n
+            LIMIT :k
           ) AS neighbors
         SQL
       end
 
+      ##
+      # Compute distance band weights for a given scope. Identifies neighbors
+      # as other observations in scope that are within the distance band
+      # from the observation.
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      # @param [Numeric] bandwidth to find neighbors in
+      #
+      # @return [Hash]
       def self.distance_band_neighbors(scope, column, bandwidth)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(column)
@@ -109,15 +159,47 @@ module SpatialStats
         SQL
       end
 
-      # DE-9IM queen contiguiety = F***T****
+      ##
+      # Compute queen contiguity weights for a given scope. Queen
+      # contiguity weights are defined by geometries sharing an edge
+      # or vertex.
+      #
+      # DE-9IM pattern = +F***T****+
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      #
+      # @return [Hash]
       def self.queen_contiguity_neighbors(scope, column)
         _contiguity_neighbors(scope, column, 'F***T****')
       end
 
+      ##
+      # Compute rook contiguity weights for a given scope. Rook
+      # contiguity weights are defined by geometries sharing an edge.
+      #
+      # DE-9IM pattern = +'F***1****'+
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      #
+      # @return [Hash]
       def self.rook_contiguity_neighbors(scope, column)
         _contiguity_neighbors(scope, column, 'F***1****')
       end
 
+      ##
+      # Generic function to compute contiguity neighbor weights for a
+      # given scope. Takes any valid DE-9IM pattern and computes the
+      # neighbors based off of that.
+      #
+      # @see https://en.wikipedia.org/wiki/DE-9IM
+      #
+      # @param [ActiveRecord::Relation] scope you want to query
+      # @param [Symbol, String] column that contains the geometry
+      # @param [String] pattern to describe neighbor relation
+      #
+      # @return [Hash]
       def self._contiguity_neighbors(scope, column, pattern)
         klass = scope.klass
         column = ActiveRecord::Base.connection.quote_column_name(column)

data/lib/spatial_stats/utils.rb

@@ -1,3 +1,10 @@
 # frozen_string_literal: true
 
 require 'spatial_stats/utils/lag'
+
+module SpatialStats
+  ##
+  # The Utils module contains various utilities used in the gem.
+  module Utils
+  end
+end

data/lib/spatial_stats/utils/lag.rb

@@ -3,23 +3,55 @@
 require 'numo/narray'
 module SpatialStats
   module Utils
+    ##
+    # Lag includes methdos for computing spatially lagged variables under
+    # different contexts.
     module Lag
-      # module for computing spatially lagged variables
-      # from a weights matrix and variable array
+      ##
+      # Dot product of the row_standardized input matrix
+      # by the input vector, variables.
+      #
+      # @param [Numo::NArray] matrix 2-D square matrix.
+      # @param [Array] variables vector multiplying the matrix
+      #
+      # @return [Array] resultant vector
       def self.neighbor_average(matrix, variables)
         matrix = matrix.row_standardized
         neighbor_sum(matrix, variables)
       end
 
+      ##
+      # Dot product of the input matrix by the input vector, variables.
+      #
+      # @param [Numo::NArray] matrix 2-D square matrix.
+      # @param [Array] variables vector multiplying the matrix
+      #
+      # @return [Array] resultant vector
       def self.neighbor_sum(matrix, variables)
         matrix.dot(variables).to_a
       end
 
+      ##
+      # Dot product of the input windowed, row standardizd matrix by
+      # the input vector, variables.
+      #
+      # @param [Numo::NArray] matrix 2-D square matrix.
+      # @param [Array] variables vector multiplying the matrix
+      #
+      # @return [Array] resultant vector
       def self.window_average(matrix, variables)
         matrix = matrix.windowed.row_standardized
         window_sum(matrix, variables)
       end
 
+      ##
+      # Dot product of the input windowed matrix by
+      # the input vector, variables.
+      #
+      # @param [Numo::NArray] matrix 2-D square matrix.
+      # @param [Array] variables vector multiplying the matrix
+      #
+      # @return [Array] resultant vector
       def self.window_sum(matrix, variables)
         matrix = matrix.windowed
         matrix.dot(variables).to_a

data/lib/spatial_stats/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SpatialStats
-  VERSION = '0.1.1'
+  VERSION = '0.2.1'
 end

data/lib/spatial_stats/weights.rb

@@ -3,3 +3,12 @@
 require 'spatial_stats/weights/contiguous'
 require 'spatial_stats/weights/distant'
 require 'spatial_stats/weights/weights_matrix'
+
+module SpatialStats
+  ##
+  # The Weights module contains the classes for computing different types of
+  # weight matrices and a weights matrix class to work with the results of
+  # queries.
+  module Weights
+  end
+end

data/lib/spatial_stats/weights/contiguous.rb

@@ -2,7 +2,18 @@
 
 module SpatialStats
   module Weights
+    ##
+    # Contiguous weights module includes methods that provide an interface to
+    # coniguous weights queries and formats the result properly to utilize
+    # a weights matrix.
     module Contiguous
+      ##
+      # Compute rook weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      #
+      # @return [WeightsMatrix]
       def self.rook(scope, field)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort
@@ -21,6 +32,13 @@ module SpatialStats
         SpatialStats::Weights::WeightsMatrix.new(keys, weights)
       end
 
+      ##
+      # Compute queen weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      #
+      # @return [WeightsMatrix]
       def self.queen(scope, field)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort

data/lib/spatial_stats/weights/distant.rb

@@ -2,7 +2,18 @@
 
 module SpatialStats
   module Weights
+    # Distant weights module includes methods that provide an interface to
+    # distance-based weights queries and formats the result properly to utilize
+    # a weights matrix.
     module Distant
+      ##
+      # Compute distance band weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      # @param [Numeric] bandwidth of distance band
+      #
+      # @return [WeightsMatrix]
       def self.distance_band(scope, field, bandwidth)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort
@@ -21,12 +32,20 @@ module SpatialStats
         SpatialStats::Weights::WeightsMatrix.new(keys, weights)
       end
 
-      def self.knn(scope, field, n)
+      ##
+      # Compute distance band weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      # @param [Integer] k neighbors to find
+      #
+      # @return [WeightsMatrix]
+      def self.knn(scope, field, k)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort
 
         neighbors = SpatialStats::Queries::Weights
-                    .knn(scope, field, n)
+                    .knn(scope, field, k)
 
         neighbors = neighbors.group_by(&:i_id)
         weights = neighbors.transform_values do |value|
@@ -39,6 +58,15 @@ module SpatialStats
         SpatialStats::Weights::WeightsMatrix.new(keys, weights)
       end
 
+      ##
+      # Compute idw, distance band weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      # @param [Numeric] bandwidth of distance band
+      # @param [Numeric] alpha used in weighting calculation (usually 1 or 2)
+      #
+      # @return [WeightsMatrix]
       def self.idw_band(scope, field, bandwidth, alpha = 1)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort
@@ -56,12 +84,21 @@ module SpatialStats
         SpatialStats::Weights::WeightsMatrix.new(keys, weights)
       end
 
-      def self.idw_knn(scope, field, n, alpha = 1)
+      ##
+      # Compute idw, knn weights matrix for a scope.
+      #
+      # @param [ActiveRecord::Relation] scope to query
+      # @param [Symbol, String] field with geometry in it
+      # @param [Integer] k neighbors to find
+      # @param [Numeric] alpha used in weighting calculation (usually 1 or 2)
+      #
+      # @return [WeightsMatrix]
+      def self.idw_knn(scope, field, k, alpha = 1)
         p_key = scope.primary_key
         keys = scope.pluck(p_key).sort
 
         neighbors = SpatialStats::Queries::Weights
-                    .idw_knn(scope, field, n, alpha)
+                    .idw_knn(scope, field, k, alpha)
         neighbors = neighbors.group_by { |pair| pair[:i_id] }
 
         # only keep j_id and weight

data/lib/spatial_stats/weights/weights_matrix.rb

@@ -4,7 +4,17 @@ require 'numo/narray'
 
 module SpatialStats
   module Weights
+    ##
+    # WeightsMatrix class is used to store spatial weights and related
+    # information in various formats.
     class WeightsMatrix
+      ##
+      # A new instance of WeightsMatrix
+      #
+      # @param [Array] keys ordered list of keys used in weights
+      # @param [Hash] weights hash of format +{key: [{j_id: neighbor_key, weight: 1}]}+ that describe the relations between neighbors
+      #
+      # @return [WeightsMatrix]
       def initialize(keys, weights)
         @keys = keys
         @weights = weights
@@ -12,6 +22,17 @@ module SpatialStats
       end
       attr_accessor :keys, :weights, :n
 
+      ##
+      # Compute the n x n Numo::Narray of the weights hash.
+      #
+      # @example
+      #   hash = {1 => [{j_id: 2, weight: 1}], 2 => [{j_id: 1, weight: 1},
+      #       {j_id: 3, weight: 1}], 3 => [{j_id: 2, weight: 1}]}
+      #   wm = WeightsMatrix.new(hash.keys, hash)
+      #   wm.full
+      #   # => Numo::DFloat[[0, 1, 0], [1, 0, 1], [0, 1, 0]]
+      #
+      # @return [Numo::DFloat]
       def full
         # returns a square matrix Wij using @keys as the order of items
         @full ||= begin
@@ -34,6 +55,10 @@ module SpatialStats
         end
       end
 
+      ##
+      # Row standardized version of +#full+
+      #
+      # @return [Numo::DFloat]
       def standardized
         @standardized ||= full.row_standardized
       end