Skip to content

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:

[project.entry-points."hani2.ufun_views"]
seasonal = "my_package.views"

Entry points are loaded the first time preferences are shown. A failing entry point only produces a warning.