distparams 0.1.0__py3-none-any.whl

distparams/__init__.py

@@ -0,0 +1,72 @@
+"""distparams — single source of truth for distribution parameterizations."""
+
+from importlib.metadata import PackageNotFoundError
+
+from distparams._types import (
+    Bijection,
+    CanonicalParametrization,
+    Distribution,
+    MatrixSupport,
+    NamingConvention,
+    Parameter,
+    ParameterSet,
+    Support,
+)
+
+__all__ = [
+    "Bijection",
+    "CanonicalParametrization",
+    "Distribution",
+    "MatrixSupport",
+    "NamingConvention",
+    "Parameter",
+    "ParameterSet",
+    "Support",
+]
+
+from distparams import (
+    _distributions,  # noqa: F401  (registers built-ins)
+    random,
+    stats,
+)
+from distparams._converter import (
+    UnknownParameterError,
+    convert,
+    supported_ecosystems,
+)
+from distparams._decorator import distribution, resolve_parameters
+from distparams._plugins import (
+    register_distribution_ops,
+    register_ecosystem_mapping,
+    register_ecosystem_vocabulary,
+    register_parameter_alias,
+    register_parameter_set,
+)
+from distparams._registry import get_distribution, list_distributions, register_distribution
+from distparams.random import Random
+
+__all__ += [
+    "Random",
+    "UnknownParameterError",
+    "convert",
+    "distribution",
+    "get_distribution",
+    "list_distributions",
+    "random",
+    "register_distribution",
+    "register_distribution_ops",
+    "register_ecosystem_mapping",
+    "register_ecosystem_vocabulary",
+    "register_parameter_alias",
+    "register_parameter_set",
+    "resolve_parameters",
+    "stats",
+    "supported_ecosystems",
+]
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("distparams")
+except PackageNotFoundError:  # pragma: no cover — running from source without install
+    __version__ = "0.0.0"

distparams/_converter.py

@@ -0,0 +1,557 @@
+"""Cross-ecosystem parameter conversion."""
+
+from __future__ import annotations
+
+import difflib
+from typing import Any
+
+from distparams._registry import get_distribution
+from distparams._vocabularies import rows_for_parametrization, vocabulary_for
+
+
+class UnknownParameterError(ValueError):
+    """Raised when a parameter name is not known to the distribution."""
+
+
+class ParameterConflictError(ValueError):
+    """Raised when two parameter names map to the same canonical parameter."""
+
+
+def convert(
+    distribution_name: str,
+    source_ecosystem: str,
+    target_ecosystem: str,
+    *,
+    partial: bool = False,
+    **params: Any,
+) -> dict[str, Any]:
+    """Convert parameters from one ecosystem's naming to another.
+
+    Conversions flow *source params → canonical parameters → target params*.
+    Source param names map to canonical parameters via the source ecosystem's
+    naming convention; values are normalized to the canonical value (through
+    parameter bijections or set-level transforms) and then emitted under
+    the target ecosystem's names.
+
+    With ``partial=True``, source params resolve independently — no complete
+    parameterization is required, and only supplied parameters are emitted. Used
+    by the decorator so callables can fill the rest from their own defaults.
+    Derived parameterization targets (``"group:..."``) are not supported in
+    partial mode, since their values depend on multiple canonical parameters.
+
+    Args:
+        distribution_name: name of the distribution (e.g. "gamma")
+        source_ecosystem: source ecosystem (e.g. "scipy")
+        target_ecosystem: target ecosystem (e.g. "pymc")
+        partial: resolve supplied params only (defaults: False)
+        **params: parameters in source ecosystem's naming
+
+    Returns:
+        Parameters in target ecosystem's naming.
+
+    Example:
+        >>> convert("gamma", "scipy", "pymc", a=2, scale=3)
+        {"alpha": 2, "beta": 0.333}
+    """
+    if partial and target_ecosystem.startswith("group:"):
+        raise ValueError(
+            "Partial conversion does not support derived parameterization targets "
+            f"('{target_ecosystem}'): their values depend on multiple canonical "
+            "parameters."
+        )
+    dist = get_distribution(distribution_name)
+
+    # Source: param names → canonical parameters via the source ecosystem.
+    source_map = _find_source_convention(dist, source_ecosystem, set(params.keys()))
+    source_transforms: dict[str, str] = {}
+
+    if source_map is not None:
+        source_map, source_transforms = _resolve_convention(dist, source_map)
+
+    if source_map is None:
+        # No naming convention — try to find a matching parameter set with transforms.
+        source_set = _find_set_with_transforms(dist, set(params.keys()))
+        if source_set is not None:
+            source_map = {p: p for p in params}
+        else:
+            # Try alias fallback (registered parameter aliases).
+            source_map = _alias_fallback(dist, set(params.keys()))
+            if source_map is None and source_ecosystem == "any":
+                # "any" source: also try matching against all conventions.
+                source_map = _try_all_conventions(dist, set(params.keys()))
+                if source_map is not None:
+                    source_map, source_transforms = _resolve_convention(dist, source_map)
+            if source_map is None and partial:
+                # Partial mode: resolve each name independently — no
+                # completeness requirement (defaults fill the rest).
+                source_map = _per_name_resolution(dist, set(params.keys()))
+                if source_map is None:
+                    incomplete = _incomplete_set_message(dist, set(params.keys()))
+                    if incomplete is not None:
+                        raise ValueError(incomplete)
+            if source_map is None:
+                raise _source_error(dist, source_ecosystem, set(params.keys()))
+
+    # Check for conflicts (multiple params mapping to the same canonical parameter).
+    seen: dict[str, str] = {}
+    for param_name, canonical_name in source_map.items():
+        if canonical_name in seen:
+            raise ParameterConflictError(
+                f"Conflict: '{param_name}' and '{seen[canonical_name]}' "
+                f"both map to parameter '{canonical_name}'"
+            )
+        seen[canonical_name] = param_name
+
+    # Check for set-level transforms on the source side. A convention may
+    # target a derived parameterization (e.g. R's size/mu for negative
+    # binomial): its names map *into* the set's transform keys, so the set
+    # can also be found through the mapped canonical names.
+    source_set = _find_set_with_transforms(dist, set(source_map.keys()))
+    if source_set is None:
+        source_set = _find_set_with_transforms(dist, set(source_map.values()))
+
+    if source_set is not None and source_set.param_transforms is not None:
+        # Use set-level transforms (cross-parameter derived parameterization).
+        # Values are keyed by transform key, whether the raw names *are* the
+        # keys (pymc mu/alpha) or map onto them (R size/mu).
+        source_values = {canonical: params[raw] for raw, canonical in source_map.items()}
+        canonical: dict[str, Any] = {}
+        for name, (to_fn, _from_fn, target_param) in source_set.param_transforms.items():
+            if name in source_values:
+                canonical[target_param] = to_fn(source_values)
+        # Add parameters without set transforms.
+        for name in source_set.parameters:
+            if name not in canonical:
+                param_name = _source_name_for_param(name, source_map)
+                if param_name is not None:
+                    canonical[name] = _apply_to_canonical(dist, name, param_name, params[param_name])
+    else:
+        # Standard path: parameter-level bijections.
+        canonical = {}
+        for param_name, value in params.items():
+            canonical_name = source_map[param_name]
+            transform = source_transforms.get(param_name, param_name)
+            canonical[canonical_name] = _apply_to_canonical(dist, canonical_name, transform, value)
+
+    # Target: canonical parameters → param names via the target ecosystem.
+    # Special targets: "canonical" emits canonical names directly;
+    # "canonical:<names>" emits the listed canonical names;
+    # "group:<names>" uses set-level transforms to emit the set's param names;
+    # "params:<names>" emits under known parameter names via their bijections.
+    target_map: dict[str, tuple[str, str]] | None = None
+    target_set = None
+
+    if target_ecosystem == "canonical":
+        # Emit canonical parameter names directly.
+        target_map = {r: (r, r) for r in canonical}
+    elif target_ecosystem.startswith("canonical:"):
+        # "canonical:mu,sigma" — emit the listed canonical names in order.
+        requested = target_ecosystem.split(":", 1)[1].split(",")
+        target_map = {r: (r, r) for r in requested if r in canonical}
+    elif target_ecosystem.startswith("params:"):
+        # "params:loc,scale" — emit under these known parameter names,
+        # applying each name's own bijection (e.g. tau = sigma**-2).
+        requested = target_ecosystem.split(":", 1)[1].split(",")
+        full = _full_lookup(dist)
+        target_map = {}
+        for name in requested:
+            canonical_param = full.get(name)
+            if canonical_param is not None:
+                target_map[canonical_param] = (name, name)
+    elif target_ecosystem.startswith("group:"):
+        # "group:mu,sigma" — use set-level transforms.
+        requested = target_ecosystem.split(":", 1)[1].split(",")
+        target_set = _find_set_with_transforms(dist, set(requested))
+        if target_set is not None:
+            target_map = {}
+            for name, (_to_fn, _from_fn, target_param) in target_set.param_transforms.items():
+                if name in requested:
+                    target_map[target_param] = (name, name)
+    else:
+        target_convention = _find_target_convention(dist, target_ecosystem, set(canonical.keys()))
+        if target_convention is not None:
+            roles, transforms = _resolve_convention(dist, target_convention)
+            target_map = {role: (p, transforms[p]) for p, role in roles.items()}
+        else:
+            # No naming convention — try a matching parameter set with transforms.
+            target_set = _find_set_with_transforms_for_params(dist, set(canonical.keys()))
+            if target_set is not None:
+                target_map = {}
+                for pn, (_to_fn, _from_fn, target_param) in target_set.param_transforms.items():
+                    target_map[target_param] = (pn, pn)
+
+    if target_map is None:
+        raise ValueError(
+            f"No naming convention found for ecosystem '{target_ecosystem}' with "
+            f"params {sorted(canonical.keys())}. "
+            f"{_available_conventions(dist, target_ecosystem)}"
+        )
+
+    result: dict[str, Any] = {}
+    skipped: set[str] = set()
+    if target_set is not None and target_set.param_transforms is not None:
+        # Use set-level transforms for target.
+        for canonical_name, value in canonical.items():
+            emitted = target_map.get(canonical_name)
+            if emitted is None:
+                skipped.add(canonical_name)
+                continue
+            param_name, transform = emitted
+            if param_name in target_set.param_transforms:
+                _to_fn, from_fn, _target_param = target_set.param_transforms[param_name]
+                result[param_name] = from_fn(canonical)
+            else:
+                result[param_name] = _apply_from_canonical(dist, canonical_name, transform, value)
+    else:
+        # Standard path: parameter-level bijections.
+        for canonical_name, value in canonical.items():
+            emitted = target_map.get(canonical_name)
+            if emitted is None:
+                skipped.add(canonical_name)
+                continue
+            param_name, transform = emitted
+            result[param_name] = _apply_from_canonical(dist, canonical_name, transform, value)
+
+    if partial and skipped:
+        # Partial mode must never silently drop a supplied parameter.
+        raise ValueError(
+            f"Resolved parameter(s) {sorted(skipped)} cannot be passed to target '{target_ecosystem}'"
+        )
+
+    return result
+
+
+def supported_ecosystems(dist) -> set[str]:
+    """Ecosystems with naming data for this distribution.
+
+    Union of the per-distribution convention ecosystems and every vocabulary
+    row registered for the distribution's canonical parametrization.
+    """
+    eco = {nc.ecosystem for nc in dist.naming_conventions}
+    eco.update(ecosystem for ecosystem, _row in rows_for_parametrization(dist.canonical.name))
+    return eco
+
+
+def _ecosystem_mappings(dist, ecosystem: str) -> list[tuple[str, dict[str, str]]]:
+    """All ``(parametrization, mapping)`` pairs for an ecosystem.
+
+    Per-distribution :class:`NamingConvention` overrides come first and take
+    precedence; the ecosystem's vocabulary row for the distribution's
+    canonical parametrization (if any) follows.
+    """
+    mappings = [
+        (
+            nc.parametrization or dist.canonical.name,
+            {p: r for p, r in nc.mapping.items() if r is not None},
+        )
+        for nc in dist.naming_conventions
+        if nc.ecosystem == ecosystem
+    ]
+    row = vocabulary_for(ecosystem, dist.canonical.name)
+    if row is not None:
+        mappings.append((dist.canonical.name, {p: r for p, r in row.items() if r is not None}))
+    return mappings
+
+
+def _find_source_convention(dist, ecosystem: str, param_names: set[str]):
+    """Find an ecosystem mapping whose param names match exactly."""
+    for _pz, mapped in _ecosystem_mappings(dist, ecosystem):
+        if set(mapped) == param_names:
+            return mapped
+    return None
+
+
+def _find_target_convention(dist, ecosystem: str, canonical_names: set[str]):
+    """Find an ecosystem mapping that covers every canonical parameter to emit."""
+    for _pz, mapped in _ecosystem_mappings(dist, ecosystem):
+        roles, _transforms = _resolve_convention(dist, mapped)
+        if canonical_names <= set(roles.values()):
+            return mapped
+    return None
+
+
+def _find_set_with_transforms(dist, param_names: set[str]):
+    """Find a parameter set whose param names match and which has transforms."""
+    for ps in dist.canonical.parameter_sets:
+        if ps.param_transforms is None:
+            continue
+        if param_names == set(ps.param_transforms.keys()):
+            return ps
+    return None
+
+
+def _find_set_with_transforms_for_params(dist, canonical_names: set[str]):
+    """Find a parameter set with transforms whose target parameters match."""
+    for ps in dist.canonical.parameter_sets:
+        if ps.param_transforms is None:
+            continue
+        target_params = {r for _, _, r in ps.param_transforms.values()}
+        if canonical_names <= target_params:
+            return ps
+    return None
+
+
+def _known_param_names(dist) -> set[str]:
+    """All parameter names the registry knows for this distribution.
+
+    Includes canonical parameters, their bijections, naming-convention parameter
+    names, vocabulary-row parameter names, and set-transform keys (e.g.
+    "mean" or "mu" for beta). Convention entries mapped to None are
+    deliberately not distribution parameters and are excluded, so they fall
+    through to context-parameter handling.
+    """
+    names: set[str] = set()
+    for name, parameter in dist.canonical.parameters.items():
+        names.add(name)
+        names.update(parameter.bijections)
+    for nc in dist.naming_conventions:
+        names.update(p for p, r in nc.mapping.items() if r is not None)
+    for _eco, row in rows_for_parametrization(dist.canonical.name):
+        names.update(p for p, r in row.items() if r is not None)
+    for ps in dist.canonical.parameter_sets:
+        if ps.param_transforms is not None:
+            names.update(ps.param_transforms)
+    return names
+
+
+def _known_params_grouped(dist) -> list[list[str]]:
+    """Group every known parameter name by the canonical parameter it resolves to.
+
+    Each group reads as ``(canonical or alias or convention-name ...)``: the
+    canonical name first, then its bijections, then convention/vocabulary names
+    mapping to it. Set-transform keys (derived parameterizations such as
+    gamma's ``mu``/``sigma``) resolve as a set rather than per parameter, so
+    they form a trailing group.
+    """
+    groups: list[list[str]] = []
+    shown: set[str] = set()
+    for name, parameter in dist.canonical.parameters.items():
+        group = [name]
+        shown.add(name)
+        for alias in parameter.bijections:
+            if alias not in shown:
+                group.append(alias)
+                shown.add(alias)
+        for nc in dist.naming_conventions:
+            for param, r in nc.mapping.items():
+                if r == name and param not in shown:
+                    group.append(param)
+                    shown.add(param)
+        for _eco, row in rows_for_parametrization(dist.canonical.name):
+            for param, r in row.items():
+                if r == name and param not in shown:
+                    group.append(param)
+                    shown.add(param)
+        groups.append(group)
+    extras: list[str] = []
+    for ps in dist.canonical.parameter_sets:
+        if ps.param_transforms is not None:
+            for key in ps.param_transforms:
+                if key not in shown:
+                    extras.append(key)
+                    shown.add(key)
+    if extras:
+        groups.append(extras)
+    return groups
+
+
+def _unknown_parameter_error(dist, param_names: set[str]) -> UnknownParameterError:
+    """Build a helpful unknown-parameter error.
+
+    Names the distribution, shows every known parameter grouped by canonical
+    parameter as ``(canonical or alias ...)`` clauses, and suggests the
+    closest known name when one is sufficiently similar.
+    """
+    unknown = sorted(param_names)
+    groups = _known_params_grouped(dist)
+    msg = f"Unknown parameter '{unknown[0]}' for distribution '{dist.name}'."
+    if len(unknown) > 1:
+        msg += f" Also unknown: {', '.join(repr(u) for u in unknown[1:])}."
+    if groups:
+        known = " and ".join("(" + " or ".join(group) + ")" for group in groups)
+        msg += f" Known parameters: {known}."
+    matches = difflib.get_close_matches(unknown[0], [name for group in groups for name in group])
+    if matches:
+        msg += f" Did you mean '{matches[0]}'?"
+    return UnknownParameterError(msg)
+
+
+def _alias_fallback(dist, param_names: set[str]) -> dict[str, str] | None:
+    """Resolve param names through parameter bijections when no convention matches.
+
+    Only accepts parameter sets whose resolved names form a complete valid
+    parameter set, so partial parameterizations are rejected rather than
+    silently converted.
+    """
+    lookup = _alias_lookup(dist)
+    if not param_names <= set(lookup):
+        return None
+    resolved = {lookup[p] for p in param_names}
+    valid_sets = {ps.parameters for ps in dist.canonical.parameter_sets}
+    if resolved not in valid_sets:
+        return None
+    return {p: lookup[p] for p in param_names}
+
+
+def _source_name_for_param(canonical_name: str, mapping: dict[str, str]) -> str | None:
+    """Find the source param name that maps to a given canonical parameter."""
+    for param, name in mapping.items():
+        if name == canonical_name:
+            return param
+    return None
+
+
+def _resolve_convention(dist, mapped: dict[str, str]) -> tuple[dict[str, str], dict[str, str]]:
+    """Resolve a convention mapping to canonical roles and transform names.
+
+    A mapping value may name a *bijection* rather than the canonical
+    parameter (e.g. the stdlib random module's gamma ``beta`` is a scale):
+    the role then resolves through that bijection and the value transform
+    uses it. Otherwise the role is the value itself and the transform comes
+    from the ecosystem name's own bijection (identity when none registered),
+    which is how every pre-existing mapping behaves.
+
+    Returns ``(roles, transforms)`` keyed by the ecosystem's parameter name.
+    """
+    full = _full_lookup(dist)
+    roles: dict[str, str] = {}
+    transforms: dict[str, str] = {}
+    for eco_name, value in mapped.items():
+        param = value if value in dist.canonical.parameters else full.get(value)
+        if (
+            param is not None
+            and param != value
+            and param in dist.canonical.parameters
+            and dist.canonical.parameters[param].bijections.get(value) is not None
+        ):
+            roles[eco_name] = param
+            transforms[eco_name] = value
+        else:
+            roles[eco_name] = value
+            transforms[eco_name] = eco_name
+    return roles, transforms
+
+
+def _apply_to_canonical(dist, canonical_name: str, param_name: str, value: Any) -> Any:
+    """Convert a source ecosystem's value to the canonical parameter value."""
+    parameter = dist.canonical.parameters[canonical_name]
+    bijection = parameter.bijections.get(param_name)
+    if bijection is not None and bijection.to_canonical is not None:
+        return bijection.to_canonical(value)
+    return value
+
+
+def _apply_from_canonical(dist, canonical_name: str, param_name: str, value: Any) -> Any:
+    """Convert a canonical parameter value to a target ecosystem's value."""
+    parameter = dist.canonical.parameters[canonical_name]
+    bijection = parameter.bijections.get(param_name)
+    if bijection is not None and bijection.from_canonical is not None:
+        return bijection.from_canonical(value)
+    return value
+
+
+def _available_conventions(dist, ecosystem: str) -> str:
+    mappings = _ecosystem_mappings(dist, ecosystem)
+    if not mappings:
+        return f"No conventions for ecosystem '{ecosystem}'."
+    details = []
+    for pz, mapped in mappings:
+        details.append(f"  {pz}: {sorted(mapped)}")
+    return f"Available for '{ecosystem}':\n" + "\n".join(details)
+
+
+def _try_all_conventions(dist, param_names: set[str]) -> dict[str, str] | None:
+    """For 'any' source: try matching param names against all ecosystems.
+
+    Considers per-distribution overrides first, then vocabulary rows for the
+    distribution's parametrization across all ecosystems.
+    """
+    for ecosystem in dict.fromkeys(nc.ecosystem for nc in dist.naming_conventions):
+        for _pz, mapped in _ecosystem_mappings(dist, ecosystem):
+            if set(mapped) == param_names:
+                return mapped
+    for _eco, row in rows_for_parametrization(dist.canonical.name):
+        mapped = {p: r for p, r in row.items() if r is not None}
+        if set(mapped) == param_names:
+            return mapped
+    return None
+
+
+def _alias_lookup(dist) -> dict[str, str]:
+    """Param name → canonical parameter via canonical names and bijections.
+
+    Canonical names are registered first so a parameter always resolves to
+    itself, even when another parameter lists that name as a bijection (e.g.
+    hypergeometric's ``K`` alias ``n`` vs the ``n`` parameter).
+    """
+    lookup: dict[str, str] = {}
+    for name in dist.canonical.parameters:
+        lookup.setdefault(name, name)
+    for name, parameter in dist.canonical.parameters.items():
+        for alias in parameter.bijections:
+            lookup.setdefault(alias, name)
+    return lookup
+
+
+def _full_lookup(dist) -> dict[str, str]:
+    """``_alias_lookup`` extended with convention and vocabulary names."""
+    lookup = _alias_lookup(dist)
+    for nc in dist.naming_conventions:
+        for p, r in nc.mapping.items():
+            if r is not None:
+                lookup.setdefault(p, r)
+    for _eco, row in rows_for_parametrization(dist.canonical.name):
+        for p, r in row.items():
+            if r is not None:
+                lookup.setdefault(p, r)
+    return lookup
+
+
+def _per_name_resolution(dist, param_names: set[str]) -> dict[str, str] | None:
+    """Resolve each param name independently to a canonical parameter (partial mode).
+
+    Looks across parameters, bijections, and all naming conventions. Set-transform
+    keys are deliberately excluded — their values depend on multiple canonical
+    parameters, so they only resolve through a complete set match.
+    """
+    lookup = _full_lookup(dist)
+    if not param_names <= set(lookup):
+        return None
+    return {p: lookup[p] for p in param_names}
+
+
+def _incomplete_set_message(dist, param_names: set[str]) -> str | None:
+    """Helpful error when params are a strict subset of a set's transform keys.
+
+    Surfaces the set's ``name``/``description`` when present, so the error
+    explains the parameterization instead of only listing its members.
+    """
+    for ps in dist.canonical.parameter_sets:
+        if ps.param_transforms is None:
+            continue
+        keys = set(ps.param_transforms.keys())
+        if param_names and param_names < keys:
+            msg = (
+                f"Parameter(s) {sorted(param_names)} belong to the "
+                f"({', '.join(sorted(keys))}) parameterization — supply all of "
+                f"{sorted(keys)} for it to resolve."
+            )
+            if ps.description:
+                prefix = f"{ps.name}: " if ps.name else ""
+                msg += f" {prefix}{ps.description}"
+            return msg
+    return None
+
+
+def _source_error(dist, ecosystem: str, param_names: set[str]) -> Exception:
+    """Build a helpful error for source resolution failure."""
+    # Check which params are unknown (not in any alias/convention/vocab).
+    lookup = _full_lookup(dist)
+    unknown = param_names - set(lookup)
+    if unknown:
+        return _unknown_parameter_error(dist, unknown)
+    return ValueError(
+        f"No naming convention found for ecosystem '{ecosystem}' with "
+        f"params {sorted(param_names)}. "
+        f"{_available_conventions(dist, ecosystem)}"
+    )