Implement time unfolded visualization (#298)

* refactor visualisations and fix/speed up matplotlib backend

* update matplotlib and tikz

* finalise static d3js

* update configs

* add automatic d3js layouting and margin config param

* optimise temporal_edges

* update d3js temporal graphs

* update curved edges

* efficiency improvements

* fix issues with higher order and curved edges

* update manim

* fix indexing

* update layout

* add temporal network layouting

* add networkx as dependency

* update manim backend

* fix window and batch functions for temporal graphs

* minor fixes

* start documentation update

* update docs and minor fixes

* fix documentation with underscore

* update visualisation notebooks

* documentation improvements

* finish visualisation code reference

* update plot dev tutorial

* fix existing tests

* update setup yaml

* fix tex setup

* update tex action

* fix

* fix tex live setup

* set up optimized ffmpeg download

* improve apt installation

* add optional python deps

* add tests and minor fixes

* update latex installation

* fix ffmpeg installation

* -

* fix ffmpeg

* backend tests

* add time-unfolded graph matplotlib

* add unfolded visualisation to tikz

* add unit-tests

* add unfolded graph to d3js backend

* update docs

* fix temporal graph RGB assignment

* fix higher-order RGB assignment

* fix tikz node border opacity

* fix unit-test fail

Author: M-Lampert

docs/reference/pathpyG/visualisations/index.md

@@ -62,12 +62,12 @@ The default backend is `d3.js`, which is suitable for both static and temporal n
 We currently support a total of four plotting backends, each with different capabilities making them suitable for different use cases.
 The table below provides an overview of the supported backends and their available file formats:
 
-| Backend       | Static Networks  | Temporal Networks  | Available File Formats| 
-|---------------|------------|-------------|--------------|
-| **d3.js**     | ✔️         | ✔️           | `html` |
-| **manim**     | ❌         | ✔️           | `mp4`, `gif` | 
-| **matplotlib**| ✔️         | ❌           | `png`, `jpg` |
-| **tikz**      | ✔️         | ❌           | `svg`, `pdf`, `tex`|
+| Backend       | Static Networks  | Temporal Networks | Time-Unfolded Networks | Available File Formats| 
+|---------------|------------|-------------|--------------|-------------|
+| **d3.js**     | ✔️         | ✔️          | ✔️           | `html` |
+| **manim**     | ❌         | ✔️          | ❌           | `mp4`, `gif` | 
+| **matplotlib**| ✔️         | ❌          | ✔️           | `png`, `jpg` |
+| **tikz**      | ✔️         | ❌          | ✔️           | `svg`, `pdf`, `tex`|
 
 #### Details
 
@@ -427,6 +427,44 @@ The layout algorithm can be any of the supported static layout algorithms descri
         <img src="plot/manim_temporal_fa2.gif" alt="Manim Custom Properties Animation" width="650"/>
     </div>
 
+### Time-Unfolded Networks
+
+For temporal networks, you can use the time-unfolded visualisation to show a static representation of the temporal network.
+In this representation, each node is duplicated for each timestep, and edges are drawn between nodes at different timesteps to represent temporal interactions.
+You can enable this visualisation by setting the "kind" argument to `"unfolded"` in the `pp.plot()` function call.
+This visualisation is supported by all backends that support static networks, i.e. D3.js, Matplotlib, and TikZ.
+
+!!! example "Time-Unfolded Visualisation of Temporal Networks"
+    
+    In the example below, we create a time-unfolded visualisation of a temporal network using the `tikz` backend.
+    ```python
+    import pathpyG as pp
+
+    # Example temporal network data
+    tedges = [
+        ("a", "b", 1),
+        ("a", "b", 2),
+        ("b", "a", 3),
+        ("b", "c", 3),
+        ("d", "c", 4),
+        ("a", "b", 4),
+        ("c", "b", 4),
+        ("c", "d", 5),
+        ("b", "a", 5),
+        ("c", "b", 6),
+    ]
+    t = pp.TemporalGraph.from_edge_list(tedges)
+
+    # Create temporal plot and display inline
+    node_color = {"a": "red", ("a", 2): "darkred"}
+    edge_color = {("a", "b", 2): "blue"}
+    pp.plot(t, backend="tikz", kind="unfolded", node_size=12, node_color=node_color, edge_color=edge_color)
+    ```
+    <img src="plot/unfolded_graph.svg" alt="Example TikZ Time-Unfolded Layout" width="650"/>
+
+    !!! tip "Customising Time-Unfolded Visualisations"
+        In the time-unfolded visualisation, you can still customise node and edge properties as described in the [Node and Edge Customisation](#node-and-edge-customisation) section.
+
 ## Customisation Options
 
 Below is full list of supported keyword arguments for each backend and their descriptions.
@@ -445,6 +483,7 @@ Below is full list of supported keyword arguments for each backend and their des
 | `layout_window_size`      |    ✔️    |     ✔️    |     ❌    |     ❌    | Size of sliding window for temporal network layouts (int or tuple of int) |
 | `delta`                   |    ✔️    |     ✔️    |   ❌      |     ❌   | Duration of timestep in milliseconds (ms)                      |
 | `separator`               |     ✔️    |     ✔️    |     ✔️    |     ✔️    | Separator for higher-order node labels        |
+| `orientation`            |     ✔️   |      ✔️   |      ❌   |    ✔️   | Orientation of the time-unfolded network plot (`"up"`, `"down"`, `"left"`, or `"right"`)        |
 | **Nodes**                 |           |           |           |           |                                               |
 | `size`               |     ✔️    |     ✔️    |      ✔️   |    ✔️     | Radius of nodes (uniform or per-node)         |
 | `color`              |     ✔️    |     ✔️    |     ✔️    |     ✔️    | Node fill color           |

docs/reference/pathpyG/visualisations/plot/documentation_plots.ipynb

@@ -32,6 +32,7 @@ curvature = 0.25  # Curvature for curved edges between nodes
 layout_window_size = [-1, -1]  # Window size for layout algorithms that use temporal information. Default is [-1, -1] meaning that all timestamps in both directions is used. If an integer is given, this defines the number of time steps that are used to compute the layout at a specific time step. If  tuple of two integers is given, this defines the number of time steps before and after the current time step that are used to compute the layout at a specific time step.
 delta = 1000  # Time between frames in milliseconds
 separator = "->"  # Separator for higher-order node labels
+orientation = "down"  # Orientation of the time-unfolded plots. Options are "down", "up", "left", "right"
 
 [visualisation.node]
 color = [36, 74, 92]  # Node color in RGB from the pathpyG logo

docs/reference/pathpyG/visualisations/plot/unfolded_graph.svg

@@ -51,6 +51,8 @@
 
 ## Network Visualization with custom Images
 
+With D3.js, you can easily use custom images for nodes by providing URLs or local paths.
+
 ```python
 import torch
 import pathpyG as pp
@@ -83,6 +85,29 @@
     - **Jupyter**: Direct display in notebook cells
     - **Web Apps**: Easy integration into existing websites
 
+## Time-Unfolded Network
+
+Below is an example of a time-unfolded network visualization using the D3.js backend.
+
+```python
+import pathpyG as pp
+
+# Example temporal network data
+tedges = [
+    ("a", "d", 1),
+    ("b", "c", 2),
+    ("b", "c", 3),
+    ("b", "a", 3),
+    ("d", "b", 4),
+
+]
+t = pp.TemporalGraph.from_edge_list(tedges)
+
+# Create temporal plot and display inline
+pp.plot(t, kind="unfolded", show_labels=False)
+```
+<iframe src="../plot/unfolded_graph_d3js.html" width="650" height="520"></iframe>
+
 ## Templates
 PathpyG uses HTML templates to generate D3.js visualizations located in the `templates` directory.
 Templates define the overall structure and include placeholders for dynamic content.

docs/reference/pathpyG/visualisations/plot/unfolded_graph_d3js.html

@@ -10,6 +10,7 @@
     - Both static and temporal network support
     - Jupyter notebook integration with inline display
 """
+
 from __future__ import annotations
 
 import json
@@ -26,14 +27,16 @@
 from pathpyG.visualisations.pathpy_plot import PathPyPlot
 from pathpyG.visualisations.plot_backend import PlotBackend
 from pathpyG.visualisations.temporal_network_plot import TemporalNetworkPlot
-from pathpyG.visualisations.utils import rgb_to_hex, unit_str_to_float
+from pathpyG.visualisations.unfolded_network_plot import TimeUnfoldedNetworkPlot
+from pathpyG.visualisations.utils import in_jupyter_notebook, rgb_to_hex, unit_str_to_float
 
 # create logger
 logger = logging.getLogger("root")
 
 SUPPORTED_KINDS: dict[type, str] = {
     NetworkPlot: "static",
     TemporalNetworkPlot: "temporal",
+    TimeUnfoldedNetworkPlot: "unfolded",
 }
 
 
@@ -62,7 +65,7 @@ class D3jsBackend(PlotBackend):
 
     !!! info "Template Architecture"
         Uses modular templates for extensibility:
-        
+
         - `styles.css`: Visual styling and responsive design
         - `setup.js`: Environment detection and D3.js loading
         - `network.js`: Core network visualization logic
@@ -105,12 +108,14 @@ def save(self, filename: str) -> None:
 
         !!! tip "Deployment Ready"
             Generated HTML files are standalone and can be:
-            
+
             - Opened directly in browsers
             - Served from web servers
             - Embedded in websites or documentation
             - Shared without additional dependencies
         """
+        # Default to the CDN version of d3js since browsers may block local scripts
+        self.config["d3js_local"] = self.config.get("d3js_local", False)
         with open(filename, "w+") as new:
             new.write(self.to_html())
 
@@ -125,6 +130,8 @@ def show(self) -> None:
             Uses pathpyG config to detect interactive environment
             and choose appropriate display method automatically.
         """
+        # Default to local d3js in Jupyter notebooks for offline use
+        self.config["d3js_local"] = self.config.get("d3js_local", False or in_jupyter_notebook())
         if config["environment"]["interactive"]:
             from IPython.display import display_html, HTML  # noqa I001
 
@@ -149,16 +156,18 @@ def _prepare_data(self) -> dict:
 
         !!! note "Data Structure"
             **Nodes**: Include uid, coordinates (xpos/ypos), and all attributes
-            
+
             **Edges**: Include uid, source/target references, and styling
         """
         node_data = self.data["nodes"].copy()
-        node_data["uid"] = self.data["nodes"].index
+        node_data["uid"] = self.data["nodes"].index.map(lambda x: f"({x[0]},{x[1]})" if isinstance(x, tuple) else str(x))
         node_data = node_data.rename(columns={"x": "xpos", "y": "ypos"})
+        if self._kind == "unfolded":
+            node_data["ypos"] = 1 - node_data["ypos"]  # Invert y-axis for unfolded layout
         edge_data = self.data["edges"].copy()
         edge_data["uid"] = self.data["edges"].index.map(lambda x: f"{x[0]}-{x[1]}")
-        edge_data["source"] = edge_data.index.get_level_values("source")
-        edge_data["target"] = edge_data.index.get_level_values("target")
+        edge_data["source"] = edge_data.index.to_frame()["source"].map(lambda x: f"({x[0]},{x[1]})" if isinstance(x, tuple) else str(x))
+        edge_data["target"] = edge_data.index.to_frame()["target"].map(lambda x: f"({x[0]},{x[1]})" if isinstance(x, tuple) else str(x))
         data_dict = {
             "nodes": node_data.to_dict(orient="records"),
             "edges": edge_data.to_dict(orient="records"),
@@ -235,9 +244,8 @@ def to_html(self) -> str:
             os.path.normpath("_d3js/templates"),
         )
 
-        # get d3js version
-        local = self.config.get("d3js_local", True)
-        if local:
+        # get d3js library path
+        if self.config.get("d3js_local", False):
             d3js = os.path.join(template_dir, "d3.v7.min.js")
         else:
             d3js = "https://d3js.org/d3.v7.min.js"
@@ -305,9 +313,9 @@ def get_template(self, template_dir: str) -> str:
 
         !!! info "Template Composition"
             **Core Template** (`network.js`): Base network visualization logic
-            
+
             **Plot Templates**: Type-specific functionality:
-            
+
             - `static.js`: Force simulation and interaction for static networks
             - `temporal.js`: Timeline controls and animation for temporal networks
 
@@ -319,7 +327,9 @@ def get_template(self, template_dir: str) -> str:
         with open(os.path.join(template_dir, "network.js")) as template:
             js_template += template.read()
 
-        with open(os.path.join(template_dir, f"{self._kind}.js")) as template:
+        with open(
+            os.path.join(template_dir, "static.js" if self._kind == "unfolded" else f"{self._kind}.js")
+        ) as template:
             js_template += template.read()
 
         return js_template

docs/reference/pathpyG/visualisations/plot/unfolded_graph_matplotlib.png

@@ -17,4 +17,32 @@
 pp.plot(g, backend="matplotlib")
 ```
 <img src="../plot/network.png" alt="Example Matplotlib Backend Output" width="550"/>
+
+## Time-Unfolded Network
+
+We also support time-unfolded static visualizations of temporal networks using the matplotlib backend.
+The example uses the `node_opacity` parameter to highlight active nodes and edges at each time step.
+
+```python
+import pathpyG as pp
+
+# Example temporal network data
+tedges = [
+    ("a", "b", 1),
+    ("a", "b", 2),
+    ("b", "a", 3),
+    ("b", "c", 3),
+    ("d", "c", 4),
+    ("a", "b", 4),
+    ("c", "b", 4),
+]
+t = pp.TemporalGraph.from_edge_list(tedges)
+
+# Create temporal plot and display inline
+node_opacity = {(node_id, time): 0.1 for node_id in t.nodes for time in range(t.data.time.max().item() + 2)}
+node_opacity.update({(source_id, time): 1.0 for source_id, target_id, time in t.temporal_edges})
+node_opacity.update({(target_id, time+1): 1.0 for source_id, target_id, time in t.temporal_edges})
+pp.plot(t, backend="matplotlib", kind="unfolded", node_size=12, node_opacity=node_opacity)
+```
+<img src="../plot/unfolded_graph_matplotlib.png" alt="Example Matplotlib Backend Time-Unfolded Output" width="550"/>
 """