affinity_propagation 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 26f8c5ca0ecef4d7c7e89341a5039eadefef5871
+  data.tar.gz: cd466acdd9604ca6e547558438203b88283d21c9
+SHA512:
+  metadata.gz: 72c71cf377b691208ffeb714022216bb3d4b259ec09157feded788f49858d8e5260538ab73dec78e1a126b9914c9eb8c251a0c44818235ba35c366b81f24cd28
+  data.tar.gz: 4fdcd1c0742094f837c95ebcd4366045006deb97dd358fe55a6575244ad07eb9207a3b5331cf9f8035fb2ec9dca2ad0b46d68188eb23d79b0a87646e79542ab5

data/.gitignore

@@ -0,0 +1,54 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+# .env
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+#
+# We recommend against adding the Pods directory to your .gitignore. However
+# you should judge for yourself, the pros and cons are mentioned at:
+# https://guides.cocoapods.org/using/using-cocoapods.html#should-i-check-the-pods-directory-into-source-control
+#
+# vendor/Pods/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+# Gemfile.lock
+# .ruby-version
+# .ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# IDEs
+.idea
+

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+affinity_propagation

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.4.1

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.4.1
+before_install: gem install bundler -v 1.15.4

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in affinity_propagation.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,47 @@
+PATH
+  remote: .
+  specs:
+    affinity_propagation (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.1.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    concurrent-ruby (1.0.5)
+    diff-lcs (1.3)
+    i18n (0.8.6)
+    minitest (5.10.3)
+    rake (10.5.0)
+    rspec (3.6.0)
+      rspec-core (~> 3.6.0)
+      rspec-expectations (~> 3.6.0)
+      rspec-mocks (~> 3.6.0)
+    rspec-core (3.6.0)
+      rspec-support (~> 3.6.0)
+    rspec-expectations (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-mocks (3.6.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.6.0)
+    rspec-support (3.6.0)
+    thread_safe (0.3.6)
+    tzinfo (1.2.3)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport
+  affinity_propagation!
+  bundler (~> 1.15)
+  rake (~> 10.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   1.15.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Shahbaz Javeed
+
+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,121 @@
+# AffinityPropagation
+
+This gem allows you to use the affinity propagation algorithm (see BJ Frey and D Dueck,
+[Science 315, Feb 16, 2007](http://www.psi.toronto.edu/affinitypropagation/FreyDueckScience07.pdf)) to cluster arbitrary
+data by providing the data and a block to calculate the similarity between any two data points in that list.
+
+For more information on affinity propagation, visit the [FAQ over at University of Toronto](http://www.psi.toronto.edu/affinitypropagation/faq.html).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'affinity_propagation'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install affinity_propagation
+
+## Usage
+
+A simple example of usage is:
+
+```ruby
+data = [1, 2, 3, 4, 500, 525, 602, 630, 1000, 1100, 1065, 1150]
+apc = AffinityPropagation::Calculator.new(data) do |datum, exemplar|
+  # A recommended similarity function from the original paper:
+  # negative square of the distance between two points
+  # However you can choose anything here and even make it asymmetrical if your data needs it
+  -((datum - exemplar) ** 2)
+end
+apc.run(stable_iterations: 50)
+apc.clusters
+```
+This will result in the following (beautified) output:
+```ruby
+[
+  {
+    :exemplar=>2,
+    :members=>[1, 2, 4]
+  },
+  {
+    :exemplar=>3,
+    :members=>[3]
+  },
+  {
+    :exemplar=>602,
+    :members=>[500, 525, 602, 630]
+  },
+  {
+    :exemplar=>1065,
+    :members=>[1000, 1100, 1065, 1150]
+  }
+]
+```
+A more real-world example would be something like the following:
+```ruby
+require 'active_support/all'
+data = [
+  { value: 'A', timestamp: 1.year.ago },
+  { value: 'B', timestamp: 1.year.ago },
+  { value: 'C', timestamp: 1.year.ago },
+  { value: 'D', timestamp: 1.year.ago + 1.hour },
+  { value: 'E', timestamp: 1.year.ago + 1.day },
+
+  { value: 'a', timestamp: 1.month.ago },
+  { value: 'b', timestamp: 1.month.ago + 1.hour },
+  { value: 'c', timestamp: 1.month.ago + 1.day },
+
+  { value: 'd', timestamp: 2.weeks.ago },
+  { value: 'e', timestamp: 2.weeks.ago - 3.hours },
+  { value: 'f', timestamp: 2.weeks.ago - 10.hours },
+  { value: 'g', timestamp: 2.weeks.ago + 5.hours },
+
+  { value: 'h', timestamp: 24.hours.ago },
+  { value: 'i', timestamp: 40.hours.ago },
+  { value: 'j', timestamp: 12.hours.ago },
+  { value: 'k', timestamp: 12.minutes.ago }
+]
+apc = AffinityPropagation::Calculator.new(data, lambda: 0.9) do |datum, exemplar|
+  difference = datum[:timestamp] - exemplar[:timestamp]
+
+  -(difference ** 2)
+end
+apc.run(stable_iterations: 25)
+apc.clusters.map { |center| center[:members].map { |item| item[:value] } }
+```
+## Tweaking the Result
+There are at least two ways to tweak the algorithm to generate clusters closer to any expectations you might have for
+your data:
+
+1. Changing the dampening factor, `lambda`, which can be provided to the constructor for `AffinityPropagation::Calculator`.
+This helps prevent numerical oscillations while updating the responsibilities and similarities matrices.  This defaults
+0.75 but can be changed by specifying the lambda name argument as in the second example above.
+1. Assigning custom values to the self-similarity nodes in the similarity matrix generated when you instantiate the
+`AffinityPropagation::Calculator` object.  These self-similarity values are currently assigned a common value to
+not suggest any one exemplar over another.  This common value is the median of all similarities found in the entire
+similarity matrix.  This is not currently tweakable from your code but there's a plan to allow this to be tweaked.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+This is my initial take on this problem and I have still to add a few usability, configuration and performance tweaks
+but wanted to get this out there so people can use it.  If you find it useful and are able to contribute to remove some
+of the clearly vast set of issues that this codebase has, please send me a pull request and let's talk!
+ 
+Bug reports and pull requests are welcome on GitHub at https://github.com/sjaveed/affinity_propagation.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/affinity_propagation.gemspec

@@ -0,0 +1,32 @@
+# coding: utf-8
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "affinity_propagation/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "affinity_propagation"
+  spec.version       = AffinityPropagation::VERSION
+  spec.authors       = ["Shahbaz Javeed"]
+  spec.email         = ["sjaveed@gmail.com"]
+
+  spec.summary       = %q{An implementation of the affinity propagation clustering algorithm by Frey and Dueck}
+  spec.description   = %q{
+    Affinity Propagation is a clustering algorithm that does not require pre-specifying the number of clusters like
+    k-means and other similar algorithms do.  This is a ruby implementation of the original version defined by Frey and
+    Dueck in http://www.psi.toronto.edu/affinitypropagation/FreyDueckScience07.pdf
+  }
+  spec.homepage      = "https://github.com/sjaveed/affinity_propagation"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.15"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "activesupport"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "affinity_propagation"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/affinity_propagation.rb

@@ -0,0 +1,6 @@
+require 'affinity_propagation/version'
+require 'affinity_propagation/calculator'
+
+module AffinityPropagation
+  # Your code goes here...
+end

data/lib/affinity_propagation/calculator.rb

@@ -0,0 +1,180 @@
+require 'matrix'
+
+module AffinityPropagation
+  refine Array do
+    def median
+      relevant_elements = if size % 2 == 0
+        # Even number of items in this list => let's get the middle two and return their mean
+        slice(size / 2, 2)
+      else
+        slice(size / 2, 1)
+      end
+
+      relevant_elements.sum / relevant_elements.size
+    end
+  end
+
+  refine Matrix do
+    def to_matlab
+      output = row_vectors.map(&:to_a).map { |row| row.join(', ') }.join('; ')
+
+      "[#{output}]"
+    end
+  end
+
+  class Calculator
+    using AffinityPropagation
+
+    LAMBDA = 0.75
+
+    attr_accessor :raw_clusters
+
+    def initialize(data, lambda: LAMBDA, &block)
+      @data = data
+      @lambda = lambda
+
+      raise 'no block provide to calculate similarities within data!' unless block_given?
+
+      @similarities = similarity_matrix(&block)
+      reset
+    end
+
+    def reset
+      @raw_clusters = {}
+      @stable_cluster_iterations = 0
+      @total_iterations = 0
+
+      @availabilities = Matrix.zero(@data.size, @data.size)
+      @responsibilities = Matrix.zero(@data.size, @data.size)
+    end
+
+    def iterate
+      @availabilities = availability_matrix
+      @responsibilities = responsibility_matrix
+      update_clusters
+
+      @total_iterations += 1
+    end
+
+    def clusters
+      clusters = []
+
+      raw_clusters.each do |exemplar_id, data_ids|
+        clusters << {
+          exemplar: @data[exemplar_id],
+          members: data_ids.map { |datum_id| @data[datum_id] }
+        }
+      end
+
+      clusters
+    end
+
+    def run(iterations: 100, stable_iterations: 10)
+      iterate while @total_iterations < iterations && @stable_cluster_iterations < stable_iterations
+    end
+
+    private
+
+    def similarity_matrix(&block)
+      similarity_array = []
+      similarities = Matrix.build(@data.size, @data.size) do |row_idx, col_idx|
+        exemplar = @data[row_idx]
+        datum = @data[col_idx]
+
+        similarity = block.call(datum, exemplar)
+        similarity_array << similarity
+        similarity
+      end
+
+      median_similarity = similarity_array.median
+
+      # Matrices can't be modified once created so we have to use this hack
+      (0...@data.size).each { |idx| similarities.send(:[]=, idx, idx, median_similarity) }
+
+      similarities
+    end
+
+    def dampen(new_value, existing_value)
+      (1 - @lambda) * new_value + @lambda * existing_value
+    end
+
+    def responsibility_matrix
+      Matrix.build(@similarities.row_count, @similarities.column_count) do |row_idx, col_idx|
+        exemplar_idx = row_idx
+        datum_idx = col_idx
+
+        availability_column = @availabilities.column(col_idx).to_a
+        availability_column.slice!(exemplar_idx)
+        similarity_column = @similarities.column(col_idx).to_a
+        similarity_column.slice!(exemplar_idx)
+
+        availability_plus_similarity = []
+        availability_column.zip(similarity_column) { |data| availability_plus_similarity << data.sum }
+
+        dampen(@similarities[row_idx, col_idx] - availability_plus_similarity.max, @responsibilities[exemplar_idx, datum_idx])
+      end
+    end
+
+    def availability_matrix
+      Matrix.build(@responsibilities.row_count, @responsibilities.column_count) do |row_idx, col_idx|
+        exemplar_idx = row_idx
+        datum_idx = col_idx
+        responsibility_column = @responsibilities.row(exemplar_idx).to_a
+
+        if exemplar_idx == datum_idx
+          # self-availability
+          responsibility_column.slice!(exemplar_idx)
+
+          dampen(responsibility_column.inject(0) { |sum, item| sum += [0, item].max },@availabilities[exemplar_idx, datum_idx])
+        else
+          self_responsibility = @responsibilities[exemplar_idx, exemplar_idx]
+          if datum_idx > exemplar_idx
+            # Slice out the datum index first since in this case it won't affect the exemplar index
+            responsibility_column.slice!(datum_idx)
+            responsibility_column.slice!(exemplar_idx)
+          else
+            responsibility_column.slice!(exemplar_idx)
+            responsibility_column.slice!(datum_idx)
+          end
+
+          responsibility_column_sum = responsibility_column.inject(0) { |sum, item| sum += [0, item].max }
+
+          dampen([0, self_responsibility + responsibility_column_sum].min, @availabilities[exemplar_idx, datum_idx])
+        end
+      end
+    end
+
+    def identify_raw_clusters
+      clusters = {}
+
+      @data.each_with_index do |item, datum_idx|
+        availability_column = @availabilities.column(datum_idx).to_a
+        responsibility_column = @responsibilities.column(datum_idx).to_a
+
+        availability_and_responsibility = @data.size.times.map do |exemplar_idx|
+          availability_column[exemplar_idx] + responsibility_column[exemplar_idx]
+        end
+        exemplar_idx = availability_and_responsibility.index(availability_and_responsibility.max)
+
+        if clusters.key?(exemplar_idx)
+          clusters[exemplar_idx] << datum_idx
+        else
+          clusters[exemplar_idx] = [datum_idx]
+        end
+      end
+
+      clusters
+    end
+
+    def update_clusters
+      new_clusters = identify_raw_clusters
+
+      if new_clusters == @raw_clusters
+        @stable_cluster_iterations += 1
+      else
+        @raw_clusters = new_clusters
+        @stable_cluster_iterations = 0
+      end
+    end
+  end
+end

data/lib/affinity_propagation/version.rb

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

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: affinity_propagation
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shahbaz Javeed
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-09-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "\n    Affinity Propagation is a clustering algorithm that does not require
+  pre-specifying the number of clusters like\n    k-means and other similar algorithms
+  do.  This is a ruby implementation of the original version defined by Frey and\n
+  \   Dueck in http://www.psi.toronto.edu/affinitypropagation/FreyDueckScience07.pdf\n
+  \ "
+email:
+- sjaveed@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-gemset"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- affinity_propagation.gemspec
+- bin/console
+- bin/setup
+- lib/affinity_propagation.rb
+- lib/affinity_propagation/calculator.rb
+- lib/affinity_propagation/version.rb
+homepage: https://github.com/sjaveed/affinity_propagation
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: An implementation of the affinity propagation clustering algorithm by Frey
+  and Dueck
+test_files: []