0
# Summary Writer
1

2
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.
3

4
## Capabilities
5

6
### Initialization
7

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

10
```python { .api }
11
class SummaryWriter:
12
    def __init__(
13
        self,
14
        logdir: Optional[str] = None,
15
        comment: Optional[str] = "",
16
        purge_step: Optional[int] = None,
17
        max_queue: Optional[int] = 10,
18
        flush_secs: Optional[int] = 120,
19
        filename_suffix: Optional[str] = '',
20
        write_to_disk: Optional[bool] = True,
21
        log_dir: Optional[str] = None,
22
        comet_config: Optional[dict] = {"disabled": True}
23
    ):
24
        """
25
        Creates a SummaryWriter for logging events and summaries.
26

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

40
### Scalar Logging
41

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

44
```python { .api }
45
def add_scalar(
46
    self,
47
    tag: str,
48
    scalar_value,
49
    global_step: Optional[int] = None,
50
    walltime: Optional[float] = None,
51
    display_name: Optional[str] = "",
52
    summary_description: Optional[str] = ""
53
):
54
    """
55
    Add scalar data to summary.
56

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

66
def add_scalars(
67
    self,
68
    main_tag: str,
69
    tag_scalar_dict: dict,
70
    global_step: Optional[int] = None,
71
    walltime: Optional[float] = None
72
):
73
    """
74
    Add multiple scalar data to summary in a group.
75

76
    Parameters:
77
    - main_tag: Parent name for the scalar group
78
    - tag_scalar_dict: Dictionary of {tag: scalar_value} pairs
79
    - global_step: Global step value for x-axis
80
    - walltime: Timestamp (uses current time if None)
81
    """
82
```
83

84
### Image Logging
85

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

88
```python { .api }
89
def add_image(
90
    self,
91
    tag: str,
92
    img_tensor,
93
    global_step: Optional[int] = None,
94
    walltime: Optional[float] = None,
95
    dataformats: str = 'CHW'
96
):
97
    """
98
    Add image data to summary.
99

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

108
def add_images(
109
    self,
110
    tag: str,
111
    img_tensor,
112
    global_step: Optional[int] = None,
113
    walltime: Optional[float] = None,
114
    dataformats: str = 'NCHW'
115
):
116
    """
117
    Add batched image data to summary.
118

119
    Parameters:
120
    - tag: Data identifier
121
    - img_tensor: Batched image tensor
122
    - global_step: Global step value
123
    - walltime: Timestamp
124
    - dataformats: Tensor format ('NCHW', 'NHWC')
125
    """
126

127
def add_image_with_boxes(
128
    self,
129
    tag: str,
130
    img_tensor,
131
    box_tensor,
132
    global_step: Optional[int] = None,
133
    walltime: Optional[float] = None,
134
    dataformats: str = 'CHW',
135
    labels: Optional[list] = None
136
):
137
    """
138
    Add image with bounding boxes overlay.
139

140
    Parameters:
141
    - tag: Data identifier
142
    - img_tensor: Image tensor
143
    - box_tensor: Bounding boxes tensor (N, 4) with format [x1, y1, x2, y2]
144
    - global_step: Global step value
145
    - walltime: Timestamp
146
    - dataformats: Image tensor format
147
    - labels: List of labels for each bounding box
148
    """
149
```
150

151
### Histogram Logging
152

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

155
```python { .api }
156
def add_histogram(
157
    self,
158
    tag: str,
159
    values,
160
    global_step: Optional[int] = None,
161
    bins: str = 'tensorflow',
162
    walltime: Optional[float] = None,
163
    max_bins=None
164
):
165
    """
166
    Add histogram of values to summary.
167

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

177
def add_histogram_raw(
178
    self,
179
    tag: str,
180
    min,
181
    max,
182
    num,
183
    sum,
184
    sum_squares,
185
    bucket_limits,
186
    bucket_counts,
187
    global_step: Optional[int] = None,
188
    walltime: Optional[float] = None
189
):
190
    """
191
    Add histogram using raw statistics.
192

193
    Parameters:
194
    - tag: Data identifier
195
    - min, max: Minimum and maximum values
196
    - num: Number of data points
197
    - sum, sum_squares: Sum and sum of squares
198
    - bucket_limits: Upper edges of histogram buckets
199
    - bucket_counts: Count of values in each bucket
200
    - global_step: Global step value
201
    - walltime: Timestamp
202
    """
203
```
204

205
### Media Logging
206

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

209
```python { .api }
210
def add_figure(
211
    self,
212
    tag: str, 
213
    figure,
214
    global_step: Optional[int] = None,
215
    close: bool = True,
216
    walltime: Optional[float] = None
217
):
218
    """
219
    Add matplotlib figure to summary.
220

221
    Parameters:
222
    - tag: Data identifier
223
    - figure: Matplotlib figure object
224
    - global_step: Global step value
225
    - close: Whether to close the figure after adding
226
    - walltime: Timestamp
227
    """
228

229
def add_video(
230
    self,
231
    tag: str,
232
    vid_tensor,
233
    global_step: Optional[int] = None,
234
    fps: int = 4,
235
    walltime: Optional[float] = None,
236
    dataformats: str = 'NTCHW'
237
):
238
    """
239
    Add video data to summary.
240

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

250
def add_audio(
251
    self,
252
    tag: str,
253
    snd_tensor,
254
    global_step: Optional[int] = None,
255
    sample_rate: int = 44100,
256
    walltime: Optional[float] = None
257
):
258
    """
259
    Add audio data to summary.
260

261
    Parameters:
262
    - tag: Data identifier
263
    - snd_tensor: Audio tensor with values in [-1, 1]
264
    - global_step: Global step value
265
    - sample_rate: Sample rate in Hz
266
    - walltime: Timestamp
267
    """
268

269
def add_text(
270
    self,
271
    tag: str,
272
    text_string: str,
273
    global_step: Optional[int] = None,
274
    walltime: Optional[float] = None
275
):
276
    """
277
    Add text data to summary.
278

279
    Parameters:
280
    - tag: Data identifier
281
    - text_string: Text content (supports markdown)
282
    - global_step: Global step value
283
    - walltime: Timestamp
284
    """
285
```
286

287
### Graph Logging
288

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

291
```python { .api }
292
def add_graph(
293
    self,
294
    model,
295
    input_to_model=None,
296
    verbose: bool = False,
297
    use_strict_trace: bool = True
298
):
299
    """
300
    Add computational graph to TensorBoard.
301

302
    Parameters:
303
    - model: PyTorch model to trace
304
    - input_to_model: Input tensor(s) for tracing (required for tracing)
305
    - verbose: Whether to print trace information
306
    - use_strict_trace: Whether to use strict tracing mode
307
    """
308

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

313
    Parameters:
314
    - onnx_model_file: Path to ONNX model file
315
    """
316

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

321
    Parameters:
322
    - xmlname: Path to OpenVINO XML file
323
    """
324
```
325

326
### Advanced Visualizations
327

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

330
```python { .api }
331
def add_embedding(
332
    self,
333
    mat,
334
    metadata=None,
335
    label_img=None,
336
    global_step: Optional[int] = None,
337
    tag: str = 'default',
338
    metadata_header=None
339
):
340
    """
341
    Add embedding projector data.
342

343
    Parameters:
344
    - mat: Matrix where each row is a data point
345
    - metadata: List of labels for each data point
346
    - label_img: Images corresponding to each data point
347
    - global_step: Global step value
348
    - tag: Data identifier
349
    - metadata_header: Header for metadata columns
350
    """
351

352
def add_pr_curve(
353
    self,
354
    tag: str,
355
    labels,
356
    predictions,
357
    global_step: Optional[int] = None,
358
    num_thresholds: int = 127,
359
    weights=None,
360
    walltime: Optional[float] = None
361
):
362
    """
363
    Add precision-recall curve.
364

365
    Parameters:
366
    - tag: Data identifier
367
    - labels: Ground truth labels (0 or 1)
368
    - predictions: Prediction scores
369
    - global_step: Global step value
370
    - num_thresholds: Number of thresholds for curve
371
    - weights: Optional weights for each sample
372
    - walltime: Timestamp
373
    """
374

375
def add_mesh(
376
    self,
377
    tag: str,
378
    vertices,
379
    colors=None,
380
    faces=None,
381
    config_dict=None,
382
    global_step: Optional[int] = None,
383
    walltime: Optional[float] = None
384
):
385
    """
386
    Add 3D mesh data.
387

388
    Parameters:
389
    - tag: Data identifier
390
    - vertices: Vertex positions tensor (N, 3)
391
    - colors: Vertex colors tensor (N, 3) with values in [0, 255]
392
    - faces: Face indices tensor (M, 3)
393
    - config_dict: Display configuration dictionary
394
    - global_step: Global step value
395
    - walltime: Timestamp
396
    """
397

398
def add_hparams(
399
    self,
400
    hparam_dict: dict,
401
    metric_dict: dict,
402
    name: Optional[str] = None,
403
    global_step: Optional[int] = None
404
):
405
    """
406
    Add hyperparameters for comparison.
407

408
    Parameters:
409
    - hparam_dict: Dictionary of hyperparameter names and values
410
    - metric_dict: Dictionary of metric names and values
411
    - name: Experiment name
412
    - global_step: Global step value
413
    """
414
```
415

416
### Custom Layouts
417

418
Create custom scalar chart layouts for advanced visualization dashboards.
419

420
```python { .api }
421
def add_custom_scalars(self, layout: dict):
422
    """
423
    Create custom scalar charts layout.
424

425
    Parameters:
426
    - layout: Nested dictionary defining chart organization
427
    """
428

429
def add_custom_scalars_multilinechart(
430
    self,
431
    tags: list,
432
    category: str = 'default',
433
    title: str = 'untitled'
434
):
435
    """
436
    Shorthand for creating multiline charts.
437

438
    Parameters:
439
    - tags: List of scalar tags to include
440
    - category: Chart category name
441
    - title: Chart title
442
    """
443

444
def add_custom_scalars_marginchart(
445
    self,
446
    tags: list,
447
    category: str = 'default', 
448
    title: str = 'untitled'
449
):
450
    """
451
    Shorthand for creating margin charts.
452

453
    Parameters:
454
    - tags: List of scalar tags (must be exactly 3)
455
    - category: Chart category name
456
    - title: Chart title
457
    """
458
```
459

460
### Data Export and Control
461

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

464
```python { .api }
465
def export_scalars_to_json(self, path: str):
466
    """
467
    Export scalar data to JSON file.
468

469
    Parameters:
470
    - path: Output file path
471
    """
472

473
def flush(self):
474
    """
475
    Force flush pending events and summaries to disk.
476
    """
477

478
def close(self):
479
    """
480
    Close writer and flush all data to disk.
481
    """
482

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

487
    Parameters:
488
    - global_step: Default global step for enclosed calls
489
    - walltime: Default walltime for enclosed calls
490

491
    Returns:
492
    Context manager that temporarily sets default metadata
493
    """
494
```
495

496
## Usage Examples
497

498
### Basic Training Loop
499

500
```python
501
from tensorboardX import SummaryWriter
502
import torch
503
import torch.nn as nn
504

505
# Initialize writer
506
writer = SummaryWriter('runs/training')
507

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

512
for epoch in range(100):
513
    # Training step
514
    output = model(train_data)
515
    loss = criterion(output, train_targets)
516
    
517
    optimizer.zero_grad()
518
    loss.backward()
519
    optimizer.step()
520
    
521
    # Log metrics
522
    writer.add_scalar('Loss/Train', loss.item(), epoch)
523
    
524
    # Log model parameters
525
    for name, param in model.named_parameters():
526
        writer.add_histogram(f'Parameters/{name}', param, epoch)
527
        if param.grad is not None:
528
            writer.add_histogram(f'Gradients/{name}', param.grad, epoch)
529

530
writer.close()
531
```
532

533
### Multi-Modal Logging
534

535
```python
536
from tensorboardX import SummaryWriter
537
import numpy as np
538
import matplotlib.pyplot as plt
539

540
writer = SummaryWriter('runs/multimodal')
541

542
for step in range(10):
543
    # Scalar metrics
544
    writer.add_scalar('Accuracy', np.random.random(), step)
545
    
546
    # Image data
547
    image = np.random.rand(3, 64, 64)
548
    writer.add_image('Sample_Image', image, step)
549
    
550
    # Audio data
551
    sample_rate = 22050
552
    audio = np.sin(2 * np.pi * 440 * np.linspace(0, 1, sample_rate))
553
    writer.add_audio('Sample_Audio', audio, step, sample_rate)
554
    
555
    # Text logging
556
    writer.add_text('Notes', f'Step {step}: experiment progressing', step)
557
    
558
    # Matplotlib figure
559
    fig, ax = plt.subplots()
560
    ax.plot(np.random.rand(10))
561
    ax.set_title(f'Step {step}')
562
    writer.add_figure('Plot', fig, step)
563

564
writer.close()
565
```