TGraphX Dashboard: Offline HTML Reports for GNN Experiments

Experiment tracking for graph neural networks creates a recurring problem: results are scattered across terminal output, log files, and notebook cells. When a collaborator asks "what hyperparameters did you use for that run last week?" the answer is rarely a single file. TGraphX includes a tgraphx.dashboard module that writes self-contained HTML reports to disk, requiring no server, no cloud account, and no running process to view.

This article covers why offline HTML reports are a practical choice for reproducibility, what the TGraphX dashboard captures, and how to generate and share reports from a standard training loop.

Why Offline HTML Reports Matter

The mainstream experiment tracking tools — MLflow UI, Weights & Biases, Neptune — require either a running server or a network connection. Both assumptions fail in common research scenarios: HPC clusters without outbound internet, air-gapped institutional environments, or simply sharing results with a reviewer who should not need to create an account to read your supplementary material.

An offline HTML file has none of these dependencies. It can be emailed, attached to a pull request, committed to a repository, or included in supplementary material for a paper submission. The recipient opens it in any browser. There is no version mismatch between the server and the client because there is no server.

The TGraphX dashboard is not a replacement for full tracking infrastructure when that infrastructure is available. It is a zero-dependency fallback that produces a human-readable audit trail without requiring any external service.

What the Dashboard Module Captures

The tgraphx.dashboard module collects several categories of information during or after a training run:

Metrics over time. Loss curves, accuracy, precision, recall, or any scalar metric logged at each epoch are rendered as interactive line charts using embedded JavaScript. No separate plotting library is needed at report-generation time.

Hyperparameters. Any Python dictionary passed as the configuration is serialized into a readable table. This covers learning rate, model architecture choices, dataset path, random seed, and any other key-value pair you consider relevant.

Graph statistics. If you pass a Graph or GraphBatch object, the dashboard records node count, edge count, feature tensor shapes, and any metadata attached to the graph.

Model summary. The module captures the str(model) representation from PyTorch, giving a layer-by-layer description without requiring TorchInfo or any additional package.

Text notes. Free-form strings can be attached to a report, useful for recording dataset version, preprocessing decisions, or known issues with a particular run.

Basic Usage: Generating a Report

The core workflow involves three steps: create a reporter, log values during training, and write the report at the end.

import torch
        import torch.nn as nn
        from tgraphx.dashboard import DashboardReporter
        
        # Create a reporter for this run
        reporter = DashboardReporter(
            run_name="sage_cora_run_01",
            output_dir="./reports"
        )
        
        # Log hyperparameters before training starts
        reporter.log_config({
            "model": "TensorGraphSAGELayer",
            "layers": 2,
            "hidden_dim": 64,
            "lr": 0.01,
            "epochs": 200,
            "dataset": "Cora",
            "seed": 42,
        })
        

Inside your training loop, call log_metric at each epoch:

for epoch in range(200):
            # ... training step ...
            train_loss = compute_loss(model, train_data)
            val_acc = evaluate(model, val_data)
        
            reporter.log_metric("train_loss", train_loss.item(), step=epoch)
            reporter.log_metric("val_accuracy", val_acc, step=epoch)
        

After training, write the report:

# Log the final model summary
        reporter.log_model_summary(model)
        
        # Optionally attach a free-form note
        reporter.log_note(
            "Stopped at epoch 180 due to plateau. "
            "Best val accuracy at epoch 147."
        )
        
        # Write the self-contained HTML file
        report_path = reporter.save()
        print(f"Report saved to: {report_path}")
        

The output is a single .html file at ./reports/sage_cora_run_01.html. Opening it in any browser shows the full run summary with interactive charts.

Attaching Graph Statistics

When your experiment involves a specific graph, you can attach graph metadata so the report documents the data structure alongside the results:

from tgraphx import Graph
        import torch
        
        g = Graph(
            node_features=torch.randn(2708, 1433),
            edge_index=torch.load("cora_edge_index.pt"),
        )
        
        reporter.log_graph_info(g)
        

The report will include node count, edge count, feature shape, and whether the graph has self-loops, making the data configuration reproducible from the report alone.

For batched experiments across multiple graphs, you can call log_graph_info with a GraphBatch and the report will show per-graph and aggregate statistics.

Comparing Multiple Runs

For a small sweep, you can generate one report per run and load them side by side in a browser. For a more structured comparison, the dashboard module provides a lightweight aggregation utility:

from tgraphx.dashboard import compare_reports
        
        summary = compare_reports([
            "./reports/sage_cora_run_01.html",
            "./reports/sage_cora_run_02.html",
            "./reports/gin_cora_run_01.html",
        ])
        
        # Writes a comparison page with metric summaries across runs
        summary.save("./reports/comparison.html")
        

The comparison report shows final metric values side by side for each run and links back to the individual run reports. This is useful for sharing a summary of a hyperparameter sweep without sending three separate files.

Integrating with the Reproducibility Module

TGraphX's tgraphx.reproducibility module seeds all random number generators and records environment information. The dashboard can consume the reproducibility context directly:

from tgraphx.reproducibility import ReproducibilityContext
        from tgraphx.dashboard import DashboardReporter
        
        ctx = ReproducibilityContext(seed=42)
        ctx.seed_all()
        
        reporter = DashboardReporter(run_name="repro_test", output_dir="./reports")
        reporter.log_config(ctx.get_config())  # includes seed, torch version, Python version
        

The resulting report documents not just what you measured but what conditions produced the measurement. This is directly useful for the GNN research reproducibility requirements common in peer-reviewed venues.

Sharing Reports Without a Server

The HTML file produced by tgraphx.dashboard is fully self-contained. All charts are rendered by embedded JavaScript (no CDN calls at view time), all styles are inline, and all data is embedded as JSON literals within the file. This means:

• The file can be opened offline on an airplane
• It can be attached to an email or uploaded to any file-sharing service
• It renders identically regardless of the viewer's operating system or installed Python packages
• A reviewer can inspect your results without installing anything

File sizes are typically between 200 KB and 2 MB depending on how many metric points were logged and whether base64-encoded images were attached. For very long runs with frequent logging, consider reducing logging frequency (log_metric every 5 epochs rather than every epoch) to keep reports compact.

Limitations and Honest Notes

The TGraphX dashboard is intentionally simple. It is not a replacement for MLflow, Weights & Biases, or Neptune when those tools are available and appropriate. Specific limitations include:

No real-time streaming. The report is generated after training completes. If a job is killed midway through, no partial report is written unless you call reporter.save() inside a try/finally block.

No automatic artifact versioning. Each report is a static snapshot. If you re-run an experiment and overwrite the output directory, the previous report is gone unless you rename it first.

No database backend. Querying across dozens of runs requires opening multiple HTML files or writing a custom aggregation script. For experiments at scale, using tgraphx.tracking with a proper backend is more appropriate.

Chart interactivity is limited. The embedded JavaScript provides zoom and hover but not the kind of rich filtering available in dedicated dashboards. For complex visualization needs, export metrics to a pandas DataFrame and use a full plotting library.

The module is intended for small-to-medium experiment volumes. If you are running hundreds of runs per day, a server-based tracking tool will be more practical.

For a deeper look at reproducibility tooling in TGraphX, see the GNN research reproducibility article. For the MLflow-based tracking workflow, see the TGraphX MLflow integration tutorial.

Frequently Asked Questions

Can I attach images to the report? Yes. The reporter accepts PIL Image objects or matplotlib figures via reporter.log_figure(), which are base64-encoded and embedded in the HTML.

Does the report include the full model weights? No. Only the string summary of the model architecture is included. Saving model weights is handled separately via standard PyTorch torch.save calls.

Can I generate a report without a training loop? Yes. You can call log_config, log_metric, and log_note in any order before calling save. All logging calls are additive.

Is the output format stable across TGraphX versions? The HTML format may change between minor versions. For long-term archival, the underlying JSON data logged by the reporter can also be exported via reporter.export_json() and processed independently.

Structuring Reports for Paper Submission

Academic papers increasingly require supplementary experiment documentation. The offline HTML format works well here, but some venues require specific formats. A practical workflow is to use the dashboard during experimentation and then generate a structured supplementary from the exported JSON.

The reporter.export_json() method returns a dictionary with all logged data: metrics, config, model summary, graph info, and notes. This can be processed with any Python script or notebook to produce the exact table format a venue requires. The HTML report serves as the human-readable version for reviewers; the JSON serves as the machine-readable version for replication.

When preparing paper submissions that use TGraphX experiments, it is good practice to include the HTML report path in the paper's code repository alongside the checkpoint files. This allows reviewers and future readers to inspect the full experimental conditions without needing to re-run anything.

Advanced: Logging Validation Curves and Custom Metrics

The log_metric call is flexible — it accepts any string key and any numeric value. This means custom metrics beyond loss and accuracy can be tracked at no extra cost:

from tgraphx.metrics.classification import macro_f1, per_class_accuracy
        
        for epoch in range(200):
            # ... training step ...
            val_preds = model(val_data.node_features, val_data.edge_index)
        
            reporter.log_metric("val_macro_f1", macro_f1(val_preds, val_data.labels).item(), step=epoch)
        
            per_class = per_class_accuracy(val_preds, val_data.labels)
            for class_idx, acc in enumerate(per_class):
                reporter.log_metric(f"val_acc_class_{class_idx}", acc.item(), step=epoch)
        

Per-class accuracy curves can reveal training dynamics that aggregate accuracy hides — for example, a model that achieves 80% overall accuracy may be predicting one class correctly 95% of the time and another only 60% of the time. The dashboard will render each metric key as a separate line on its chart panel.

Integrating with Version Control

One underused practice is committing HTML reports alongside code changes. For a research codebase tracked in git, the commit log then becomes a timeline of experimental results:

git add reports/sage_cora_run_baseline.html
        git commit -m "Baseline SAGE run before applying residual connections"
        

After adding residual connections and re-running:

git add reports/sage_cora_run_residual.html
        git commit -m "SAGE run with residual connections: val acc +3.2%"
        

This practice creates an auditable history of experiment results that is visible to any collaborator with repository access. The diff between runs is not in the HTML itself (which is binary-like) but in the commit messages and the separately tracked source code. For a deeper treatment of experiment versioning and reproducibility, see the GNN research reproducibility guide.

What This Article Builds On

This article assumes familiarity with basic TGraphX training loops. The dashboard module is most useful once you have a working experiment and want to document it systematically. If you are still setting up your first TGraphX experiment, see the shape-aware validation guide for the validation utilities that catch issues before training, and the articles hub at /articles/ for a full index of available guides.