framework-py 0.1.0.dev25__py3-none-any.whl → 0.1.0.dev26__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
framework/_artifacts.py CHANGED
@@ -278,6 +278,8 @@ def as_frame(source: Any) -> pd.DataFrame | None:
278
278
  name = "value" if source.name is None or source.name == "" else str(source.name)
279
279
  return source.to_frame(name)
280
280
  if isinstance(source, np.ndarray):
281
+ if _axes_array(source):
282
+ return None
281
283
  return _numpy_frame(source)
282
284
  if _has_class(source, "polars", "DataFrame", "Series"):
283
285
  if _has_class(source, "polars", "Series"):
@@ -709,11 +711,14 @@ class _Design:
709
711
  self.predictors.append(name)
710
712
  return next(iter(used)) if len(used) == 1 else None
711
713
 
712
- def match(self, names: Sequence[str], factors: Sequence[Sequence[_Part]]) -> None:
714
+ def match(
715
+ self, names: Sequence[str], factors: Sequence[Sequence[_Part]], prefix: str = ""
716
+ ) -> None:
713
717
  """Map each design column to the parts whose names join to its name."""
714
718
  candidates: dict[str, tuple[_Part, ...]] = {}
715
719
  for combination in itertools.product(*factors):
716
- candidates.setdefault(":".join(part.name for part in combination), combination)
720
+ name = prefix + ":".join(part.name for part in combination)
721
+ candidates.setdefault(name, combination)
717
722
  for name in names:
718
723
  parts = candidates.get(name)
719
724
  if parts is None or not all(part.mappable for part in parts):
@@ -1308,11 +1313,51 @@ def _structured(source: Any) -> dict[str, Any] | None:
1308
1313
  return _test_document(source)
1309
1314
  if _from(source, "statsmodels"):
1310
1315
  raise FrameworkError("This statsmodels result does not expose coefficient statistics.")
1316
+ return _bayesian_document(source)
1317
+
1318
+
1319
+ def _bayesian_document(source: Any) -> dict[str, Any] | None:
1320
+ from framework import _bayesian
1321
+
1322
+ if isinstance(source, _bayesian.BambiFit):
1323
+ return _bayesian.bambi_document(source)
1324
+ if _bayesian.is_posterior(source):
1325
+ return _bayesian.posterior_document(source)
1326
+ if _bayesian.is_bambi_model(source):
1327
+ raise FrameworkError(
1328
+ "Publish the InferenceData that fit() returned, with the model: "
1329
+ "publish(idata, model=model)."
1330
+ )
1311
1331
  return None
1312
1332
 
1313
1333
 
1334
+ def _axes_array(source: Any) -> bool:
1335
+ """Whether an array holds matplotlib Axes, as ArviZ 0.x multi-panel plots return."""
1336
+ return (
1337
+ isinstance(source, np.ndarray)
1338
+ and source.dtype == object
1339
+ and source.size > 0
1340
+ and all(_from(item, "matplotlib") for item in source.flat)
1341
+ )
1342
+
1343
+
1344
+ def _plot_collection(source: Any) -> Any:
1345
+ """Return the backend figure an ArviZ 1.x PlotCollection draws on, or the source."""
1346
+ if not _has_class(source, "arviz_plots", "PlotCollection"):
1347
+ return source
1348
+ try:
1349
+ figure = source.get_viz("figure")
1350
+ except Exception:
1351
+ return source
1352
+ if hasattr(figure, "item") and getattr(figure, "ndim", 1) == 0:
1353
+ figure = figure.item()
1354
+ return source if figure is None else figure
1355
+
1356
+
1314
1357
  def _figure(source: Any) -> Any:
1315
1358
  """Return the matplotlib Figure behind an Axes, Figure, or seaborn grid."""
1359
+ if _axes_array(source):
1360
+ source = next(iter(source.flat))
1316
1361
  figure = source
1317
1362
  for _ in range(3):
1318
1363
  if callable(getattr(figure, "savefig", None)):
@@ -1322,6 +1367,8 @@ def _figure(source: Any) -> Any:
1322
1367
 
1323
1368
 
1324
1369
  def is_figure(source: Any) -> bool:
1370
+ if _axes_array(source):
1371
+ return True
1325
1372
  return _from(source, "matplotlib", "seaborn") and _figure(source) is not None
1326
1373
 
1327
1374
 
@@ -1365,6 +1412,7 @@ def _styler_html(source: Any, directory: Path) -> Path:
1365
1412
 
1366
1413
  def rendered(source: Any, directory: Path, cloud: bool) -> Path | None:
1367
1414
  """Write figures, formatted tables, and charts to their file formats, or return None."""
1415
+ source = _plot_collection(source)
1368
1416
  exporters: list[tuple[Callable[[Any], bool], Callable[[Any, Path], Path]]] = [
1369
1417
  (is_figure, lambda s, d: save_figure(s, d, svg=cloud)),
1370
1418
  (lambda s: _has_class(s, "pandas", "Styler"), _styler_html),
framework/_bayesian.py ADDED
@@ -0,0 +1,608 @@
1
+ """Posterior summaries for models fit by sampling.
2
+
3
+ A sampled model publishes as a ``model`` representation with ``model.inference`` set
4
+ to ``"bayesian"``. Each parameter is summarized over its draws: posterior mean and SD,
5
+ an equal-tailed credible interval, R-hat, and bulk and tail effective sample sizes.
6
+ The draws themselves, the observed data, and any per-observation quantities stay out.
7
+
8
+ Two sources are supported: an ArviZ ``InferenceData`` (or the ``xarray.DataTree`` that
9
+ ArviZ 1.x uses) on its own, summarized variable by variable, and the same object with the
10
+ Bambi model that produced it, which adds the family, formula, priors, and variables.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import contextlib
16
+ import importlib
17
+ import itertools
18
+ import warnings
19
+ from collections.abc import Iterator, Sequence
20
+ from typing import Any
21
+
22
+ import numpy as np
23
+ import pandas as pd
24
+
25
+ from framework._artifacts import (
26
+ CONFIDENCE_LEVEL,
27
+ _classes,
28
+ _coding,
29
+ _description,
30
+ _Design,
31
+ _document,
32
+ _from,
33
+ _has_class,
34
+ _labels,
35
+ _metrics,
36
+ _Part,
37
+ _position,
38
+ _referenced,
39
+ _variable,
40
+ _variables_fields,
41
+ table,
42
+ )
43
+ from framework.errors import FrameworkError
44
+
45
+ SAMPLE_DIMS = ("chain", "draw")
46
+ ELEMENT_LIMIT = 100
47
+ ROW_LIMIT = 1000
48
+ _INTERCEPT = "(Intercept)"
49
+ _LIBRARIES = {
50
+ "pymc": "PyMC",
51
+ "numpyro": "NumPyro",
52
+ "cmdstanpy": "Stan",
53
+ "pystan": "Stan",
54
+ "stan": "Stan",
55
+ "nutpie": "nutpie",
56
+ "blackjax": "BlackJAX",
57
+ "pyro": "Pyro",
58
+ }
59
+ _NUTS_STATS = ("tree_depth", "n_steps", "step_size", "depth", "treedepth")
60
+ _SUMMARY_COLUMNS = (
61
+ "estimate",
62
+ "std_error",
63
+ "conf_low",
64
+ "conf_high",
65
+ "rhat",
66
+ "ess_bulk",
67
+ "ess_tail",
68
+ )
69
+
70
+
71
+ class BambiFit:
72
+ """A Bambi model with the InferenceData its ``fit()`` returned."""
73
+
74
+ def __init__(self, posterior: Any, model: Any) -> None:
75
+ self.posterior = posterior
76
+ self.model = model
77
+
78
+
79
+ def with_model(source: Any, model: Any) -> BambiFit:
80
+ """Pair a posterior with the model that produced it, for ``publish(model=...)``."""
81
+ if not _has_class(model, "bambi", "Model"):
82
+ raise FrameworkError(
83
+ f"publish(model=...) accepts a Bambi model, not {type(model).__name__}."
84
+ )
85
+ if not is_posterior(source):
86
+ raise FrameworkError(
87
+ "publish(source, model=...) needs the InferenceData that the model's fit() "
88
+ f"returned, not {type(source).__name__}."
89
+ )
90
+ return BambiFit(source, model)
91
+
92
+
93
+ # --------------------------------------------------------------------------- posterior access
94
+
95
+
96
+ def _group(data: Any, name: str) -> Any:
97
+ """Return one group of an InferenceData or DataTree as an xarray Dataset, or None."""
98
+ children = getattr(data, "children", None)
99
+ if children is not None:
100
+ node = children.get(name)
101
+ return None if node is None else node.to_dataset()
102
+ groups = getattr(data, "groups", None)
103
+ if callable(groups) and name in groups():
104
+ return getattr(data, name)
105
+ return None
106
+
107
+
108
+ def is_posterior(source: Any) -> bool:
109
+ """Whether the object is an InferenceData or DataTree with sampled posterior draws."""
110
+ if not (
111
+ _has_class(source, "arviz", "InferenceData") or _has_class(source, "xarray", "DataTree")
112
+ ):
113
+ return False
114
+ with contextlib.suppress(Exception):
115
+ posterior = _group(source, "posterior")
116
+ return posterior is not None and all(d in posterior.dims for d in SAMPLE_DIMS)
117
+ return False
118
+
119
+
120
+ def _elements(array: Any) -> Iterator[tuple[str, dict[str, int]]]:
121
+ """Yield each scalar element's label suffix (``[a, b]``) and its position by dimension."""
122
+ dims = [d for d in array.dims if d not in SAMPLE_DIMS]
123
+ for position in itertools.product(*(range(array.sizes[d]) for d in dims)):
124
+ selection = dict(zip(dims, position, strict=True))
125
+ labels = [
126
+ str(array[d].values[i]) if d in array.coords else str(i) for d, i in selection.items()
127
+ ]
128
+ yield ("[" + ", ".join(labels) + "]" if labels else ""), selection
129
+
130
+
131
+ def _diagnostics(posterior: Any, names: Sequence[str]) -> tuple[Any, Any, Any]:
132
+ """R-hat and bulk and tail ESS for these variables, or Nones without ArviZ."""
133
+ for module in ("arviz_stats", "arviz"):
134
+ try:
135
+ library = importlib.import_module(module)
136
+ except ImportError:
137
+ continue
138
+ rhat, ess = library.rhat, library.ess
139
+ break
140
+ else:
141
+ return None, None, None
142
+ subset = posterior[list(names)]
143
+ results: list[Any] = []
144
+ for function, method in ((rhat, "rank"), (ess, "bulk"), (ess, "tail")):
145
+ with warnings.catch_warnings():
146
+ # Short chains warn; the numbers still describe the draws published.
147
+ warnings.simplefilter("ignore")
148
+ try:
149
+ results.append(function(subset, method=method))
150
+ except Exception:
151
+ results.append(None)
152
+ return results[0], results[1], results[2]
153
+
154
+
155
+ def _value(result: Any, name: str, selection: dict[str, int]) -> float | None:
156
+ if result is None or name not in result:
157
+ return None
158
+ try:
159
+ value = float(result[name].isel(selection).values)
160
+ except (TypeError, ValueError, IndexError, KeyError):
161
+ return None
162
+ return value if np.isfinite(value) else None
163
+
164
+
165
+ def _summarize(draws: np.ndarray[Any, Any]) -> list[float]:
166
+ low, high = (1 - CONFIDENCE_LEVEL) / 2, (1 + CONFIDENCE_LEVEL) / 2
167
+ q_low, q_high = np.quantile(draws, [low, high])
168
+ sd = float(draws.std(ddof=1)) if draws.size > 1 else float("nan")
169
+ return [float(draws.mean()), sd, float(q_low), float(q_high)]
170
+
171
+
172
+ def _rows(
173
+ posterior: Any,
174
+ variables: Sequence[tuple[str, str]],
175
+ ratio: set[str] | None = None,
176
+ group: dict[str, str] | None = None,
177
+ ) -> pd.DataFrame:
178
+ """Summarize each element of each (variable, term) pair; one row per element.
179
+
180
+ ``ratio`` names the variables whose rows also get summaries of the exponentiated
181
+ draws. ``group`` names a grouping factor per variable for group-level tables.
182
+ """
183
+ names = [name for name, _ in variables]
184
+ rhat, bulk, tail = _diagnostics(posterior, names)
185
+ rows = []
186
+ for name, term in variables:
187
+ array = posterior[name]
188
+ for suffix, selection in _elements(array):
189
+ draws = np.asarray(
190
+ array.isel(selection).transpose(*SAMPLE_DIMS).values, dtype="float64"
191
+ ).ravel()
192
+ row: dict[str, Any] = {}
193
+ if group is not None:
194
+ row["group"] = group.get(name)
195
+ row["term"] = term + suffix
196
+ row |= dict(zip(_SUMMARY_COLUMNS[:4], _summarize(draws), strict=True))
197
+ row |= {
198
+ "rhat": _value(rhat, name, selection),
199
+ "ess_bulk": _value(bulk, name, selection),
200
+ "ess_tail": _value(tail, name, selection),
201
+ }
202
+ if ratio is not None:
203
+ values = _summarize(np.exp(draws)) if name in ratio else [None, None, None, None]
204
+ row |= dict(
205
+ zip(
206
+ ("ratio_estimate", "ratio_std_error", "ratio_conf_low", "ratio_conf_high"),
207
+ values,
208
+ strict=True,
209
+ )
210
+ )
211
+ rows.append(row)
212
+ frame = pd.DataFrame(rows)
213
+ for column in ("rhat", "ess_bulk", "ess_tail"):
214
+ if column in frame and frame[column].isna().all():
215
+ frame = frame.drop(columns=column)
216
+ return frame
217
+
218
+
219
+ def _observed_dims(data: Any) -> set[str]:
220
+ dims: set[str] = set()
221
+ for name in ("observed_data", "constant_data", "predictions_constant_data"):
222
+ group = _group(data, name)
223
+ if group is not None:
224
+ dims |= {str(d) for d in group.dims}
225
+ return dims
226
+
227
+
228
+ def _nobs(data: Any) -> int | None:
229
+ observed = _group(data, "observed_data")
230
+ if observed is None or len(observed.data_vars) != 1:
231
+ return None
232
+ array = next(iter(observed.data_vars.values()))
233
+ return int(array.shape[0]) if array.ndim else None
234
+
235
+
236
+ def _sampling_metrics(data: Any, posterior: Any) -> list[dict[str, Any]]:
237
+ chains, draws = int(posterior.sizes["chain"]), int(posterior.sizes["draw"])
238
+ attrs = dict(getattr(posterior, "attrs", {}) or {})
239
+ warmup = attrs.get("tuning_steps")
240
+ if warmup is None:
241
+ warm = _group(data, "warmup_posterior")
242
+ warmup = warm.sizes.get("draw") if warm is not None else None
243
+ stats = _group(data, "sample_stats")
244
+ sampler = divergent = treedepth = None
245
+ if stats is not None:
246
+ if "diverging" in stats:
247
+ divergent = int(np.asarray(stats["diverging"].values, dtype=bool).sum())
248
+ if "reached_max_treedepth" in stats:
249
+ treedepth = int(np.asarray(stats["reached_max_treedepth"].values, dtype=bool).sum())
250
+ library = _LIBRARIES.get(str(attrs.get("inference_library", "")).lower())
251
+ if library and "diverging" in stats and any(s in stats for s in _NUTS_STATS):
252
+ sampler = f"NUTS ({library})"
253
+ return _metrics(
254
+ [
255
+ ("chains", chains),
256
+ ("draws", chains * draws),
257
+ ("warmup", int(warmup) if isinstance(warmup, (int, np.integer)) else None),
258
+ ("sampler", sampler),
259
+ ("divergent_transitions", divergent),
260
+ ("max_treedepth_hits", treedepth),
261
+ ]
262
+ )
263
+
264
+
265
+ def _interval_metrics() -> list[dict[str, Any]]:
266
+ return [
267
+ {"name": "confidence_level", "value": CONFIDENCE_LEVEL},
268
+ {"name": "interval_method", "value": "Equal-tailed"},
269
+ ]
270
+
271
+
272
+ def _with_classes(document: dict[str, Any], *sources: Any) -> dict[str, Any]:
273
+ document["source"]["class"] = [
274
+ f"{module}.{name}"
275
+ for source in sources
276
+ for module, name in _classes(source)
277
+ if module.split(".")[0] not in ("builtins", "collections", "typing")
278
+ ]
279
+ return document
280
+
281
+
282
+ # --------------------------------------------------------------------------- InferenceData
283
+
284
+
285
+ def posterior_document(data: Any) -> dict[str, Any]:
286
+ """Summarize every named posterior variable of an InferenceData or DataTree.
287
+
288
+ Variables indexed by an observation dimension (one shared with observed or constant
289
+ data) and variables with more than ``ELEMENT_LIMIT`` elements are left out: they
290
+ describe observations or latent values, not parameters.
291
+ """
292
+ posterior = _group(data, "posterior")
293
+ skip = _observed_dims(data)
294
+ names = []
295
+ for name, array in posterior.data_vars.items():
296
+ dims = [str(d) for d in array.dims if d not in SAMPLE_DIMS]
297
+ size = int(np.prod([array.sizes[d] for d in dims])) if dims else 1
298
+ if skip & set(dims) or size > ELEMENT_LIMIT:
299
+ continue
300
+ if not np.issubdtype(array.dtype, np.number) or np.issubdtype(array.dtype, np.bool_):
301
+ continue
302
+ names.append(str(name))
303
+ if not names:
304
+ raise FrameworkError(
305
+ "This InferenceData has no posterior parameters to publish: every variable is "
306
+ "indexed by observation or has more than 100 elements."
307
+ )
308
+ frame = _rows(posterior, [(name, name) for name in names])
309
+ truncated = len(frame) > ROW_LIMIT
310
+ coefficients = table(frame.head(ROW_LIMIT), "Posterior summaries", role="coefficients")
311
+ if truncated:
312
+ coefficients |= {"row_count": len(frame), "truncated": True}
313
+ document = _with_classes(_document(data, "model"), data) | {
314
+ "model": _description("other", inference="bayesian"),
315
+ "tables": [coefficients],
316
+ "metrics": _metrics([("nobs", _nobs(data))])
317
+ + _interval_metrics()
318
+ + _sampling_metrics(data, posterior),
319
+ }
320
+ return document
321
+
322
+
323
+ # --------------------------------------------------------------------------- Bambi
324
+
325
+ _BAMBI_FAMILIES = {
326
+ "bernoulli": "binomial",
327
+ "binomial": "binomial",
328
+ "gaussian": "gaussian",
329
+ "poisson": "poisson",
330
+ "negativebinomial": "negative binomial",
331
+ "gamma": "gamma",
332
+ "t": "student t",
333
+ "categorical": "multinomial",
334
+ "multinomial": "multinomial",
335
+ "dirichlet_multinomial": "multinomial",
336
+ }
337
+ _ORDINAL = {"cumulative", "sratio"}
338
+
339
+
340
+ def _quiet(source: Any, *names: str) -> Any:
341
+ """The first attribute present among names, without Bambi's deprecation warnings."""
342
+ with warnings.catch_warnings():
343
+ warnings.simplefilter("ignore")
344
+ for name in names:
345
+ value = getattr(source, name, None)
346
+ if value is not None:
347
+ return value
348
+ return None
349
+
350
+
351
+ def _components(model: Any) -> dict[str, Any]:
352
+ components = _quiet(model, "_components", "components")
353
+ return dict(components) if isinstance(components, dict) else {}
354
+
355
+
356
+ def _bambi_description(model: Any, grouped: bool, response: str | None) -> dict[str, Any]:
357
+ family = model.family
358
+ name = str(getattr(family, "name", "")).lower()
359
+ parent = family.likelihood.parent
360
+ link = getattr(family.link.get(parent), "name", None) if isinstance(family.link, dict) else None
361
+ mapped = _BAMBI_FAMILIES.get(name, name or None)
362
+ if name in _ORDINAL:
363
+ model_type = "ordinal"
364
+ mapped = None
365
+ elif mapped == "multinomial":
366
+ model_type = "multinomial"
367
+ elif grouped:
368
+ model_type = "mixed"
369
+ elif mapped == "gaussian" and link == "identity":
370
+ model_type = "linear"
371
+ else:
372
+ model_type = "glm"
373
+ return _description(
374
+ model_type, family=mapped, link=link, response=response, inference="bayesian"
375
+ )
376
+
377
+
378
+ def _prior_text(prior: Any) -> str:
379
+ """Bambi priors as text, with array arguments collapsed when every entry is equal."""
380
+ if not _has_class(prior, "bambi", "Prior"):
381
+ return _number_text(prior)
382
+ args = ", ".join(f"{key}: {_number_text(value)}" for key, value in prior.args.items())
383
+ return f"{prior.name}({args})"
384
+
385
+
386
+ def _number_text(value: Any) -> str:
387
+ if _has_class(value, "bambi", "Prior"):
388
+ return _prior_text(value)
389
+ if isinstance(value, (np.ndarray, list, tuple)):
390
+ values = np.asarray(value).ravel()
391
+ if values.size and np.issubdtype(values.dtype, np.number) and np.all(values == values[0]):
392
+ return _number_text(values[0])
393
+ return "[" + ", ".join(_number_text(v) for v in values) + "]"
394
+ if isinstance(value, (bool, np.bool_)):
395
+ return str(bool(value))
396
+ if isinstance(value, (int, np.integer)):
397
+ return str(int(value))
398
+ if isinstance(value, (float, np.floating)):
399
+ return f"{float(value):.4g}"
400
+ return str(value)
401
+
402
+
403
+ def _formulae_design(terms: dict[str, Any], design: _Design, prefix: str) -> None:
404
+ """Map a formulae design's common terms to variables, as Bambi names their columns."""
405
+ for term in terms.values():
406
+ components = getattr(term, "components", None)
407
+ if not components:
408
+ continue
409
+ names = [prefix + str(label) for label in term.labels]
410
+ factors: list[list[_Part]] = []
411
+ single_numeric: str | None = None
412
+ for component in components:
413
+ expression = str(component.name)
414
+ kind = getattr(component, "kind", None)
415
+ variable = design.predictor(expression)
416
+ if kind == "numeric":
417
+ design.factor(variable)
418
+ factors.append([_Part(expression, variable)])
419
+ single_numeric = variable if len(components) == 1 else None
420
+ elif kind == "categoric" and component.contrast_matrix is not None:
421
+ contrast = component.contrast_matrix
422
+ categories = [str(level) for level in component.levels]
423
+ levels, reference = _coding(np.asarray(contrast.matrix), categories)
424
+ design.factor(variable, categories)
425
+ factors.append(
426
+ [
427
+ _Part(
428
+ f"{expression}[{label}]",
429
+ variable,
430
+ level,
431
+ indicator=level is not None,
432
+ categories=categories,
433
+ reference=reference,
434
+ )
435
+ for label, level in zip(contrast.labels, levels, strict=True)
436
+ ]
437
+ )
438
+ else:
439
+ factors = []
440
+ break
441
+ if not factors:
442
+ continue
443
+ design.match(names, factors, prefix=prefix)
444
+ if single_numeric is not None:
445
+ # Multi-column transformations such as poly(x, 2) name columns their own way.
446
+ for name in names:
447
+ if name not in design.terms:
448
+ design.add(name, [_Part(name, single_numeric)])
449
+
450
+
451
+ def _bambi_variables(
452
+ model: Any, frame: pd.DataFrame, response: str | None, coefficients: dict[str, Any]
453
+ ) -> dict[str, Any]:
454
+ """Return ``variables`` and ``terms`` for a Bambi model, or {} when unknown."""
455
+ columns = [str(c) for c in frame.columns]
456
+ if len(set(columns)) != len(columns):
457
+ return {}
458
+ frame = frame.set_axis(columns, axis=1)
459
+ design = _Design(columns)
460
+ groups: list[str] = []
461
+ for component in _components(model).values():
462
+ matrices = getattr(component, "design", None)
463
+ if matrices is None:
464
+ continue
465
+ is_parent = bool(getattr(component, "is_parent", False))
466
+ prefix = "" if is_parent else f"{component.prefix}_" if component.prefix else ""
467
+ common = getattr(matrices, "common", None)
468
+ if common is not None:
469
+ _formulae_design(common.terms, design, prefix)
470
+ group = getattr(matrices, "group", None)
471
+ for term in getattr(group, "terms", {}).values():
472
+ for part in getattr(term.expr, "components", []) or []:
473
+ design.factor(design.predictor(str(part.name)))
474
+ for part in getattr(term.factor, "components", []) or []:
475
+ used = _referenced(str(part.name), design.columns)
476
+ groups += [name for name in sorted(used) if name not in groups]
477
+ labels = _labels(model.data)
478
+ formula = str(getattr(model.formula, "main", ""))
479
+ variables = []
480
+ if response is not None and response in frame:
481
+ label = labels.get(response)
482
+ variables.append(_variable(response, frame[response], "response", label=label))
483
+ predictors = sorted(design.predictors, key=lambda name: _position(name, formula))
484
+ variables += [
485
+ _variable(name, frame[name], "predictor", design, labels.get(name))
486
+ for name in predictors
487
+ if name != response and name not in groups
488
+ ]
489
+ variables += [
490
+ _variable(name, frame[name], "group", label=labels.get(name))
491
+ for name in groups
492
+ if name != response
493
+ ]
494
+ return _variables_fields(variables, design.terms, coefficients)
495
+
496
+
497
+ def _used_frame(model: Any, components: dict[str, Any], nobs: int | None) -> pd.DataFrame | None:
498
+ """The rows the model was fit on: formulae's frame after dropping missing values."""
499
+ for component in components.values():
500
+ matrices = getattr(component, "design", None)
501
+ frame = getattr(matrices, "data", None)
502
+ if isinstance(frame, pd.DataFrame) and (nobs is None or len(frame) == nobs):
503
+ return frame
504
+ data = getattr(model, "data", None)
505
+ if isinstance(data, pd.DataFrame) and (nobs is None or len(data) == nobs):
506
+ return data
507
+ return None
508
+
509
+
510
+ def bambi_document(fit: BambiFit) -> dict[str, Any]:
511
+ """Summarize a Bambi model's posterior by its terms, with its priors and variables."""
512
+ model, data = fit.model, fit.posterior
513
+ posterior = _group(data, "posterior")
514
+ available = {str(name) for name in posterior.data_vars}
515
+ components = _components(model)
516
+ family = model.family
517
+ parent = family.likelihood.parent
518
+
519
+ common: list[tuple[str, str]] = [] # (posterior variable, term label)
520
+ ratio: set[str] = set()
521
+ grouped: list[tuple[str, str]] = []
522
+ group_of: dict[str, str] = {}
523
+ extra: list[tuple[str, str]] = []
524
+ priors: list[tuple[str, str]] = []
525
+ for name, component in components.items():
526
+ terms = getattr(component, "terms", None)
527
+ if not isinstance(terms, dict):
528
+ # A parameter with no formula of its own, such as sigma or alpha.
529
+ if name in available:
530
+ extra.append((name, name))
531
+ prior = getattr(component, "prior", None)
532
+ if prior is not None:
533
+ priors.append((name, _prior_text(prior)))
534
+ continue
535
+ is_parent = bool(getattr(component, "is_parent", False)) or name == parent
536
+ group_terms = getattr(component, "group_specific_terms", {}) or {}
537
+ for key, term in terms.items():
538
+ variable = str(getattr(term, "name", key))
539
+ label = _INTERCEPT if variable == "Intercept" else variable
540
+ prior = getattr(term, "prior", None)
541
+ if prior is not None:
542
+ priors.append((label, _prior_text(prior)))
543
+ if key in group_terms:
544
+ sigma = f"{variable}_sigma"
545
+ if sigma in available:
546
+ grouped.append((sigma, sigma))
547
+ factor = getattr(getattr(term, "term", None), "factor", None)
548
+ group_of[sigma] = str(getattr(factor, "name", key.split("|", 1)[-1]))
549
+ continue
550
+ if variable in available:
551
+ common.append((variable, label))
552
+ # The exponent of an intercept is a baseline, not a ratio: R leaves it out too
553
+ if is_parent and label != "(Intercept)":
554
+ ratio.add(variable)
555
+
556
+ if not common:
557
+ raise FrameworkError("This Bambi model's posterior has none of its terms.")
558
+ response_name = str(getattr(getattr(model, "formula", None), "main", "")).split("~", 1)[0]
559
+ response_name = response_name.strip()
560
+ nobs = _nobs(data)
561
+ frame = _used_frame(model, components, nobs)
562
+ response = None
563
+ if frame is not None:
564
+ used = _referenced(response_name, {str(c) for c in frame.columns})
565
+ response = next(iter(used)) if len(used) == 1 else None
566
+ description = _bambi_description(model, bool(grouped), response or response_name or None)
567
+ exponentiate = description.get("exponentiate")
568
+ tables = [
569
+ table(
570
+ _rows(posterior, common, ratio=ratio if exponentiate else None),
571
+ "Population-level effects",
572
+ role="coefficients",
573
+ )
574
+ ]
575
+ if grouped:
576
+ tables.append(
577
+ table(
578
+ _rows(posterior, grouped, group=group_of),
579
+ "Group-level effects",
580
+ role="random_effects",
581
+ )
582
+ )
583
+ if extra:
584
+ tables.append(table(_rows(posterior, extra), "Distributional parameters"))
585
+ if priors:
586
+ tables.append(
587
+ table(pd.DataFrame(priors, columns=["parameter", "prior"]), "Priors", role="priors")
588
+ )
589
+ formula = getattr(model, "formula", None)
590
+ formulas = [str(getattr(formula, "main", "") or "")]
591
+ formulas += [str(f) for f in getattr(formula, "additionals", ()) or ()]
592
+ document = _with_classes(_document(model, "model"), model, data) | {
593
+ "model": description,
594
+ "tables": tables,
595
+ "metrics": _metrics([("nobs", nobs)])
596
+ + _interval_metrics()
597
+ + _sampling_metrics(data, posterior),
598
+ }
599
+ if formulas[0]:
600
+ document["formula"] = "; ".join(f for f in formulas if f)
601
+ if frame is not None:
602
+ with contextlib.suppress(Exception):
603
+ document |= _bambi_variables(model, frame, response, tables[0])
604
+ return document
605
+
606
+
607
+ def is_bambi_model(source: Any) -> bool:
608
+ return _from(source, "bambi") and _has_class(source, "bambi", "Model")
framework/storage.py CHANGED
@@ -350,8 +350,8 @@ def _slug_ignored(slug: str | bool | None) -> None:
350
350
  _ACCEPTED = (
351
351
  "publish() accepts a file or rendered folder; a pandas or polars DataFrame or Series; a "
352
352
  "numpy array; a pandas Styler; a scipy.stats test result; a statsmodels results object; "
353
- "a fitted scikit-learn, xgboost, or lightgbm model; a matplotlib Figure or Axes or a "
354
- "seaborn plot; a plotly Figure; or an altair chart."
353
+ "a fitted scikit-learn, xgboost, or lightgbm model; an ArviZ InferenceData; a matplotlib "
354
+ "Figure or Axes or a seaborn plot; a plotly Figure; or an altair chart."
355
355
  )
356
356
 
357
357
 
@@ -552,6 +552,7 @@ def publish(
552
552
  visibility: str | None = None,
553
553
  collection: str | int | None = None,
554
554
  share_unlisted: bool = False,
555
+ model: Any = None,
555
556
  ) -> str | list[str]:
556
557
  """Publish an artifact to a named destination or the project default.
557
558
 
@@ -559,14 +560,15 @@ def publish(
559
560
  source: A file, a rendered folder, or an object. Accepted objects are pandas and
560
561
  polars DataFrames and Series, numpy arrays with one or two dimensions, pandas
561
562
  Styler tables, scipy.stats test results, statsmodels results, fitted
562
- scikit-learn, xgboost, and lightgbm models, matplotlib Figures and Axes, seaborn
563
- plots and grids, plotly Figures, and altair charts. On Framework Cloud, tables
564
- become typed tables with column summaries (every row is kept), tests and models
565
- become structured summaries, and static plots become SVG. Model exports carry
566
- coefficients, importance, and fit statistics, never observations, residuals, or
567
- serialized models. Buckets receive CSV tables, PNG figures, and HTML model
568
- summaries; Styler tables, plotly figures, and altair charts keep their HTML or
569
- Vega-Lite form everywhere.
563
+ scikit-learn, xgboost, and lightgbm models, ArviZ InferenceData (alone or with
564
+ the Bambi model that produced it, through ``model``), matplotlib Figures and Axes
565
+ (including ArviZ plots), seaborn plots and grids, plotly Figures, and altair
566
+ charts. On Framework Cloud, tables become typed tables with column summaries
567
+ (every row is kept), tests and models become structured summaries, and static
568
+ plots become SVG. Model exports carry coefficients, importance, and fit
569
+ statistics, never observations, residuals, posterior draws, or serialized models.
570
+ Buckets receive CSV tables, PNG figures, and HTML model summaries; Styler tables,
571
+ plotly figures, and altair charts keep their HTML or Vega-Lite form everywhere.
570
572
  dest: Where to put it in the bucket. Default: the source's name.
571
573
  connection: A storage bucket name. Default: the project's default bucket.
572
574
  overwrite: Accepted for parity with R; uploads always replace.
@@ -591,6 +593,9 @@ def publish(
591
593
  ``slug=True`` or ``False``.
592
594
  collection: Existing project collection ID or slug; follows the latest artifact version.
593
595
  share_unlisted: Explicitly allow collection readers to access an unlisted artifact.
596
+ model: The Bambi model whose ``fit()`` returned ``source``, an InferenceData:
597
+ ``publish(idata, model=model)``. The model adds its family, formula, priors,
598
+ group-level effects, and variables to the posterior summaries.
594
599
  allow_private: Deprecated name for ``include_private``.
595
600
 
596
601
  Returns:
@@ -630,6 +635,11 @@ def publish(
630
635
  else:
631
636
  driver = _target(connection, to)
632
637
  validate(Destination(driver, driver, {}), visibility, password, collection)
638
+ fitted = None
639
+ if model is not None:
640
+ from framework._bayesian import with_model
641
+
642
+ fitted = with_model(source, model)
633
643
  if isinstance(source, (str, Path)):
634
644
  path = Path(source)
635
645
  if not path.exists():
@@ -647,6 +657,8 @@ def publish(
647
657
  include_private_arg(include_private, allow_private),
648
658
  sensitive_reasons(f"this {type(source).__name__}"),
649
659
  )
660
+ if fitted is not None:
661
+ source = fitted
650
662
  with tempfile.TemporaryDirectory(prefix="fw_publish_bundle_") as temp:
651
663
  bundle = Path(temp) / "bundle"
652
664
  manifest = build_bundle(
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: framework-py
3
- Version: 0.1.0.dev25
3
+ Version: 0.1.0.dev26
4
4
  Summary: Structured data science projects: a data catalog, integrity tracking, caching, outputs, and AI guardrails
5
5
  Project-URL: Homepage, https://framework.pub
6
6
  Project-URL: Source, https://github.com/frameworktools/framework-py
@@ -1,8 +1,9 @@
1
1
  framework/__init__.py,sha256=wu0kbAo9WBq74juy_W5v55CuB2KsabuiS21hZC5iAJU,6700
2
2
  framework/__main__.py,sha256=S0ChmRQnNa9W5_MPXhHnH61Kjr_pNthkeS41eJU1w0U,9093
3
3
  framework/_agents_md.py,sha256=PSWPJiCUTRirk81sz-Y33qHnqY16HOhHY8pH77ct1ik,11857
4
- framework/_artifacts.py,sha256=rJVMifCuZ0nnaEFoD8TCMFaca-tga20kngsAtXDyXLI,54226
4
+ framework/_artifacts.py,sha256=XjYOBQOQJuvztUyqwWsc3xc1qJ5o4O5XpCW49WN548k,55807
5
5
  framework/_backups.py,sha256=ra1DhGcIbIXB0zqDFVFJ3yPEjmXpYKFX-fjV01b9Rtg,1958
6
+ framework/_bayesian.py,sha256=Yx8deM_LWsfPPM8n3rX7b1R9L1qcdeaDU2aUIZZyhB4,23675
6
7
  framework/_csv.py,sha256=oAaLUChyUsHJsh0YuUDt0viC8SAImMgUseNKGk7kLXo,4855
7
8
  framework/_defaults_cache.py,sha256=pyqQ7rMcKwo_fTSAvDDNyQXIAjiJZfWccnkRPw340WQ,1711
8
9
  framework/_depends.py,sha256=KLU4iog3zdyKcXoUuI0Tg9ArZ-3NdKbMEc8XS-DM7Bo,8579
@@ -53,7 +54,7 @@ framework/security.py,sha256=-x66bSIIE_xOzkTf5Ojt7xIECKuAIpKVJZ5TtIGrwys,51147
53
54
  framework/settings.py,sha256=Sb2YyE53aYLWPj423P-pQVCvRpLsiHydgZh2K0luTQQ,23893
54
55
  framework/skill_pull.py,sha256=vr_yxe446JhHbtI0hps19AnLN6S7BacSt2oxn7BIlos,21859
55
56
  framework/skill_sync.py,sha256=0gqaeVkiNaqGJxmrVrKrYaX8wI3DNFZUsJEgG63xcKc,23060
56
- framework/storage.py,sha256=UnTL9buYwawFFGll4D0FRDqsVXjj_B2uYMELXntfq_M,55486
57
+ framework/storage.py,sha256=Haz8CBXrz2CCqGHOVgHKC3mUUwobnod2SanU759lK7c,56115
57
58
  framework/sync_all.py,sha256=tmSnapf-JfaL1_8rMpnr3wqHvSGJamn7c8ja4GQFKHA,34610
58
59
  framework/upgrade.py,sha256=WtghpLR65YFH_JQFmo1JlH9lHdwsXQd-ZzzOTmyOL28,65593
59
60
  framework/_assets/init.sql,sha256=-aIiuIcCmBniGKq-CHdRtUiV9e_CLXoqxxd05snmgOE,1156
@@ -139,7 +140,7 @@ framework/templates/stubs/notebook-default.qmd,sha256=8Js1S2BcHYeQWmJS-kt31gBvIj
139
140
  framework/templates/stubs/notebook-minimal.qmd,sha256=2U2k8judffhrh_6m6r6OAbQBCYEtViAjeKRBqBYCJTM,178
140
141
  framework/templates/stubs/notebook-revealjs.qmd,sha256=_ztT_gHoudpB5DIjlbvtB5zQ8163DeV8xbWcT-HgJrI,409
141
142
  framework/templates/stubs/script-default.py,sha256=vbWqgW0_rHot17mQC3tYb92g_9L-cbTOeL3y99BRrSk,216
142
- framework_py-0.1.0.dev25.dist-info/METADATA,sha256=n_1EYAEJZWoCVgexl1ZvSNxxLWCyp7M8DXgDM-rLD78,4682
143
- framework_py-0.1.0.dev25.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
144
- framework_py-0.1.0.dev25.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
145
- framework_py-0.1.0.dev25.dist-info/RECORD,,
143
+ framework_py-0.1.0.dev26.dist-info/METADATA,sha256=ZFaJ834HxwvPY1yz8vaGH-bRHdi0gdCtaYgYdY3PMrU,4682
144
+ framework_py-0.1.0.dev26.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
145
+ framework_py-0.1.0.dev26.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
146
+ framework_py-0.1.0.dev26.dist-info/RECORD,,