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

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page