pyphi.visualize.plot_ces#

pyphi.visualize.plot_ces(ces_, *, view='lattice', theme=Theme(colorscale='Viridis', node_size_range=(10.0, 36.0), edge_color='rgba(60, 60, 60, 0.4)', edge_width=2.0, font_family='Helvetica, Arial, sans-serif', background='white', role_colors=(('extended', '#e6b422'), ('includes', '#2f6fdb'), ('included', '#d85a46'), ('none', '#b0b0b0')), cause_color='#8D3D00', effect_color='#006146', face_colorscale='Blues', face_opacity=0.2, text_size=12, spoke_width=1.5, spoke_curvature=0.0, spoke_color='rgba(100, 100, 100, 0.45)', hub_size_range=(4.0, 22.0), relation_rgb=(35, 45, 200), relation_alpha_range=(0.06, 0.95)), node_labels=None, fig=None, layout='barycentric', order='mechanism', rank='chain', size_by='sum_phi_relations', color_by=None, geometry=None, show=None, degrees=None, star_min_degree=None, max_relations=None)[source]#

Plot a CauseEffectStructure.

Parameters:

  • ces (CauseEffectStructure) – The cause-effect structure to plot (distinctions and relations).

  • view (str, optional) –

    Which rendering of the structure to produce.

    "lattice"

    An inclusion partial order over the distinctions drawn as a 2-D Hasse diagram, with marker size given by each distinction’s total relation φ and color by its φ.

    "hypergraph"

    The 3-D view with cause/effect purviews as vertices and relation faces drawn as star expansions (hub + spokes) by default; raise star_min_degree to keep degree-2 faces as line segments and degree-3 faces as triangles.

    "scatter"

    Distinctions on a deterministic PCA embedding of their unit composition, sized by total relation φ and colored by relational role.

    "matrix"

    A distinctions-by-distinctions heatmap of shared relation φ, with self-relation strength on the diagonal.

    "spectrum"

    A 2-D bar panel of relation count and sum of φ per relation degree, summarizing the high-degree structure.

  • theme (Theme, optional) – Visual theme.

  • node_labels (NodeLabels, optional) – Labels for substrate units. Defaults to the labels carried by the distinctions.

  • fig (plotly.graph_objects.Figure, optional) – An existing plotly figure to draw into.

  • layout (str, optional) – Within-level ordering. In the lattice view, "barycentric" orders each rank by the mean position of its cover neighbors to reduce edge crossings; in the hypergraph view it orders each shell ring so subsets connected by drawn elements sit at nearby angles, shortening edges. "sorted" orders by label in both views. "embedding" (hypergraph view) ignores the shells and positions each MICE by a deterministic embedding of its composition (HypergraphGeometry.embedding_method selects "mds", the default, or "pca"), so proximity reflects compositional similarity.

  • order (str, optional) – Which partial order the lattice view shows: "mechanism" orders distinctions by subset relation on their mechanisms; "purview_union" by subset relation on the unions of their cause and effect purviews.

  • rank (str, optional) – Vertical placement in the lattice view: "chain" places each distinction at its longest-down-chain rank (compact); "size" at the cardinality of its mechanism or purview union, leaving gaps at sizes with no distinctions.

  • size_by (str, optional) – Marker size encoding (lattice and scatter views): "sum_phi_relations", "phi", or None for uniform markers.

  • color_by (str, optional) – Marker color encoding (lattice and scatter views). None (the default) uses the view’s default — "phi" for the lattice, "role" for the scatter. Both views accept "phi" and "sum_phi_relations"; the scatter additionally accepts "role".

  • geometry (HypergraphGeometry, optional) – Layout knobs for the hypergraph view.

  • show (tuple of str, optional) – Element classes the hypergraph view draws. Defaults to all of them.

  • degrees (tuple of int, optional) – Restrict the hypergraph view to relation faces of these degrees. Defaults to all degrees present.

  • star_min_degree (int, optional) – In the hypergraph view, the lowest relation-face degree drawn as a star expansion (hub + spokes); lower degrees keep their geometric form (degree-2 lines, degree-3 triangles). Must be 2, 3, or 4. 2 (the default) draws every face as a star; 4 keeps degree-2 lines and degree-3 triangles.

  • max_relations (int, optional) – Render only the strongest max_relations relations by φ_r. If None, every relation is rendered when the set is enumerable; analytically computed relations (not enumerable) default to the strongest 1000. Node sizes and the spectrum view remain exact regardless.

Raises:

  • TypeError – If ces_ is not relation-closed (e.g. a PhiFold); use highlight_phi_fold() to render a fold against its parent structure.

  • ValueError – If view is not one of the recognized view names.