prefopt package

Submodules

prefopt.data module

Preference data.

class prefopt.data.PreferenceDict(init_dict=None, **kwargs)

Bases: collections.abc.MutableMapping

Dict for preference data.

The key is assumed to be a tuple (r, c) where r and c are tuples that represent preference items and the value is a preference relation (positive if r is preferred over c, negative is c is preferred over r, and zero if they are equivalent).

What makes this the PreferenceDict special is the fact that the value v corresponding to a key (r, c) can also be looked up using (c, r) as the key; in that case, the preference relation will be negated, i.e., -v will be returned.

>>> from prefopt.data import PreferenceDict
>>> d = PreferenceDict()
>>> a, b = (0, 1, 2), (3, 4, 5)
>>> d[a, b] = 1
>>> d[b, a] == -1
True
>>> e, f = (9, 9), (1, 1)
>>> d[e, f] = -1
>>> d[f, e] == 1
True
>>> len(d) == 2
True
>>> sorted(d.preferences())
[(0, 1, 2), (1, 1), (3, 4, 5), (9, 9)]
preferences()

Get set of preference items.

class prefopt.data.UniformPreferenceDict(key_length, **kwargs)

Bases: prefopt.data.PreferenceDict

PreferenceDict that enforces uniform key length.

>>> from prefopt.data import UniformPreferenceDict
>>> UniformPreferenceDict("foo")
Traceback (most recent call last):
    ...
ValueError: key length needs to be positive integer
>>> UniformPreferenceDict(-1)
Traceback (most recent call last):
    ...
ValueError: key length needs to be positive integer
>>> d = UniformPreferenceDict(3)
>>> a, b = (0, 1, 2), (3, 4, 5)
>>> d[a, b] = 1
>>> d[b, a] == -1
True
>>> e = (9, 9)
>>> d[a, e] = -1
Traceback (most recent call last):
    ...
ValueError: invalid key length

prefopt.experiment module

Active preference learning experiment.

class prefopt.experiment.InputPresenter

Bases: object

Presenter interface for the user input of an experiment.

get_choice(a, b)

Present the user with a pair of items and return their choice.

Parameters:

a : tuple

Query point.

b : tuple

Comparison point.
Returns:

choice : int

The user preference for the choice a vs. b. Possible values are: 1 (a preferred over b); 0 (a is equivalent to b); -1 (b preferred over a).
class prefopt.experiment.OutputPresenter

Bases: object

Presenter interface for the output of an experiment.

present(i, xn, xb, choice)

Present the output of a single iteration of the experiment.

Parameters:

i : int

The current iteration.

xn : tuple

The new query point.

xb : tuple

The incumbent against which the new query point is compared.

choice : int

The user preference for the choice xn vs. xb.
present_valuations(valuations)

Present the current valuations of the model.

Parameters:

valuations : iterable

Iterable of (item, valuation) tuples.
class prefopt.experiment.PreferenceExperiment(acquirer, input_presenter, output_presenter, seed_data=None)

Bases: object

Active preference learning experiment.

Parameters:

acquirer : PreferenceAcquirer

Acquirer object that is capable of finding new query points based on the optimization of some acquisition function.

input_presenter : InputPresenter

Presenter object that is capable of presenting a choice to the user and returning their preference.

output_presenter : OutputPresenter

Presenter object that is capable of presenting the output of an iteration of the experiment.

Attributes

iteration (int) The current iteration, starting from zero.
monitor()

Monitor the current valuations of the model.

run()

Run one iteration of the preference experiment.

prefopt.experiment.create_acquirer(acquisition_strategy, model, optimizer, bounds)
prefopt.experiment.to_classname(name, suffix='')

prefopt.utility module

Utility functions.

class prefopt.utility.BoundingBox(bounds)

Bases: collections.abc.Sequence

sample()
class prefopt.utility.NegativeAbsoluteValueUtilityFunction(bounds)

Bases: prefopt.utility.UtilityFunction

Negative-absolute-value utility function.

argmax

Argmax of function on domain.

bounds

Bounding box of function domain.

evaluate(x)

Evaluate utility function.

Parameters:

x : numpy.array

Point at which to evaluate the function.
Returns:

fx : float

The utility at point x.
Raises:

ValueError

If the point x is outside of the specified bounds.
class prefopt.utility.NegativeQuadraticUtilityFunction(bounds)

Bases: prefopt.utility.UtilityFunction

Negative-quadratic utility function.

argmax

Argmax of function on domain.

bounds

Bounding box of function domain.

evaluate(x)

Evaluate utility function.

Parameters:

x : numpy.array

Point at which to evaluate the function.
Returns:

fx : float

The utility at point x.
Raises:

ValueError

If the point x is outside of the specified bounds.

Module contents