TangleDistribution API#

def __init__(
    self,
    distribution: str = "norm",
    params: Optional[Dict[str, float]] = None,
    bounds: Optional[Dict[str, Tuple[Optional[float], Optional[float]]]] = None,
    steps: Optional[Dict[str, float]] = None,
    pixels_per_step: int = 2,
    template: str = "{mean} ± {sd}",
    digits: Optional[int] = None,
    sync_throttle_ms: int = 100,
    **kwargs: Any,
) -> None:
    """Create an inline distribution control.

    Args:
        distribution: One of ``TangleDistribution.distributions``, see
            the table above.
        params: Starting parameters by scipy name; missing ones use the
            family default.
        bounds: Optional ``(low, high)`` per parameter; either end may be
            ``None``. Defaults: ``loc`` and randint's ``low``/``high`` are
            unbounded, a probability like ``p`` stays inside
            ``(step, 1 - step)``, binom's ``n`` is at least 1, and
            everything else stays positive with ``(step, None)``.
        steps: Change per drag step, per parameter. Defaults to 1 for whole
            numbers and otherwise a power of ten that suits the starting
            value.
        pixels_per_step: Drag distance per step (both directions).
        template: Inline text. ``{name}`` placeholders take any parameter
            of the family plus ``mean`` and ``sd`` (see ``template_fields``);
            add ``:.Nf`` (e.g. ``{mean:.0f}``) to override ``digits`` for
            that placeholder.
        digits: Default number of decimals in the inline text; defaults
            to what the smallest step and the starting sd need. Whole
            number parameters always show without decimals.
        sync_throttle_ms: Cap on how often ``live_params`` reaches Python
            while dragging, in milliseconds. ``0`` syncs every move.
        **kwargs: Forwarded to ``anywidget.AnyWidget``.
    """
    if distribution not in FAMILIES:
        raise ValueError(
            f"distribution={distribution!r} is not supported; pick one of {list(FAMILIES)}."
        )
    spec = FAMILIES[distribution]
    names = list(spec["params"])
    params, bounds, steps = dict(params or {}), dict(bounds or {}), dict(steps or {})
    for given in (params, bounds, steps):
        unknown = set(given) - set(names)
        if unknown:
            raise ValueError(
                f"{distribution!r} has parameters {names}; got unknown {sorted(unknown)}."
            )

    full_params, full_bounds, full_steps = {}, {}, {}
    for name in names:
        value = params.get(name, spec["params"][name])
        unbounded = name in spec.get("unbounded", [])
        if name in spec.get("integer", []):
            if value != int(value):
                raise ValueError(f"{name!r} must be a whole number, got {value}.")
            value = int(value)
            step = steps.get(name, 1)
            if step != int(step) or step < 1:
                raise ValueError(f"The step for {name!r} must be a whole number of at least 1.")
            step = int(step)
            low, high = bounds.get(name, (None, None) if unbounded else (1, None))
            if not unbounded and (low is None or low < 1):
                raise ValueError(f"The lower bound for {name!r} must be at least 1.")
        elif name in spec.get("probability", []):
            value = float(value)
            step = float(steps.get(name, _default_step(value)))
            low, high = bounds.get(name, (step, 1 - step))
            if low is None or high is None or low <= 0 or high >= 1:
                raise ValueError(f"The bounds for {name!r} must lie strictly between 0 and 1.")
        else:
            value = float(value)
            step = float(steps.get(name, _default_step(value)))
            low, high = bounds.get(name, (None, None) if unbounded else (step, None))
            if not unbounded and (low is None or low <= 0):
                raise ValueError(f"The lower bound for {name!r} must be positive.")
        if (low is not None and value < low) or (high is not None and value > high):
            raise ValueError(f"{name}={value} is outside the bounds ({low}, {high}).")
        full_params[name], full_bounds[name], full_steps[name] = value, [low, high], step

    if distribution == "randint" and full_params["low"] >= full_params["high"]:
        raise ValueError("randint needs low < high (high itself is excluded, as in scipy).")

    allowed = names + ["mean", "sd"]
    for _, field, fmt_spec, _ in string.Formatter().parse(template):
        if field is None:
            continue
        if field not in allowed:
            raise ValueError(
                f"Unknown placeholder {{{field}}} in template; {distribution!r} supports {allowed}."
            )
        if fmt_spec and not re.fullmatch(r"\.\d+f", fmt_spec):
            raise ValueError(f"Only '.Nf' precision is supported in the template, got {fmt_spec!r}.")

    if digits is None:
        # Enough decimals for the finest drag step, and for two significant
        # figures of the starting sd so "{mean} ± {sd}" never reads "0.3 ± 0.2".
        step_digits = max(-math.floor(math.log10(s)) for s in full_steps.values())
        sd = moments(distribution, full_params)[1]
        sd_digits = 1 - math.floor(math.log10(sd)) if sd > 0 else 0  # randint can have one value
        digits = max(0, step_digits, sd_digits)

    super().__init__(
        distribution=distribution,
        params=full_params,
        live_params=dict(full_params),
        bounds=full_bounds,
        steps=full_steps,
        pixels_per_step=pixels_per_step,
        template=template,
        digits=digits,
        sync_throttle_ms=sync_throttle_ms,
        **kwargs,
    )