HTML visualisation of a full event history as a directed acyclic graph (DAG).

Parameters:¶

output : str or Path¶

Location to which the HTML file should be written.

edges : iterable[tuple[int, int]]¶

COO format adjacency, referring to edges by the pairs of source and destination vertices, respectively.

pdgs : iterable[int]¶

PDG codes for each particle in the DAG.

masks : sequence[iterable[bool]] or mapping[str, iterable[bool]]¶

Optional masks grouping particles. Usually refers to the particle ancestries. Each group will be represented with a different color in the visualisation. Where masks overlap, their colors will be blended. Default is None.

width : str or int¶

Width of the IFrame containing the visualisation. Default is "100%".

height : str or int¶

height of the IFrame containing the visualisation. Default is 750.

notebook : bool¶

If running in a Jupyter Notebook, passing True will render the visualisation as the output of the cell. Default is False.

hover_width : int¶

Number of characters in node hover labels to allow per line, before text-wrapping. Default is 80.

Returns:¶

If notebook parameter is passed True, this function returns an IFrame containing the HTML visualisation.

Return type:¶

IFrame or None

Raises:¶

ValueError – If masks is passed nested mapping, ie. a dict-of-dicts, or a non-flat graphicle.MaskGroup instance.

Notes

Particles are represented by edges on this plot. Therefore, edges, pdgs, and the elements of masks must all have the same length.

Dimensions of the IFrame given by width and height are inferred as pixels if passed integers. Any common browser unit of length may be used if passed as strings.

masks must be “flat”, ie. all the iterables of booleans must be at the top level of the passed data structure. If using the graphicle package, you may use MaskGroup.flatten() to ensure this is properly handled.

Examples

Generating and plotting a top pair production using showerpipe and graphicle, highlighting the descendants of the top quarks.

>>> import showerpipe as shp
... import graphicle as gcl
... import colliderscope as csp
...
>>> gen = shp.generator.PythiaGenerator(
...     "pythia-settings.cmnd", "top-events.lhe.gz", None
... )
... graph = gcl.Graphicle.from_event(next(gen))
... hier = gcl.select.hierarchy(graph)
... print(hier)
MaskGroup(agg_op=OR)
├── t
│   ├── b
│   ├── W+
│   │   ├── u
│   │   ├── d~
│   │   └── latent
│   └── latent
└── t~
    ├── b~
    ├── W-
    │   ├── d
    │   ├── u~
    │   └── latent
    └── latent
>>> masks = hier.flatten("agg")  # flatten nested levels
... print(masks)
MaskGroup(agg_op=OR)
├── t
└── t~
>>> csp.shower_dag("top_dag.html", graph.adj, graph.pdg, masks)