| Title: | Write Events for 'TensorBoard' |
| Version: | 0.0.4 |
| 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. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.2.3 |
| LinkingTo: | Rcpp |
| Imports: | Rcpp, withr, fs, rlang (≥ 1.0.0), vctrs, blob, png, digest,cli, zeallot |
| Suggests: | testthat (≥ 3.0.0), tibble, tidyr, reticulate, rmarkdown,ggplot2, tensorflow, wav |
| SystemRequirements: | libprotobuf, protobuf-compiler |
| URL: | https://github.com/mlverse/tfevents,https://mlverse.github.io/tfevents/ |
| BugReports: | https://github.com/mlverse/tfevents/issues |
| Config/testthat/edition: | 3 |
| Config/Needs/website: | tensorflow, webshot2, keras |
| NeedsCompilation: | yes |
| Packaged: | 2024-06-27 12:24:11 UTC; dfalbel |
| Author: | 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 <daniel@posit.co> |
| Repository: | CRAN |
| Date/Publication: | 2024-06-27 12:40:02 UTC |
Coerce an object to a event.
Description
Coerce an object to a event.
Usage
as_event(x, step, wall_time, ...)Arguments
x | Object that will be coerced to an event. |
step | The step that will be used when the event is logged. This is usedby TensorBoard when showing data. |
wall_time | The all time the event will appended to the event. This fieldis used by TensorBoard when displaying information based on actual time. |
... | currently unused. |
Value
A event vctr with class <tfevents_event>.
Extendingas_event
as_event is an S3 generic and you can implement method for your own class.We don't export theevent constructor though, so you should implement itin terms of otheras_event methods.
Examples
as_event(list(hello = 1), step = 1, wall_time = 1)Collect data from tfevents records
Description
Collects all events of a kind in a single data.frame ready for analysis.
Usage
collect_events( logdir = get_default_logdir(), n = NULL, type = c("any", "summary", "scalar"))events_logdir(logdir = get_default_logdir())Arguments
logdir | The log directory that you want to query events from. Either afile 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 areread. If a different type is specified, then the result can include othercolumns as well as more lines. |
Value
Atibble with the collected events.
Functions
events_logdir(): Creates a connection to a logdir that can be reusedto read further events later.
Examples
temp <- tempfile()with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) }})# collect all events in files, including file description eventscollect_events(temp)# collect summaries in the logdircollect_events(temp, type = "summary")# collect only scalar eventscollect_events(temp, type = "scalar")Creates events
Description
We try to match events as closely as possible to the protobuf messages.The hierarchy looks like:
event (<event>): - run (<character>) - wall_time (<integer>) - step (<integer>) - summary (<summary> aka list_of<summary_values>): - values (list): - <summary_value>: - metadata (<summary_metadata>) - tag (<character>) - value (<numeric>) - image (<summary_summary_image>) - buffer (<blob>) - width (<integer>) - height (<integer>) - colorspace (<integer>)
Usage
event(run, wall_time, step, ..., summary = NA, file_version = NA)Query and modify the logdir
Description
log_event() has a notion of default logdir, so you don't need to specify itat every call. These functions allow you to query and the current logdir.
Usage
get_default_logdir()set_default_logdir(logdir = "logs")with_logdir(logdir, code)local_logdir(logdir, .env = parent.frame())Arguments
logdir | The |
code | Expressions that will be evaluated in a context with the |
.env | Environment that controls scope of changes. For expert use only. |
Value
Thelogdir forget_default_logdir() otherwise invisibly returnsNULL
Functions
set_default_logdir(): Modifies the defaultlogdir.with_logdir(): Temporarily modify the defaultlogdir.local_logdir(): Temporarily modify thedefaultlogdir.
Examples
temp <- tempfile()get_default_logdir()with_logdir(temp, { print(get_default_logdir())})Global step counters
Description
Global step counters
Usage
get_global_step(increment = TRUE)set_global_step(step)Arguments
increment | Wether to increment the |
step | New value for |
Details
tfevents tracks and automatically increased the step counter wheneverlog_event() is called. Note that, it maintains a separate step counter foreach rootlogdir, thus if you change thelogdir usingset_default_logdir()orwith_logdir(), a different step counter will be used.
Value
The global step value for the default logdir, whenget_global_step,otherwise returnsNULL invisibly.
Functions
set_global_step(): Set the global step.
Examples
temp <- tempfile()with_logdir(temp, { print(get_global_step()) set_global_step(100) print(get_global_step())})print(get_global_step())Defines a HParam
Description
Hparam object are used to describe names and domains of hyperparameters soTensorBoard UI can show additional information about them.
Usage
hparams_hparam(name, domain = NA, display_name = name, description = name)Arguments
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 theTensorBoard UI. |
Value
Ahparams_hparam object.
Note
A list ofhparam values can be passed tolog_hparams_config() soyou define the hyperparameters that are tracked by the experiment.
Examples
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))Defines a Metric
Description
Metric objects are passed tolog_hparams_config() in order to define thecollection of scalars that will be displayed in the HParams tab in TensorBoard.
Usage
hparams_metric( tag, group = NA, display_name = tag, description = tag, dataset_type = NA)Arguments
tag | The tag name of the scalar summary that corresponds to thismetric. |
group | An optional string listing the subdirectory under thesession's log directory containing summaries for this metric.For instance, if summaries for training runs are written toevents files in |
display_name | An optional human-readable display name. |
description | An optional Markdown string with a human-readabledescription of this metric, to appear in TensorBoard. |
dataset_type | dataset_type: Either |
Value
Ahparams_metric object.
Examples
hparams_metric("loss", group = "train")hparams_metric("acc")Log event
Description
Log event
Usage
log_event(..., step = get_global_step(increment = TRUE))Arguments
... | 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 |
Value
Invisibly returns the logged data.
Note
log_event() writes events to the defaultlogdir. You can query thedefaultlogdir withget_default_logdir() and modify it withset_default_logdir(). You can also use thewith_logdir() context switcherto temporarily modify the logdir.
Examples
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
Description
Log hyperaparameters
Usage
log_hparams(..., trial_id = NA, time_created_secs = get_wall_time())summary_hparams(..., trial_id = NA, time_created_secs = get_wall_time())Arguments
... | Named values of hyperparameters. |
trial_id | A name for the current trail. by default it's the hash of thehparams names and values. |
time_created_secs | The time the experiment is created in secondssince the UNIX epoch. |
Details
This function should only be called once in a logdir and it willrecord the set of hyperparameters used in that run. Undefined behavior canhappen if it's called more than once in a logdir - specially how TensorBoardbehaves during visualization.
Value
A hyperparameter summary. USed for the side effects of logging thehyperparameter to the logdir.
Functions
summary_hparams(): For advanced users only. It's recommended to use thelog_hparams()function instead. Creates a hyperparameter summary that can be written withlog_event().
See Also
Examples
temp <- tempfile()with_logdir(temp, { log_hparams(optimizer = "adam", num_units = 16)})Logs hyperparameters configuration
Description
Logs the hyperaparameter configuration for a HyperParameter tuning experiment.It allows you to define the domain for each hyperparameters and what are themetrics that should be shown in the TensorBoard UI, along with configuringtheir display name and descriptions.
Usage
log_hparams_config(hparams, metrics, time_created_secs = get_wall_time())summary_hparams_config(hparams, metrics, time_created_secs = get_wall_time())Arguments
hparams | A list of |
metrics | A list of |
time_created_secs | The time the experiment is created in secondssince the UNIX epoch. |
Value
Invisibly returns the HParam conffuration data as asummary object.
Functions
summary_hparams_config(): For advanced users only. Creates a hyperaparameterconfiguration summary that can be logged withlog_event().
Recommendations
When loging hyperparameter tuning experiments, the log directory organizationis:
- 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 hyperaparameterconfig log, as created withlog_hparams_config(). Then each run in theexperiment will have it's own logdir as a child directory of the root logdir.
See Also
Summary audio
Description
Audio summaries can be played withing the TensorBoard UI.
Usage
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)Arguments
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. |
Value
An audio summary that can be logged withlog_event().
Methods (by class)
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 containinga WAV encoded audio file.summary_audio(blob): Creates an audio summary from a blob (ie list of raw vectors)containing WAV encoded audio files.
See Also
Other summary:summary_histogram(),summary_image(),summary_scalar(),summary_text()
Examples
tmp <- tempfile()with_logdir(tmp, { summary_audio(array(runif(100), dim = c(1,100, 1)))})Creates an histogram summary
Description
Writes an histogram for later analysis in TensorBoard's Histograms andDistributions tab.
Usage
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)Arguments
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' leftand right endpoints are the same and only the last bucket has nonzero count.Defaults to 30 if not specified. |
Value
An histogram summary that can be logged withlog_event().
Methods (by class)
summary_histogram(numeric): Creates an histogram summary for a numeric vector.summary_histogram(array): Creates an histogram for array data.
See Also
Other summary:summary_audio(),summary_image(),summary_scalar(),summary_text()
Examples
temp <- tempfile()with_logdir(temp, { for(i in 1:10) { log_event(x = summary_histogram(rnorm(10000))) }})Creates a image summary
Description
Creates a image summary
Usage
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)Arguments
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 |
Value
An image summary that can be logged withlog_event().
Methods (by class)
summary_image(ggplot): Cretes an image summary from a ggplot2 graph object.The...will be forwarded togrDevices::png().summary_image(array): Creates an image from an R array. The array should benumeric, with values between 0 and 1. Dimensions should be(batch, height, width, channels).summary_image(blob): Creates an image fromblob::blob()vctr of PNG encoded images,(eg usingpng::writePNG()).width,heightandcolorspaceare recycledthus 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, createdwithpng::writePNG(). In this case you need to providewidth,heightandcolorspacearguments.
See Also
Other summary:summary_audio(),summary_histogram(),summary_scalar(),summary_text()
Examples
tmp <- tempfile()with_logdir(tmp, { summary_image(array(runif(100), dim = c(1,10, 10, 1)))})Summary metadata
Description
Creates a summary metadata that can be passed to multiplesummary_ functions.
Usage
summary_metadata( plugin_name, display_name = NA_character_, description = NA_character_, ..., plugin_content = NA)Arguments
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 beused if the C++ function |
Value
Asummary_metadata object.
Examples
summary <- summary_scalar(1, metadata = summary_metadata("scalars"))Scalar event
Description
Scalar event
Usage
summary_scalar(value, ..., metadata = NULL, tag = NA)Arguments
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 |
Value
A<scalar_event> object.
See Also
Other summary:summary_audio(),summary_histogram(),summary_image(),summary_text()
Examples
temp <- tempfile()with_logdir(temp, { log_event(loss = summary_scalar(1))})Creates a text summary
Description
Creates a text summary
Usage
summary_text(txt, ..., metadata = NULL, tag = NA)## S3 method for class 'character'summary_text(txt, ..., metadata = NULL, tag = NA)Arguments
txt | An object that can be converted to a text. |
... | Currently unused. |
metadata | A |
tag | A tag that within the TensorBoard UI. See |
Value
A summary that can be logged withlog_event().
Methods (by class)
summary_text(character): Creates a summary from a scalar character vector.
See Also
Other summary:summary_audio(),summary_histogram(),summary_image(),summary_scalar()
Examples
temp <- tempfile()with_logdir(temp, { log_event( x = "hello world", y = summary_text("hello world") )})Extracts the value of a summary value
Description
Summaries are complicated objects because they reflect the Protobuf objectstructure that are serialized in the tfevents records files. This functionallows one to easily query vaues from summaries and will dispatch to thecorrect way to extract images, audio, text, etc from summary values.
Usage
value(x, ...)## S3 method for class 'tfevents_summary_values'value(x, ..., as_list = FALSE)Arguments
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 frommultiple summaries use |
Value
Depending on the type of the summary it returns an image, audio, text orscalar.
Methods (by class)
value(tfevents_summary_values): Acess values fromsummary_values.
Examples
temp <- tempfile()with_logdir(temp, { for(i in 1:5) { log_event(my_log = runif(1)) }})# iterate over all eventssummary <- collect_events(temp, n = 1, type = "summary")value(summary$summary)