vector_number 0.6.0 → 0.7.0

data/lib/vector_number/similarity.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+class VectorNumber
+  # @group Similarity measures
+
+  # Calculate cosine between this vector and +other+.
+  #
+  # Cosine can be used as a measure of similarity.
+  #
+  # @example
+  #   v = VectorNumber[2, "a"]
+  #   v.cosine(v) # => 1.0
+  #   v.cosine_similarity(1) # => 0.8944271909999159
+  #   v.cosine("b") # => 0.0
+  #   v.cosine_similarity(-v) # => -1.0
+  #   v.cosine(0) # ZeroDivisionError
+  #   VectorNumber[0].cosine(v) # ZeroDivisionError
+  #
+  # @see #angle
+  #
+  # @param other [VectorNumber, Any]
+  # @return [Numeric]
+  # @raise [ZeroDivisionError] if either +self+ or +other+ is a zero vector
+  #
+  # @since 0.7.0
+  def cosine(other)
+    has_direction?
+    return 1.0 if equal?(other)
+
+    other = new([other]) unless VectorNumber === other
+    has_direction?(other)
+    return 0.0 if (product = dot_product(other)).zero?
+
+    # Due to precision errors, the result might be slightly outside [-1, 1], so we clamp.
+    (product / magnitude / other.magnitude).clamp(-1.0, 1.0)
+  end
+
+  # @since 0.7.0
+  alias cosine_similarity cosine
+
+  # Calculate Jaccard index of similarity between this vector and +other+.
+  #
+  # This measure is binary: it considers only sets of non-zero dimensions in vectors,
+  # ignoring coefficients.
+  #
+  # @example
+  #   v = VectorNumber[2, "a"]
+  #   v.jaccard_index(v) # => (1/1)
+  #   v.jaccard_index(1) # => (1/2)
+  #   v.jaccard_index("b") # => (0/1)
+  #   v.jaccard_index(-v) # => (1/1)
+  #   v.jaccard_index(0) # => (0/1)
+  #   VectorNumber[0].jaccard_index(v) # => (0/1)
+  #   VectorNumber[0].jaccard_index(0) # ZeroDivisionError
+  #
+  # @see #jaccard_similarity
+  #
+  # @param other [VectorNumber, Any]
+  # @return [Rational]
+  # @raise [ZeroDivisionError] if both vectors are zero vectors
+  #
+  # @since 0.7.0
+  def jaccard_index(other)
+    other = new([other]) unless VectorNumber === other
+    intersection = units.intersection(other.units)
+    Rational(intersection.size, size + other.size - intersection.size)
+  end
+
+  # Calculate weighted Jaccard similarity index between this vector and +other+.
+  #
+  # This measure only makes sense for non-negative vectors.
+  #
+  # @example
+  #   v = VectorNumber[2, "a"]
+  #   v.jaccard_similarity(v) # => (1/1)
+  #   v.jaccard_similarity(1) # => (1/3)
+  #   v.jaccard_similarity("b") # => (0/1)
+  #   v.jaccard_similarity(-v) # => (-1/1)
+  #   v.jaccard_similarity(0) # => (0/1)
+  #   VectorNumber[0].jaccard_similarity(v) # => (0/1)
+  #   VectorNumber[0].jaccard_similarity(0) # ZeroDivisionError
+  #
+  # @see #jaccard_index
+  #
+  # @param other [VectorNumber, Any]
+  # @return [Rational]
+  # @raise [ZeroDivisionError] if both vectors are zero vectors
+  #
+  # @since 0.7.0
+  def jaccard_similarity(other)
+    other = new([other]) unless VectorNumber === other
+    Rational(
+      @data.sum { |u, c| [c, other[u]].min },
+      units.union(other.units).sum { |u| [self[u], other[u]].max }
+    )
+  end
+end

data/lib/vector_number/special_unit.rb

@@ -1,20 +1,22 @@
 # frozen_string_literal: true
 
 class VectorNumber
-  # Class for representing special units.
+  # Class for representing special (unique) units.
   #
-  # The public API consists of:
-  # - +#==+/+#eql?+/+#equal?+ (from +Object+)
-  # - +#hash+ (from +Object+)
-  # - {#to_s}
-  # - {#inspect}
+  # There usually isn't much point in using these, aside from {VectorNumber::NUMERIC_UNITS}.
+  # However, they can be helpful to denote units that aren't equal to any other object.
+  #
+  # +VectorNumber#to_s+ (and +inspect+) will use {#to_s} text instead of {#inspect} text
+  # for these units by default, without a multiplication operator. However, consider
+  # using customization of +VectorNumber#to_s+ instead if this is what you want.
   #
   # @since 0.6.0
   class SpecialUnit
-    # @api private
+    # Returns a new, unique unit, not equal to any other unit.
+    #
     # @param unit [#to_s] name for {#inspect}
     # @param text [String] text for {#to_s}
-    def initialize(unit, text)
+    def initialize(unit, text = unit.to_s)
       @unit = unit
       @text = text
     end
@@ -26,6 +28,16 @@ class VectorNumber
       @text
     end
 
+    # Support for PP, outputs the same text as {#inspect}.
+    #
+    # @param pp [PP]
+    # @return [void]
+    #
+    # @since 0.7.0
+    def pretty_print(pp)
+      pp.text(inspect)
+    end
+
     # Get string representation of the unit for debugging.
     #
     # @return [String]

data/lib/vector_number/stringifying.rb

@@ -15,29 +15,30 @@ class VectorNumber
 
   # @group Miscellaneous methods
 
-  # Return string representation of the vector.
+  # Return string representation of the vector suitable for output.
   #
   # An optional block can be supplied to provide customized substrings
   # for each unit and coefficient pair.
   # Care needs to be taken in handling +VectorNumber::R+ and +VectorNumber::I+ units.
-  # {.numeric_unit?} can be used to check if a particular unit needs special handling.
+  # {.numeric_unit?}/{.special_unit?} can be used to check if a particular unit
+  # requires different logic.
   #
   # @example
   #   VectorNumber[5, "s"].to_s # => "5 + 1⋅\"s\""
   #   VectorNumber["s", 5].to_s # => "1⋅\"s\" + 5"
   # @example with :mult argument
-  #   VectorNumber[5, :s].to_s(mult: :asterisk) # => "5 + 1*s"
-  #   (-VectorNumber[5, :s]).to_s(mult: "~~~") # => "-5 - 1~~~s"
+  #   VectorNumber[5, :s].to_s(mult: :asterisk) # => "5 + 1*:s"
+  #   (-VectorNumber[5, :s]).to_s(mult: "~~~") # => "-5 - 1~~~:s"
   # @example with a block
   #   VectorNumber[5, :s].to_s { |k, v| "#{format("%+.0f", v)}%#{k}" } # => "+5%1+1%s"
   #   VectorNumber[5, :s].to_s(mult: :cross) { |k, v, i, op|
-  #     "#{',' unless i.zero?}#{v}#{op+k.to_s unless k == VectorNumber::R}"
-  #   } # => "5,1×s"
+  #     "#{',' unless i.zero?}#{v}#{op+k.inspect unless k == VectorNumber::R}"
+  #   } # => "5,1×:s"
   #
   # @param mult [Symbol, String]
   #   text to use between coefficient and unit,
   #   can be one of the keys in {MULT_STRINGS} or an arbitrary string
-  # @yieldparam unit [Object]
+  # @yieldparam unit [Any]
   # @yieldparam coefficient [Numeric]
   # @yieldparam index [Integer]
   # @yieldparam operator [String]
@@ -46,27 +47,57 @@ class VectorNumber
   # @raise [ArgumentError]
   #   if +mult+ is not a String and is not in {MULT_STRINGS}'s keys
   def to_s(mult: :dot, &block)
-    if !mult.is_a?(String) && !MULT_STRINGS.key?(mult)
+    if !(String === mult) && !MULT_STRINGS.key?(mult)
       raise ArgumentError, "unknown key #{mult.inspect}", caller
     end
     return "0" if zero?
 
-    operator = mult.is_a?(String) ? mult : MULT_STRINGS[mult]
+    operator = (String === mult) ? mult : MULT_STRINGS[mult]
     build_string(operator, &block)
   end
 
-  # Return string representation of the vector.
+  # Return string representation of the vector suitable for display.
   #
-  # This is similar to +Complex#inspect+: it returns result of {#to_s} in round brackets.
+  # This is similar to +Complex#inspect+ — it returns result of {#to_s} in round brackets.
   #
   # @example
-  #   VectorNumber[5, :s].inspect # => "(5 + 1⋅s)"
+  #   VectorNumber[5, :s].inspect # => "(5 + 1⋅:s)"
   #
   # @return [String]
   #
   # @see to_s
   def inspect
-    "(#{self})"
+    return "(0)" if zero?
+
+    "(#{build_string("⋅")})"
+  end
+
+  # Support for PP, usually outputs the same text as {#inspect}.
+  #
+  # @param pp [PP]
+  # @return [void]
+  #
+  # @since 0.7.0
+  def pretty_print(pp) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
+    pp.text("(0)") and return if zero?
+
+    pp.group(1, "(", ")") do
+      # This should use `pp.fill_breakable`, but PrettyPrint::SingleLine haven't had it.
+      pp.seplist(@data, -> { fill_breakable(pp) }, :each_with_index) do |(unit, coefficient), i|
+        pp.text("-") if coefficient.negative?
+        unless i.zero?
+          pp.text("+") if coefficient.positive?
+          fill_breakable(pp)
+        end
+        pp.pp(coefficient.abs)
+        if SpecialUnit === unit
+          pp.text(unit.to_s)
+        else
+          pp.text("⋅")
+          pp.pp(unit)
+        end
+      end
+    end
   end
 
   private
@@ -90,16 +121,19 @@ class VectorNumber
     result
   end
 
-  # @param unit [Object]
+  # @param unit [Any]
   # @param coefficient [Numeric]
   # @param operator [String]
   # @return [String]
   def value_to_s(unit, coefficient, operator)
-    if NUMERIC_UNITS.include?(unit)
-      "#{coefficient}#{unit}"
+    if SpecialUnit === unit
+      "#{coefficient.inspect}#{unit}"
     else
-      unit = unit.inspect if unit.is_a?(String)
-      "#{coefficient}#{operator}#{unit}"
+      "#{coefficient.inspect}#{operator}#{unit.inspect}"
     end
   end
+
+  def fill_breakable(pp)
+    pp.group { pp.breakable }
+  end
 end