Skip to main content

A WeightedCollection assigns probability weights per elements and returns elements randomly using those weights.

Project description

Weighted Collection

A WeightedCollection assigns probability weights per elements and returns elements randomly using those weights.

For example: if "anakin" has a weight of 1, "constantine" a weight of 1, and "xenophon" a weight of 2, then "xenophon" will be randomly selected 50% of the time, "anakin" 25% of the time, and "xenophon" 25% of the time.

Usage

from weighted_collection.weighted_collection import WeightedCollection

w = WeightedCollection(obj_type=str)

w.add("anakin", 1)
w.add("constantine", 1)
w.add("xenophon", 2)

# 25% of the time, this will return "anakin", 
# 25% of the time "constantine",
# 50% of the time "xenophon".
print(w.get())

Requirements

Python 3.6+

Installation

pip3 install weighted-collection

WeightedCollection API

WeightedCollection()

The constructor.

w = WeightedCollection() # Default constructor.
w = WeightedCollection(obj_type=str) # All elements in the collection must be strings.
w = WeightedCollection(random_seed=0)
w = WeightedCollection(obj_type=str, random_seed=0)
Parameter Type Description Optional Default
obj_type Type[T] The type of objects that can be added to the collection. object
random_seed int The random number generator seed. 0

add(obj, weight)

Try to add an object to the collection.

  • The object's type must be the class or a subclass of the obj_type parameter in the constructor.
  • The object must not already be in the collection.
  • The weight must be > 0.

Return: True if the object was added.

w = WeightedCollection(obj_type=str)

w.add("anakin", 1) # Adds element "anakin" with a weight of 1. Returns True.

w.add("anakin", 3) # Returns False (object is already in the collecction).

w.add(33, 1) # Returns False (wrong type).

w.add("constantine", -2) # Returns False (weight must be > 0).
Parameter Type Description Optional Default
obj T (the value of the obj_type parameter in the constructor) The object. Must not already be in the WeightedCollection.
weight int The probability weight. Must be > 0.

add_many(objs)

Try to add many objects to the collection.

Return: A dictionary of each object and whether it was added to the collection.

w = WeightedCollection(obj_type=str)

result = w.add_many({"anakin": 1, "constantine": 1, 33: 0, "xenophon": -1})

print(result) # {"anakin": True, "constantine": True, 33: False, "xenophon": False}
Parameter Type Description Optional Default
objs Dict[T, int](T is the value of the obj_type parameter in the constructor) A dictionary of objects. A dictionary of objects. Key = the object. Value = the probability weight.See add(obj, weight) for object and weight requirements.

remove(obj)

Remove an object from the collection.

Return: True if the object was removed.

w = WeightedCollection(obj_type=str)

w.add("anakin", 1)

w.remove("anakin") # Returns True.
w.remove("constantine") # Returns False.
Parameter Type Description Optional Default
obj T (the value of the obj_type parameter in the constructor) The object in the collection.

get()

Return: A randomly selected object using the probability weights per object.

w = WeightedCollection(obj_type=str)

w.add("anakin", 1)
w.add("constantine", 1)
w.add("xenophon", 2)

# 25% of the time, this will return "anakin", 
# 25% of the time "constantine",
# 50% of the time "xenophon".
print(w.get())

Project details


Release history Release notifications | RSS feed

This version

1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for weighted-collection, version 1
Filename, size File type Python version Upload date Hashes
Filename, size weighted_collection-1.tar.gz (3.6 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page