Merge pull request #77 from gustaphe/aspectratio

Unitful aspect ratios

Author: gustaphe

.gitignore

@@ -11,3 +11,5 @@ docs/Manifest.toml
 docs/build/
 docs/src/examples/
 docs/src/notebooks/
+
+test/test.png

Project.toml

@@ -1,7 +1,7 @@
 name = "UnitfulRecipes"
 uuid = "42071c24-d89e-48dd-8a24-8a12d9b8861f"
 authors = ["Benoit Pasquier", "Jan Weidner"]
-version = "1.5.3"
+version = "1.6.0"
 
 [deps]
 RecipesBase = "3cdcf5f2-1ef4-517c-9805-6587b60abb01"

docs/lit/examples/1_Examples.jl

@@ -188,3 +188,24 @@ plot!(model, u"s"; label="True function")
 
 plot(u"m", u"s")
 plot!([2u"ft"], [1u"minute"], st=:scatter)
+
+# ## Aspect ratio
+#
+# Unlike in a normal unitless plot, the aspect ratio of a unitful plot is in turn a unitful
+# number $r$, such that $r\cdot \hat{y}$ would take as much space on the $x$ axis as
+# $\hat{y}$ does on the $y$ axis.
+#
+# By default, `aspect_ratio` is set to `:auto`, which lets you ignore this.
+#
+# Another special value is `:equal`, which (possibly unintuitively) corresponds to $r=1$.
+# Consider a rectangle drawn in a plot with $\mathrm{m}$ on the $x$ axis and
+# $\mathrm{km}$ on the $y$ axis. If the rectangle is
+# $100\;\mathrm{m} \times 0.1\;\mathrm{km}$, `aspect_ratio=:equal` will make it appear
+# square.
+
+plot(
+     plot(randn(10)u"m", randn(10)u"dm"; aspect_ratio=:equal, title=":equal"),
+     plot(randn(10)u"m", randn(10)u"s"; aspect_ratio=2u"m/s",
+          title="\$2\\;\\mathrm{m}/\\mathrm{s}\$"),
+     plot(randn(10)u"m", randn(10); aspect_ratio=5u"m", title="\$5\\;\\mathrm{m}\$")
+    )

src/UnitfulRecipes.jl

@@ -50,6 +50,7 @@ function fixaxis!(attr, x, axisletter)
         ustripattribute!(attr, :ribbon, u)
         ustripattribute!(attr, :fillrange, u)
     end
+    fixaspectratio!(attr, u, axisletter)
     fixmarkercolor!(attr)
     fixmarkersize!(attr)
     fixlinecolor!(attr)
@@ -124,6 +125,36 @@ end
 #===============
 Attribute fixing
 ===============#
+# Aspect ratio
+function fixaspectratio!(attr, u, axisletter)
+    aspect_ratio = get!(attr, :aspect_ratio, :auto)
+    if aspect_ratio in (:auto, :none)
+        # Keep the default behavior (let Plots figure it out)
+        return
+    end
+    if aspect_ratio === :equal
+        aspect_ratio = 1
+    end
+    #=======================================================================================
+    Implementation example:
+
+    Consider an x axis in `u"m"` and a y axis in `u"s"`, and an `aspect_ratio` in `u"m/s"`.
+    On the first pass, `axisletter` is `:x`, so `aspect_ratio` is converted to `u"m/s"/u"m"
+    = u"s^-1"`. On the second pass, `axisletter` is `:y`, so `aspect_ratio` becomes
+    `u"s^-1"*u"s" = 1`. If at this point `aspect_ratio` is *not* unitless, an error has been
+    made, and the default aspect ratio fixing of Plots throws a `DimensionError` as it tries
+    to compare `0 < 1u"m"`.
+    =======================================================================================#
+    if axisletter === :y
+        attr[:aspect_ratio] = aspect_ratio*u
+        return
+    end
+    if axisletter === :x
+        attr[:aspect_ratio] = aspect_ratio/u
+        return
+    end
+    return
+end
 
 # Markers / lines
 function fixmarkercolor!(attr)

test/runtests.jl

@@ -2,6 +2,8 @@ using Test, Unitful, Plots
 using Unitful: m, s, cm, DimensionError
 using UnitfulRecipes
 
+testfile = "test.png"
+
 # Some helper functions to access the subplot labels and the series inside each test plot
 xguide(plt, idx=length(plt.subplots)) = plt.subplots[idx].attr[:xaxis].plotattributes[:guide]
 yguide(plt, idx=length(plt.subplots)) = plt.subplots[idx].attr[:yaxis].plotattributes[:guide]
@@ -293,6 +295,35 @@ end
     @test yguide(plt) == "s"
 end
 
+@testset "Aspect ratio" begin
+    plt = plot(
+               (1:10)u"m",
+               (1:10)u"dm";
+               aspect_ratio=:equal,
+              )
+    savefig(plt, testfile) # Force a render, to make it evaluate aspect ratio
+    @test abs(-(ylims(plt)...)) > 50
+    plt = plot(
+               (1:10)u"m",
+               (1:10)u"dm";
+               aspect_ratio=2,
+              )
+    savefig(plt, testfile)
+    @test 25 < abs(-(ylims(plt)...)) < 50
+    plt = plot(
+               (1:10)u"m",
+               (1:10)u"s";
+               aspect_ratio=1u"m/s",
+              )
+    savefig(plt, testfile)
+    @test 7.5 < abs(-(ylims(plt)...)) < 12.5
+    @test_throws DimensionError savefig(plot(
+                                     (1:10)u"m",
+                                     (1:10)u"s";
+                                     aspect_ratio=:equal,
+                                    ), testfile)
+end
+
 # https://github.com/jw3126/UnitfulRecipes.jl/issues/60
 @testset "Start with empty plot" begin
     plt = plot()