topologicpy.Plotly module

class topologicpy.Plotly.Plotly

Bases: object

Methods

AddColorBar(figure[, values, nTicks, ...])	Adds an independent scalar colour bar to a Plotly figure.
ColorScale([colorScale])	Returns a Plotly scale, including syntax (Depthmap Classic) and syntax_r.
Colors()	Returns the list of named CSS colors that plotly can use.
DataByGraph(graph[, sagitta, absolute, ...])	Render a TGraph; retained as a public plotting method name.
DataByProofGraph([proofGraphData, result, ...])	Creates Plotly traces for a proof graph.
DataByTGraph(graph[, sagitta, absolute, ...])	Creates Plotly traces from a topologicpy.TGraph.
DataByTopology(topology[, showVertices, ...])	Creates Plotly data from a Topologic topology.
ExportToImage(figure, path[, format, width, ...])	Exports a Plotly figure to a static image using the current Kaleido pathway.
FigureByConfusionMatrix(matrix[, ...])	Returns a Plotly Figure of the input confusion matrix.
FigureByCorrelation(actual, predicted[, ...])	Creates a parity/correlation plot for paired actual and predicted values.
FigureByData(data[, width, height, xAxis, ...])	Creates a Plotly figure from a list of traces.
FigureByDataFrame(dataFrame[, labels, ...])	Returns a Plotly figure from a pandas-compatible dataframe.
FigureByJSONFile(file)	Imports a Plotly figure from an open JSON file object or path-like object.
FigureByJSONPath(path)	Imports a Plotly figure from a JSON file path.
FigureByMatrix(matrix[, xCategories, ...])	Returns a Plotly Figure of the input matrix.
FigureByPieChart(data, values, names)	Creates a plotly pie chart figure.
FigureByProofGraph([proofGraphData, result, ...])	Creates a Plotly figure for a proof graph.
FigureByTopology(topology[, showVertices, ...])	Creates a Plotly figure from a Topologic topology.
FigureExportToJSON(figure, path[, overwrite])	Exports a Plotly figure to JSON.
FigureExportToPDF(figure, path[, width, ...])	Exports a Plotly figure to PDF.
FigureExportToPNG(figure, path[, width, ...])	Exports a Plotly figure to PNG.
FigureExportToSVG(figure, path[, width, ...])	Exports a Plotly figure to SVG.
ProofGraphHTML([proofGraphData, result, ...])	Exports a proof graph visualisation to an HTML file.
Renderer()	Return the renderer most suitable for the environment in which the script is running.
Renderers()	Returns the Plotly renderers available in the current installation.
SetCamera(figure[, camera, center, up, ...])	Sets the 3D scene camera of a Plotly figure.
Show(figure[, camera, center, up, renderer, ...])	Displays a Plotly figure without silently overwriting its existing camera.
edgeData(vertices, edges[, dictionaries, ...])	Creates Plotly line traces from indexed straight or sampled curved edges.
vertexData(vertices[, dictionaries, color, ...])	Creates Plotly vertex traces with source-correct labels, styles, and hover text.

static AddColorBar(figure, values=None, nTicks=5, xPosition=-0.15, width=15, outlineWidth=0, title='', subTitle='', units='', colorScale='viridis', mantissa: int = 6)

Adds an independent scalar colour bar to a Plotly figure.

static ColorScale(colorScale: str = 'viridis')

Returns a Plotly scale, including syntax (Depthmap Classic) and syntax_r.

static Colors()

Returns the list of named CSS colors that plotly can use.

Returns

list

The list of named CSS colors.

static DataByGraph(graph, sagitta: float = 0, absolute: bool = False, sides: int = 8, angle: float = 0, directed: bool = False, arrowSize: int = 0.1, arrowSizeKey: str = None, vertexColor: str = 'black', vertexColorKey: str = None, vertexSize: float = 10, vertexSizeKey: str = None, vertexLabelKey: str = None, vertexBorderColor: str = 'black', vertexBorderWidth: float = 0, vertexBorderColorKey: str = None, vertexBorderWidthKey: float = None, vertexGroupKey: str = None, vertexGroups: list = None, vertexMinGroup=None, vertexMaxGroup=None, showVertices: bool = True, showVertexLabel: bool = False, vertexLabelFontSize: int = 5, showVertexLegend: bool = False, vertexLegendLabel='Graph Vertices', vertexLegendRank=4, vertexLegendGroup=4, edgeColor: str = 'red', edgeColorKey: str = None, edgeWidth: float = 1, edgeWidthKey: str = None, edgeDash: bool = False, edgeDashKey: str = None, edgeLabelKey: str = None, edgeGroupKey: str = None, edgeGroups: list = None, edgeMinGroup=None, edgeMaxGroup=None, showEdges: bool = True, showEdgeLabel: bool = False, showEdgeLegend: bool = False, edgeLegendLabel='Graph Edges', edgeLegendRank=5, edgeLegendGroup=5, colorScale: str = 'viridis', mantissa: int = 6, silent: bool = False)

Render a TGraph; retained as a public plotting method name.

static DataByProofGraph(proofGraphData=None, result=None, triple=None, graph=None, layout: str = 'tree', useExistingCoordinates: bool = True, showNodes: bool = True, showEdges: bool = True, showNodeLabel: bool = True, showEdgeLabel: bool = False, nodeLabelKey: str = 'label', edgeLabelKey: str = 'label', nodeTypeKey: str = 'type', edgeTypeKey: str = 'type', nodeSize: float = 12, ruleNodeSize: float = 15, factNodeSize: float = 12, literalNodeSize: float = 9, edgeWidth: float = 3, levelSpacing: float = 1.8, nodeSpacing: float = 1.35, radialRadiusStep: float = 1.5, forceIterations: int = 120, forceScale: float = 1.0, showLegend: bool = True, hover: bool = True, mantissa: int = 6, silent: bool = False)

Creates Plotly traces for a proof graph.

This method is designed for the explainable reasoning workflow in topologicpy.Reasoner. It accepts a proof-graph data dictionary, a proof TGraph, or an inference result and triple from which proof-graph data can be requested.

The expected dictionary format is intentionally permissive:

{"nodes": [...], "edges": [...]}

where each node may contain id, label, type/kind, depth/level, x, y, and z; and each edge may contain source/src/from, target/dst/to, label, and type/role. This loose contract allows the method to consume proof data from Reasoner, KnowledgeGraph, or user-authored dictionaries.

Parameters

proofGraphDatadict or topologicpy.TGraph , optional

The proof graph data or proof TGraph. Default is None.

resultobject , optional

An inference result returned by Reasoner.Infer or TGraph.InferOntology. Used only when proofGraphData is None.

tripletuple or list , optional

The inferred triple to explain. Used only when proofGraphData is None.

graphobject , optional

Optional source TGraph/RDF graph to pass to Reasoner when deriving proofGraphData. Default is None.

layoutstr , optional

The layout to use. Options include “tree”, “radial”, and “force”. Default is “tree”.

useExistingCoordinatesbool , optional

If True, existing node coordinates in proofGraphData are used when available. Default is True.

showNodes, showEdgesbool , optional

Controls visibility of proof graph nodes and edges.

showNodeLabel, showEdgeLabelbool , optional

Controls permanent text labels.

nodeLabelKey, edgeLabelKeystr , optional

Dictionary keys used for node and edge labels.

nodeTypeKey, edgeTypeKeystr , optional

Dictionary keys used for node and edge type classification.

nodeSize, ruleNodeSize, factNodeSize, literalNodeSizefloat , optional

Marker sizes.

edgeWidthfloat , optional

Line width for proof graph edges.

levelSpacing, nodeSpacing, radialRadiusStepfloat , optional

Layout spacing controls.

forceIterationsint , optional

Number of iterations for the force-directed layout.

forceScalefloat , optional

Scale factor for force-directed layout coordinates.

showLegendbool , optional

If True, show node/edge legends.

hoverbool , optional

If True, attach dictionary metadata to hover text.

mantissaint , optional

Number of decimal places to round coordinates.

silentbool , optional

If True, suppress warnings.

Returns

list or None

A list of Plotly traces, or None if proof graph data cannot be derived.

static DataByTGraph(graph, sagitta: float = 0, absolute: bool = False, sides: int = 16, angle: float = 0, directed: bool = None, showBidirectionalArrows: bool = True, arrowSize: float = 0.15, arrowSizeKey: str = None, vertexColor: str = 'black', vertexColorKey: str = 'color', vertexSize: float = 10, vertexSizeKey: str = 'size', vertexShape: str = 'circle', vertexShapeKey: str = None, vertexLabelKey: str = None, vertexBorderColor: str = 'black', vertexBorderWidth: float = 0, vertexBorderColorKey: str = None, vertexBorderWidthKey: str = None, vertexGroupKey: str = None, vertexGroups: list = None, vertexMinGroup=None, vertexMaxGroup=None, showVertices: bool = True, showVertexLabel: bool = False, vertexLabelFontSize: int = 10, showVertexLegend: bool = False, vertexLegendLabel: str = 'TGraph Vertices', vertexLegendRank: int = 4, vertexLegendGroup: int = 4, edgeColor: str = 'red', edgeColorKey: str = 'color', edgeWidth: float = 2, edgeWidthKey: str = 'width', edgeDash: bool = False, edgeDashKey: str = None, edgeLabelKey: str = None, edgeGroupKey: str = None, edgeGroups: list = None, edgeMinGroup=None, edgeMaxGroup=None, showEdges: bool = True, showEdgeLabel: bool = False, edgeLabelFontSize: int = 10, showEdgeLegend: bool = False, edgeLegendLabel: str = 'TGraph Edges', edgeLegendRank: int = 5, edgeLegendGroup: int = 5, colorScale: str = 'viridis', selfLoopMode: str = 'circle', selfLoopRadius: float = 0.25, selfLoopMajorRadius: float = None, selfLoopMinorRadius: float = None, selfLoopSides: int = 48, selfLoopNormal: list = None, selfLoopVertexSize: float = 0, splitVertexTracesByStyle: bool = False, mantissa: int = 6, tolerance: float = 0.0001, silent: bool = False)

Creates Plotly traces from a topologicpy.TGraph.

The implementation is optimised for large graphs. Instead of creating one Scatter3d trace per edge, edges are bucketed by visual style and rendered in aggregated traces. Labels and cone arrowheads are emitted as separate traces only when requested. Self-loops are supported without conversion to topologic_core geometry.

Parameters

graphtopologicpy.TGraph

The input TGraph.

sagittafloat, optional

If non-zero, non-loop edges are drawn as quadratic arcs. If absolute is False, sagitta is interpreted as a ratio of chord length. If True, it is interpreted as model units.

directedbool or None, optional

If None, each edge’s directed flag is used. If True or False, the input value overrides edge-level directionality.

splitVertexTracesByStylebool, optional

If True, vertices are split by marker symbol and border style. This enables per-style borders but creates more traces.

Returns

list or None

A list of Plotly graph objects, or None if the input is invalid.

static DataByTopology(topology, showVertices=True, vertexSize=2.8, vertexSizeKey=None, vertexColor='black', vertexColorKey=None, vertexLabelKey=None, vertexBorderColor='black', vertexBorderWidth=0, vertexBorderColorKey=None, vertexBorderWidthKey=None, showVertexLabel=False, vertexLabelFontSize=5, vertexGroupKey=None, vertexGroups=None, vertexMinGroup=None, vertexMaxGroup=None, showVertexLegend=False, vertexLegendLabel='Topology Vertices', vertexLegendRank=1, vertexLegendGroup=1, directed=False, arrowSize=0.1, arrowSizeKey=None, showEdges=True, edgeWidth=1, edgeWidthKey=None, edgeColor='black', edgeColorKey=None, edgeDash=False, edgeDashKey=None, edgeLabelKey=None, showEdgeLabel=False, edgeGroupKey=None, edgeGroups=None, edgeMinGroup=None, edgeMaxGroup=None, showEdgeLegend=False, edgeLegendLabel='Topology Edges', edgeLegendRank=2, edgeLegendGroup=2, showFaces=True, faceOpacity=0.5, faceOpacityKey=None, faceColor='#FAFAFA', faceColorKey=None, faceLabelKey=None, faceGroupKey=None, faceGroups=None, faceMinGroup=None, faceMaxGroup=None, showFaceLegend=False, faceLegendLabel='Topology Faces', faceLegendRank=3, faceLegendGroup=3, intensityKey=None, intensities=None, material='default', materialKey=None, flatShading=False, ambient=None, ambientKey=None, diffuse=None, diffuseKey=None, specular=None, specularKey=None, roughness=None, roughnessKey=None, colorScale='viridis', mantissa=6, tolerance=0.0001, silent=False)

Creates Plotly data from a Topologic topology.

Curved edges are sampled for display and faces are tessellated from their actual geometry. Visual dictionary keys are resolved on each source sub-topology, with the root topology dictionary acting only as a fallback.

static ExportToImage(figure, path, format='png', width=1920, height=1080)

Exports a Plotly figure to a static image using the current Kaleido pathway.

static FigureByConfusionMatrix(matrix, categories=None, minValue=None, maxValue=None, title='Confusion Matrix', xTitle='Actual Categories', yTitle='Predicted Categories', width=950, height=500, showScale=True, colorScale='viridis', colorSamples=10, backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=40, marginBottom=0, baseFontSize=16, tickFontSize=14, titleFontSize=22, axisTitleFontSize=16, annotationFontSize=18, grayScale=False)

Returns a Plotly Figure of the input confusion matrix. Actual categories are displayed on the X-Axis, Predicted categories are displayed on the Y-Axis.

Parameters

matrixlist or numpy.array

The matrix to display.

categorieslist

The list of categories to use on the X and Y axes.

minValuefloat , optional

The desired minimum value to use for the color scale. If set to None, the minimum value found in the input matrix will be used.

maxValuefloat , optional

The desired maximum value to use for the color scale. If set to None, the maximum value found in the input matrix will be used.

titlestr , optional

The desired title to display. Default is “Confusion Matrix”.

xTitlestr , optional

The desired X-axis title to display. Default is “Actual Categories”.

yTitlestr , optional

The desired Y-axis title to display. Default is “Predicted Categories”.

widthint , optional

The desired width of the figure. Default is 950.

heightint , optional

The desired height of the figure. Default is 500.

showScalebool , optional

If set to True, a color scale is shown on the right side of the figure. Default is True.

colorScalestr , optional

The desired type of plotly color scales to use (e.g. “Viridis”, “Plasma”). Default is “Viridis”.

colorSamplesint , optional

The number of discrete color samples to use for displaying the data. Default is 10.

backgroundColorlist or str , optional

The desired background color (see docstring above). Default is transparent.

marginLeft, marginRight, marginTop, marginBottomint , optional

Plot margins in pixels.

baseFontSizeint , optional

The base font size. Default is 16.

tickFontSizeint , optional

The tick font size. Default is 14.

titleFontSizeint , optional

The title font size. Default is 22.

axisTitleFontSizeint , optional

The axis title font size. Default is 16.

annotationFontSizeint , optional

The annotation font size. Default is 18.

grayScalebool , optional

If set to True, the figure is rendered in grayscale. Default is False.

Returns

plotly.graph_objects.Figure

The created plotly figure.

static FigureByCorrelation(actual, predicted, title='Correlation between Actual and Predicted Values', xTitle='Actual Values', yTitle='Predicted Values', showIdentity=True, showBestFit=True, dotSize=6, dotColor='blue', lineColor='red', width=800, height=600, theme='default', backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=40, marginBottom=0)

Creates a parity/correlation plot for paired actual and predicted values.

static FigureByData(data, width=950, height=500, xAxis=False, yAxis=False, zAxis=False, axisSize=1, backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=20, marginBottom=0, tolerance=0.0001)

Creates a Plotly figure from a list of traces.

static FigureByDataFrame(dataFrame, labels=None, width=950, height=500, title='Untitled', xTitle='X Axis', xSpacing=1, yTitle='Y Axis', ySpacing=1.0, useMarkers=False, chartType='Line', backgroundColor='rgba(0,0,0,0)', gridColor='lightgray', marginLeft=0, marginRight=0, marginTop=40, marginBottom=0)

Returns a Plotly figure from a pandas-compatible dataframe.

static FigureByJSONFile(file)

Imports a Plotly figure from an open JSON file object or path-like object.

static FigureByJSONPath(path)

Imports a Plotly figure from a JSON file path.

static FigureByMatrix(matrix, xCategories=None, yCategories=None, minValue=None, maxValue=None, title='Matrix', xTitle='X Axis', yTitle='Y Axis', width=950, height=950, showScale=False, colorScale='gray', colorSamples=10, backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=40, marginBottom=0, baseFontSize=16, tickFontSize=14, titleFontSize=22, axisTitleFontSize=16, annotationFontSize=18, grayscale=False, mantissa: int = 6)

Returns a Plotly Figure of the input matrix.

Notes

• Plots matrix values as provided (no implicit normalization).

• If grayscale is True, the figure becomes publication-friendly:

white background, black axis lines/ticks, grayscale colorscale, and annotation contrast tuned for grayscale.

static FigureByPieChart(data, values, names)

Creates a plotly pie chart figure.

Parameters

datalist

The input list of plotly data.

valueslist

The input list of values.

nameslist

The input list of names.

static FigureByProofGraph(proofGraphData=None, result=None, triple=None, graph=None, layout: str = 'tree', title: str = 'Proof Graph', width: int = 950, height: int = 700, backgroundColor='rgba(0,0,0,0)', showNodeLabel: bool = True, showEdgeLabel: bool = False, showLegend: bool = True, xAxis: bool = False, yAxis: bool = False, zAxis: bool = False, marginLeft: int = 0, marginRight: int = 0, marginTop: int = 40, marginBottom: int = 0, silent: bool = False, **kwargs)

Creates a Plotly figure for a proof graph.

Parameters

proofGraphDatadict or topologicpy.TGraph , optional

The proof graph data or proof TGraph.

resultobject , optional

An inference result returned by Reasoner.Infer or TGraph.InferOntology.

tripletuple or list , optional

The inferred triple to explain.

graphobject , optional

Optional source graph passed to Reasoner when deriving proof data.

layoutstr , optional

Layout type: “tree”, “radial”, or “force”.

titlestr , optional

Figure title.

width, heightint , optional

Figure size in pixels.

backgroundColorstr or list , optional

Figure background colour.

showNodeLabel, showEdgeLabel, showLegendbool , optional

Display controls.

xAxis, yAxis, zAxisbool , optional

Axis visibility controls.

marginLeft, marginRight, marginTop, marginBottomint , optional

Figure margins.

silentbool , optional

If True, suppress warnings.

**kwargsdict

Additional arguments passed to Plotly.DataByProofGraph.

Returns

plotly.graph_objects.Figure or None

The resulting figure.

static FigureByTopology(topology, showVertices=True, vertexSize=1.1, vertexColor='black', vertexLabelKey=None, vertexGroupKey=None, vertexGroups=None, vertexMinGroup=None, vertexMaxGroup=None, showVertexLegend=False, vertexLegendLabel='Topology Vertices', vertexLegendRank=1, vertexLegendGroup=1, showEdges=True, edgeWidth=1, edgeColor='black', edgeLabelKey=None, edgeGroupKey=None, edgeGroups=None, edgeMinGroup=None, edgeMaxGroup=None, showEdgeLegend=False, edgeLegendLabel='Topology Edges', edgeLegendRank=2, edgeLegendGroup=2, showFaces=True, faceOpacity=0.5, faceColor='#FAFAFA', faceLabelKey=None, faceGroupKey=None, faceGroups=None, faceMinGroup=None, faceMaxGroup=None, showFaceLegend=False, faceLegendLabel='Topology Faces', faceLegendRank=3, faceLegendGroup=3, intensityKey=None, width=950, height=500, xAxis=False, yAxis=False, zAxis=False, axisSize=1, backgroundColor='rgba(0,0,0,0)', marginLeft=0, marginRight=0, marginTop=20, marginBottom=0, showScale=False, cbValues=None, cbTicks=5, cbX=-0.15, cbWidth=15, cbOutlineWidth=0, cbTitle='', cbSubTitle='', cbUnits='', colorScale='viridis', mantissa=6, tolerance=0.0001, vertexSizeKey=None, vertexColorKey=None, vertexBorderColor='black', vertexBorderWidth=0, vertexBorderColorKey=None, vertexBorderWidthKey=None, showVertexLabel=False, vertexLabelFontSize=5, directed=False, arrowSize=0.1, arrowSizeKey=None, edgeWidthKey=None, edgeColorKey=None, edgeDash=False, edgeDashKey=None, showEdgeLabel=False, faceOpacityKey=None, faceColorKey=None, intensities=None, material='default', materialKey=None, flatShading=False, ambient=None, ambientKey=None, diffuse=None, diffuseKey=None, specular=None, specularKey=None, roughness=None, roughnessKey=None, silent=False)

Creates a Plotly figure from a Topologic topology.

static FigureExportToJSON(figure, path, overwrite=False)

Exports a Plotly figure to JSON.

static FigureExportToPDF(figure, path, width=1920, height=1200, overwrite=False)

Exports a Plotly figure to PDF.

static FigureExportToPNG(figure, path, width=1920, height=1200, overwrite=False)

Exports a Plotly figure to PNG.

static FigureExportToSVG(figure, path, width=1920, height=1200, overwrite=False)

Exports a Plotly figure to SVG.

static ProofGraphHTML(proofGraphData=None, result=None, triple=None, graph=None, path: str = 'proof_graph.html', layout: str = 'tree', title: str = 'Proof Graph', includePlotlyJS: str = 'cdn', autoOpen: bool = False, silent: bool = False, **kwargs)

Exports a proof graph visualisation to an HTML file.

Parameters

proofGraphDatadict or topologicpy.TGraph , optional

The proof graph data or proof TGraph.

resultobject , optional

An inference result returned by Reasoner.Infer or TGraph.InferOntology.

tripletuple or list , optional

The inferred triple to explain.

graphobject , optional

Optional source graph passed to Reasoner when deriving proof data.

pathstr , optional

The output HTML path. Default is “proof_graph.html”.

layoutstr , optional

Layout type: “tree”, “radial”, or “force”.

titlestr , optional

Figure title.

includePlotlyJSstr or bool , optional

Passed to plotly.io.write_html. Common values are “cdn”, True, or False. Default is “cdn”.

autoOpenbool , optional

If True, open the HTML file after writing it.

silentbool , optional

If True, suppress warnings.

**kwargsdict

Additional arguments passed to Plotly.FigureByProofGraph.

Returns

str or None

The output path if successful; otherwise None.

static Renderer()

Return the renderer most suitable for the environment in which the script is running.

Parameters

Returns

str

The most suitable renderer type for the environment in which the script is running. Currently, this is limited to: - “vscode” if running in Visual Studio Code - “colab” if running in Google Colab - “iframe” if running in jupyter notebook or jupyterlab - “browser” if running in anything else

static Renderers()

Returns the Plotly renderers available in the current installation.

static SetCamera(figure, camera=None, center=None, up=None, projection='perspective')

Sets the 3D scene camera of a Plotly figure.

static Show(figure, camera=None, center=None, up=None, renderer=None, projection=None)

Displays a Plotly figure without silently overwriting its existing camera.

Camera components are changed only when the corresponding arguments are explicitly supplied. This preserves camera settings applied with figure.update_layout or Plotly.SetCamera.

static edgeData(vertices, edges, dictionaries=None, color='black', colorKey=None, width=1, widthKey=None, dash=False, dashKey=None, directed=False, arrowSize=0.1, arrowSizeKey=None, labelKey=None, showEdgeLabel=False, groupKey=None, minGroup=None, maxGroup=None, groups=None, legendLabel='Topology Edges', legendGroup=2, legendRank=2, showLegend=True, colorScale='Viridis')

Creates Plotly line traces from indexed straight or sampled curved edges.

static vertexData(vertices, dictionaries=None, color='black', colorKey=None, size=1.1, sizeKey=None, borderColor='black', borderWidth=0, borderColorKey=None, borderWidthKey=None, labelKey=None, showVertexLabel=False, vertexLabelFontSize=5, groupKey=None, minGroup=None, maxGroup=None, groups=None, legendLabel='Topology Vertices', legendGroup=1, legendRank=1, showLegend=True, colorScale='Viridis')

Creates Plotly vertex traces with source-correct labels, styles, and hover text.