Add extension for Plots.jl, and put UnicodePlots.jl on equal footing

Remove the definition for the 3-argument `Base.show()` method when
UnicodePlots.jl is loaded. This treats UnicodePlots more like a plotting
package than a fancy text output.

Author: jmert

Project.toml

@@ -1,7 +1,7 @@
 name = "KernelDensityEstimation"
 uuid = "e46ec5f4-66dc-4371-a668-81bd92d19d7d"
-authors = ["Justin Willmert <[email protected]>"]
 version = "0.8.0"
+authors = ["Justin Willmert <[email protected]>"]
 
 [deps]
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
@@ -12,22 +12,26 @@ PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
 [weakdeps]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 
 [extensions]
 KDEDistributionsExt = ["Distributions"]
 KDEMakieExt = ["Makie"]
+KDERecipesBaseExt = ["RecipesBase"]
 KDEUnicodePlotsExt = ["UnicodePlots"]
 
 [compat]
 Distributions = "0.25.46"
 FFTW = "1.4"
 Makie = "0.15,0.16,0.17,0.18,0.19,0.20,0.21,0.22,0.23,0.24"
 PrecompileTools = "1.1"
+RecipesBase = "1.3"
 UnicodePlots = "3"
 julia = "1.6"
 
 [extras]
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"

docs/Project.toml

@@ -8,6 +8,7 @@ KernelDensity = "5ab0869b-81aa-558d-bb23-cbf5423bbe9b"
 KernelDensityEstimation = "e46ec5f4-66dc-4371-a668-81bd92d19d7d"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 UnicodePlots = "b8865327-cd53-5732-bb35-84acbb429228"
 
@@ -19,6 +20,7 @@ Documenter = "1.3"
 DocumenterInterLinks = "1"
 KernelDensity = "0.6"
 Makie = "0.20, 0.21, 0.22, 0.23"
+Plots = "1"
 julia = "1.6"
 
 [extras]

docs/make.jl

@@ -16,6 +16,7 @@ bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib");
                            style = :numeric)
 links = InterLinks(
     "Julia" => "https://docs.julialang.org/en/v1/",
+    "UnicodePlots" => "https://juliaplots.org/UnicodePlots.jl/stable/",
 )
 
 showcases = map(ff -> joinpath("showcase", ff),

docs/src/extensions.md

@@ -89,21 +89,67 @@ nothing  # hide
 
 ![](ext_makie.svg)
 
+
+## [Plots.jl](@id ext-plots)
+
+Plotting the [`UnivariateKDE`](@ref) object is natively supported within the
+[`Plots.jl`](https://juliahub.com/ui/Packages/General/Plots)
+ecosystem of backends by defining a plot recipe for `RecipesBase.jl`.
+
+The density estimate is interpreted by default as a `:line` series type with
+xlabel `"value"` and ylabel `"density"`.
+
+```@example ext_plots
+using KernelDensityEstimation: kde, LinearBinning
+using Random  # hide
+Random.seed!(100)  # hide
+
+# 500 samples from a Chisq(ν=4) distribution
+rv = dropdims(sum(abs2, randn(4, 500), dims=1), dims=1)
+nothing  # hide
+```
+
+```@example ext_plots
+using Plots
+
+K = kde(rv; lo = 0.0, boundary = :closedleft)
+H = kde(rv; lo = 0.0, boundary = :closedleft,
+            bwratio = 1.0, method = LinearBinning())
+
+plot(
+    plot(H, title = "stairs", seriestype = :stepmid),
+    plot(K, title = "lines", ylabel = nothing),
+    layout = (1, 2), size = (800, 300),
+    leftmargin = (2.5, :mm), bottommargin = (3.0, :mm),
+    link = :all, legend = false
+)
+
+savefig("ext_plots.svg")  # hide
+nothing  # hide
+```
+
+![](ext_plots.svg)
+
+
 ## [UnicodePlots.jl](@id ext-unicodeplots)
 
 For quick, approximate visualization of a density within the terminal, an extension is provided for the
 [`UnicodePlots.jl`](https://juliahub.com/ui/Packages/General/UnicodePlots)
-package.
-The three-argument `Base.show` method is defined to show the Unicode plot by default, so the distribution will be
-previewed at the REPL automatically.
+package and extends the `lineplot` (and `lineplot!`) methods.
 
 ```@example ext_unicodeplots
 using KernelDensityEstimation
-using UnicodePlots
 using Random  # hide
 Random.seed!(100)  # hide
 
 # 500 samples from a Chisq(ν=4) distribution
 rv = dropdims(sum(abs2, randn(4, 500), dims=1), dims=1)
+nothing  # hide
+```
+
+```@example ext_unicodeplots
+using UnicodePlots
+
 K = kde(rv; lo = 0.0, boundary = :closedleft)
+lineplot(K)
 ```

docs/src/releasenotes.md

@@ -13,6 +13,18 @@ Depth = 2:2
 
 ## v0.8.0 — Unreleased
 
+- The [package extension](extensions.md#ext-unicodeplots) for
+  [`UnicodePlots.jl`](https://juliahub.com/ui/Packages/General/UnicodePlots)
+  no longer defines the 3-argument [`Base.show`](@extref Base.show-Tuple{IO, Any, Any}) method for the
+  [`UnivariateKDE`](@ref) type in favor of requiring the user to explicitly plot it in the terminal
+  with [`UnicodePlots.lineplot`](@extref)
+
+- The [package extension](extensions.md#ext-plots) for
+  [`RecipesBase.jl`](https://juliahub.com/ui/Packages/General/RecipesBase)
+  has been added to aid in plotting within the
+  [`Plots.jl`](https://juliahub.com/ui/Packages/General/Plots)
+  ecosystem.
+
 - Various changes to the interfaces and type definitions have been made to allow for future support of bivariate (and
   possibly multivariate) density estimates.
 

ext/KDERecipesBaseExt.jl

@@ -0,0 +1,13 @@
+module KDERecipesBaseExt
+
+import KernelDensityEstimation: AbstractBinningKDE, UnivariateKDE
+import RecipesBase: @recipe
+
+@recipe function f(K::UnivariateKDE)
+    seriestype --> :line
+    xlabel --> "value"
+    ylabel --> "density"
+    return K.x, K.f
+end
+
+end

ext/KDEUnicodePlotsExt.jl

@@ -1,26 +1,14 @@
 module KDEUnicodePlotsExt
 
-import KernelDensityEstimation
-const KDE = KernelDensityEstimation
+import KernelDensityEstimation: UnivariateKDE
+import UnicodePlots: Plot, lineplot, lineplot!
 
-using UnicodePlots: lineplot
-
-function Base.show(io::IO, mime::MIME"text/plain", K::KDE.UnivariateKDE{T}) where {T}
-    print(io, KDE.UnivariateKDE, '{', T, '}', '(')
-    io′ = IOContext(io, :compact => true)
-    println(io′, first(K.x), ':', step(K.x), ':', last(K.x), ", [ … ])")
-
-    sigdigits = 4
-    ylim = (0.0, round(maximum(K.f); sigdigits))
-    ytickwd = textwidth(string(ylim[2]))
-
-    ht, wd = displaysize(io)
-    ht -= 3#=borders=# + 1#=tick label=# + 1#=first line print=# + 2#=repl context=#
-    wd -= 4#=borders=# + ytickwd
+function lineplot(K::UnivariateKDE; kws...)
+    lineplot(K.x, K.f; kws...)
+end
 
-    pl = lineplot(K...; ylim, margin = 0, height = ht, width = wd)
-    show(io, mime, pl)
-    return nothing
+function lineplot!(plot::Plot, K::UnivariateKDE; kws...)
+    lineplot!(plot, K.x, K.f; kws...)
 end
 
 end

test/Project.toml

@@ -5,6 +5,7 @@ FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
 KernelDensityEstimation = "e46ec5f4-66dc-4371-a668-81bd92d19d7d"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

test/extensions.jl

@@ -76,20 +76,56 @@ end
     end
 end
 
-@moduletestset "UnicodePlots" begin
-    import UnicodePlots
 
-    io = IOBuffer()
-    ht, wd = 50, 120
-    ioc = IOContext(io, :displaysize => (ht, wd))
+@moduletestset "Plots" begin
+    using Plots
+
+    rv = rand(1000)
+    K = kde(rv, lo = 0.0, hi = 1.0, boundary = :closed)
+
+    # simply test that invocation is not an error
+    @test plot(K) isa Plots.Plot
+    @test plot(K, linetype = :steppre) isa Plots.Plot
+
+    # default labels are set
+    p = plot(K)
+    @test p[1][:xaxis][:guide] == "value"
+    @test p[1][:yaxis][:guide] == "density"
+end
 
-    K = kde(collect(0:0.01:1), bandwidth = 0.5, boundary = :closed)
-    show(ioc, MIME"text/plain"(), K)
-    str = String(take!(io))
 
-    let S = split(str, '\n')
-        @test all(length(s) <= wd for s in S)
-        @test length(S) < ht
+@moduletestset "UnicodePlots" begin
+    using UnicodePlots
+
+    K = kde(sqrt.(0:0.01:1), bandwidth = 0.5, boundary = :closed)
+
+    function termprint(x)
+        context = (:displaysize => (50, 120), :color => true)
+        return sprint(x; context) do io, obj
+            show(io, MIME"text/plain"(), obj)
+        end
     end
-    @test any(!isascii, str)
+
+    # generate an empty plot (to check that plotting is different from)
+    empty = termprint(Plot(Float64[], Float64[]; xlim = (0, 1), ylim = (0, 3)))
+
+    # plot from scratch
+    p1 = lineplot(K, color = :green)
+    str1 = termprint(p1)
+    @test str1 != empty
+    @test any(!isascii, str1)
+
+    # plot into a canvas
+    p2 = Plot(Float64[], Float64[]; xlim = (0, 1), ylim = (0, 3))
+    lineplot!(p2, K, color = :green)
+    str2 = termprint(p2)
+    @test str1 == str2
+    # change color and overplot, resulting in different (color!) plot
+    lineplot!(p2, K, color = :blue)
+    str3 = termprint(p2)
+    @test str3 != str2
+    # but contents are the same if the color information is stripped away
+    #  pattern based on https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
+    stripcolor(s) = replace(s, r"\e\[(\d+;)*\d*m" => "")
+    @test stripcolor(str3) == stripcolor(str2)
 end