Merge pull request #64 from fissoreg/master

Support for CUSTOM_SCALARS

Author: PhilipVinc

Project.toml

@@ -1,7 +1,7 @@
 name = "TensorBoardLogger"
 uuid = "899adc3e-224a-11e9-021f-63837185c80f"
 authors = ["Filippo Vicentini <filippovicentini@gmail.com>"]
-version = "0.1.7"
+version = "0.1.8"
 
 [deps]
 CRC32c = "8bf52ea8-c179-5cab-976a-9e18b702a9bc"

docs/src/explicit_interface.md

@@ -38,3 +38,19 @@ log_audios
 ```@docs
 log_embeddings
 ```
+
+## Custom Scalars plugin
+See [TensorBoard Custom Scalar page](https://github.com/tensorflow/tensorboard/tree/master/tensorboard/plugins/custom_scalar).
+
+For example, to combine in the same plot panel the two curves logged under tags `"Curve/1"` and `"Curve/2"` you can run once the command:
+```julia
+layout = Dict("Cat" => Dict("Curve" => ("Multiline", ["Curve/1", "Curve/2"])))
+
+log_custom_scalar(lg, layout)
+
+```
+
+See also the documentation below
+```@docs
+log_custom_scalars
+```

proto/layout.proto

@@ -0,0 +1,80 @@
+syntax = "proto3";
+
+package tensorboard;
+
+/**
+ * Encapsulates information on a single chart. Many charts appear in a category.
+ */
+message Chart {
+  // The title shown atop this chart. Optional. Defaults to 'untitled'.
+  string title = 1;
+
+  // The content of the chart. This depends on the type of the chart.
+  oneof content {
+    MultilineChartContent multiline = 2;
+    MarginChartContent margin = 3;
+  }
+}
+
+/**
+ * Encapsulates information on a single line chart. This line chart may have
+ * lines associated with several tags.
+ */
+message MultilineChartContent {
+  // A list of regular expressions for tags that should appear in this chart.
+  // Tags are matched from beginning to end. Each regex captures a set of tags.
+  repeated string tag = 1;
+}
+
+/**
+ * Encapsulates information on a single margin chart. A margin chart uses fill
+ * area to visualize lower and upper bounds that surround a value.
+ */
+message MarginChartContent {
+  /**
+   * Encapsulates a tag of data for the chart.
+   */
+  message Series {
+    // The exact tag string associated with the scalar summaries making up the
+    // main value between the bounds.
+    string value = 1;
+
+    // The exact tag string associated with the scalar summaries making up the
+    // lower bound.
+    string lower = 2;
+
+    // The exact tag string associated with the scalar summaries making up the
+    // upper bound.
+    string upper = 3;
+  }
+
+  // A list of data series to include within this margin chart.
+  repeated Series series = 1;
+}
+
+/**
+ * A category contains a group of charts. Each category maps to a collapsible
+ * within the dashboard.
+ */
+message Category {
+  // This string appears atop each grouping of charts within the dashboard.
+  string title = 1;
+
+  // Encapsulates data on charts to be shown in the category.
+  repeated Chart chart = 2;
+
+  // Whether this category should be initially closed. False by default.
+  bool closed = 3;
+}
+
+/**
+ * A layout encapsulates how charts are laid out within the custom scalars
+ * dashboard.
+ */
+message Layout {
+  // Version `0` is the only supported version.
+  int32 version = 1;
+
+  // The categories here are rendered from top to bottom.
+  repeated Category category = 2;
+}

src/Loggers/LogCustomScalar.jl

@@ -0,0 +1,59 @@
+# possible chart types
+@enum tb_chart_type tb_multiline=1 tb_margin=2
+
+"""
+log_custom_scalar(logger, layout::AbstractDict; step = step(logger))
+
+Groups multiple scalars in the same plot to be visualized by the CUSTOM_SCALARS
+plugin. Note that this function sets the metadata: the actual values must be
+logged separately with `log_value` and referenced with the correct tag.
+
+The `layout` argument is structured as follows:
+
+layout = Dict(category => Dict(name => (chart_type, [tag1, tag2, ...])))
+
+where `category` is the main tag for the plot, `name` is the plot's name,
+`chart_type` is one between `tb_multiline` and `tb_margin` and the array of tags
+contains the actual references to the logged scalars.
+"""
+function log_custom_scalar(logger::TBLogger, layout::AbstractDict; step = nothing)
+    summ = SummaryCollection(custom_scalar_summary(layout))
+    write_event(logger.file, make_event(logger, summ, step = step))
+end
+
+function chart(name::String, metadata::Tuple{tb_chart_type, AbstractArray})
+    chart_type, tags = metadata
+
+    if chart_type == tb_multiline
+        content = MultilineChartContent(tag = tags)
+        return Chart(title = name, multiline = content)
+    elseif chart_type == tb_margin
+        @assert length(tags) == 3
+        args = Dict(k => v for (k, v) in zip([:value, :lower, :upper], tags))
+        content = MarginChartContent(
+                    series = [MarginChartContent_Series(; args...)])
+        return Chart(title = name, margin = content)
+    else
+        @error "The chart type must be `tb_multiline` or `tb_margin`"
+    end
+end
+
+function charts(dict::AbstractDict)
+    [chart(name, meta) for (name, meta) in zip(keys(dict), values(dict))]
+end
+
+function custom_scalar_summary(layout)
+    cat_spec = zip(keys(layout), values(layout))
+    categories = [Category(title = k, chart = charts(c)) for (k, c) in cat_spec]
+
+    layout = Layout(category = categories)
+    plugin_data = SummaryMetadata_PluginData(plugin_name = "custom_scalars")
+    smd = SummaryMetadata(plugin_data = plugin_data)
+    cs_tensor = TensorProto(dtype = _DataType.DT_STRING,
+                            string_val = [serialize_proto(layout)],
+                            tensor_shape = TensorShapeProto())
+
+    Summary_Value(tag = "custom_scalars__config__",
+                  tensor = cs_tensor,
+                  metadata = smd)
+end

src/TensorBoardLogger.jl

@@ -12,12 +12,15 @@ using  Base.CoreLogging: CoreLogging, AbstractLogger, LogLevel, Info,
 
 export TBLogger, reset!, set_step!, increment_step!
 export log_histogram, log_value, log_vector, log_text, log_image, log_images,
-       log_audio, log_audios, log_graph, log_embeddings
+       log_audio, log_audios, log_graph, log_embeddings, log_custom_scalar
 export map_summaries
 
 export ImageFormat, L, CL, LC, LN, NL, NCL, NLC, CLN, LCN, HW, WH, HWC, WHC,
        CHW, CWH,HWN, WHN, NHW, NWH, HWCN, WHCN, CHWN, CWHN, NHWC, NWHC, NCHW, NCWH
 
+# Custom Scalar Plugin
+export tb_multiline, tb_margin
+
 # Wrapper types
 export TBText, TBVector, TBHistogram, TBImage, TBImages, TBAudio, TBAudios
 
@@ -36,6 +39,8 @@ include("protojl/types_pb.jl")
 include("protojl/summary_pb.jl")
 include("protojl/event_pb.jl")
 include("protojl/plugin_text_pb.jl")
+include("protojl/tensorboard.jl")
+include("protojl/layout_pb.jl")
 
 include("PNG.jl")
 using .PNGImage
@@ -54,6 +59,9 @@ include("Loggers/LogHistograms.jl")
 include("Loggers/LogAudio.jl")
 include("Loggers/LogEmbeddings.jl")
 
+# Custom Scalar Plugin
+include("Loggers/LogCustomScalar.jl")
+
 include("logger_dispatch.jl")
 include("logger_dispatch_overrides.jl")
 

src/protojl/layout_pb.jl

@@ -0,0 +1,45 @@
+# syntax: proto3
+using ProtoBuf
+import ProtoBuf.meta
+
+mutable struct MultilineChartContent <: ProtoType
+    tag::Base.Vector{AbstractString}
+    MultilineChartContent(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct MultilineChartContent
+
+mutable struct MarginChartContent_Series <: ProtoType
+    value::AbstractString
+    lower::AbstractString
+    upper::AbstractString
+    MarginChartContent_Series(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct MarginChartContent_Series
+
+mutable struct MarginChartContent <: ProtoType
+    series::Base.Vector{MarginChartContent_Series}
+    MarginChartContent(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct MarginChartContent
+
+mutable struct Chart <: ProtoType
+    title::AbstractString
+    multiline::MultilineChartContent
+    margin::MarginChartContent
+    Chart(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct Chart
+const __oneofs_Chart = Int[0,1,1]
+const __oneof_names_Chart = [Symbol("content")]
+meta(t::Type{Chart}) = meta(t, ProtoBuf.DEF_REQ, ProtoBuf.DEF_FNUM, ProtoBuf.DEF_VAL, true, ProtoBuf.DEF_PACK, ProtoBuf.DEF_WTYPES, __oneofs_Chart, __oneof_names_Chart, ProtoBuf.DEF_FIELD_TYPES)
+
+mutable struct Category <: ProtoType
+    title::AbstractString
+    chart::Base.Vector{Chart}
+    closed::Bool
+    Category(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct Category
+
+mutable struct Layout <: ProtoType
+    version::Int32
+    category::Base.Vector{Category}
+    Layout(; kwargs...) = (o=new(); fillunset(o); isempty(kwargs) || ProtoBuf._protobuild(o, kwargs); o)
+end #mutable struct Layout
+
+export Chart, MultilineChartContent, MarginChartContent_Series, MarginChartContent, Category, Layout

src/protojl/tensorboard.jl

@@ -0,0 +1,4 @@
+module tensorboard
+  const _ProtoBuf_Top_ = @static isdefined(parentmodule(@__MODULE__), :_ProtoBuf_Top_) ? (parentmodule(@__MODULE__))._ProtoBuf_Top_ : parentmodule(@__MODULE__)
+  include("layout_pb.jl")
+end