ckmeans 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 72a2d84963628565eb94d962dc73aa1230f7af8c6948dc6713b0f9582d1bb401
+  data.tar.gz: ec3cb0c09eaaf38147d1a7dfd1f772b960905f336b801aade402d6f795329d27
+SHA512:
+  metadata.gz: ceb63e72327d2f3a00aee2c23c7ba8bd63f835d7b0132ce0785f9636b550a79ea4827eadfeb9a6d95c36e9b046ae5005325adeaf2cdd1689444d8f7af181bbc1
+  data.tar.gz: 0d7d7ca2c942ecb238c7d26cc601d64187ae97218bdd59aeb6ca067d11f08472725e6b3e8ca9021be88d63aa4ae45a5d629a5f8966a3731b7941aa6c0a205619

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,11 @@
+inherit_from: .rubocop_todo.yml
+
+AllCops:
+  TargetRubyVersion: 3.1
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.rubocop_todo.yml

@@ -0,0 +1,62 @@
+# This configuration was generated by
+# `rubocop --auto-gen-config`
+# on 2025-03-31 15:04:58 UTC using RuboCop version 1.75.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 7
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+Metrics/AbcSize:
+  Max: 95
+
+# Offense count: 3
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# AllowedMethods: refine
+Metrics/BlockLength:
+  Max: 112
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+# Offense count: 5
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+Metrics/MethodLength:
+  Max: 48
+
+# Offense count: 5
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 9
+
+# Offense count: 3
+# Configuration parameters: AllowedMethods, AllowedPatterns.
+Metrics/PerceivedComplexity:
+  Max: 13
+
+# Offense count: 13
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/ckmeans/clusterer.rb'
+
+# Offense count: 1
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+Naming/VariableNumber:
+  Exclude:
+    - 'lib/ckmeans/clusterer.rb'
+
+# Offense count: 6
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/ckmeans/clusterer.rb'

data/.ruby-version

@@ -0,0 +1 @@
+3.2.2

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+## [Unreleased]
+
+## [0.1.2] - 2025-03-31
+
+- https://github.com/vlebedeff/rb-ckmeans/pull/3
+
+## [0.1.1] - 2025-03-31
+
+- https://github.com/vlebedeff/rb-ckmeans/pull/2
+
+## [0.1.0] - 2025-03-31
+
+- Initial release

data/LICENSE

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

data/README.md

@@ -0,0 +1,33 @@
+# Ckmeans
+
+Repeatable unidimensional data clustering inspired by Ckmeans.1d.dp
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add ckmeans
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install ckmeans
+```
+
+## Usage
+
+```rb
+Ckmeans::Clusterer(data, kmin).clusters # fixed cluster count
+Ckmeans::Clusterer(data, kmin, kmax).clusters # estimate optimal cluster count within kmin and kmax
+Ckmeans::Clusterer(data, kmin, kmax, :sensitive).clusters # Adjust Bayesian Information Criteria favoring more smaller clusters
+```
+
+## License
+
+The gem is available as open source under the terms of the [LGPL v3 License](https://opensource.org/license/lgpl-3-0).
+
+## References
+
+- https://github.com/cran/Ckmeans.1d.dp

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/ckmeans/clusterer.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Ckmeans
+  class Clusterer # rubocop:disable Style/Documentation, Metrics/ClassLength
+    attr_reader :xcount, :xsorted, :kmin, :kmax, :smat, :jmat, :kestimate
+
+    PI_DOUBLE = Math::PI * 2
+
+    def initialize(entries, kmin, kmax = kmin, kestimate = :regular)
+      @xcount = entries.size
+
+      raise ArgumentError, "Minimum cluster count is bigger than element count" if kmin > @xcount
+      raise ArgumentError, "Maximum cluster count is bigger than element count" if kmax > @xcount
+
+      @kmin = kmin
+      @unique_xcount = entries.uniq.size
+      @kmax = [@unique_xcount, kmax].min
+      @xsorted = entries.sort
+      @kestimate = kestimate
+    end
+
+    def clusters
+      @clusters ||=
+        if @unique_xcount <= 1
+          [xsorted]
+        else
+          @smat = Array.new(kmax) { Array.new(xcount) { 0.0 } }
+          @jmat = Array.new(kmax) { Array.new(xcount) { 0 } }
+
+          kappa = kmax
+          n = xcount
+          xsum = Array.new(n)
+          xsumsq = Array.new(n)
+          shift = xsorted[n / 2]
+          xsum[0] = xsorted[0] - shift
+          xsumsq[0] = xsum[0]**2
+          1.upto(n - 1) do |i|
+            xsum[i] = xsum[i - 1] + xsorted[i] - shift
+            xsumsq[i] = xsumsq[i - 1] + ((xsorted[i] - shift) * (xsorted[i] - shift))
+            smat[0][i] = dissim(0, i, xsum, xsumsq)
+            jmat[0][i] = 0
+          end
+
+          kappa_dec = kappa - 1
+          1.upto(kappa_dec) do |q|
+            imin = q < kappa_dec ? [1, q].max : n - 1
+            fill_row(q, imin, n - 1, xsum, xsumsq)
+          end
+
+          kopt = koptimal
+
+          results = []
+          backtrack(kopt) do |q, left, right|
+            results[q] = xsorted[left..right]
+          end
+          results
+        end
+    end
+
+    private
+
+    def koptimal
+      kopt = kmin
+      n = xcount
+      max_bic = 0.0
+
+      # Deviation from BIC formula to favor smaller clusters
+      adjustment = kestimate == :sensitive ? 0.0 : 1.0
+
+      kmin.upto(kmax) do |k|
+        sizes = Array.new(k)
+        backtrack(k) { |q, left, right| sizes[q] = right - left + 1 }
+        index_left = 0
+        index_right = nil
+        loglikelihood = 0.0
+        bin_left = nil
+        bin_right = nil
+
+        k.times do |kb|
+          num_points_in_bin = sizes[kb]
+          index_right = index_left + num_points_in_bin - 1
+
+          if xsorted[index_left] < xsorted[index_right]
+            bin_left = xsorted[index_left]
+            bin_right = xsorted[index_right]
+          elsif xsorted[index_left] == xsorted[index_right]
+            bin_left = index_left == 0 ? xsorted[0] : (xsorted[index_left - 1] + xsorted[index_left]) / 2.0
+            bin_right = index_right < n - 1 ? (xsorted[index_right] + xsorted[index_right + 1]) / 2.0 : xsorted[n - 1]
+          else
+            raise "ERROR: binLeft > binRight"
+          end
+
+          bin_width = bin_right - bin_left
+
+          mean, variance = shifted_data_variance(index_left, index_right)
+
+          if variance > 0
+            (index_left..index_right).each do |i|
+              loglikelihood += -(xsorted[i] - mean) * (xsorted[i] - mean) / (2.0 * variance)
+            end
+            loglikelihood +=
+              num_points_in_bin *
+              ((Math.log(num_points_in_bin / n.to_f) * adjustment) - (0.5 * Math.log(PI_DOUBLE * variance)))
+          else
+            loglikelihood += num_points_in_bin * Math.log(1.0 / bin_width / n)
+          end
+
+          index_left = index_right + 1
+        end
+
+        bic = (2.0 * loglikelihood) - (((3 * k) - 1) * Math.log(n.to_f))
+
+        if k == kmin
+          max_bic = bic
+          kopt = kmin
+        elsif bic > max_bic
+          max_bic = bic
+          kopt = k
+        end
+      end
+
+      kopt
+    end
+
+    def shifted_data_variance(ileft, iright)
+      sum = 0.0
+      sumsq = 0.0
+      mean = 0.0
+      variance = 0.0
+      n = iright - ileft + 1
+
+      if iright >= ileft
+        median = xsorted[(ileft + iright) / 2]
+
+        ileft.upto(iright) do |i|
+          sumi = xsorted[i] - median
+          sum += sumi
+          sumsq += sumi**2
+        end
+
+        mean = (sum / n) + median
+        variance = (sumsq - (sum * sum / n)) / (n - 1) if n > 1
+      end
+
+      [mean, variance]
+    end
+
+    def backtrack(k)
+      n = jmat[0].size
+      right = n - 1
+      left = nil
+
+      (k - 1).downto(0) do |q|
+        left = jmat[q][right]
+
+        yield q, left, right
+
+        right = left - 1 if q > 0
+      end
+    end
+
+    def dissim(j, i, xsum, xsumsq)
+      return 0.0 if j >= i
+
+      sji =
+        if j > 0
+          segment_sum = xsum[i] - xsum[j - 1]
+          segment_size = i - j + 1
+          xsumsq[i] - xsumsq[j - 1] - (segment_sum * segment_sum / segment_size)
+        else
+          xsumsq[i] - (xsum[i] * xsum[i] / (i + 1))
+        end
+
+      [0, sji].max
+    end
+
+    def fill_row(q, imin, imax, xsum, xsumsq)
+      size = imax - q + 1
+
+      js = Array.new(size) { |i| q + i }
+      smawk(imin, imax, 1, q, js, xsum, xsumsq)
+    end
+
+    def smawk(imin, imax, istep, q, js, xsum, xsumsq)
+      if (imax - imin) <= (0 * istep)
+        find_min_from_candidates(q, imin, imax, istep, js, xsum, xsumsq)
+      else
+        js_odd = js_reduced(imin, imax, istep, q, js, xsum, xsumsq)
+        istepx2 = istep * 2
+        imin_odd = imin + istep
+        imax_odd = imin_odd + ((imax - imin_odd) / istepx2 * istepx2)
+        smawk(imin_odd, imax_odd, istepx2, q, js_odd, xsum, xsumsq)
+        fill_even_positions(imin, imax, istep, q, js, smat, jmat, xsum, xsumsq)
+      end
+    end
+
+    def find_min_from_candidates(q, imin, imax, istep, js, xsum, xsumsq)
+      rmin_prev = 0
+
+      (imin..imax).step(istep) do |i|
+        rmin = rmin_prev
+        smat[q][i] = smat[q - 1][js[rmin] - 1] + dissim(js[rmin], i, xsum, xsumsq)
+        jmat[q][i] = js[rmin]
+
+        ((rmin + 1)...js.size).each do |r|
+          jabs = js[r]
+
+          next if jabs < jmat[q - 1][i]
+          break if jabs > i
+
+          sj = smat[q - 1][jabs - 1] + dissim(jabs, i, xsum, xsumsq)
+
+          next unless sj <= smat[q][i]
+
+          smat[q][i] = sj
+          jmat[q][i] = js[r]
+          rmin_prev = r
+        end
+      end
+    end
+
+    def js_reduced(imin, imax, istep, q, js, xsum, xsumsq)
+      n = ((imax - imin) / istep) + 1
+      m = js.size
+
+      return js if n >= m
+
+      js_red = js.dup
+      left = -1
+      right = 0
+
+      while m > n
+        p = left + 1
+        i = imin + (p * istep)
+        j = js_red[right]
+        sl = smat[q - 1][j - 1] + dissim(j, i, xsum, xsumsq)
+        jplus1 = js_red[right + 1]
+        splus1 = smat[q - 1][jplus1 - 1] + dissim(jplus1, i, xsum, xsumsq)
+
+        if (sl < splus1) && (p < n - 1)
+          left += 1
+          js_red[left] = j
+          right += 1
+        elsif (sl < splus1) && (p == n - 1)
+          right += 1
+          js_red[right] = j
+          m -= 1
+        else
+          if p > 0
+            js_red[right] = js_red[left]
+            left -= 1
+          else
+            right += 1
+          end
+
+          m -= 1
+        end
+      end
+
+      ((left + 1)...m).each do |r|
+        js_red[r] = js_red[right]
+        right += 1
+      end
+
+      js_red.slice!(m..-1) if js_red.size > m
+      js_red
+    end
+
+    def fill_even_positions(imin, imax, istep, q, js, smat, jmat, xsum, xsumsq)
+      n = js.size
+      istepx2 = istep * 2
+      jl = js[0]
+
+      i = imin
+      r = 0
+      while i <= imax
+        r += 1 while js[r] < jl
+
+        smat[q][i] = smat[q - 1][js[r] - 1] + dissim(js[r], i, xsum, xsumsq)
+        jmat[q][i] = js[r]
+        jh         = ((i + istep) <= imax ? jmat[q][i + istep] : js[n - 1]).to_i
+        jmax       = [jh, i].min.to_i
+        sjimin     = dissim(jmax, i, xsum, xsumsq)
+
+        r += 1
+        while r < n && js[r] <= jmax
+          jabs = js[r]
+
+          break if jabs > i
+
+          if jabs < jmat[q - 1][i]
+            r += 1
+            next
+          end
+
+          s  = dissim(jabs, i, xsum, xsumsq)
+          sj = smat[q - 1][jabs - 1] + s
+
+          if sj <= smat[q][i]
+            smat[q][i] = sj
+            jmat[q][i] = js[r]
+          elsif smat[q - 1][jabs - 1] + sjimin > smat[q][i]
+            break
+          end
+
+          r += 1
+        end
+
+        r -= 1
+        jl = jh
+
+        i += istepx2
+      end
+    end
+  end
+end

data/lib/ckmeans/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ckmeans
+  VERSION = "0.1.2"
+end

data/lib/ckmeans.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "ckmeans/version"
+require_relative "ckmeans/clusterer"
+
+module Ckmeans
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/ckmeans.rbs

@@ -0,0 +1,4 @@
+module Ckmeans
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: ckmeans
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Vlad Lebedev
+bindir: exe
+cert_chain: []
+date: 2025-03-31 00:00:00.000000000 Z
+dependencies: []
+description: Repeatable clustering of unidimensional data
+email:
+- vladlebedeff@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".rubocop_todo.yml"
+- ".ruby-version"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/ckmeans.rb
+- lib/ckmeans/clusterer.rb
+- lib/ckmeans/version.rb
+- sig/ckmeans.rbs
+homepage: https://github.com/vlebedeff/rb-ckmeans
+licenses:
+- LGPL-3.0-only
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/vlebedeff/rb-ckmeans
+  source_code_uri: https://github.com/vlebedeff/rb-ckmeans
+  changelog_uri: https://github.com/vlebedeff/rb-ckmeans/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: Ruby implementation of Ckmeans.1d.dp
+test_files: []