See a basic example and a Yu-Gi-Oh! card network to explore what this tool can create!
This tool builds interactive network visualisations from a compact YAML description and renders them using pyvis.
You declare entities and relationships in YAML and specify styling. The script infers structure from the entries and constructs a network accordingly.
Highlights:
Note: This script is intended to create visual summaries from structured YAML input. It is not designed for hierarchical layouts or for configuring individual nodes/edges one-by-one. Instead, it applies block- and entry-level styles inferred from your YAML.
Section names are not fixed — the examples shown (series, parallel, convergence, divergence, etc.) are conventional. The script decides how to process a section by inspecting the structure of its entries.
series:
- edge:
title: "Evolution"
items:
- ["Caterpillar", "Chrysalis", "Butterfly"]
- ["Seed", "Sprout", "Plant", "Flower"]
- edge:
title: "Process Steps"
items:
- ["Draft", "Review", "Approval", "Publication"]
parallel:
- items:
- ["Left", "Right"]
- ["North", "South"]
edge:
arrows: "none"
series and parallel above contain list-like entries and are treated as linear chains: each node is connected to its immediate neighbour.
convergence:
- from: ["Salt", "Water"]
to: "Saltwater"
- from: ["Flour", "Eggs", "Milk"]
to: "Pancake Batter"
divergence:
- edge:
title: "Branches"
items:
- from: "Tree"
to:
- "Branch1"
- "Branch2"
convergence and divergence use from/to mappings and are processed as branching relationships: every node in from connects to every node in to.
complete:
- edge:
closed: "complete"
title: "Letters"
items:
- ["X", "Y", "Z"]
complete is a special case: each list is treated as a complete subgraph (every node connects to every other node in that list).
Blocks are items in a section’s list and usually include items plus optional node or edge defaults. An entry is an element of a block’s items list; when a block has no items key the block itself acts as a single entry.
Block-level node and edge mappings act as defaults for the entries they directly contain. Entry-level node and edge mappings take precedence and override block defaults for that entry only.
Example:
series:
- edge:
title: "Special Chain"
color: "red"
items:
- ["Step1", "Step2", "Step3"]
- edge:
title: "Subchain"
color: "green"
items:
- ["SubstepA", "SubstepB"]
parallel:
- edge:
title: "Highlighted Pair"
color: "orange"
smooth: false
items:
- ["Alpha", "Beta"]
convergence:
- edge:
title: "Merge"
items:
- from: ["A", "B"]
to: "AB"
edge:
color: "pink"
title: "Pink Merge"
divergence:
- edge:
title: "Special Branch"
color: "teal"
items:
- from: "Origin"
to:
- "BranchX"
Note: The script accepts one level of entries and does not cascade into nested sub-blocks.
edge.title overrides the title shown for an edge. If no title is provided, the script falls back to the containing section name (for example series, convergence, etc.).
config)The config block controls global visual and behavioural options. Example:
config:
buttons:
show: True
filter: ["physics", "interaction"]
node:
scale_factor: 10
size: 100
borderWidthSelected: 4
edge:
width: 20
arrowStrikethrough: False
section:
series:
edge:
color: "orange"
convergence:
edge:
color: "purple"
smooth: True
parallel:
edge:
color: "green"
smooth: False
arrows: "none"
divergence:
edge:
color: "red"
physics:
enabled: True
repulsion:
node_distance: 1000
central_gravity: 0.2
spring_length: 200
spring_strength: 0.015
damping: 0.5
network:
height: "90vh"
width: "100%"
select_menu: True
interaction:
navigationButtons: True
download_images: True
Key options:
node: default node attributes.edge: default edge attributes.section: per-section defaults for nodes/edges.interaction: drag and navigation controls.physics: physics settings.network: networkinitialization parameters such as height and width.download_images: enable image downloading.options: The vis.js options can be provided as a JSON string or in YAML syntax. If the argument merge=True is passed, these options will be merged with other configuration options instead of overwriting them.For convenience, the script supplies a default config when none is provided:
node:
scale_factor: 0
shape: image
font:
size: 5
shapeProperties:
useBorderWithImage: True
buttons:
show: false
filter:
- physics
- interaction
network:
directed: True
height: "85vh"
select_menu: True
download_images: False
Note about edge vs edges and pyvis options.
edge (singular) in config and in block/entry mappings for per-edge attribute defaults (colour, width, arrows, etc.).edges (plural) in config to configure the pyvis Options edges sub-object (this controls pyvis rendering options, not per-edge attributes).Also supported as top-level keys and mapped straight to pyvis Options sub-objects are: physics, layout, interaction and configure. These keys are forwarded to get_options(), which applies them to the Options object used by pyvis.
Image handling is pluggable. The code expects an imageManager module that exposes two functions. A template imageManager module is provided as a starting point; you can customise it to fit your needs:
imageManager.download(names, config): download or prepare images for the provided names.imageManager.filename(name): return the filename or path to use for a given node name.The script imports download and filename from imageManager (or prints a warning if unavailable). Implement these functions to support remote APIs, local caching, resizing, or format conversion. If config.download_images is true, the script calls imageManager.download(...) once for all nodes. For nodes with image shapes, the script calls imageManager.filename() to retrieve their image paths.
config.buttons.show: true and tune visible groups via config.buttons.filter (for example [physics, interaction]).config.interaction.navigationButtons: true and control drag behaviour using dragNodes, hideEdgesOnDrag and hideNodesOnDrag.Script-level features are controlled by config.node:
scale_factor (numeric): when greater than zero, after all edges are added, the script increases each node’s size by scale_factor * degree (degree counts both incoming and outgoing edges).recolor (boolean): when enabled, a node is recoloured to match the most common colour among its incident edges.table (boolean): when enabled, the script prints a summary table of node degrees and colours once the network is built.The script consumes (pops) the following keys from node/edge mappings; these keys are interpreted by the script and are not forwarded as pyvis attributes:
node.scale_factornode.recolornode.tableedge.closed — when true on a linear/list entry, the list is treated as a closed circuit (the last node connects back to the first).Keep these keys at block or entry level as required; they will be removed before pyvis receives node/edge attributes.
Prepare your YAML file following the examples and override rules above.
Run the script to produce an HTML visualisation:
python network.py network.yaml
The output HTML file will be named after your YAML file (e.g., network.yaml produces network.html) and saved in the current directory. Open it in a browser to explore the interactive visualisation.
from network import build_network
net = build_network('your_data.yaml')
net.show('network.html')
You may further modify the returned net object before saving or displaying.
download_images: false to disable fetching.pip install pyvis pillow pyyaml requests.physics and layout settings in config.node/edge overrides to control colour, smoothness and titles.For further customisation, consult the script’s inline comments and the pyvis documentation.