tessl/pypi-tensorboardx

TensorBoardX lets you watch Tensors Flow without Tensorflow

Overview

Eval results

Files

Summary Writer

Name: tessl/pypi-tensorboardx
Author: tessl

The primary high-level interface for logging data to TensorBoard. SummaryWriter handles all common visualization types and manages event file creation, writing, and cleanup automatically.

Capabilities

Initialization

Creates a SummaryWriter instance with flexible configuration for logging directory, file management, and performance tuning.

class SummaryWriter:
    def __init__(
        self,
        logdir: Optional[str] = None,
        comment: Optional[str] = "",
        purge_step: Optional[int] = None,
        max_queue: Optional[int] = 10,
        flush_secs: Optional[int] = 120,
        filename_suffix: Optional[str] = '',
        write_to_disk: Optional[bool] = True,
        log_dir: Optional[str] = None,
        comet_config: Optional[dict] = {"disabled": True}
    ):
        """
        Creates a SummaryWriter for logging events and summaries.

        Parameters:
        - logdir: Save directory location. Default creates runs/**CURRENT_DATETIME_HOSTNAME**
        - comment: Comment suffix appended to default logdir (ignored if logdir specified)
        - purge_step: Purge events with global_step >= this value from crashed runs
        - max_queue: Queue size for pending events before forcing flush (default: 10)
        - flush_secs: Seconds between automatic flushes to disk (default: 120)
        - filename_suffix: Suffix added to all event filenames
        - write_to_disk: Whether to write files to disk (False creates dummy writer)
        - log_dir: Deprecated alias for logdir
        - comet_config: Comet integration configuration (default: {"disabled": True})
        """

Scalar Logging

Log scalar values like loss, accuracy, learning rates, and other single-value metrics over training steps.

def add_scalar(
    self,
    tag: str,
    scalar_value,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None,
    display_name: Optional[str] = "",
    summary_description: Optional[str] = ""
):
    """
    Add scalar data to summary.

    Parameters:
    - tag: Data identifier (e.g., 'Loss/Train', 'Accuracy/Validation')
    - scalar_value: Value to record (float, int, numpy scalar, or 0-d tensor)
    - global_step: Global step value for x-axis (auto-increments if None)
    - walltime: Timestamp (uses current time if None)
    - display_name: Display name in TensorBoard (uses tag if empty)
    - summary_description: Description for the summary
    """

def add_scalars(
    self,
    main_tag: str,
    tag_scalar_dict: dict,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None
):
    """
    Add multiple scalar data to summary in a group.

    Parameters:
    - main_tag: Parent name for the scalar group
    - tag_scalar_dict: Dictionary of {tag: scalar_value} pairs
    - global_step: Global step value for x-axis
    - walltime: Timestamp (uses current time if None)
    """

Image Logging

Log images, image batches, and images with bounding box overlays for computer vision tasks and data visualization.

def add_image(
    self,
    tag: str,
    img_tensor,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None,
    dataformats: str = 'CHW'
):
    """
    Add image data to summary.

    Parameters:
    - tag: Data identifier
    - img_tensor: Image tensor (torch.Tensor, numpy.ndarray, or PIL Image)
    - global_step: Global step value
    - walltime: Timestamp
    - dataformats: Tensor format ('CHW', 'HWC', 'HW')
    """

def add_images(
    self,
    tag: str,
    img_tensor,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None,
    dataformats: str = 'NCHW'
):
    """
    Add batched image data to summary.

    Parameters:
    - tag: Data identifier
    - img_tensor: Batched image tensor
    - global_step: Global step value
    - walltime: Timestamp
    - dataformats: Tensor format ('NCHW', 'NHWC')
    """

def add_image_with_boxes(
    self,
    tag: str,
    img_tensor,
    box_tensor,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None,
    dataformats: str = 'CHW',
    labels: Optional[list] = None
):
    """
    Add image with bounding boxes overlay.

    Parameters:
    - tag: Data identifier
    - img_tensor: Image tensor
    - box_tensor: Bounding boxes tensor (N, 4) with format [x1, y1, x2, y2]
    - global_step: Global step value
    - walltime: Timestamp
    - dataformats: Image tensor format
    - labels: List of labels for each bounding box
    """

Histogram Logging

Log distributions of tensor values like weights, gradients, and activations to monitor training dynamics.

def add_histogram(
    self,
    tag: str,
    values,
    global_step: Optional[int] = None,
    bins: str = 'tensorflow',
    walltime: Optional[float] = None,
    max_bins=None
):
    """
    Add histogram of values to summary.

    Parameters:
    - tag: Data identifier
    - values: Values to histogram (tensor or array)
    - global_step: Global step value
    - bins: Binning method ('tensorflow', 'auto', 'fd', etc.) or int for fixed bins
    - walltime: Timestamp
    - max_bins: Maximum number of bins
    """

def add_histogram_raw(
    self,
    tag: str,
    min,
    max,
    num,
    sum,
    sum_squares,
    bucket_limits,
    bucket_counts,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None
):
    """
    Add histogram using raw statistics.

    Parameters:
    - tag: Data identifier
    - min, max: Minimum and maximum values
    - num: Number of data points
    - sum, sum_squares: Sum and sum of squares
    - bucket_limits: Upper edges of histogram buckets
    - bucket_counts: Count of values in each bucket
    - global_step: Global step value
    - walltime: Timestamp
    """

Media Logging

Log multimedia content including videos, audio, figures, and text for rich experiment documentation.

def add_figure(
    self,
    tag: str, 
    figure,
    global_step: Optional[int] = None,
    close: bool = True,
    walltime: Optional[float] = None
):
    """
    Add matplotlib figure to summary.

    Parameters:
    - tag: Data identifier
    - figure: Matplotlib figure object
    - global_step: Global step value
    - close: Whether to close the figure after adding
    - walltime: Timestamp
    """

def add_video(
    self,
    tag: str,
    vid_tensor,
    global_step: Optional[int] = None,
    fps: int = 4,
    walltime: Optional[float] = None,
    dataformats: str = 'NTCHW'
):
    """
    Add video data to summary.

    Parameters:
    - tag: Data identifier
    - vid_tensor: Video tensor with values in [0, 1] or [0, 255]
    - global_step: Global step value
    - fps: Frames per second
    - walltime: Timestamp
    - dataformats: Video tensor format ('NTCHW', 'NTHWC')
    """

def add_audio(
    self,
    tag: str,
    snd_tensor,
    global_step: Optional[int] = None,
    sample_rate: int = 44100,
    walltime: Optional[float] = None
):
    """
    Add audio data to summary.

    Parameters:
    - tag: Data identifier
    - snd_tensor: Audio tensor with values in [-1, 1]
    - global_step: Global step value
    - sample_rate: Sample rate in Hz
    - walltime: Timestamp
    """

def add_text(
    self,
    tag: str,
    text_string: str,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None
):
    """
    Add text data to summary.

    Parameters:
    - tag: Data identifier
    - text_string: Text content (supports markdown)
    - global_step: Global step value
    - walltime: Timestamp
    """

Graph Logging

Log computational graphs from PyTorch models, ONNX models, and OpenVINO models for architecture visualization.

def add_graph(
    self,
    model,
    input_to_model=None,
    verbose: bool = False,
    use_strict_trace: bool = True
):
    """
    Add computational graph to TensorBoard.

    Parameters:
    - model: PyTorch model to trace
    - input_to_model: Input tensor(s) for tracing (required for tracing)
    - verbose: Whether to print trace information
    - use_strict_trace: Whether to use strict tracing mode
    """

def add_onnx_graph(self, onnx_model_file: str):
    """
    Add ONNX graph to TensorBoard.

    Parameters:
    - onnx_model_file: Path to ONNX model file
    """

def add_openvino_graph(self, xmlname: str):
    """
    Add OpenVINO graph to TensorBoard.

    Parameters:
    - xmlname: Path to OpenVINO XML file
    """

Advanced Visualizations

Log embeddings, precision-recall curves, 3D meshes, and hyperparameter comparisons for advanced analysis.

def add_embedding(
    self,
    mat,
    metadata=None,
    label_img=None,
    global_step: Optional[int] = None,
    tag: str = 'default',
    metadata_header=None
):
    """
    Add embedding projector data.

    Parameters:
    - mat: Matrix where each row is a data point
    - metadata: List of labels for each data point
    - label_img: Images corresponding to each data point
    - global_step: Global step value
    - tag: Data identifier
    - metadata_header: Header for metadata columns
    """

def add_pr_curve(
    self,
    tag: str,
    labels,
    predictions,
    global_step: Optional[int] = None,
    num_thresholds: int = 127,
    weights=None,
    walltime: Optional[float] = None
):
    """
    Add precision-recall curve.

    Parameters:
    - tag: Data identifier
    - labels: Ground truth labels (0 or 1)
    - predictions: Prediction scores
    - global_step: Global step value
    - num_thresholds: Number of thresholds for curve
    - weights: Optional weights for each sample
    - walltime: Timestamp
    """

def add_mesh(
    self,
    tag: str,
    vertices,
    colors=None,
    faces=None,
    config_dict=None,
    global_step: Optional[int] = None,
    walltime: Optional[float] = None
):
    """
    Add 3D mesh data.

    Parameters:
    - tag: Data identifier
    - vertices: Vertex positions tensor (N, 3)
    - colors: Vertex colors tensor (N, 3) with values in [0, 255]
    - faces: Face indices tensor (M, 3)
    - config_dict: Display configuration dictionary
    - global_step: Global step value
    - walltime: Timestamp
    """

def add_hparams(
    self,
    hparam_dict: dict,
    metric_dict: dict,
    name: Optional[str] = None,
    global_step: Optional[int] = None
):
    """
    Add hyperparameters for comparison.

    Parameters:
    - hparam_dict: Dictionary of hyperparameter names and values
    - metric_dict: Dictionary of metric names and values
    - name: Experiment name
    - global_step: Global step value
    """

Custom Layouts

Create custom scalar chart layouts for advanced visualization dashboards.

def add_custom_scalars(self, layout: dict):
    """
    Create custom scalar charts layout.

    Parameters:
    - layout: Nested dictionary defining chart organization
    """

def add_custom_scalars_multilinechart(
    self,
    tags: list,
    category: str = 'default',
    title: str = 'untitled'
):
    """
    Shorthand for creating multiline charts.

    Parameters:
    - tags: List of scalar tags to include
    - category: Chart category name
    - title: Chart title
    """

def add_custom_scalars_marginchart(
    self,
    tags: list,
    category: str = 'default', 
    title: str = 'untitled'
):
    """
    Shorthand for creating margin charts.

    Parameters:
    - tags: List of scalar tags (must be exactly 3)
    - category: Chart category name
    - title: Chart title
    """

Data Export and Control

Export data, manage writer lifecycle, and control flushing behavior.

def export_scalars_to_json(self, path: str):
    """
    Export scalar data to JSON file.

    Parameters:
    - path: Output file path
    """

def flush(self):
    """
    Force flush pending events and summaries to disk.
    """

def close(self):
    """
    Close writer and flush all data to disk.
    """

def use_metadata(self, *, global_step=None, walltime=None):
    """
    Context manager to set default metadata for enclosed operations.

    Parameters:
    - global_step: Default global step for enclosed calls
    - walltime: Default walltime for enclosed calls

    Returns:
    Context manager that temporarily sets default metadata
    """

Usage Examples

Basic Training Loop

from tensorboardX import SummaryWriter
import torch
import torch.nn as nn

# Initialize writer
writer = SummaryWriter('runs/training')

model = nn.Linear(10, 1)
criterion = nn.MSELoss()
optimizer = torch.optim.SGD(model.parameters(), lr=0.01)

for epoch in range(100):
    # Training step
    output = model(train_data)
    loss = criterion(output, train_targets)
    
    optimizer.zero_grad()
    loss.backward()
    optimizer.step()
    
    # Log metrics
    writer.add_scalar('Loss/Train', loss.item(), epoch)
    
    # Log model parameters
    for name, param in model.named_parameters():
        writer.add_histogram(f'Parameters/{name}', param, epoch)
        if param.grad is not None:
            writer.add_histogram(f'Gradients/{name}', param.grad, epoch)

writer.close()

Multi-Modal Logging

from tensorboardX import SummaryWriter
import numpy as np
import matplotlib.pyplot as plt

writer = SummaryWriter('runs/multimodal')

for step in range(10):
    # Scalar metrics
    writer.add_scalar('Accuracy', np.random.random(), step)
    
    # Image data
    image = np.random.rand(3, 64, 64)
    writer.add_image('Sample_Image', image, step)
    
    # Audio data
    sample_rate = 22050
    audio = np.sin(2 * np.pi * 440 * np.linspace(0, 1, sample_rate))
    writer.add_audio('Sample_Audio', audio, step, sample_rate)
    
    # Text logging
    writer.add_text('Notes', f'Step {step}: experiment progressing', step)
    
    # Matplotlib figure
    fig, ax = plt.subplots()
    ax.plot(np.random.rand(10))
    ax.set_title(f'Step {step}')
    writer.add_figure('Plot', fig, step)

writer.close()

Install with Tessl CLI