Cathy facilitates modeling a weighted probability distribution from which one can draw a sample. Say you want to pick a realistic weather forecast and you know there's one sunny day for every two cloudy days and one rainy day for every two sunny days. Cathy will let you model this. But more importantly, Cathy will let you modify the probabilities on the fly (if you don't need an updatable distribution, I suggest you try pick_me_too, which is more efficient in this case).

require 'cathy'

# make a new distribution
cathy = Cathy.new

# teach cathy some things
10.times { cathy.add :foo }
5.times { cathy.add :bar }
2.times { cathy.add :plugh }

# ask cathy for a sample
10.times.map { cathy.pick } # => [:foo, :foo, :bar, :foo, :foo, :foo, :foo, :foo, :plugh, :foo]

# teach cathy more things!
20.times { cathy.add :plugh }

# another sample
10.times.map { cathy.pick } # => [:plugh, :plugh, :foo, :bar, :foo, :bar, :plugh, :plugh, :foo, :plugh]

Install the gem and add to the application's Gemfile by executing:

$ bundle add cathy

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install cathy

See here for an example.

Make an updatable probability distribution. In this state if you ask for a sample it will only give you nil.

Increase the frequency of thing by one.

Draw a sample from the distribution given the frequencies seen so far.

Returns a map from things to their frequencies.

This is basically a serialization method.

Build a distribution from a map from things to their frequencies.

This is basically a deserialization method.

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/cathy. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Cathy project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

My aim in writing this has been to be lean on memory usage and to use as few mathematical operations and fetches from memory as possible when picking things. The underlying data structure is a heap, which allows drawing a sample in sub-logarithmic time in the typical case using only integer subtraction, and comparison. Updating is similarly efficient.

Cathy is named after Chatty Cathy. Why? Because the only time I wanted to have this was when I made a chat bot for my kids to play with.

Also, naming is hard.

My wife Paula and son Jude have been exceedingly tolerant of my messing about with this silliness. Also, my co-workers at Green River have humored me.