Showing other kinds of preferences¶
The Preferences tool (and the admin-only Opponent Preferences tool) explains how a negotiator values every possible deal. Scenarios can describe preferences in many ways, so HANI2 picks a view that fits the type of the utility function and falls back to a general view for anything it does not know.
Every view shows the value on disagreement (what you get if no agreement is reached) and a short, plain-language explanation of how the total is worked out.
Supported types¶
| Utility function | What is shown |
|---|---|
LinearAdditiveUtilityFunction, LinearUtilityAggregationFunction |
Issue weights (donut), the value of each option of the selected issue, the starting amount if not zero |
LinearUtilityFunction, AffineUtilityFunction |
Signed weight per numeric issue, the formula, the starting amount |
GLAUtilityFunction |
Weight of each factor; for the selected factor its value function, or a heatmap for two small discrete issues |
PAUtilityFunction, GPAUtilityFunction |
Table of polynomial terms (coefficient and product of factors) and the value functions |
NonLinearAggregationUtilityFunction |
Value of each option per issue, best deals, a note on the custom rule |
HyperRectangleUtilityFunction, NonlinearHyperRectangleUtilityFunction |
Table of regions with their ranges, values and weights |
WeightedUtilityFunction |
Donut of the parts' weights and a collapsible, nested view of every part |
ComplexNonlinearUtilityFunction |
Collapsible, nested view of every part |
ExpDiscountedUFun, LinDiscountedUFun |
The time-pressure parameters and the view of the underlying preferences |
RankOnlyUtilityFunction |
Deals from best to worst |
ConstUtilityFunction |
The single value of every deal |
Probabilistic ones (IPUtilityFunction, ProbMappingUtilityFunction, ...) |
Deals ranked by expected value |
MappingUtilityFunction and anything else |
Table of the best deals and a histogram of values |
Spaces with more than 5000 possible deals are sampled, and the view says so. Nesting is limited to three levels; deeper parts use the general view. A view that fails never breaks the tool: it falls back to the general view.
Registering a custom view¶
A view is a function that takes a context and returns a list of
UI components. Register it for a class with the
register_ufun_view decorator. The most specific class in the utility
function's MRO wins; priority breaks ties for the same class.
from hani2.tools import ui
from hani2.tools.ufun_views import register_ufun_view
from my_package import SeasonalUtility
@register_ufun_view(SeasonalUtility)
def seasonal_view(ctx):
u = ctx.ufun
season, select = ctx.choose("season", u.seasons, "Season") # widget name unique when nested
return [
ctx.layout(
ui.text_block("Deals are worth more in the high season."),
right=ui.card(select, title=f"{ctx.title_prefix}Value by season"),
),
*ctx.explain("Your total depends on the **season** of the deal."),
]
ctx gives you the tool (ctx.tool), the utility function (ctx.ufun),
ctx.title_prefix (for example "Opponent "), ctx.issues,
ctx.issue_names, ctx.key() / ctx.value() for widget names and values, and
ctx.child(ufun, label) for nested views (render them with
render_ufun_view(ctx.tool, sub, ctx=ctx.child(sub, "part1"))). The value on
disagreement is added automatically; ctx.layout(...) places it for you.
The module hani2.tools.ufun_views also offers helpers such as
ranking_components(ctx) (the general view) and sample_outcomes(ufun).
From a package: entry point¶
Packages can ship views without any change to HANI2. Declare an entry point in
the hani2.ufun_views group that points to a module that registers its views
when imported, or to a function that does the registering:
Entry points are loaded the first time preferences are shown. A failing entry point only produces a warning.