framework-py 0.1.0.dev24__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
@@ -9,8 +9,12 @@ from them is published.
9
9
 
10
10
  from __future__ import annotations
11
11
 
12
+ import ast
13
+ import contextlib
14
+ import itertools
12
15
  import json
13
16
  import math
17
+ import re
14
18
  from collections.abc import Callable, Iterable, Sequence
15
19
  from datetime import date, datetime
16
20
  from pathlib import Path
@@ -274,6 +278,8 @@ def as_frame(source: Any) -> pd.DataFrame | None:
274
278
  name = "value" if source.name is None or source.name == "" else str(source.name)
275
279
  return source.to_frame(name)
276
280
  if isinstance(source, np.ndarray):
281
+ if _axes_array(source):
282
+ return None
277
283
  return _numpy_frame(source)
278
284
  if _has_class(source, "polars", "DataFrame", "Series"):
279
285
  if _has_class(source, "polars", "Series"):
@@ -658,9 +664,429 @@ def _statsmodels_document(result: Any) -> dict[str, Any]:
658
664
  formula = getattr(model, "formula", None)
659
665
  if isinstance(formula, str):
660
666
  document["formula"] = formula
667
+ # Variables are optional; a design this code can't read leaves them out.
668
+ with contextlib.suppress(Exception):
669
+ document |= _statsmodels_variables(result, tables[0])
661
670
  return document
662
671
 
663
672
 
673
+ # --------------------------------------------------------------------------- model variables
674
+
675
+ VARIABLE_LIMIT = 100
676
+ LEVEL_LIMIT = 50
677
+ TERM_LIMIT = 500
678
+ PART_LIMIT = 10
679
+ _LABEL_ATTRS = ("column_labels", "variable_labels", "labels")
680
+
681
+
682
+ class _Part:
683
+ """One factor's contribution to a design column: its name piece, variable, and level."""
684
+
685
+ def __init__(
686
+ self, name: str, variable: str | None, level: str | None = None, **coding: Any
687
+ ) -> None:
688
+ self.name, self.variable, self.level = name, variable, level
689
+ # A categorical part is mappable only when its column is one level's indicator.
690
+ self.mappable = variable is not None and coding.get("indicator", True)
691
+ self.categories: list[str] | None = coding.get("categories")
692
+ self.reference: str | None = coding.get("reference")
693
+
694
+
695
+ class _Design:
696
+ """What a model's design says about its variables and coefficient terms."""
697
+
698
+ def __init__(self, columns: Sequence[str]) -> None:
699
+ self.columns = set(columns)
700
+ self.predictors: list[str] = []
701
+ self.terms: dict[str, list[dict[str, str]]] = {}
702
+ self.categories: dict[str, list[list[str]]] = {}
703
+ self.references: dict[str, set[str | None]] = {}
704
+ self.numeric: set[str] = set()
705
+
706
+ def predictor(self, expression: str) -> str | None:
707
+ """Note the variables an expression uses; return the one it transforms, if one."""
708
+ used = _referenced(expression, self.columns)
709
+ for name in sorted(used):
710
+ if name not in self.predictors:
711
+ self.predictors.append(name)
712
+ return next(iter(used)) if len(used) == 1 else None
713
+
714
+ def match(
715
+ self, names: Sequence[str], factors: Sequence[Sequence[_Part]], prefix: str = ""
716
+ ) -> None:
717
+ """Map each design column to the parts whose names join to its name."""
718
+ candidates: dict[str, tuple[_Part, ...]] = {}
719
+ for combination in itertools.product(*factors):
720
+ name = prefix + ":".join(part.name for part in combination)
721
+ candidates.setdefault(name, combination)
722
+ for name in names:
723
+ parts = candidates.get(name)
724
+ if parts is None or not all(part.mappable for part in parts):
725
+ continue
726
+ self.add(name, parts)
727
+
728
+ def factor(self, variable: str | None, categories: list[str] | None = None) -> None:
729
+ """Note how the model codes a variable: numeric, or categorical with these levels."""
730
+ if variable is None:
731
+ return
732
+ if categories is None:
733
+ self.numeric.add(variable)
734
+ else:
735
+ self.categories.setdefault(variable, []).append(categories)
736
+
737
+ def add(self, name: str, parts: Sequence[_Part]) -> None:
738
+ self.terms[name] = [
739
+ {"variable": str(p.variable)} | ({"level": p.level} if p.level is not None else {})
740
+ for p in parts
741
+ ]
742
+ for part in parts:
743
+ if part.categories is not None:
744
+ self.references.setdefault(str(part.variable), set()).add(part.reference)
745
+
746
+
747
+ def _referenced(expression: str, columns: set[str]) -> set[str]:
748
+ """Return the data columns a formula factor reads, or an empty set when unsure."""
749
+ if expression in columns:
750
+ return {expression}
751
+ used = {name for name in re.findall(r"`([^`]+)`", expression)}
752
+ code = re.sub(r"`[^`]+`", "_fw_quoted_", expression)
753
+ try:
754
+ tree = ast.parse(code, mode="eval")
755
+ except SyntaxError:
756
+ return set()
757
+ skip = set()
758
+ for node in ast.walk(tree):
759
+ if isinstance(node, ast.Call):
760
+ skip.add(id(node.func))
761
+ quoted = node.args[0] if len(node.args) == 1 else None
762
+ if (
763
+ isinstance(node.func, ast.Name)
764
+ and node.func.id == "Q"
765
+ and isinstance(quoted, ast.Constant)
766
+ and isinstance(quoted.value, str)
767
+ ):
768
+ used.add(quoted.value)
769
+ elif isinstance(node, ast.Attribute):
770
+ skip.add(id(node.value))
771
+ used |= {
772
+ node.id
773
+ for node in ast.walk(tree)
774
+ if isinstance(node, ast.Name) and id(node) not in skip and node.id in columns
775
+ }
776
+ return used if used <= columns else set()
777
+
778
+
779
+ def _indicator(column: Any, categories: Sequence[str]) -> str | None:
780
+ """Return the level a contrast column indicates, or None for other codings."""
781
+ values = np.asarray(column, dtype="float64")
782
+ ones = np.flatnonzero(values == 1)
783
+ if len(ones) == 1 and np.all((values == 0) | (values == 1)):
784
+ return categories[int(ones[0])]
785
+ return None
786
+
787
+
788
+ def _coding(matrix: Any, categories: Sequence[str]) -> tuple[list[str | None], str | None]:
789
+ """Return each contrast column's level and the coding's reference level, if any."""
790
+ matrix = np.asarray(matrix, dtype="float64")
791
+ levels = [_indicator(matrix[:, j], categories) for j in range(matrix.shape[1])]
792
+ reference = None
793
+ zero = [i for i in range(matrix.shape[0]) if not np.any(matrix[i])]
794
+ if all(level is not None for level in levels) and len(zero) == 1:
795
+ reference = categories[zero[0]]
796
+ return levels, reference
797
+
798
+
799
+ def _patsy_design(info: Any, design: _Design) -> None:
800
+ for term, subterms in info.term_codings.items():
801
+ if not term.factors:
802
+ continue
803
+ names = info.column_names[info.term_slices[term]]
804
+ variables = {factor: design.predictor(factor.name()) for factor in term.factors}
805
+ for subterm in subterms:
806
+ factors: list[list[_Part]] = []
807
+ for factor in subterm.factors:
808
+ factor_info = info.factor_infos[factor]
809
+ variable = variables[factor]
810
+ if factor_info.type == "categorical":
811
+ contrast = subterm.contrast_matrices[factor]
812
+ categories = [str(c) for c in factor_info.categories]
813
+ levels, reference = _coding(contrast.matrix, categories)
814
+ design.factor(variable, categories)
815
+ factors.append(
816
+ [
817
+ _Part(
818
+ factor.name() + suffix,
819
+ variable,
820
+ level,
821
+ indicator=level is not None,
822
+ categories=categories,
823
+ reference=reference,
824
+ )
825
+ for suffix, level in zip(contrast.column_suffixes, levels, strict=True)
826
+ ]
827
+ )
828
+ else:
829
+ width = factor_info.num_columns
830
+ design.factor(variable)
831
+ factors.append(
832
+ [
833
+ _Part(
834
+ factor.name() if width == 1 else f"{factor.name()}[{i}]", variable
835
+ )
836
+ for i in range(width)
837
+ ]
838
+ )
839
+ design.match(names, factors)
840
+
841
+
842
+ def _formulaic_design(spec: Any, design: _Design) -> None:
843
+ for term in spec.terms:
844
+ names = [spec.column_names[i] for i in spec.term_indices[term]]
845
+ factors: list[list[_Part]] = []
846
+ single_numeric: str | None = None
847
+ for factor in term.factors:
848
+ expression = str(factor.expr)
849
+ state = spec.encoder_state.get(expression)
850
+ kind = getattr(state[0], "value", None) if state else None
851
+ if kind not in ("categorical", "numerical"):
852
+ factors = []
853
+ break
854
+ variable = design.predictor(expression)
855
+ if kind == "numerical":
856
+ design.factor(variable)
857
+ factors.append([_Part(expression, variable)])
858
+ single_numeric = variable if len(term.factors) == 1 else None
859
+ continue
860
+ contrasts = state[1].get("contrasts")
861
+ categories = [str(c) for c in contrasts.levels]
862
+ design.factor(variable, categories)
863
+ parts = []
864
+ for reduced in (True, False):
865
+ coding = contrasts.contrasts.get_coding_matrix(
866
+ contrasts.levels, reduced_rank=reduced
867
+ )
868
+ template = contrasts.contrasts.get_factor_format(
869
+ contrasts.levels, reduced_rank=reduced
870
+ )
871
+ levels, reference = _coding(coding.to_numpy(), categories)
872
+ parts += [
873
+ _Part(
874
+ template.format(name=expression, field=field),
875
+ variable,
876
+ level,
877
+ indicator=level is not None,
878
+ categories=categories,
879
+ reference=reference,
880
+ )
881
+ for field, level in zip(coding.columns, levels, strict=True)
882
+ ]
883
+ factors.append(parts)
884
+ if not factors:
885
+ continue
886
+ design.match(names, factors)
887
+ if single_numeric is not None:
888
+ # Multi-column transformations such as poly(x, 2) name columns their own way.
889
+ for name in names:
890
+ if name not in design.terms:
891
+ design.add(name, [_Part(name, single_numeric)])
892
+
893
+
894
+ def _position(name: str, formula: str) -> int:
895
+ right = formula.split("~", 1)[-1]
896
+ match = re.search(rf"(?<![\w.`]){re.escape(name)}(?![\w`])", right)
897
+ return match.start() if match else len(right)
898
+
899
+
900
+ def _labels(frame: Any) -> dict[str, str]:
901
+ attrs = getattr(frame, "attrs", None)
902
+ if not isinstance(attrs, dict):
903
+ return {}
904
+ for key in _LABEL_ATTRS:
905
+ labels = attrs.get(key)
906
+ if isinstance(labels, dict):
907
+ return {
908
+ str(name): label.strip()
909
+ for name, label in labels.items()
910
+ if isinstance(label, str) and label.strip()
911
+ }
912
+ return {}
913
+
914
+
915
+ def _variable(
916
+ name: str,
917
+ series: pd.Series | None,
918
+ role: str,
919
+ design: _Design | None = None,
920
+ label: str | None = None,
921
+ ) -> dict[str, Any]:
922
+ categories = design.categories.get(name) if design else None
923
+ categorical = bool(categories) and name not in (design.numeric if design else set())
924
+ kind = _column_type(series) if series is not None else "number"
925
+ entry: dict[str, Any] = {"name": name, "role": role}
926
+ if categorical and categories:
927
+ entry["type"] = "boolean" if kind == "boolean" else "categorical"
928
+ if all(levels == categories[0] for levels in categories):
929
+ entry["levels"] = categories[0][:LEVEL_LIMIT]
930
+ references = design.references.get(name, set()) if design else set()
931
+ if len(references) == 1 and None not in references:
932
+ entry["reference"] = next(iter(references))
933
+ else:
934
+ entry["type"] = kind
935
+ if label:
936
+ entry["label"] = label
937
+ if series is not None:
938
+ summary = _summary(series, "string" if entry["type"] == "categorical" else kind)
939
+ summary.pop("histogram", None)
940
+ entry["summary"] = summary
941
+ return entry
942
+
943
+
944
+ def _used_rows(model: Any, frame: Any) -> pd.DataFrame | None:
945
+ """Return the rows of a formula model's data that the fit used, or None if unsure."""
946
+ if not isinstance(frame, pd.DataFrame):
947
+ return None
948
+ count = len(np.asarray(model.endog))
949
+ labels = getattr(model.data, "row_labels", None)
950
+ if (
951
+ labels is not None
952
+ and len(labels) == count
953
+ and frame.index.is_unique
954
+ and pd.Index(labels).isin(frame.index).all()
955
+ ):
956
+ used: pd.DataFrame = frame.loc[labels]
957
+ return used
958
+ return frame if len(frame) == count else None
959
+
960
+
961
+ def _group_values(model: Any, count: int) -> pd.Series | None:
962
+ """Rebuild a mixed model's grouping column from its per-group row positions."""
963
+ rows = getattr(model, "row_indices", None)
964
+ if not isinstance(rows, dict):
965
+ return None
966
+ values = np.empty(count, dtype=object)
967
+ for group, positions in rows.items():
968
+ values[np.asarray(positions, dtype=int)] = group
969
+ series = pd.Series(values)
970
+ return series.infer_objects() if not series.isna().any() else None
971
+
972
+
973
+ def _group_name(model: Any) -> str | None:
974
+ names = list(getattr(model.data, "exog_re_names", None) or [])
975
+ exog_re = np.asarray(getattr(model, "exog_re", np.empty((0, 0))))
976
+ intercept = exog_re.ndim == 2 and exog_re.size > 0 and bool(np.all(exog_re[:, 0] == 1))
977
+ if intercept and names and names[0] != "Group":
978
+ return str(names[0])
979
+ return None
980
+
981
+
982
+ def _statsmodels_variables(result: Any, coefficients: dict[str, Any]) -> dict[str, Any]:
983
+ """Return ``variables`` and ``terms`` for a statsmodels result, or {} when unknown."""
984
+ model = result.model
985
+ data = model.data
986
+ spec = getattr(data, "model_spec", None)
987
+ variables: list[dict[str, Any]] = []
988
+ if spec is not None:
989
+ frame = _used_rows(model, getattr(data, "frame", None))
990
+ if frame is None:
991
+ return {}
992
+ columns = [str(c) for c in frame.columns]
993
+ if isinstance(frame.columns, pd.MultiIndex) or len(set(columns)) != len(columns):
994
+ return {}
995
+ frame = frame.set_axis(columns, axis=1)
996
+ design = _Design(columns)
997
+ if _has_class(spec, "patsy", "DesignInfo"):
998
+ _patsy_design(spec, design)
999
+ elif _has_class(spec, "formulaic", "ModelSpec"):
1000
+ _formulaic_design(spec, design)
1001
+ else:
1002
+ return {}
1003
+ labels = _labels(frame)
1004
+ formula = getattr(model, "formula", None)
1005
+ response = None
1006
+ if isinstance(formula, str) and "~" in formula:
1007
+ used = _referenced(formula.split("~", 1)[0].strip(), design.columns)
1008
+ response = next(iter(used)) if len(used) == 1 else None
1009
+ if response is not None:
1010
+ variables.append(
1011
+ _variable(response, frame[response], "response", label=labels.get(response))
1012
+ )
1013
+ predictors = design.predictors
1014
+ if isinstance(formula, str):
1015
+ # Patsy and formulaic sort terms; list predictors as the formula names them.
1016
+ predictors = sorted(predictors, key=lambda name: _position(name, formula))
1017
+ variables += [
1018
+ _variable(name, frame[name], "predictor", design, labels.get(name))
1019
+ for name in predictors
1020
+ if name != response
1021
+ ]
1022
+ mapping = design.terms
1023
+ if type(model).__name__ == "MixedLM":
1024
+ group = _group_name(model)
1025
+ values = _group_values(model, len(frame)) if group else None
1026
+ if group and values is not None and group not in {v["name"] for v in variables}:
1027
+ variables.append(_variable(group, values, "group", label=labels.get(group)))
1028
+ else:
1029
+ exog = getattr(data, "orig_exog", None)
1030
+ endog = getattr(data, "orig_endog", None)
1031
+ count = len(np.asarray(model.endog))
1032
+ if not isinstance(exog, pd.DataFrame) or len(exog) != count:
1033
+ return {}
1034
+ const = getattr(data, "const_idx", None)
1035
+ names = [str(c) for i, c in enumerate(exog.columns) if i != const]
1036
+ if len(set(names)) != len(names):
1037
+ return {}
1038
+ labels = _labels(exog)
1039
+ if isinstance(endog, pd.Series) and endog.name is not None and len(endog) == count:
1040
+ variables.append(
1041
+ _variable(str(endog.name), endog, "response", label=labels.get(str(endog.name)))
1042
+ )
1043
+ variables += [
1044
+ _variable(str(c), exog.iloc[:, i], "predictor", label=labels.get(str(c)))
1045
+ for i, c in enumerate(exog.columns)
1046
+ if i != const
1047
+ ]
1048
+ mapping = {name: [{"variable": name}] for name in names}
1049
+ two_way = getattr(result.params, "ndim", 1) == 2
1050
+ return _variables_fields(variables, mapping, coefficients, two_way)
1051
+
1052
+
1053
+ def _variables_fields(
1054
+ variables: list[dict[str, Any]],
1055
+ mapping: dict[str, list[dict[str, str]]],
1056
+ coefficients: dict[str, Any],
1057
+ prefixed: bool = False,
1058
+ ) -> dict[str, Any]:
1059
+ """Cap the variables, then map each coefficient term cell to its parts."""
1060
+ seen: set[str] = set()
1061
+ kept = []
1062
+ for variable in variables:
1063
+ if variable["name"] not in seen:
1064
+ seen.add(variable["name"])
1065
+ kept.append(variable)
1066
+ kept = kept[:VARIABLE_LIMIT]
1067
+ names = {v["name"] for v in kept}
1068
+ terms = []
1069
+ for row in coefficients["rows"]:
1070
+ cell = row[0]
1071
+ parts = mapping.get(cell) if isinstance(cell, str) else None
1072
+ if parts is None and prefixed and isinstance(cell, str) and ": " in cell:
1073
+ # Multi-equation tables label each term "<equation>: <term>".
1074
+ parts = next((p for name, p in mapping.items() if cell.endswith(f": {name}")), None)
1075
+ if not parts or len(parts) > PART_LIMIT:
1076
+ continue
1077
+ if any(part["variable"] not in names for part in parts):
1078
+ continue
1079
+ terms.append({"term": cell, "parts": parts})
1080
+ if len(terms) == TERM_LIMIT:
1081
+ break
1082
+ fields: dict[str, Any] = {}
1083
+ if kept:
1084
+ fields["variables"] = kept
1085
+ if terms:
1086
+ fields["terms"] = terms
1087
+ return fields
1088
+
1089
+
664
1090
  # --------------------------------------------------------------------------- machine learning
665
1091
 
666
1092
 
@@ -738,6 +1164,17 @@ def _sklearn_document(model: Any) -> dict[str, Any]:
738
1164
  exponentiate=None if binary else False,
739
1165
  )
740
1166
  frame = pd.DataFrame({"term": terms, "estimate": estimates})
1167
+ coefficients = table(frame, "Coefficients", role="coefficients")
1168
+ variables: dict[str, Any] = {}
1169
+ if getattr(model, "feature_names_in_", None) is not None and features == [
1170
+ str(n) for n in model.feature_names_in_
1171
+ ]:
1172
+ # Linear models fit on a data frame: one numeric input column per coefficient.
1173
+ variables = _variables_fields(
1174
+ [{"name": f, "role": "predictor", "type": "number"} for f in features],
1175
+ {f"{label}{f}": [{"variable": f}] for label in labels for f in features},
1176
+ coefficients,
1177
+ )
741
1178
  metrics = _metrics(
742
1179
  [
743
1180
  *_params(model, ("alpha", "l1_ratio", "C", "penalty", "fit_intercept")),
@@ -745,11 +1182,15 @@ def _sklearn_document(model: Any) -> dict[str, Any]:
745
1182
  ("n_classes", len(classes) if classes else None),
746
1183
  ]
747
1184
  )
748
- return _document(model, "model") | {
749
- "model": description,
750
- "tables": [table(frame, "Coefficients", role="coefficients")],
751
- "metrics": metrics,
752
- }
1185
+ return (
1186
+ _document(model, "model")
1187
+ | {
1188
+ "model": description,
1189
+ "tables": [coefficients],
1190
+ "metrics": metrics,
1191
+ }
1192
+ | variables
1193
+ )
753
1194
  if hasattr(model, "feature_importances_"):
754
1195
  importance = np.asarray(model.feature_importances_, dtype="float64")
755
1196
  document = _importance_document(
@@ -841,7 +1282,18 @@ def structured(source: Any) -> dict[str, Any] | None:
841
1282
  if document is None:
842
1283
  return None
843
1284
  # Readable key order: what it is, then the description, then tables and metrics.
844
- order = ("schema", "kind", "source", "formula", "model", "test", "tables", "metrics")
1285
+ order = (
1286
+ "schema",
1287
+ "kind",
1288
+ "source",
1289
+ "formula",
1290
+ "model",
1291
+ "test",
1292
+ "tables",
1293
+ "metrics",
1294
+ "variables",
1295
+ "terms",
1296
+ )
845
1297
  return {key: document[key] for key in order if key in document} | document
846
1298
 
847
1299
 
@@ -861,11 +1313,51 @@ def _structured(source: Any) -> dict[str, Any] | None:
861
1313
  return _test_document(source)
862
1314
  if _from(source, "statsmodels"):
863
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
+ )
864
1331
  return None
865
1332
 
866
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
+
867
1357
  def _figure(source: Any) -> Any:
868
1358
  """Return the matplotlib Figure behind an Axes, Figure, or seaborn grid."""
1359
+ if _axes_array(source):
1360
+ source = next(iter(source.flat))
869
1361
  figure = source
870
1362
  for _ in range(3):
871
1363
  if callable(getattr(figure, "savefig", None)):
@@ -875,6 +1367,8 @@ def _figure(source: Any) -> Any:
875
1367
 
876
1368
 
877
1369
  def is_figure(source: Any) -> bool:
1370
+ if _axes_array(source):
1371
+ return True
878
1372
  return _from(source, "matplotlib", "seaborn") and _figure(source) is not None
879
1373
 
880
1374
 
@@ -918,6 +1412,7 @@ def _styler_html(source: Any, directory: Path) -> Path:
918
1412
 
919
1413
  def rendered(source: Any, directory: Path, cloud: bool) -> Path | None:
920
1414
  """Write figures, formatted tables, and charts to their file formats, or return None."""
1415
+ source = _plot_collection(source)
921
1416
  exporters: list[tuple[Callable[[Any], bool], Callable[[Any, Path], Path]]] = [
922
1417
  (is_figure, lambda s, d: save_figure(s, d, svg=cloud)),
923
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.dev24
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=cOk2XLqctoqLaQSkksmc7cP4W0_AgqSxYNCTJxyZyik,36068
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.dev24.dist-info/METADATA,sha256=AO0jqjl_730e6cN5rB6qlmGY77wCb7wqn6ZOEK6jaEE,4682
143
- framework_py-0.1.0.dev24.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
144
- framework_py-0.1.0.dev24.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
145
- framework_py-0.1.0.dev24.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,,