framework-py 0.1.0.dev33__py3-none-any.whl → 0.1.0.dev34__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/__init__.py +3 -0
- framework/_artifacts.py +4 -0
- framework/dags.py +492 -0
- framework/storage.py +2 -1
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev34.dist-info}/METADATA +1 -1
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev34.dist-info}/RECORD +8 -7
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev34.dist-info}/WHEEL +0 -0
- {framework_py-0.1.0.dev33.dist-info → framework_py-0.1.0.dev34.dist-info}/licenses/LICENSE +0 -0
framework/__init__.py
CHANGED
|
@@ -62,6 +62,7 @@ from framework.create import (
|
|
|
62
62
|
project_create,
|
|
63
63
|
project_create_from_layers,
|
|
64
64
|
)
|
|
65
|
+
from framework.dags import dagitty, publish_dag
|
|
65
66
|
from framework.data import data_add, data_read, data_save
|
|
66
67
|
from framework.data_registry import pull_data_registry, push_data_registry
|
|
67
68
|
from framework.display import TableDisplay, show_table
|
|
@@ -194,6 +195,7 @@ __all__ = [
|
|
|
194
195
|
"config_sync",
|
|
195
196
|
"configure_global",
|
|
196
197
|
"connections_list",
|
|
198
|
+
"dagitty",
|
|
197
199
|
"data_add",
|
|
198
200
|
"data_info",
|
|
199
201
|
"data_list",
|
|
@@ -248,6 +250,7 @@ __all__ = [
|
|
|
248
250
|
"project_root",
|
|
249
251
|
"project_unregister",
|
|
250
252
|
"publish",
|
|
253
|
+
"publish_dag",
|
|
251
254
|
"publish_data",
|
|
252
255
|
"publish_dir",
|
|
253
256
|
"publish_list",
|
framework/_artifacts.py
CHANGED
|
@@ -1298,6 +1298,10 @@ def structured(source: Any) -> dict[str, Any] | None:
|
|
|
1298
1298
|
|
|
1299
1299
|
|
|
1300
1300
|
def _structured(source: Any) -> dict[str, Any] | None:
|
|
1301
|
+
if _has_class(source, "networkx", "Graph"):
|
|
1302
|
+
from framework import dags
|
|
1303
|
+
|
|
1304
|
+
return dags.structured(source)
|
|
1301
1305
|
frame = as_frame(source)
|
|
1302
1306
|
if frame is not None:
|
|
1303
1307
|
return _table_document(source, frame)
|
framework/dags.py
ADDED
|
@@ -0,0 +1,492 @@
|
|
|
1
|
+
"""Causal diagrams (DAGs) as DAGitty model text, published to Framework Cloud.
|
|
2
|
+
|
|
3
|
+
A DAG is a ``framework.artifact/v1`` document with ``kind: "dag"``. Its ``dagitty`` field
|
|
4
|
+
holds DAGitty model text, which R's dagitty and ggdag and dagitty.net read. Framework Cloud
|
|
5
|
+
validates the graph, lays it out, and draws it, so this module only writes the text and
|
|
6
|
+
collects the labels, code, and analysis that ride along.
|
|
7
|
+
|
|
8
|
+
A graph comes from a ``networkx.DiGraph`` (or a subclass, such as pgmpy's ``DAG``) or
|
|
9
|
+
from DAGitty text. networkx is never imported: graphs are recognized by class name.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import json
|
|
15
|
+
import math
|
|
16
|
+
import re
|
|
17
|
+
import tempfile
|
|
18
|
+
from collections.abc import Iterable, Mapping
|
|
19
|
+
from pathlib import Path
|
|
20
|
+
from typing import Any
|
|
21
|
+
|
|
22
|
+
from framework.errors import FrameworkError
|
|
23
|
+
|
|
24
|
+
SCHEMA = "framework.artifact/v1"
|
|
25
|
+
KIND = "dag"
|
|
26
|
+
ROLES = ("exposure", "outcome", "latent", "adjusted", "selected")
|
|
27
|
+
MAX_NAME = 100
|
|
28
|
+
# Names DAGitty can read without quotes. Graph-type words are quoted so they never read
|
|
29
|
+
# as a header.
|
|
30
|
+
_BARE = re.compile(r"[A-Za-z_][A-Za-z0-9_.]*")
|
|
31
|
+
_KEYWORDS = {"dag", "pdag", "mag", "pag", "graph", "digraph", "node", "edge"}
|
|
32
|
+
_EFFECTS = ("total", "direct")
|
|
33
|
+
_Y = ("up", "down")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
# ---------------------------------------------------------------------------
|
|
37
|
+
# DAGitty text
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _quote(name: str) -> str:
|
|
41
|
+
"""A node name as DAGitty reads it: bare when it can be, else double-quoted."""
|
|
42
|
+
if _BARE.fullmatch(name) and name.lower() not in _KEYWORDS:
|
|
43
|
+
return name
|
|
44
|
+
return '"' + name.replace("\\", "\\\\").replace('"', '\\"') + '"'
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def _number(value: float) -> str:
|
|
48
|
+
return str(int(value)) if value.is_integer() and abs(value) < 1e15 else format(value, ".10g")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def _name(node: Any) -> str:
|
|
52
|
+
name = str(node)
|
|
53
|
+
if not name or name != name.strip() or len(name) > MAX_NAME:
|
|
54
|
+
raise FrameworkError(
|
|
55
|
+
f"DAG variable names are 1 to {MAX_NAME} characters without leading or trailing "
|
|
56
|
+
f"spaces: {name!r}."
|
|
57
|
+
)
|
|
58
|
+
if any(ord(char) < 32 or ord(char) == 127 for char in name):
|
|
59
|
+
raise FrameworkError(f"DAG variable names can't hold control characters: {name!r}.")
|
|
60
|
+
return name
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _roles(name: str, value: Any) -> list[str]:
|
|
64
|
+
"""A node's ``role`` attribute: one role or a list of them."""
|
|
65
|
+
if value is None:
|
|
66
|
+
return []
|
|
67
|
+
values = [value] if isinstance(value, str) else value
|
|
68
|
+
if not isinstance(values, Iterable):
|
|
69
|
+
raise FrameworkError(f'The role of {name} must be a string or a list, such as "exposure".')
|
|
70
|
+
roles = set()
|
|
71
|
+
for role in values:
|
|
72
|
+
if role not in ROLES:
|
|
73
|
+
raise FrameworkError(
|
|
74
|
+
f"{name} has the role {role!r}. A role is one of {', '.join(ROLES)}."
|
|
75
|
+
)
|
|
76
|
+
roles.add(role)
|
|
77
|
+
return [role for role in ROLES if role in roles]
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _position(name: str, value: Any) -> tuple[float, float] | None:
|
|
81
|
+
if value is None:
|
|
82
|
+
return None
|
|
83
|
+
try:
|
|
84
|
+
x, y = (float(part) for part in value)
|
|
85
|
+
except (TypeError, ValueError):
|
|
86
|
+
raise FrameworkError(
|
|
87
|
+
f"The position of {name} must be two numbers, such as (1, 0)."
|
|
88
|
+
) from None
|
|
89
|
+
if not (math.isfinite(x) and math.isfinite(y)):
|
|
90
|
+
raise FrameworkError(f"The position of {name} must be two finite numbers.")
|
|
91
|
+
return x, y
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _cycle(nodes: list[str], edges: list[tuple[str, str, str]]) -> list[str] | None:
|
|
95
|
+
"""A directed cycle as a path that ends where it starts, or None."""
|
|
96
|
+
children: dict[str, list[str]] = {name: [] for name in nodes}
|
|
97
|
+
for start, end, kind in edges:
|
|
98
|
+
if kind == "->":
|
|
99
|
+
children[start].append(end)
|
|
100
|
+
state: dict[str, int] = {}
|
|
101
|
+
for root in nodes:
|
|
102
|
+
if state.get(root):
|
|
103
|
+
continue
|
|
104
|
+
path = [root]
|
|
105
|
+
state[root] = 1
|
|
106
|
+
stack = [iter(children[root])]
|
|
107
|
+
while stack:
|
|
108
|
+
child = next(stack[-1], None)
|
|
109
|
+
if child is None:
|
|
110
|
+
state[path.pop()] = 2
|
|
111
|
+
stack.pop()
|
|
112
|
+
elif state.get(child) == 1:
|
|
113
|
+
return [*path[path.index(child) :], child]
|
|
114
|
+
elif not state.get(child):
|
|
115
|
+
state[child] = 1
|
|
116
|
+
path.append(child)
|
|
117
|
+
stack.append(iter(children[child]))
|
|
118
|
+
return None
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class _Graph:
|
|
122
|
+
"""A graph's nodes, roles, positions, labels, and edges, checked to be a DAG."""
|
|
123
|
+
|
|
124
|
+
def __init__(
|
|
125
|
+
self, source: Any, pos: Mapping[Any, Any] | None = None, y: str | None = None
|
|
126
|
+
) -> None:
|
|
127
|
+
if not _is_digraph(source):
|
|
128
|
+
if _is_graph(source):
|
|
129
|
+
raise FrameworkError(
|
|
130
|
+
"This networkx graph is undirected. A DAG needs a networkx.DiGraph."
|
|
131
|
+
)
|
|
132
|
+
raise FrameworkError(
|
|
133
|
+
"A DAG is a networkx.DiGraph or DAGitty text, such as "
|
|
134
|
+
'publish_dag("dag { x -> y }").'
|
|
135
|
+
)
|
|
136
|
+
if pos is not None and not isinstance(pos, Mapping):
|
|
137
|
+
raise FrameworkError("pos must map node names to (x, y) positions.")
|
|
138
|
+
y = "up" if y is None else y
|
|
139
|
+
if y not in _Y:
|
|
140
|
+
raise FrameworkError('y must be "up", as networkx draws, or "down", as DAGitty reads.')
|
|
141
|
+
# DAGitty's y points down. networkx and matplotlib draw y pointing up.
|
|
142
|
+
self.flip = y == "up"
|
|
143
|
+
latents = {str(node) for node in (getattr(source, "latents", None) or ())}
|
|
144
|
+
self.names: list[str] = []
|
|
145
|
+
self.roles: dict[str, list[str]] = {}
|
|
146
|
+
self.positions: dict[str, tuple[float, float] | None] = {}
|
|
147
|
+
self.labels: dict[str, str] = {}
|
|
148
|
+
names: dict[Any, str] = {}
|
|
149
|
+
for node, attributes in source.nodes(data=True):
|
|
150
|
+
name = _name(node)
|
|
151
|
+
if name in self.roles:
|
|
152
|
+
raise FrameworkError(f"Two nodes are both named {name}.")
|
|
153
|
+
names[node] = name
|
|
154
|
+
self.names.append(name)
|
|
155
|
+
roles = _roles(name, attributes.get("role"))
|
|
156
|
+
if name in latents and "latent" not in roles:
|
|
157
|
+
roles = [role for role in ROLES if role in {*roles, "latent"}]
|
|
158
|
+
self.roles[name] = roles
|
|
159
|
+
given = pos.get(node, pos.get(name)) if pos is not None else None
|
|
160
|
+
if given is None:
|
|
161
|
+
given = attributes.get("pos")
|
|
162
|
+
self.positions[name] = _position(name, given)
|
|
163
|
+
label = attributes.get("label")
|
|
164
|
+
if label is not None and str(label).strip():
|
|
165
|
+
self.labels[name] = str(label)
|
|
166
|
+
if pos is not None:
|
|
167
|
+
unknown = [str(key) for key in pos if key not in names and str(key) not in self.roles]
|
|
168
|
+
if unknown:
|
|
169
|
+
raise FrameworkError(
|
|
170
|
+
f"pos names nodes the graph doesn't have: {', '.join(unknown)}."
|
|
171
|
+
)
|
|
172
|
+
self.edges: list[tuple[str, str, str]] = []
|
|
173
|
+
seen: set[tuple[str, str, str]] = set()
|
|
174
|
+
for start, end, attributes in source.edges(data=True):
|
|
175
|
+
a, b = names[start], names[end]
|
|
176
|
+
if a == b:
|
|
177
|
+
raise FrameworkError(f"{a} points to itself. A DAG has no loops.")
|
|
178
|
+
if attributes.get("bidirected"):
|
|
179
|
+
a, b = sorted((a, b))
|
|
180
|
+
edge = (a, b, "<->")
|
|
181
|
+
else:
|
|
182
|
+
edge = (a, b, "->")
|
|
183
|
+
if edge not in seen:
|
|
184
|
+
seen.add(edge)
|
|
185
|
+
self.edges.append(edge)
|
|
186
|
+
cycle = _cycle(self.names, self.edges)
|
|
187
|
+
if cycle is not None:
|
|
188
|
+
raise FrameworkError(
|
|
189
|
+
f"The graph has a cycle: {' -> '.join(cycle)}. A DAG has none. "
|
|
190
|
+
"Mark an edge that stands for a latent common cause with bidirected=True."
|
|
191
|
+
)
|
|
192
|
+
|
|
193
|
+
def text(self) -> str:
|
|
194
|
+
lines = ["dag {"]
|
|
195
|
+
for name in self.names:
|
|
196
|
+
attributes = list(self.roles[name])
|
|
197
|
+
position = self.positions[name]
|
|
198
|
+
if position is not None:
|
|
199
|
+
x, y = position[0], -position[1] if self.flip else position[1]
|
|
200
|
+
attributes.append(f'pos="{_number(x)},{_number(y)}"')
|
|
201
|
+
lines.append(_quote(name) + (f" [{','.join(attributes)}]" if attributes else ""))
|
|
202
|
+
lines += [f"{_quote(a)} {kind} {_quote(b)}" for a, b, kind in self.edges]
|
|
203
|
+
lines.append("}")
|
|
204
|
+
return "\n".join(lines)
|
|
205
|
+
|
|
206
|
+
|
|
207
|
+
def _classes(source: Any) -> list[tuple[str, str]]:
|
|
208
|
+
return [(cls.__module__.split(".")[0], cls.__name__) for cls in type(source).__mro__]
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def _is_digraph(source: Any) -> bool:
|
|
212
|
+
return ("networkx", "DiGraph") in _classes(source)
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def _is_graph(source: Any) -> bool:
|
|
216
|
+
return ("networkx", "Graph") in _classes(source)
|
|
217
|
+
|
|
218
|
+
|
|
219
|
+
def dagitty(graph: Any, *, pos: Mapping[Any, Any] | None = None, y: str | None = None) -> str:
|
|
220
|
+
"""DAGitty model text for a networkx graph.
|
|
221
|
+
|
|
222
|
+
::
|
|
223
|
+
|
|
224
|
+
import networkx as nx
|
|
225
|
+
|
|
226
|
+
g = nx.DiGraph()
|
|
227
|
+
g.add_node("smoking", role="exposure", label="Smoking status")
|
|
228
|
+
g.add_node("cancer", role="outcome")
|
|
229
|
+
g.add_edges_from([("age", "smoking"), ("age", "cancer"), ("smoking", "cancer")])
|
|
230
|
+
print(fw.dagitty(g))
|
|
231
|
+
|
|
232
|
+
The text opens with ``dag {``, lists every node with its roles and position, then
|
|
233
|
+
every edge. R's dagitty and ggdag and dagitty.net read it. A name that isn't a plain
|
|
234
|
+
identifier, such as ``parental SES``, is double-quoted.
|
|
235
|
+
|
|
236
|
+
The graph's node and edge attributes say what DAGitty needs:
|
|
237
|
+
|
|
238
|
+
- ``role``: ``"exposure"``, ``"outcome"``, ``"latent"``, ``"adjusted"``, or
|
|
239
|
+
``"selected"``, or a list of them. A pgmpy ``DAG``'s ``latents`` are latent too.
|
|
240
|
+
- ``pos``: an ``(x, y)`` position, as ``nx.draw(G, pos)`` takes it: y points up.
|
|
241
|
+
DAGitty's y points down, so y is negated in the text, and the drawing on
|
|
242
|
+
Framework Cloud matches ``nx.draw()``. ``y="down"`` writes positions as they are.
|
|
243
|
+
- ``label``: the name to show. ``dagitty()`` leaves labels out; ``publish_dag()``
|
|
244
|
+
sends them.
|
|
245
|
+
- ``bidirected=True`` on an edge: ``a <-> b``, a latent common cause. The edge's
|
|
246
|
+
direction doesn't matter, and it isn't part of the cycle check.
|
|
247
|
+
|
|
248
|
+
Args:
|
|
249
|
+
graph: A ``networkx.DiGraph``, or a subclass such as pgmpy's ``DAG``.
|
|
250
|
+
pos: Positions by node, such as ``{"age": (0, 0), "smoking": (1, 1)}`` or a
|
|
251
|
+
networkx layout. They win over ``pos`` node attributes.
|
|
252
|
+
y: Which way y points in the positions: ``"up"``, as networkx and matplotlib
|
|
253
|
+
draw, or ``"down"``, as DAGitty reads. Default: ``"up"``.
|
|
254
|
+
|
|
255
|
+
Returns:
|
|
256
|
+
The DAGitty model text.
|
|
257
|
+
|
|
258
|
+
Raises:
|
|
259
|
+
FrameworkError: The graph is undirected or has a directed cycle, a node points to
|
|
260
|
+
itself, or a role or position isn't valid.
|
|
261
|
+
"""
|
|
262
|
+
return _Graph(graph, pos, y).text()
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
# ---------------------------------------------------------------------------
|
|
266
|
+
# The document
|
|
267
|
+
|
|
268
|
+
|
|
269
|
+
def _code(code: str | None) -> dict[str, str] | None:
|
|
270
|
+
if code is None:
|
|
271
|
+
return None
|
|
272
|
+
if not isinstance(code, str):
|
|
273
|
+
raise FrameworkError("code must be the Python code that built the graph, as a string.")
|
|
274
|
+
text = code.strip("\n")
|
|
275
|
+
return {"language": "python", "text": text} if text.strip() else None
|
|
276
|
+
|
|
277
|
+
|
|
278
|
+
def _labels(labels: Mapping[Any, Any] | None) -> dict[str, str]:
|
|
279
|
+
if labels is None:
|
|
280
|
+
return {}
|
|
281
|
+
if not isinstance(labels, Mapping):
|
|
282
|
+
raise FrameworkError('labels must map node names to labels: {"ses": "Parental SES"}.')
|
|
283
|
+
return {str(name): str(label) for name, label in labels.items()}
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def _set(value: Any, what: str) -> list[str]:
|
|
287
|
+
if isinstance(value, str) or not isinstance(value, Iterable):
|
|
288
|
+
raise FrameworkError(f"{what} must be a list of node names.")
|
|
289
|
+
return [str(name) for name in value]
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def _analysis(analysis: Mapping[str, Any] | None) -> dict[str, Any] | None:
|
|
293
|
+
"""The producer's analysis, checked for shape. Framework computes none of it."""
|
|
294
|
+
if analysis is None:
|
|
295
|
+
return None
|
|
296
|
+
if not isinstance(analysis, Mapping):
|
|
297
|
+
raise FrameworkError('analysis must be a dict, such as {"adjustment_sets": [["age"]]}.')
|
|
298
|
+
unknown = sorted(set(analysis) - {"effect", "adjustment_sets", "implications"})
|
|
299
|
+
if unknown:
|
|
300
|
+
raise FrameworkError(
|
|
301
|
+
f"analysis takes effect, adjustment_sets, and implications, not {', '.join(unknown)}."
|
|
302
|
+
)
|
|
303
|
+
out: dict[str, Any] = {}
|
|
304
|
+
effect = analysis.get("effect")
|
|
305
|
+
if effect is not None:
|
|
306
|
+
if effect not in _EFFECTS:
|
|
307
|
+
raise FrameworkError('analysis["effect"] must be "total" or "direct".')
|
|
308
|
+
out["effect"] = effect
|
|
309
|
+
if analysis.get("adjustment_sets") is not None:
|
|
310
|
+
sets = analysis["adjustment_sets"]
|
|
311
|
+
if isinstance(sets, str) or not isinstance(sets, Iterable):
|
|
312
|
+
raise FrameworkError(
|
|
313
|
+
'analysis["adjustment_sets"] must be a list of sets of node names: '
|
|
314
|
+
"[[]] when no adjustment is needed, [] when no set works."
|
|
315
|
+
)
|
|
316
|
+
out["adjustment_sets"] = [_set(item, "Each adjustment set") for item in sets]
|
|
317
|
+
if analysis.get("implications") is not None:
|
|
318
|
+
implications = []
|
|
319
|
+
for item in analysis["implications"]:
|
|
320
|
+
if not isinstance(item, Mapping) or "x" not in item or "y" not in item:
|
|
321
|
+
raise FrameworkError(
|
|
322
|
+
'Each implication is {"x": "a", "y": "b", "given": ["c"]}: x is '
|
|
323
|
+
"independent of y given the nodes in given."
|
|
324
|
+
)
|
|
325
|
+
implications.append(
|
|
326
|
+
{
|
|
327
|
+
"x": str(item["x"]),
|
|
328
|
+
"y": str(item["y"]),
|
|
329
|
+
"given": _set(item.get("given") or [], "given"),
|
|
330
|
+
}
|
|
331
|
+
)
|
|
332
|
+
out["implications"] = implications
|
|
333
|
+
return out or None
|
|
334
|
+
|
|
335
|
+
|
|
336
|
+
def _document(
|
|
337
|
+
graph: Any,
|
|
338
|
+
*,
|
|
339
|
+
labels: Mapping[Any, Any] | None = None,
|
|
340
|
+
code: str | None = None,
|
|
341
|
+
analysis: Mapping[str, Any] | None = None,
|
|
342
|
+
pos: Mapping[Any, Any] | None = None,
|
|
343
|
+
y: str | None = None,
|
|
344
|
+
) -> dict[str, Any]:
|
|
345
|
+
"""The ``dag`` document for a graph or DAGitty text."""
|
|
346
|
+
shown = _labels(labels)
|
|
347
|
+
if isinstance(graph, Path):
|
|
348
|
+
if not graph.is_file():
|
|
349
|
+
raise FrameworkError(f"DAGitty file not found: {graph}")
|
|
350
|
+
graph = graph.read_text(encoding="utf-8")
|
|
351
|
+
if isinstance(graph, str):
|
|
352
|
+
if pos is not None:
|
|
353
|
+
raise FrameworkError('pos is for networkx graphs. In DAGitty text, write pos="x,y".')
|
|
354
|
+
if y not in (None, "down"):
|
|
355
|
+
raise FrameworkError("DAGitty text is sent as written, with y pointing down.")
|
|
356
|
+
text = graph.strip()
|
|
357
|
+
if not text:
|
|
358
|
+
raise FrameworkError("The DAGitty text is empty.")
|
|
359
|
+
source: dict[str, Any] = {"language": "python"}
|
|
360
|
+
else:
|
|
361
|
+
parsed = _Graph(graph, pos, y)
|
|
362
|
+
unknown = sorted(set(shown) - set(parsed.names))
|
|
363
|
+
if unknown:
|
|
364
|
+
raise FrameworkError(
|
|
365
|
+
f"labels names nodes the graph doesn't have: {', '.join(unknown)}."
|
|
366
|
+
)
|
|
367
|
+
shown = {**parsed.labels, **shown}
|
|
368
|
+
text = parsed.text()
|
|
369
|
+
source = {
|
|
370
|
+
"language": "python",
|
|
371
|
+
"class": [
|
|
372
|
+
f"{cls.__module__}.{cls.__name__}"
|
|
373
|
+
for cls in type(graph).__mro__
|
|
374
|
+
if cls is not object
|
|
375
|
+
],
|
|
376
|
+
}
|
|
377
|
+
document: dict[str, Any] = {"schema": SCHEMA, "kind": KIND, "source": source, "dagitty": text}
|
|
378
|
+
if shown:
|
|
379
|
+
document["labels"] = shown
|
|
380
|
+
written = _code(code)
|
|
381
|
+
if written is not None:
|
|
382
|
+
document["code"] = written
|
|
383
|
+
checked = _analysis(analysis)
|
|
384
|
+
if checked is not None:
|
|
385
|
+
document["analysis"] = checked
|
|
386
|
+
return document
|
|
387
|
+
|
|
388
|
+
|
|
389
|
+
def structured(graph: Any) -> dict[str, Any]:
|
|
390
|
+
"""The document ``publish()`` sends for a networkx graph."""
|
|
391
|
+
return _document(graph)
|
|
392
|
+
|
|
393
|
+
|
|
394
|
+
# ---------------------------------------------------------------------------
|
|
395
|
+
# Publishing
|
|
396
|
+
|
|
397
|
+
|
|
398
|
+
def publish_dag(
|
|
399
|
+
graph: Any,
|
|
400
|
+
*,
|
|
401
|
+
labels: Mapping[Any, Any] | None = None,
|
|
402
|
+
code: str | None = None,
|
|
403
|
+
analysis: Mapping[str, Any] | None = None,
|
|
404
|
+
pos: Mapping[Any, Any] | None = None,
|
|
405
|
+
y: str | None = None,
|
|
406
|
+
slug: str | None = None,
|
|
407
|
+
title: str | None = None,
|
|
408
|
+
description: str | None = None,
|
|
409
|
+
visibility: str | None = None,
|
|
410
|
+
password: str | None = None,
|
|
411
|
+
collection: str | int | None = None,
|
|
412
|
+
share_unlisted: bool = False,
|
|
413
|
+
to: str | None = None,
|
|
414
|
+
include_private: bool = False,
|
|
415
|
+
) -> str | list[str]:
|
|
416
|
+
"""Publish a causal diagram (DAG) to Framework Cloud.
|
|
417
|
+
|
|
418
|
+
::
|
|
419
|
+
|
|
420
|
+
g = nx.DiGraph()
|
|
421
|
+
g.add_node("education", role="exposure")
|
|
422
|
+
g.add_node("health", role="outcome")
|
|
423
|
+
g.add_edges_from([("income", "education"), ("income", "health"),
|
|
424
|
+
("education", "health")])
|
|
425
|
+
fw.publish_dag(g, slug="education-health", code=CODE,
|
|
426
|
+
analysis={"adjustment_sets": [["income"]]})
|
|
427
|
+
|
|
428
|
+
fw.publish_dag("dag { smoking [exposure] cancer [outcome] smoking -> cancer }",
|
|
429
|
+
slug="smoking")
|
|
430
|
+
|
|
431
|
+
A ``networkx.DiGraph`` becomes DAGitty text as ``dagitty()`` writes it: roles,
|
|
432
|
+
positions, and labels come from node attributes, and ``bidirected=True`` on an edge
|
|
433
|
+
makes it ``<->``. Positions are read as ``nx.draw(G, pos)`` reads them, with y
|
|
434
|
+
pointing up, so the drawing on Framework Cloud matches. A string is DAGitty text,
|
|
435
|
+
sent as it is, with DAGitty's y pointing down; a ``Path`` names a ``.dagitty`` file.
|
|
436
|
+
``publish(graph)`` publishes a networkx graph too, without code or analysis.
|
|
437
|
+
|
|
438
|
+
Framework Cloud checks the graph, lays it out, and draws it, with the DAGitty text
|
|
439
|
+
and the code to copy. A graph with a cycle, an undirected edge, more than 100 nodes,
|
|
440
|
+
or more than 400 edges is refused. Framework computes no adjustment sets or
|
|
441
|
+
implications. Pass what another tool found in ``analysis``.
|
|
442
|
+
|
|
443
|
+
Args:
|
|
444
|
+
graph: A ``networkx.DiGraph`` (or pgmpy ``DAG``), DAGitty text, or a ``Path`` to a
|
|
445
|
+
``.dagitty`` file.
|
|
446
|
+
labels: Display labels by node name. They win over ``label`` node attributes.
|
|
447
|
+
code: The Python code that built the graph, shown with it.
|
|
448
|
+
analysis: What the producer computed: ``effect`` (``"total"`` or ``"direct"``),
|
|
449
|
+
``adjustment_sets`` (a list of lists of names: ``[[]]`` when no adjustment is
|
|
450
|
+
needed, ``[]`` when no set works), and ``implications`` (``{"x", "y",
|
|
451
|
+
"given"}`` conditional independencies).
|
|
452
|
+
pos: Positions by node, such as ``{"age": (0, 0)}`` or a networkx layout. For
|
|
453
|
+
networkx graphs.
|
|
454
|
+
y: Which way y points in a graph's positions: ``"up"``, as networkx and
|
|
455
|
+
matplotlib draw, or ``"down"``, as DAGitty reads. Default: ``"up"``.
|
|
456
|
+
DAGitty text is always read with y pointing down.
|
|
457
|
+
slug: Artifact slug. Default: from ``title``, else ``dag``. Name each DAG, or a
|
|
458
|
+
second one publishes as a new version of the first.
|
|
459
|
+
title: Artifact title. Default: the slug.
|
|
460
|
+
description: Artifact description.
|
|
461
|
+
visibility: "public", "unlisted", or "private". Default: a new artifact is
|
|
462
|
+
unlisted and an existing one keeps its setting.
|
|
463
|
+
password: Password required to view the DAG.
|
|
464
|
+
collection: Project collection ID or slug.
|
|
465
|
+
share_unlisted: Allow collection readers to see an unlisted DAG.
|
|
466
|
+
to: A configured destination name, or "cloud".
|
|
467
|
+
include_private: Publish without asking about private folders.
|
|
468
|
+
|
|
469
|
+
Returns:
|
|
470
|
+
The artifact's URL.
|
|
471
|
+
"""
|
|
472
|
+
from framework.publish_bundle import artifact_slug
|
|
473
|
+
from framework.storage import publish
|
|
474
|
+
|
|
475
|
+
document = _document(graph, labels=labels, code=code, analysis=analysis, pos=pos, y=y)
|
|
476
|
+
slug = slug or (artifact_slug(title) if title else None)
|
|
477
|
+
with tempfile.TemporaryDirectory(prefix="fw_dag_") as temp:
|
|
478
|
+
path = Path(temp) / "dag.json"
|
|
479
|
+
path.write_text(json.dumps(document, ensure_ascii=False, indent=2), encoding="utf-8")
|
|
480
|
+
return publish(
|
|
481
|
+
path,
|
|
482
|
+
kind=KIND,
|
|
483
|
+
slug=slug,
|
|
484
|
+
title=title,
|
|
485
|
+
description=description,
|
|
486
|
+
visibility=visibility,
|
|
487
|
+
password=password,
|
|
488
|
+
collection=collection,
|
|
489
|
+
share_unlisted=share_unlisted,
|
|
490
|
+
to=to,
|
|
491
|
+
include_private=include_private,
|
|
492
|
+
)
|
framework/storage.py
CHANGED
|
@@ -469,7 +469,7 @@ def _publish_legacy(
|
|
|
469
469
|
with tempfile.TemporaryDirectory(prefix="fw_artifact_") as temp:
|
|
470
470
|
is_cloud = to != "github" and _target(connection, to) == "cloud"
|
|
471
471
|
path = _artifact_file(source, Path(temp), cloud=is_cloud)
|
|
472
|
-
if kind is None and is_cloud and path.name in ("table.json", "model.json"):
|
|
472
|
+
if kind is None and is_cloud and path.name in ("table.json", "model.json", "dag.json"):
|
|
473
473
|
kind = path.stem
|
|
474
474
|
return _publish_legacy(
|
|
475
475
|
path,
|
|
@@ -567,6 +567,7 @@ def publish(
|
|
|
567
567
|
(every row is kept), tests and models become structured summaries, and static
|
|
568
568
|
plots become SVG. Model exports carry coefficients, importance, and fit
|
|
569
569
|
statistics, never observations, residuals, posterior draws, or serialized models.
|
|
570
|
+
A ``networkx.DiGraph`` becomes a DAG (see ``publish_dag()``).
|
|
570
571
|
Buckets receive CSV tables, PNG figures, and HTML model summaries; Styler tables,
|
|
571
572
|
plotly figures, and altair charts keep their HTML or Vega-Lite form everywhere.
|
|
572
573
|
dest: Where to put it in the bucket. Default: the source's name.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: framework-py
|
|
3
|
-
Version: 0.1.0.
|
|
3
|
+
Version: 0.1.0.dev34
|
|
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,7 +1,7 @@
|
|
|
1
|
-
framework/__init__.py,sha256=
|
|
1
|
+
framework/__init__.py,sha256=oNThlKgpfAON6v0upCbudEDfJeFxQ8EPw8v6ch79-PQ,6980
|
|
2
2
|
framework/__main__.py,sha256=S0ChmRQnNa9W5_MPXhHnH61Kjr_pNthkeS41eJU1w0U,9093
|
|
3
3
|
framework/_agents_md.py,sha256=yI_8YYF3D3zqNNZs5skzGQMLTgL9KH35L_Ben_vUY5I,15803
|
|
4
|
-
framework/_artifacts.py,sha256=
|
|
4
|
+
framework/_artifacts.py,sha256=Svc2m3vR4_g5FlT7U0EF5OtDQj89fGi6IJUevLS8Wjk,55930
|
|
5
5
|
framework/_backups.py,sha256=ra1DhGcIbIXB0zqDFVFJ3yPEjmXpYKFX-fjV01b9Rtg,1958
|
|
6
6
|
framework/_bayesian.py,sha256=Yx8deM_LWsfPPM8n3rX7b1R9L1qcdeaDU2aUIZZyhB4,23675
|
|
7
7
|
framework/_csv.py,sha256=oAaLUChyUsHJsh0YuUDt0viC8SAImMgUseNKGk7kLXo,4855
|
|
@@ -32,6 +32,7 @@ framework/config_home.py,sha256=iSb0VuENgNOSnsZ_v53xFqjRiGgrB7OzZbHbyDOqKzs,8265
|
|
|
32
32
|
framework/connections.py,sha256=99JqrNAi2zBpNYyxLV6SYj-NAJjh56pYh9jaMSYOHCU,32742
|
|
33
33
|
framework/console.py,sha256=zQ0LuFDcxe1W1kuc5E1bJ03h8d3cvwFoqDT8dAJQyN0,1267
|
|
34
34
|
framework/create.py,sha256=KSODHvnRFrSha79LH-0e4o1y_3e1ZjbTrjCDzQbhbYk,54728
|
|
35
|
+
framework/dags.py,sha256=I00zMb10ZUGWUw3P9P1zOW14GxfO-pUtQ97Y5cZx9pY,20134
|
|
35
36
|
framework/data.py,sha256=jWWkUeLey_FxOafsFrwKhoJoVXb9NguNcjhsd_laDL0,41817
|
|
36
37
|
framework/data_registry.py,sha256=QrFki_-zd7gF4afOesYPAn7xZEvnhYolhxtz_0bsaSA,22477
|
|
37
38
|
framework/db.py,sha256=UYEUCvk4vGytBkmdNTUxRpYPtoFSDHwTpgpfWFw31aE,8522
|
|
@@ -56,7 +57,7 @@ framework/settings.py,sha256=Sb2YyE53aYLWPj423P-pQVCvRpLsiHydgZh2K0luTQQ,23893
|
|
|
56
57
|
framework/skill_pull.py,sha256=BsprrVhv4khrXQJupAChLi_s0qJLmA0KBrfrTD6A_9k,75964
|
|
57
58
|
framework/skill_sync.py,sha256=2xPcEIN_ftjX4QpA4ZkRzjFHS9rkoIHcnKPO59eKr8U,35813
|
|
58
59
|
framework/snippets.py,sha256=J8j36YqHgG-HhWlhJ9RmJK-qwVGOOSOOd1pNakJyuVE,26481
|
|
59
|
-
framework/storage.py,sha256=
|
|
60
|
+
framework/storage.py,sha256=ohF5OT2EJoMYMJHuLJGhv3pnapxEsRnpjW3RH_xoBK0,56201
|
|
60
61
|
framework/sync_all.py,sha256=hcp-EYI8OVV9l40S4S8Iu0-2k7CUbF6faBcrRD3Up3M,36757
|
|
61
62
|
framework/upgrade.py,sha256=vMtL9_04LgJ4AHj6EXg5PmV3n699XvFNj820Auqa0hM,66546
|
|
62
63
|
framework/_assets/init.sql,sha256=-aIiuIcCmBniGKq-CHdRtUiV9e_CLXoqxxd05snmgOE,1156
|
|
@@ -142,7 +143,7 @@ framework/templates/stubs/notebook-default.qmd,sha256=8Js1S2BcHYeQWmJS-kt31gBvIj
|
|
|
142
143
|
framework/templates/stubs/notebook-minimal.qmd,sha256=2U2k8judffhrh_6m6r6OAbQBCYEtViAjeKRBqBYCJTM,178
|
|
143
144
|
framework/templates/stubs/notebook-revealjs.qmd,sha256=_ztT_gHoudpB5DIjlbvtB5zQ8163DeV8xbWcT-HgJrI,409
|
|
144
145
|
framework/templates/stubs/script-default.py,sha256=vbWqgW0_rHot17mQC3tYb92g_9L-cbTOeL3y99BRrSk,216
|
|
145
|
-
framework_py-0.1.0.
|
|
146
|
-
framework_py-0.1.0.
|
|
147
|
-
framework_py-0.1.0.
|
|
148
|
-
framework_py-0.1.0.
|
|
146
|
+
framework_py-0.1.0.dev34.dist-info/METADATA,sha256=gcsZlhWG0LmoOntREDlWlXad4fpHbJ0I7WZqSeN9ZIs,5143
|
|
147
|
+
framework_py-0.1.0.dev34.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
148
|
+
framework_py-0.1.0.dev34.dist-info/licenses/LICENSE,sha256=giOOgSwALkZimC7uhLZQK8Untez641bLW1-2-Cjvmq0,1072
|
|
149
|
+
framework_py-0.1.0.dev34.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|