dicey 0.15.0 → 0.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a269ac8baf4bf849781175b605d92c23ff95fae3e53baa540519ece9947cec0d
-  data.tar.gz: af8f74b92b35a2818d18dc91d9917d8af6e91e16f8674f02eebfb5e56b1759fd
+  metadata.gz: c18dbf421c9c19d438194ec9f63a9a22bfd18abb50d1f3b491a6e8067e3a04ae
+  data.tar.gz: e01eabaa58523f5fb2e1610ec671fc41a31f4aee7a583b64aa52d5bb9f083462
 SHA512:
-  metadata.gz: 1b031d4ee67b9c3b1ebe0ba23ac2289f7d14536af4fda1b98b7f481fd9e027ef3b57d8911f7d3c78ca46da0554b63226312e7ae4fa136fc34431bf7f86b7f349
-  data.tar.gz: ac52115c59f846e4662ed055e871bf31f2e87b2080acb07042730698d5fa6d107daaf64792645752b47bced701ace913b58464a7a96e56dffe6d3aba3a0af2d8
+  metadata.gz: 48759bc7919e8dbf699777a92735c586a8365f517c2c12d48cb725f12ada1fcfd6904e2c08e54ec7159267ad79003e7a1725a1e6e97694d7d4cbfb32198b2566
+  data.tar.gz: fa0cd4f20b6262cf927eb98cb5c296db2473910a27e2500323f80aeb5d2ac3224de143f67e0990fe555890535ff395d8514996934759984316d9fe22c4fb0e17

data/README.md

@@ -28,7 +28,8 @@ In seriousness, this program is mainly useful for calculating total frequency (p
 - [Usage: API](#usage-api)
   - [Dice](#dice)
   - [Rolling](#rolling)
-  - [Calculators](#calculators)
+  - [Distribution calculators](#distribution-calculators)
+  - [Distribution properties](#distribution-properties)
 - [Diving deeper](#diving-deeper)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -75,7 +76,6 @@ gem "dicey", "~> 0.14"
 
 **Dicey** is tested to work on CRuby 3.0+, latest JRuby and TruffleRuby. Compatible implementations should work too.
 - JSON and YAML formatting require `json` and `yaml`.
-- Decimal dice require `bigdecimal`.
 
 Otherwise, there are no direct dependencies.
 
@@ -111,13 +111,13 @@ If probability is preferred, there is an option for that:
 ```sh
 $ dicey 4 4 --result probabilities # or -r p for short
 # D4+D4
-2 => 0.0625
-3 => 0.125
-4 => 0.1875
-5 => 0.25
-6 => 0.1875
-7 => 0.125
-8 => 0.0625
+2 => 1/16
+3 => 1/8
+4 => 3/16
+5 => 1/4
+6 => 3/16
+7 => 1/8
+8 => 1/16
 ```
 
 This shows that 5 will probably be rolled a quarter of the time.
@@ -230,9 +230,9 @@ You have a sudden urge to roll dice while only having boring integer dice at hom
 
 Look no further than **roll** mode introduced in **Dicey** 0.12:
 ```sh
-$ dicey 0.5,1.5,2.5 4 --mode roll # As always, can be abbreviated to -m r
-# (0.5e0,0.15e1,0.25e1)+D4
-roll => 0.35e1 # You probably will get a different value here.
+$ dicey 0.5,1.0,1.5,2.0,2.5 4 --mode roll # As always, can be abbreviated to -m r
+# (1/2,1,3/2,2,5/2)+D4
+roll => 7/2 # You probably will get a different value here.
 ```
 
 > [!NOTE]
@@ -333,10 +333,10 @@ die.roll
 > [!NOTE]
 > 💡 Randomness source is *global*, shared between all dice and probably not thread-safe.
 
-### Calculators
+### Distribution calculators
 
-Frequency calculators live in `Dicey::SumFrequencyCalculators` module. There are four calculators currently:
-- `Dicey::SumFrequencyCalculators::KroneckerSubstitution` is the recommended calculator, able to handle all `Dicey::RegularDie`. It is very fast, calculating distribution for *100d6* in about 0.1 seconds on my laptop.
+Distribution calculators live in `Dicey::SumFrequencyCalculators` module. There are four calculators currently:
+- `Dicey::SumFrequencyCalculators::KroneckerSubstitution` is the recommended calculator, able to handle all `Dicey::RegularDie`. It is very fast, calculating distribution for *100d6* in about 0.1 seconds on a laptop.
 - `Dicey::SumFrequencyCalculators::MultinomialCoefficients` is specialized for repeated numeric dice, with performance only slightly worse. However, it is currently limited to dice with arithmetic sequences.
 - `Dicey::SumFrequencyCalculators::BruteForce` is the most generic and slowest one, but can in principle work with any dice. Currently, it is also limited to `Dicey::NumericDie`, as it's unclear how to handle other values.
 - `Dicey::SumFrequencyCalculators::Empirical`. This is more of a tool than a calculator. It can be interesting to play around with and see how practical results compare to theoretical ones.
@@ -345,7 +345,57 @@ Calculators inherit from `Dicey::SumFrequencyCalculators::BaseCalculator` and pr
 - `#call(dice, result_type: {:frequencies | :probabilities}, **options) : Hash`
 - `#valid_for?(dice) : Boolean`
 
-See [next section](#diving-deeper) for more details on limitations and complexity considerations.
+See [Diving deeper](#diving-deeper) for more details on limitations and complexity considerations.
+
+### Distribution properties
+
+While distribution itself is already enough in most cases (we are talking just dice here, after all). it may be of interest to calculate properties of it: mode, mean, expected value, standard deviation, etc. `Dicey::DistributionPropertiesCalculator` already provides this functionality:
+```rb
+Dicey::DistributionPropertiesCalculator.new.call(
+  Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
+    Dicey::RegularDie.from_count(2, 3)
+  )
+)
+  # => 
+  # {:mode=>[4],
+  # :min=>2,
+  # :max=>6,
+  # :total_range=>4,
+  # :mid_range=>4,
+  # :median=>4,
+  # :arithmetic_mean=>4,
+  # :expected_value=>4,
+  # :variance=>(4/3),
+  # :standard_deviation=>1.1547005383792515,
+  # :skewness=>0.0,
+  # :kurtosis=>(9/4),
+  # :excess_kurtosis=>(-3/4)}
+```
+
+Of course, for regular dice most properties are quite simple and predicatable due to symmetricity of distribution. It becomes more interesting with unfair, lopsided dice. Remember [Example 3](#example-3-custom-dice)?
+```rb
+Dicey::DistributionPropertiesCalculator.new.call(
+  Dicey::SumFrequencyCalculators::KroneckerSubstitution.new.call(
+    [Dicey::RegularDie.new(4), Dicey::NumericDie.new([1,3,4])]
+  )
+)
+  # => 
+  # {:mode=>[5],
+  # :min=>2,
+  # :max=>8,
+  # :total_range=>6,
+  # :mid_range=>5,
+  # :median=>5,
+  # :arithmetic_mean=>5,
+  # :expected_value=>(31/6),
+  # :variance=>(101/36),
+  # :standard_deviation=>1.674979270186815,
+  # :skewness=>-0.15762965389465178,
+  # :kurtosis=>(23145/10201),
+  # :excess_kurtosis=>(-7458/10201)}
+```
+
+This disitrubution is obviosuly skewed (as can be immediately seen from non-zero skewness), with expected value no longer equal to mean. This is a mild example. It is easily possible to create a distribution with multiple local maxima and high skewness.
 
 ## Diving deeper
 
@@ -416,7 +466,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/trinis
 - Tests cover the behavior and its interactions. 100% coverage *is not enough*, as it does not guarantee that all code paths are tested.
 - Documentation is up-to-date: generate it with `rake docs` and read it.
 - "*CHANGELOG.md*" lists the change if it has impact on users.
-- "*README.md*" is updated if the feature should be visible there, including the Kanban board.
+- "*README.md*" is updated if the feature should be visible there.
 
 ## License
 

data/lib/dicey/die_foundry.rb

@@ -3,9 +3,13 @@
 require_relative "numeric_die"
 require_relative "regular_die"
 
+require_relative "rational_to_integer"
+
 module Dicey
   # Helper class to define die definitions and automatically select the best one.
   class DieFoundry
+    include RationalToInteger
+
     # Regexp for matching a possible count.
     PREFIX = /(?>(?<count>[1-9]\d*+)?d)?+/i
 
@@ -17,7 +21,7 @@ module Dicey
       [/\A#{PREFIX}\(?(?<begin>-?\d++)(?>[-–—…]|\.{2,3})(?<end>-?\d++)\)?\z/, :range_mold].freeze,
       # List of numbers goes into the NumericDie mold.
       [/\A#{PREFIX}\(?(?<sides>-?\d++(?>,(?>-?\d++)?)+|,)\)?\z/, :weirdly_shaped_mold].freeze,
-      # Non-integers require arbitrary precision arithmetic, which is not enabled by default.
+      # Non-integers require special handling for precision.
       [/\A#{PREFIX}\(?(?<sides>-?\d++(?>\.\d++)?(?>,(?>-?\d++(?>\.\d++)?)?)+|,)\)?\z/,
        :weirdly_precise_mold].freeze,
       # Anything else is spilled on the floor.
@@ -30,7 +34,7 @@ module Dicey
     # - integer range (like "3-6" or "(-5..5)"), which produces a {NumericDie};
     # - list of integers (like "3,4,5", "(-1,0,1)", or "2,"), which produces a {NumericDie};
     # - list of decimal numbers (like "0.5,0.2,0.8" or "(2.0,)"), which produces a {NumericDie},
-    #   but uses +BigDecimal+ for values to maintain precise results.
+    #   but uses +Rational+ for values to maintain precise results.
     #
     # Any die definition can be prefixed with a count, like "2D6" or "1d1,3,5" to create an array.
     # A plain "d" without an explicit count is ignored instead, creating a single die.
@@ -69,9 +73,7 @@ module Dicey
     end
 
     def weirdly_precise_mold(definition)
-      require "bigdecimal" unless defined?(BigDecimal)
-
-      sides = definition[:sides].split(",").map { BigDecimal(_1) }
+      sides = definition[:sides].split(",").map { rational_to_integer(Rational(_1)) }
       build_dice(NumericDie, definition[:count], sides)
     end
 

data/lib/dicey/distribution_properties_calculator.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "rational_to_integer"
+
+module Dicey
+  # Calculates distribution properties,
+  # also known as descriptive statistics when applied to a population sample.
+  #
+  # These are well-known properties such as:
+  # - min, max, mid-range;
+  # - mode(s), median, arithmetic mean;
+  # - important moments (expected value, variance, skewness, kurtosis).
+  #
+  # It is notable that most dice create symmetric distributions,
+  # which means that skewness is 0, while properties denoting center in some way
+  # (median, mean, ...) are all equal.
+  # Mode is often not unique, but includes this center.
+  class DistributionPropertiesCalculator
+    include RationalToInteger
+
+    # Calculate properties for a given distribution.
+    #
+    # Depending on values in the distribution, some properties may be undefined.
+    # In such cases, only mode(s) are guaranteed to be present.
+    #
+    # On empty distribution, returns an empty hash.
+    #
+    # @param distribution [Hash{Numeric => Numeric}, Hash{Any => Numeric}]
+    #   distribution with pre-sorted keys
+    # @return [Hash{Symbol => Numeric, Array<Numeric>, Array<Array<Numeric>>}]
+    def call(distribution)
+      return {} if distribution.empty?
+
+      calculate_properties(distribution)
+    end
+
+    private
+
+    def calculate_properties(distribution)
+      outcomes = distribution.keys
+      weights = distribution.values
+
+      {
+        mode: mode(outcomes, weights),
+        modes: modes(distribution),
+        **range_characteristics(outcomes),
+        **median(outcomes),
+        **means(outcomes, weights),
+        **moments(distribution),
+      }
+    end
+
+    def mode(outcomes, weights)
+      max_weight = weights.max
+      outcomes.select.with_index { |_, index| weights[index] == max_weight }
+    end
+
+    def modes(distribution)
+      # Split into chunks with different weights,
+      # then select those with higher weights than their neighbors.
+      chunks = distribution.chunk_while { |(_, w_1), (_, w_2)| w_1 == w_2 }.to_a
+      return [chunks.first.map(&:first)] if chunks.size == 1
+
+      modes = []
+      add_local_mode(modes, nil, chunks[0], chunks[1])
+      chunks.each_cons(3).each do |chunk_before, chunk, chunk_after|
+        add_local_mode(modes, chunk_before, chunk, chunk_after)
+      end
+      add_local_mode(modes, chunks[-2], chunks[-1], nil)
+      modes
+    end
+
+    def add_local_mode(modes, chunk_before, chunk, chunk_after)
+      if (!chunk_before || chunk_before.first.last < chunk.first.last) &&
+         (!chunk_after || chunk_after.first.last < chunk.first.last)
+        modes << chunk.map(&:first)
+      end
+    end
+
+    def range_characteristics(outcomes)
+      min = outcomes.min
+      max = outcomes.max
+      {
+        min: min,
+        max: max,
+        range_length: max - min,
+        mid_range: rational_to_integer(Rational(min + max, 2)),
+      }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not comparable with each other, so a range can not be determined.
+      {}
+    end
+
+    def means(outcomes, _weights)
+      {
+        arithmetic_mean: rational_to_integer(Rational(outcomes.sum, outcomes.size)),
+      }
+    rescue ArgumentError, TypeError
+      # Outcomes are not summable with each other, means are meaningless.
+      {}
+    end
+
+    def median(outcomes)
+      outcomes = outcomes.sort
+      value =
+        if outcomes.size.odd?
+          outcomes[outcomes.size / 2]
+        else
+          Rational(outcomes[(outcomes.size / 2) - 1] + outcomes[outcomes.size / 2], 2)
+        end
+      { median: value }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not compatible with each other, so a median can not be determined.
+      {}
+    end
+
+    def moments(distribution)
+      total_weight = distribution.values.sum
+      expected_value = rational_to_integer(moment(distribution, total_weight, 1))
+      variance = rational_to_integer(moment(distribution, total_weight, 2) - (expected_value**2))
+      skewness =
+        rational_to_integer(moment(distribution, total_weight, 3, expected_value, variance))
+      kurtosis =
+        rational_to_integer(moment(distribution, total_weight, 4, expected_value, variance))
+
+      {
+        expected_value: expected_value,
+        variance: variance,
+        standard_deviation: Math.sqrt(variance),
+        skewness: skewness,
+        kurtosis: kurtosis,
+        excess_kurtosis: kurtosis ? kurtosis - 3 : nil,
+      }
+    rescue ArgumentError, TypeError, NoMethodError
+      # Outcomes are not compatible with each other, moments are fleeing.
+      {}
+    end
+
+    def moment(distribution, total_weight, degree, center = 0, variance = nil)
+      # With 0 variance, normalized moments are undefined.
+      return nil if variance == 0 # rubocop:disable Style/NumericPredicate
+
+      unnormalized = distribution.sum { |r, w| ((r - center)**degree) * Rational(w, total_weight) }
+      variance ? (unnormalized / (variance**(degree/2r))) : unnormalized
+    end
+  end
+end

data/lib/dicey/numeric_die.rb

@@ -9,8 +9,8 @@ module Dicey
     # @raise [DiceyError] if +sides_list+ contains non-numerical values or is empty
     def initialize(sides_list)
       if Range === sides_list
-        unless Numeric === sides_list.begin && Numeric === sides_list.end
-          raise DiceyError, "`#{sides_list.inspect}` is not a numerical range!"
+        unless Integer === sides_list.begin && Integer === sides_list.end
+          raise DiceyError, "`#{sides_list.inspect}` is not a valid range!"
         end
       else
         sides_list.each do |value|

data/lib/dicey/output_formatters/gnuplot_formatter.rb

@@ -5,8 +5,20 @@ require_relative "key_value_formatter"
 module Dicey
   module OutputFormatters
     # Formats a hash as a text file suitable for consumption by Gnuplot.
+    #
+    # Will transform Rational probabilities to Floats.
     class GnuplotFormatter < KeyValueFormatter
       SEPARATOR = " "
+
+      private
+
+      def transform(key, value)
+        [derationalize(key), derationalize(value)]
+      end
+
+      def derationalize(value)
+        value.is_a?(Rational) ? value.to_f : value
+      end
     end
   end
 end

data/lib/dicey/output_formatters/hash_formatter.rb

@@ -22,7 +22,10 @@ module Dicey
       private
 
       def to_primitive(value)
-        primitive?(value) ? value : value.to_s
+        return value if primitive?(value)
+        return value.to_f if Numeric === value
+
+        value.to_s
       end
 
       def primitive?(value)

data/lib/dicey/output_formatters/key_value_formatter.rb

@@ -1,20 +1,34 @@
 # frozen_string_literal: true
 
+require_relative "../rational_to_integer"
+
 module Dicey
   module OutputFormatters
     # Base formatter for outputting lists of key-value pairs separated by newlines.
     # Can add an optional description into the result.
     # @abstract
     class KeyValueFormatter
+      include RationalToInteger
+
       # @param hash [Hash{Object => Object}]
       # @param description [String] text to add as a comment.
       # @return [String]
       def call(hash, description = nil)
         initial_string = description ? "# #{description}\n" : +""
         hash.each_with_object(initial_string) do |(key, value), output|
-          output << "#{key}#{self.class::SEPARATOR}#{value}\n"
+          output << line(transform(key, value)) << "\n"
         end
       end
+
+      private
+
+      def transform(key, value)
+        [rational_to_integer(key), rational_to_integer(value)]
+      end
+
+      def line((key, value))
+        "#{key}#{self.class::SEPARATOR}#{value}"
+      end
     end
   end
 end

data/lib/dicey/rational_to_integer.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Dicey
+  # @api private
+  # Mix-in for converting rationals with denominator of 1 to integers.
+  module RationalToInteger
+    private
+
+    # Convert +value+ to +Integer+ if it's a +Rational+ with denominator of 1.
+    # Otherwise, return +value+ as-is.
+    #
+    # @value [Numeric, Any]
+    # @return [Numeric, Integer, Any]
+    def rational_to_integer(value)
+      (Rational === value && value.denominator == 1) ? value.numerator : value
+    end
+  end
+end

data/lib/dicey/roller.rb

@@ -2,9 +2,13 @@
 
 require_relative "die_foundry"
 
+require_relative "rational_to_integer"
+
 module Dicey
   # Let the dice roll!
   class Roller
+    include RationalToInteger
+
     # @param arguments [Array<String>] die definitions
     # @param format [#call] formatter for output
     # @return [nil]
@@ -15,7 +19,7 @@ module Dicey
       dice = arguments.flat_map { |definition| die_foundry.cast(definition) }
       result = dice.sum(&:roll)
 
-      format.call({ "roll" => result }, AbstractDie.describe(dice))
+      format.call({ "roll" => rational_to_integer(result) }, AbstractDie.describe(dice))
     end
 
     private

data/lib/dicey/sum_frequency_calculators/base_calculator.rb

@@ -5,6 +5,14 @@ module Dicey
   module SumFrequencyCalculators
     # Base frequencies calculator.
     #
+    # *Result types:*
+    # - +:frequencies+ (default)
+    # - +:probabilities+
+    #
+    # By default, returns frequencies as they are easier to calculate and
+    # can be represented with integers.
+    # Probabilities are calculated using +Rational+ numbers to return exact results.
+    #
     # *Options:*
     #
     # Calculators may have calculator-specific options,
@@ -20,7 +28,7 @@ module Dicey
       # @param dice [Enumerable<AbstractDie>]
       # @param result_type [Symbol] one of {RESULT_TYPES}
       # @param options [Hash{Symbol => Any}] calculator-specific options
-      # @return [Hash{Numeric => Numeric}] frequencies of each sum
+      # @return [Hash{Numeric => Numeric}] frequencies or probabilities for each outcome
       # @raise [DiceyError] if +result_type+ is invalid
       # @raise [DiceyError] if dice list is invalid for the calculator
       # @raise [DiceyError] if calculator returned obviously wrong results
@@ -92,7 +100,7 @@ module Dicey
           frequencies
         else
           total = frequencies.values.sum
-          frequencies.transform_values { _1.fdiv(total) }
+          frequencies.transform_values { Rational(_1, total) }
         end
       end
     end

data/lib/dicey/sum_frequency_calculators/empirical.rb

@@ -27,7 +27,7 @@ module Dicey
       def calculate(dice, rolls: N)
         statistics = rolls.times.with_object(Hash.new(0)) { |_, hash| hash[dice.sum(&:roll)] += 1 }
         total_results = dice.map(&:sides_num).reduce(:*)
-        statistics.transform_values { (_1 * total_results).fdiv(rolls) }
+        statistics.transform_values { Rational(_1 * total_results, rolls) }
       end
 
       def verify_result(*)

data/lib/dicey/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Dicey
-  VERSION = "0.15.0"
+  VERSION = "0.15.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dicey
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.15.2
 platform: ruby
 authors:
 - Alexandr Bulancov
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-22 00:00:00.000000000 Z
+date: 2025-10-08 00:00:00.000000000 Z
 dependencies: []
 description: |
   Dicey provides a CLI executable and a Ruby API for fast calculation of
@@ -35,6 +35,7 @@ files:
 - lib/dicey/cli/blender.rb
 - lib/dicey/cli/options.rb
 - lib/dicey/die_foundry.rb
+- lib/dicey/distribution_properties_calculator.rb
 - lib/dicey/numeric_die.rb
 - lib/dicey/output_formatters/gnuplot_formatter.rb
 - lib/dicey/output_formatters/hash_formatter.rb
@@ -42,6 +43,7 @@ files:
 - lib/dicey/output_formatters/key_value_formatter.rb
 - lib/dicey/output_formatters/list_formatter.rb
 - lib/dicey/output_formatters/yaml_formatter.rb
+- lib/dicey/rational_to_integer.rb
 - lib/dicey/regular_die.rb
 - lib/dicey/roller.rb
 - lib/dicey/sum_frequency_calculators/base_calculator.rb
@@ -58,9 +60,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/trinistr/dicey
   bug_tracker_uri: https://github.com/trinistr/dicey/issues
-  documentation_uri: https://rubydoc.info/gems/dicey/0.15.0
-  source_code_uri: https://github.com/trinistr/dicey/tree/v0.15.0
-  changelog_uri: https://github.com/trinistr/dicey/blob/v0.15.0/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/dicey/0.15.2
+  source_code_uri: https://github.com/trinistr/dicey/tree/v0.15.2
+  changelog_uri: https://github.com/trinistr/dicey/blob/v0.15.2/CHANGELOG.md
   rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: