HiddenLayer Documentation

HiddenLayer requires GraphViz and its Python wrapper to generate neural network graphs.

Using Conda:

conda install graphviz python-graphviz

Using Pip (Manual GraphViz installation required):

1. Install GraphViz from the official website.
2. Install the Python wrapper:

pip3 install graphviz

You can install HiddenLayer using one of the following methods depending on your needs:

Stable Release

Use pip to install the stable version:

pip install hiddenlayer

Latest Version from GitHub

To install the latest version directly from the GitHub repository:

pip install git+https://github.com/waleedka/hiddenlayer.git

Developer Mode

If you intend to edit or customize the library locally, clone the repository and install it in editable mode:

git clone git@github.com:waleedka/hiddenlayer.git
cd hiddenlayer
pip install -e .

HiddenLayer uses Graph Expressions to find specific patterns of nodes and Transforms to modify them.

Graph Expressions

Graph Expressions act like Regular Expressions for graph structures:

• Conv > Relu: Matches a Conv layer followed by a Relu layer.
• Conv | MaxPool: Matches Conv and MaxPool layers that are in parallel branches (sharing the same parent node).

Transforms

Once nodes are identified by an expression, a Transform is applied to modify the graph. Common transforms include:

• hl.transforms.Fold(expression, new_name, display_name): Groups a pattern of nodes into a single node.
• hl.transforms.Prune(expression): Deletes nodes matching the expression.
• hl.transforms.FoldDuplicates(): Folds repeated patterns.

To track training progress, use two primary classes: hl.History to store metric data and hl.Canvas to visualize it.

1. Initialize hl.History() to act as a data store.
2. Initialize hl.Canvas() to handle rendering.
3. During your training loop, use history.log(step, metric_name=value) to record data.
4. Use canvas.draw_plot([history["metric1"], history["metric2"]]) to render the metrics.

import hiddenlayer as hl

history1 = hl.History()
canvas1 = hl.Canvas()

for step in range(800):
    # ... training logic ...
    if step % 10 == 0:
        history1.log(step, loss=loss, accuracy=accuracy)
        canvas1.draw_plot([history1["loss"], history1["accuracy"]])

HiddenLayer uses Graph Expressions (similar to Regular Expressions) to find patterns in the model graph and Transforms to modify those patterns.

Graph Expressions

• Conv > Relu: Matches a Conv layer followed by a Relu layer.
• Conv | MaxPool: Matches Conv and MaxPool layers that are in parallel branches (sharing the same parent node).
• ((A > B) | C) > D: Complex nested patterns using grouping and logical operators.

Transforms

Once a pattern is matched, a transform can be applied. Common transforms include:

• ht.Fold(expression, name, label): Groups nodes matching the expression into a single node with a specific name and display label.
• ht.FoldDuplicates(): Folds repeated identical nodes.
• ht.Prune(type): Deletes nodes of a specific type (e.g., ht.Prune("Const")).

If running on a remote server without a display, follow these steps to avoid errors:

1. Set Matplotlib backend to Agg: This must be done before importing hiddenlayer.
2. Use text progress: Call history.progress() to print a text-based status of the metrics to the console.
3. Save snapshots: Use canvas.save("filename.png") to periodically save plots to disk for later viewing.

If you are running training on a remote server without a GUI, follow these steps:

1. Set the Matplotlib backend to 'Agg': This must be done before importing hiddenlayer. This prevents the library from attempting to open interactive windows.
2. Use .progress(): Call history.progress() inside your training loop to print a text-based status of the metrics to the console.
3. Save plots to disk: Use canvas.save("filename.png") to periodically save snapshots of your training graphs as image files.

# MUST be done BEFORE importing hiddenlayer
import matplotlib
matplotlib.use("Agg")
import hiddenlayer as hl

# In training loop
history.progress()
canvas.draw_plot([h["loss"], h["accuracy"]])
canvas.save("training_graph.png")

To compare different experiments (different History objects) on the same plot, use the with canvas: context manager. This ensures that multiple draw_plot calls are rendered together in a single view. You can provide custom labels to distinguish between the metrics being compared.

history1 = hl.History()
history2 = hl.History()
canvas2 = hl.Canvas()

# ... training loops for history1 and history2 ...

# Draw comparison plots
with canvas2:
    canvas2.draw_plot([history1["loss"], history2["loss"]], labels=["Loss 1", "Loss 2"])
    canvas2.draw_plot([history1["accuracy"], history2["accuracy"]], labels=["Accuracy 1", "Accuracy 2"]])

To visualize a Keras model using HiddenLayer, you can use hl.build_graph() by passing the Keras session graph. You can also apply transforms during the build process to group nodes into higher-level modules.

Note: Ensure you have set the Keras learning phase (K.set_learning_phase) appropriately (1 for training, 0 for inference) before building the model to ensure the graph reflects the intended state.

import tensorflow.keras.backend as K
import hiddenlayer as hl

# Set learning phase
K.set_learning_phase(0)

# Build model
model = VGG16(input_shape=(224, 224, 3))

# Build graph view
hl_graph = hl.build_graph(K.get_session().graph)

# Display
hl_graph