neighbor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f346d121745bd39998267c45f77009970c014de887376022f8b6425192d37354
+  data.tar.gz: '0293bc9fd3633ca3ee811940c59995407357d4b880fcf8ea8cd9223e5df0e75b'
+SHA512:
+  metadata.gz: cf080c46ad8133a460453c773faabac02e229821625fa9f2d51a320195b1e821b230c94c7fe45bc7f7d12b0b51ce6d3e5f1d4c0d74e446b0ce22dde2f5171cde
+  data.tar.gz: f2e0ae2247979bd3dd083b1869b56f7b6ed879ce8dd1c0ef31d965392d8250548acb304a78ba99a1d6cdfea116c10e0d67aff9c06185a793e576bddae4d624f1

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0 (2021-02-15)
+
+- First release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Andrew Kane
+
+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,142 @@
+# Neighbor
+
+Nearest neighbor search for Rails and Postgres
+
+[![Build Status](https://github.com/ankane/neighbor/workflows/build/badge.svg?branch=master)](https://github.com/ankane/neighbor/actions)
+
+## Installation
+
+Add this line to your application’s Gemfile:
+
+```ruby
+gem 'neighbor'
+```
+
+And run:
+
+```sh
+bundle install
+rails generate neighbor:install
+rails db:migrate
+```
+
+## Getting Started
+
+Create a migration
+
+```ruby
+class AddNeighborVectorToItems < ActiveRecord::Migration[6.1]
+  def change
+    add_column :items, :neighbor_vector, :cube
+  end
+end
+```
+
+Add to your model
+
+```ruby
+class Item < ApplicationRecord
+  has_neighbors dimensions: 3
+end
+```
+
+Update the vectors
+
+```ruby
+item.update(neighbor_vector: [1.0, 1.2, 0.5])
+```
+
+> With cosine distance (the default), vectors are normalized before being stored
+
+And get the nearest neighbors
+
+```ruby
+item.nearest_neighbors.first(5)
+```
+
+## Distances
+
+Specify the distance metric
+
+```ruby
+class Item < ApplicationRecord
+  has_neighbors dimensions: 20, distance: "euclidean"
+end
+```
+
+Supported distances are:
+
+- `cosine` (default)
+- `euclidean`
+- `taxicab`
+- `chebyshev`
+
+Returned records will have a `neighbor_distance` attribute
+
+```ruby
+returned_item.neighbor_distance
+```
+
+## Example
+
+You can use Neighbor for online item recommendations with [Disco](https://github.com/ankane/disco). We’ll use MovieLens data for this example.
+
+Generate a model
+
+```sh
+rails generate model Movie name:string neighbor_vector:cube
+rails db:migrate
+```
+
+And add `has_neighbors`
+
+```ruby
+class Movie < ApplicationRecord
+  has_neighbors dimensions: 20
+end
+```
+
+Fit the recommender
+
+```ruby
+data = Disco.load_movielens
+recommender = Disco::Recommender.new(factors: 20)
+recommender.fit(data)
+```
+
+Use item factors for the neighbor vector
+
+```ruby
+recommender.item_ids.each do |item_id|
+  Movie.create!(name: item_id, neighbor_vector: recommender.item_factors(item_id))
+end
+```
+
+And get similar movies
+
+```ruby
+movie = Movie.find_by(name: "Star Wars (1977)")
+movie.nearest_neighbors.first(5).map(&:name)
+```
+
+## History
+
+View the [changelog](https://github.com/ankane/neighbor/blob/master/CHANGELOG.md)
+
+## Contributing
+
+Everyone is encouraged to help improve this project. Here are a few ways you can help:
+
+- [Report bugs](https://github.com/ankane/neighbor/issues)
+- Fix bugs and [submit pull requests](https://github.com/ankane/neighbor/pulls)
+- Write, clarify, or fix documentation
+- Suggest or add new features
+
+To get started with development:
+
+```sh
+git clone https://github.com/ankane/neighbor.git
+cd neighbor
+bundle install
+bundle exec rake test
+```

data/lib/generators/neighbor/install_generator.rb

@@ -0,0 +1,18 @@
+require "rails/generators/active_record"
+
+module Neighbor
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+      source_root File.join(__dir__, "templates")
+
+      def copy_migration
+        migration_template "migration.rb", "db/migrate/install_neighbor.rb", migration_version: migration_version
+      end
+
+      def migration_version
+        "[#{ActiveRecord::VERSION::MAJOR}.#{ActiveRecord::VERSION::MINOR}]"
+      end
+    end
+  end
+end

data/lib/generators/neighbor/templates/migration.rb.tt

@@ -0,0 +1,5 @@
+class <%= migration_class_name %> < ActiveRecord::Migration<%= migration_version %>
+  def change
+    enable_extension "cube"
+  end
+end

data/lib/neighbor.rb

@@ -0,0 +1,27 @@
+# dependencies
+require "active_support"
+
+# modules
+require "neighbor/version"
+
+module Neighbor
+  class Error < StandardError; end
+
+  module RegisterCubeType
+    def initialize_type_map(m = type_map)
+      super
+      m.register_type "cube", ActiveRecord::ConnectionAdapters::PostgreSQL::OID::SpecializedString.new(:cube)
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  require "neighbor/model"
+  require "neighbor/vector"
+
+  extend Neighbor::Model
+
+  # prevent unknown OID warning
+  require "active_record/connection_adapters/postgresql_adapter"
+  ActiveRecord::ConnectionAdapters::PostgreSQLAdapter.prepend(Neighbor::RegisterCubeType)
+end

data/lib/neighbor/model.rb

@@ -0,0 +1,44 @@
+module Neighbor
+  module Model
+    def has_neighbors(dimensions:, distance: "cosine")
+      distance = distance.to_s
+      raise ArgumentError, "Invalid distance: #{distance}" unless %w(cosine euclidean taxicab chebyshev).include?(distance)
+
+      class_eval do
+        attribute :neighbor_vector, Neighbor::Vector.new(dimensions: dimensions, distance: distance)
+
+        define_method :nearest_neighbors do
+          return self.class.none if neighbor_vector.nil?
+
+          operator =
+            case distance
+            when "taxicab"
+              "<#>"
+            when "chebyshev"
+              "<=>"
+            else
+              "<->"
+            end
+
+          # important! neighbor_vector should already be typecast
+          # but use to_f as extra safeguard against SQL injection
+          order = "neighbor_vector #{operator} cube(array[#{neighbor_vector.map(&:to_f).join(", ")}])"
+
+          # https://stats.stackexchange.com/questions/146221/is-cosine-similarity-identical-to-l2-normalized-euclidean-distance
+          # with normalized vectors:
+          # cosine similarity = 1 - (euclidean distance)**2 / 2
+          # cosine distance = 1 - cosine similarity
+          # this transformation doesn't change the order, so only needed for select
+          neighbor_distance = distance == "cosine" ? "POWER(#{order}, 2) / 2.0" : order
+
+          # for select, use column_names instead of * to account for ignored columns
+          self.class
+            .select(*self.class.column_names, "#{neighbor_distance} AS neighbor_distance")
+            .where.not(self.class.primary_key => send(self.class.primary_key))
+            .where.not(neighbor_vector: nil)
+            .order(Arel.sql(order))
+        end
+      end
+    end
+  end
+end

data/lib/neighbor/vector.rb

@@ -0,0 +1,35 @@
+module Neighbor
+  class Vector < ActiveRecord::Type::Value
+    def initialize(dimensions:, distance:)
+      super()
+      @dimensions = dimensions
+      @distance = distance
+    end
+
+    def cast(value)
+      return if value.nil?
+
+      value = value.to_a.map(&:to_f)
+      raise Error, "Expected #{@dimensions} dimensions, not #{value.size}" unless value.size == @dimensions
+
+      if @distance == "cosine"
+        norm = 0.0
+        value.each do |v|
+          norm += v * v
+        end
+        norm = Math.sqrt(norm)
+        value.map { |v| v / norm }
+      else
+        value
+      end
+    end
+
+    def serialize(value)
+      "(#{cast(value).join(", ")})" unless value.nil?
+    end
+
+    def deserialize(value)
+      value[1..-1].split(",").map(&:to_f) unless value.nil?
+    end
+  end
+end

data/lib/neighbor/version.rb

@@ -0,0 +1,3 @@
+module Neighbor
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: neighbor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Kane
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-02-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email: andrew@ankane.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/generators/neighbor/install_generator.rb
+- lib/generators/neighbor/templates/migration.rb.tt
+- lib/neighbor.rb
+- lib/neighbor/model.rb
+- lib/neighbor/vector.rb
+- lib/neighbor/version.rb
+homepage: https://github.com/ankane/neighbor
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key:
+specification_version: 4
+summary: Nearest neighbor search for Rails and Postgres
+test_files: []