Title: | Write Events for 'TensorBoard' |
---|---|
Description: | Provides a convenient way to log scalars, images, audio, and histograms in the 'tfevent' record file format. Logged data can be visualized on the fly using 'TensorBoard', a web based tool that focuses on visualizing the training progress of machine learning models. |
Authors: | Daniel Falbel [aut, cre, cph], Posit, PBC [cph], The tl::optional authors [cph] (For the vendored tl::optional code.), Mark Adler [cph] (For the included crc32c code.) |
Maintainer: | Daniel Falbel <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.0.4.9000 |
Built: | 2024-10-25 05:02:57 UTC |
Source: | https://github.com/mlverse/tfevents |
Coerce an object to a event.
as_event(x, step, wall_time, ...)
as_event(x, step, wall_time, ...)
x |
Object that will be coerced to an event. |
step |
The step that will be used when the event is logged. This is used by TensorBoard when showing data. |
wall_time |
The all time the event will appended to the event. This field is used by TensorBoard when displaying information based on actual time. |
... |
currently unused. |
A event vctr with class <tfevents_event>.
as_event
as_event
is an S3 generic and you can implement method for your own class.
We don't export the event
constructor though, so you should implement it
in terms of other as_event
methods.
as_event(list(hello = 1), step = 1, wall_time = 1)
as_event(list(hello = 1), step = 1, wall_time = 1)
Collects all events of a kind in a single data.frame ready for analysis.
collect_events( logdir = get_default_logdir(), n = NULL, type = c("any", "summary", "scalar") ) events_logdir(logdir = get_default_logdir())
collect_events( logdir = get_default_logdir(), n = NULL, type = c("any", "summary", "scalar") ) events_logdir(logdir = get_default_logdir())
logdir |
The log directory that you want to query events from. Either a
file path or a connection created with |
n |
The maximum number of events to read from the connection. If |
type |
The kind of events that are to be read. By default all events are read. If a different type is specified, then the result can include other columns as well as more lines. |
A tibble
with the collected events.
events_logdir()
: Creates a connection to a logdir that can be reused
to read further events later.
temp <- tempfile() with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) } }) # collect all events in files, including file description events collect_events(temp) # collect summaries in the logdir collect_events(temp, type = "summary") # collect only scalar events collect_events(temp, type = "scalar")
temp <- tempfile() with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) } }) # collect all events in files, including file description events collect_events(temp) # collect summaries in the logdir collect_events(temp, type = "summary") # collect only scalar events collect_events(temp, type = "scalar")
log_event()
has a notion of default logdir, so you don't need to specify it
at every call. These functions allow you to query and the current logdir.
get_default_logdir() set_default_logdir(logdir = "logs") with_logdir(logdir, code) local_logdir(logdir, .env = parent.frame())
get_default_logdir() set_default_logdir(logdir = "logs") with_logdir(logdir, code) local_logdir(logdir, .env = parent.frame())
logdir |
The |
code |
Expressions that will be evaluated in a context with the |
.env |
Environment that controls scope of changes. For expert use only. |
The logdir
for get_default_logdir()
otherwise invisibly returns
NULL
set_default_logdir()
: Modifies the default logdir
.
with_logdir()
: Temporarily modify the default logdir
.
local_logdir()
: Temporarily modify thedefault logdir
.
temp <- tempfile() get_default_logdir() with_logdir(temp, { print(get_default_logdir()) })
temp <- tempfile() get_default_logdir() with_logdir(temp, { print(get_default_logdir()) })
Global step counters
get_global_step(increment = TRUE) set_global_step(step)
get_global_step(increment = TRUE) set_global_step(step)
increment |
Wether to increment the |
step |
New value for |
tfevents
tracks and automatically increased the step counter whenever
log_event()
is called. Note that, it maintains a separate step counter for
each root logdir
, thus if you change the logdir
using set_default_logdir()
or with_logdir()
, a different step counter will be used.
The global step value for the default logdir, when get_global_step
,
otherwise returns NULL
invisibly.
set_global_step()
: Set the global step.
temp <- tempfile() with_logdir(temp, { print(get_global_step()) set_global_step(100) print(get_global_step()) }) print(get_global_step())
temp <- tempfile() with_logdir(temp, { print(get_global_step()) set_global_step(100) print(get_global_step()) }) print(get_global_step())
Hparam object are used to describe names and domains of hyperparameters so TensorBoard UI can show additional information about them.
hparams_hparam(name, domain = NA, display_name = name, description = name)
hparams_hparam(name, domain = NA, display_name = name, description = name)
name |
Name of the hyperparameter. |
domain |
A list of values that can be assumed by the hyperparameter.
It can be |
display_name |
Display name of the hparameter for the TensorBoard UI. By default it's identical to the name. |
description |
Parameter description. Shown in tooltips around the TensorBoard UI. |
A hparams_hparam
object.
A list of hparam
values can be passed to log_hparams_config()
so
you define the hyperparameters that are tracked by the experiment.
hparams_hparam("optimizer", domain = c("adam", "sgd")) hparams_hparam("num_units", domain = c(128, 512, 1024)) hparams_hparam("use_cnn", domain = c(TRUE, FALSE)) hparams_hparam("dropout", domain = c(min_value = 0, max_value = 0.5))
hparams_hparam("optimizer", domain = c("adam", "sgd")) hparams_hparam("num_units", domain = c(128, 512, 1024)) hparams_hparam("use_cnn", domain = c(TRUE, FALSE)) hparams_hparam("dropout", domain = c(min_value = 0, max_value = 0.5))
Metric objects are passed to log_hparams_config()
in order to define the
collection of scalars that will be displayed in the HParams tab in TensorBoard.
hparams_metric( tag, group = NA, display_name = tag, description = tag, dataset_type = NA )
hparams_metric( tag, group = NA, display_name = tag, description = tag, dataset_type = NA )
tag |
The tag name of the scalar summary that corresponds to this metric. |
group |
An optional string listing the subdirectory under the
session's log directory containing summaries for this metric.
For instance, if summaries for training runs are written to
events files in |
display_name |
An optional human-readable display name. |
description |
An optional Markdown string with a human-readable description of this metric, to appear in TensorBoard. |
dataset_type |
dataset_type: Either |
A hparams_metric
object.
hparams_metric("loss", group = "train") hparams_metric("acc")
hparams_metric("loss", group = "train") hparams_metric("acc")
Log event
log_event(..., step = get_global_step(increment = TRUE))
log_event(..., step = get_global_step(increment = TRUE))
... |
Named values that you want to log. They can be possibly nested, in this case, the enclosing names are considered 'run' names by TensorBoard. |
step |
The step associated the logs. If |
Invisibly returns the logged data.
log_event()
writes events to the default logdir
. You can query the
default logdir
with get_default_logdir()
and modify it with
set_default_logdir()
. You can also use the with_logdir()
context switcher
to temporarily modify the logdir.
temp <- tempfile() with_logdir(temp, { log_event( train = list(loss = runif(1), acc = runif(1)), valid = list(loss = runif(1), acc = runif(1)) ) })
temp <- tempfile() with_logdir(temp, { log_event( train = list(loss = runif(1), acc = runif(1)), valid = list(loss = runif(1), acc = runif(1)) ) })
Log hyperaparameters
log_hparams(..., trial_id = NA, time_created_secs = get_wall_time()) summary_hparams(..., trial_id = NA, time_created_secs = get_wall_time())
log_hparams(..., trial_id = NA, time_created_secs = get_wall_time()) summary_hparams(..., trial_id = NA, time_created_secs = get_wall_time())
... |
Named values of hyperparameters. |
trial_id |
A name for the current trail. by default it's the hash of the hparams names and values. |
time_created_secs |
The time the experiment is created in seconds since the UNIX epoch. |
This function should only be called once in a logdir and it will record the set of hyperparameters used in that run. Undefined behavior can happen if it's called more than once in a logdir - specially how TensorBoard behaves during visualization.
A hyperparameter summary. USed for the side effects of logging the hyperparameter to the logdir.
summary_hparams()
: For advanced users only. It's recommended to use the log_hparams()
function instead. Creates a hyperparameter summary that can be written with log_event()
.
temp <- tempfile() with_logdir(temp, { log_hparams(optimizer = "adam", num_units = 16) })
temp <- tempfile() with_logdir(temp, { log_hparams(optimizer = "adam", num_units = 16) })
Logs the hyperaparameter configuration for a HyperParameter tuning experiment. It allows you to define the domain for each hyperparameters and what are the metrics that should be shown in the TensorBoard UI, along with configuring their display name and descriptions.
log_hparams_config(hparams, metrics, time_created_secs = get_wall_time()) summary_hparams_config(hparams, metrics, time_created_secs = get_wall_time())
log_hparams_config(hparams, metrics, time_created_secs = get_wall_time()) summary_hparams_config(hparams, metrics, time_created_secs = get_wall_time())
hparams |
A list of |
metrics |
A list of |
time_created_secs |
The time the experiment is created in seconds since the UNIX epoch. |
Invisibly returns the HParam conffuration data as a summary
object.
summary_hparams_config()
: For advanced users only. Creates a hyperaparameter
configuration summary that can be logged with log_event()
.
When loging hyperparameter tuning experiments, the log directory organization is:
- root: - log_hparams_config(...) - run1: - log_hparams(...) - log_event(...) - run2: - log_hparams(...) - log_event(...)
Ie you should have a root logdir that will only contain the hyperaparameter
config log, as created with log_hparams_config()
. Then each run in the
experiment will have it's own logdir as a child directory of the root logdir.
Audio summaries can be played withing the TensorBoard UI.
summary_audio(audio, ..., metadata = NULL, tag = NA) ## S3 method for class 'array' summary_audio(audio, ..., sample_rate = 44100, metadata = NULL, tag = NA) ## S3 method for class 'raw' summary_audio(audio, ..., metadata = NULL, tag = NA) ## S3 method for class 'blob' summary_audio(audio, ..., metadata = NULL, tag = NA)
summary_audio(audio, ..., metadata = NULL, tag = NA) ## S3 method for class 'array' summary_audio(audio, ..., sample_rate = 44100, metadata = NULL, tag = NA) ## S3 method for class 'raw' summary_audio(audio, ..., metadata = NULL, tag = NA) ## S3 method for class 'blob' summary_audio(audio, ..., metadata = NULL, tag = NA)
audio |
Object that will be written as an audio event in the tfevents record. |
... |
Currently unused. |
metadata |
A |
tag |
A tag that within the TensorBoard UI. See |
sample_rate |
The sample rate in Hz associated to the audio values. |
An audio summary that can be logged with log_event()
.
summary_audio(array)
: Creates a summary from a 3D array with dimensions
(batch_size, n_samples, n_channels)
. Values must be in the range [-1, 1]
.
summary_audio(raw)
: Creates an audio summary from a raw vector containing
a WAV encoded audio file.
summary_audio(blob)
: Creates an audio summary from a blob (ie list of raw vectors)
containing WAV encoded audio files.
Other summary:
summary_histogram()
,
summary_image()
,
summary_scalar()
,
summary_text()
tmp <- tempfile() with_logdir(tmp, { summary_audio(array(runif(100), dim = c(1,100, 1))) })
tmp <- tempfile() with_logdir(tmp, { summary_audio(array(runif(100), dim = c(1,100, 1))) })
Writes an histogram for later analysis in TensorBoard's Histograms and Distributions tab.
summary_histogram(data, ..., metadata = NULL, tag = NA) ## S3 method for class 'numeric' summary_histogram(data, ..., metadata = NULL, tag = NA, buckets = 30) ## S3 method for class 'array' summary_histogram(data, ..., metadata = NULL, tag = NA, buckets = 30)
summary_histogram(data, ..., metadata = NULL, tag = NA) ## S3 method for class 'numeric' summary_histogram(data, ..., metadata = NULL, tag = NA, buckets = 30) ## S3 method for class 'array' summary_histogram(data, ..., metadata = NULL, tag = NA, buckets = 30)
data |
A Tensor of any shape. The histogram is computed over its elements, which must be castable to float64. |
... |
Currently unused. To allow future expansion. |
metadata |
A |
tag |
A tag that within the TensorBoard UI. See |
buckets |
Optional positive int. The output will have this many buckets, except in two edge cases. If there is no data, then there are no buckets. If there is data but all points have the same value, then all buckets' left and right endpoints are the same and only the last bucket has nonzero count. Defaults to 30 if not specified. |
An histogram summary that can be logged with log_event()
.
summary_histogram(numeric)
: Creates an histogram summary for a numeric vector.
summary_histogram(array)
: Creates an histogram for array data.
Other summary:
summary_audio()
,
summary_image()
,
summary_scalar()
,
summary_text()
temp <- tempfile() with_logdir(temp, { for(i in 1:10) { log_event(x = summary_histogram(rnorm(10000))) } })
temp <- tempfile() with_logdir(temp, { for(i in 1:10) { log_event(x = summary_histogram(rnorm(10000))) } })
Creates a image summary
summary_image(img, ..., metadata = NULL, tag = NA) ## S3 method for class 'ggplot' summary_image(img, ..., width = 480, height = 480, metadata = NULL, tag = NA) ## S3 method for class 'array' summary_image(img, ..., metadata = NULL, tag = NA) ## S3 method for class 'blob' summary_image(img, ..., width, height, colorspace, metadata = NULL, tag = NA) ## S3 method for class 'raw' summary_image(img, ..., width, height, colorspace, metadata = NULL, tag = NA)
summary_image(img, ..., metadata = NULL, tag = NA) ## S3 method for class 'ggplot' summary_image(img, ..., width = 480, height = 480, metadata = NULL, tag = NA) ## S3 method for class 'array' summary_image(img, ..., metadata = NULL, tag = NA) ## S3 method for class 'blob' summary_image(img, ..., width, height, colorspace, metadata = NULL, tag = NA) ## S3 method for class 'raw' summary_image(img, ..., width, height, colorspace, metadata = NULL, tag = NA)
img |
An object that can be converted to an image. |
... |
Currently unused. |
metadata |
A |
tag |
A tag that within the TensorBoard UI. See |
width |
Width of the image. |
height |
Height of the image. |
colorspace |
Valid colorspace values are
|
An image summary that can be logged with log_event()
.
summary_image(ggplot)
: Cretes an image summary from a ggplot2 graph object.
The ...
will be forwarded to grDevices::png()
.
summary_image(array)
: Creates an image from an R array. The array should be
numeric, with values between 0 and 1. Dimensions should be (batch, height, width, channels)
.
summary_image(blob)
: Creates an image from blob::blob()
vctr of PNG encoded images,
(eg using png::writePNG()
). width
, height
and colorspace
are recycled
thus they can be a single scalar or a vector the same size of the images blob.
summary_image(raw)
: Creates an image from a png encoded image. Eg, created
with png::writePNG()
. In this case you need to provide width
, height
and
colorspace
arguments.
Other summary:
summary_audio()
,
summary_histogram()
,
summary_scalar()
,
summary_text()
tmp <- tempfile() with_logdir(tmp, { summary_image(array(runif(100), dim = c(1,10, 10, 1))) })
tmp <- tempfile() with_logdir(tmp, { summary_image(array(runif(100), dim = c(1,10, 10, 1))) })
Creates a summary metadata that can be passed to multiple summary_
functions.
summary_metadata( plugin_name, display_name = NA_character_, description = NA_character_, ..., plugin_content = NA )
summary_metadata( plugin_name, display_name = NA_character_, description = NA_character_, ..., plugin_content = NA )
plugin_name |
The name of the TensorBoard plugin that might use the summary. |
display_name |
Display name for the summary. |
description |
A description of the summary. |
... |
Currently unused. For future expansion. |
plugin_content |
An optional plugin content. Note that it will only be
used if the C++ function |
A summary_metadata
object.
summary <- summary_scalar(1, metadata = summary_metadata("scalars"))
summary <- summary_scalar(1, metadata = summary_metadata("scalars"))
Scalar event
summary_scalar(value, ..., metadata = NULL, tag = NA)
summary_scalar(value, ..., metadata = NULL, tag = NA)
value |
A numeric scalar value to be logged. |
... |
Currently unused. To allow future expansion. |
metadata |
A |
tag |
A tag that within the TensorBoard UI. See |
A <scalar_event>
object.
Other summary:
summary_audio()
,
summary_histogram()
,
summary_image()
,
summary_text()
temp <- tempfile() with_logdir(temp, { log_event(loss = summary_scalar(1)) })
temp <- tempfile() with_logdir(temp, { log_event(loss = summary_scalar(1)) })
Creates a text summary
summary_text(txt, ..., metadata = NULL, tag = NA) ## S3 method for class 'character' summary_text(txt, ..., metadata = NULL, tag = NA)
summary_text(txt, ..., metadata = NULL, tag = NA) ## S3 method for class 'character' summary_text(txt, ..., metadata = NULL, tag = NA)
txt |
An object that can be converted to a text. |
... |
Currently unused. |
metadata |
A |
tag |
A tag that within the TensorBoard UI. See |
A summary that can be logged with log_event()
.
summary_text(character)
: Creates a summary from a scalar character vector.
Other summary:
summary_audio()
,
summary_histogram()
,
summary_image()
,
summary_scalar()
temp <- tempfile() with_logdir(temp, { log_event( x = "hello world", y = summary_text("hello world") ) })
temp <- tempfile() with_logdir(temp, { log_event( x = "hello world", y = summary_text("hello world") ) })
Summaries are complicated objects because they reflect the Protobuf object structure that are serialized in the tfevents records files. This function allows one to easily query vaues from summaries and will dispatch to the correct way to extract images, audio, text, etc from summary values.
value(x, ...) ## S3 method for class 'tfevents_summary_values' value(x, ..., as_list = FALSE)
value(x, ...) ## S3 method for class 'tfevents_summary_values' value(x, ..., as_list = FALSE)
x |
A |
... |
Currently unused. To allow future extension. |
as_list |
A boolean indicating if the results should be returned in a list.
The default is to return a single value. If you need to extract values from
multiple summaries use |
Depending on the type of the summary it returns an image, audio, text or scalar.
value(tfevents_summary_values)
: Acess values from summary_values
.
temp <- tempfile() with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) } }) # iterate over all events summary <- collect_events(temp, n = 1, type = "summary") value(summary$summary)
temp <- tempfile() with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) } }) # iterate over all events summary <- collect_events(temp, n = 1, type = "summary") value(summary$summary)