pyhs3 0.4.2

pure-Python HS3 implementation with tensors and autodiff

Hello World

This section shows two ways to build the same statistical model and evaluate it: using PyHS3 Python objects directly, and using HS3 JSON-like dictionaries.

Hello World (Python)

This is how you use the pyhs3 Python API to build a statistical model directly with objects:

>>> import pyhs3
>>> import scipy
>>> import math
>>> import numpy as np
>>> from pyhs3.distributions import GaussianDist
>>> from pyhs3.parameter_points import ParameterPoint, ParameterSet
>>> from pyhs3.axes import DomainAxis
>>> from pyhs3.domains import ProductDomain
>>> from pyhs3.metadata import Metadata
>>>
>>> # Create metadata
>>> metadata = Metadata(hs3_version="0.2")
>>>
>>> # Create a Gaussian distribution
>>> gaussian_dist = GaussianDist(name="model", x="x", mean="mu", sigma="sigma")
>>>
>>> # Create parameter points with values
>>> param_points = ParameterSet(
...     name="default_values",
...     parameters=[
...         ParameterPoint(name="x", value=0.0),
...         ParameterPoint(name="mu", value=0.0),
...         ParameterPoint(name="sigma", value=1.0),
...     ],
... )
>>>
>>> # Create domain with parameter bounds
>>> domain = ProductDomain(
...     name="default_domain",
...     axes=[
...         dict(name="x", min=-5.0, max=5.0),
...         dict(name="mu", min=-2.0, max=2.0),
...         dict(name="sigma", min=0.1, max=3.0),
...     ],
... )
>>>
>>> # Build workspace from objects
>>> ws = pyhs3.Workspace(
...     metadata=metadata,
...     distributions=[gaussian_dist],
...     parameter_points=[param_points],
...     domains=[domain],
... )
>>> model = ws.model(0)
<BLANKLINE>
>>> print(model)
Model(
    mode: FAST_RUN
    parameters: 3 (sigma, mu, x)
    distributions: 1 (model)
    functions: 0 ()
)
>>> parameters = {par.name: np.array(par.value) for par in model.parameterset}
>>> result = -2 * model.logpdf("model", **parameters)
>>> print(f"parameters: {parameters}")
parameters: {'x': array(0.), 'mu': array(0.), 'sigma': array(1.)}
>>> print(f"nll: {result:.8f}")
nll: 1.83787707
>>>
>>> # Serialize workspace back to dictionary for saving/sharing
>>> workspace_dict = ws.model_dump()
>>> print("Serialized workspace keys:", list(workspace_dict.keys()))
Serialized workspace keys: ['metadata', 'distributions', 'functions', 'domains', 'parameter_points', 'data', 'likelihoods', 'analyses', 'misc']

Hello World (HS3)

This is the same model built using HS3 JSON-like dictionary format:

>>> import pyhs3
>>> import scipy
>>> import math
>>> import numpy as np
>>> workspace_data = {
...     "metadata": {"hs3_version": "0.2"},
...     "distributions": [
...         {
...             "name": "model",
...             "type": "gaussian_dist",
...             "x": "x",
...             "mean": "mu",
...             "sigma": "sigma",
...         }
...     ],
...     "parameter_points": [
...         {
...             "name": "default_values",
...             "parameters": [
...                 {"name": "x", "value": 0.0},
...                 {"name": "mu", "value": 0.0},
...                 {"name": "sigma", "value": 1.0},
...             ],
...         }
...     ],
...     "domains": [
...         {
...             "name": "default_domain",
...             "type": "product_domain",
...             "axes": [
...                 {"name": "x", "min": -5.0, "max": 5.0},
...                 {"name": "mu", "min": -2.0, "max": 2.0},
...                 {"name": "sigma", "min": 0.1, "max": 3.0},
...             ],
...         }
...     ],
... }
>>> ws = pyhs3.Workspace(**workspace_data)
>>> model = ws.model(0)
<BLANKLINE>
>>> print(model)
Model(
    mode: FAST_RUN
    parameters: 3 (sigma, mu, x)
    distributions: 1 (model)
    functions: 0 ()
)
>>> parameters = {par.name: np.array(par.value) for par in model.parameterset}
>>> result = -2 * model.logpdf("model", **parameters)
>>> print(f"parameters: {parameters}")
parameters: {'x': array(0.), 'mu': array(0.), 'sigma': array(1.)}
>>> print(f"nll: {result:.8f}")
nll: 1.83787707
>>> result_scipy = -2 * math.log(scipy.stats.norm.pdf(0, loc=0, scale=1))
>>> print(f"nll: {result_scipy:.8f}")
nll: 1.83787707
>>>
>>> # Round-trip: serialize workspace back to dictionary
>>> serialized_dict = ws.model_dump()
>>> print("Round-trip successful:", serialized_dict["metadata"]["hs3_version"])
Round-trip successful: 0.2
>>>
>>> # Can recreate workspace from serialized dictionary
>>> ws_roundtrip = pyhs3.Workspace(**serialized_dict)
>>> model_roundtrip = ws_roundtrip.model(0)
<BLANKLINE>
>>> print("Round-trip model:", model_roundtrip.parameterset.name)
Round-trip model: default_values