Succession api and docs

[jcrozum]

This PR updates much of the SuccessionDiagram documentation and API (according to #93).

Changes to the API are reflected in other files (hence the large number of changed files).

For us, the main changes are

• SuccessionDiagram.from_bnet and similar are removed in favor of SuccessionDiagram.from_rules, which takes a format argument ("bnet" by default). The from_file function is kept separate.
• Many of the SuccessionDiagram.node_... functions are replaced by a SuccessionDiagram.node_data function that returns the node dictionary, cast to a NodeData object that inherits from TypedDict. This should not have any impact on performance, since we were accessing that node dictionary anyway (just casting the values instead of the whole thing). Now, for example, you should access sd.node_data(x)["depth"] instead of sd.node_depth(x). Replaced functions are
  • node_depth -> "depth"
  • node_restricted_petri_net -> "petri_net"
  • node_is_expanded -> "expanded"
  • node_space -> "space"
  • "attractors" is included (no function for this previously)
    Functions NOT replaced (yet?):
  • node_nfvs (actually a network thing, not an sd-node thing)
  • node_attractor_seeds (because of the compute option)
  • node_successors (because it needs network info)
  • node_is_minimal (again, needs network info)
• I added SuccessionDiagram.expanded_attractor_seeds for quickly getting attractors out of the object.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
balm
control.py	114	14	88%	102, 114, 120, 124, 129, 138–154, 472, 475, 488
interaction_graph_utils.py	30	4	87%	6–8, 145–146
motif_avoidant.py	152	2	99%	25, 124
petri_net_translation.py	148	11	93%	18–22, 58, 94, 207–208, 232–233, 242, 346
space_utils.py	129	4	97%	25–27, 252, 278
succession_diagram.py	257	16	94%	6, 184–189, 197, 257–258, 268, 274, 390, 580, 772, 810, 847
symbolic_utils.py	26	3	88%	10–12, 44
trappist_core.py	183	30	84%	11–15, 45, 47, 82, 129, 195, 197, 199, 227–230, 234–236, 256–262, 320, 322, 352, 392, 394, 425, 454
balm/_sd_algorithms
compute_attractor_seeds.py	30	1	97%	8
expand_attractor_seeds.py	51	5	90%	6, 42, 97–102
expand_bfs.py	28	1	96%	6
expand_dfs.py	30	1	97%	6
expand_minimal_spaces.py	37	2	95%	6, 31
expand_source_SCCs.py	164	6	96%	19–21, 91, 101, 143, 287
expand_to_target.py	31	3	90%	6, 38, 43
TOTAL	1471	103	93%

Tests	Skipped	Failures	Errors	Time
361	0 💤	0 ❌	0 🔥	49.761s ⏱️

[daemontus]

I see no immediate issues. We can merge this :)