Julia Community 🟣: Mathieu Aucejo

Waterfall plot a la Matlab using PyPlot, PlotlyJS and Makie

Mathieu Aucejo — Wed, 01 Mar 2023 19:47:58 +0000

When I switched from Matlab to Julia, one of the Matlab features I really missed was the waterfall plot and I am not the only one (see here and there). Actually, such a plot is the ideal way to display space-time or space-frequency series, for example.

In this tutorial, I will try to show you how to reproduce the following Matlab figure.

Waterfall plot to reproduce - Matlab

Matlab Code

x = linspace(0, 2*pi, 100);
y = linspace(0, 1, 5);
z = zeros(5, 100);

for i = 1:5
    z(i, :) = sin(i*x/2);
end

waterfall(x, y, z)
xlabel('Time (s)')
ylabel('Location (m)')
zlabel('Amplitude')

My goal in this tutorial is to try to reproduce as closely as possible the previous figure using Makie.jl, PyPlot.jl and PlotlyJS.jl.

Let's go!

0. Data generation

x = range(0., 2π, 100)
y = range(0., 1., 5)

nx = length(x)
ny = length(y)
z = zeros(ny, nx)

for i in eachindex(y)
    z[i, :] = sin.(i*x/2.)
end

1. PyPlot.jl

PyPlot.jl provides a Julia interface to the Matplotlib plotting library from Python thanks to PyCall.jl. The syntax is similar to matplotlib.pyplot making it easier to convert python code into julia code. You can find a lot of PyPlot examples here.

For implementing the waterfall plot with PyPlot.jl, I took my inspiration from the blog post of Siladittya Manna. This blog explains how to obtain a waterfall plot using Matplotlib. I have adapted the pieces of codes given in this blog to fit my needs.

In the end, the function waterfall_pyplot is implemented as follows:

function waterfall_pyplot(x, y, z; zmin = minimum(z), lw = 1., colorline = :blue, colorband = :blue, alpha = 0.1, xlab = "x", ylab = "y", zlab = "z")
    # Initialisation
    nx = length(x)

    fig = figure(figsize = (8, 6), layout = "constrained")
    using3D()
    ax = fig[:add_subplot](111, projection = "3d")
    for (j, yv) in enumerate(y)
        zj = z[j, :]
        yj = yv*ones(nx)

        # Line
        ax.plot(x, yj, zs = zj, zdir = "z", lw = lw, color = colorline)

        # Surface under the line
        col = ax.fill_between(x, zmin, zj, fc = colorband, alpha = alpha)
        ax.add_collection3d(col, zs = yj, zdir = "y")

        # Edges
        ax.plot(x[1]*ones(2), yv*ones(2), zs = [zmin, zj[1]], zdir = "z", lw = lw, color = colorline)
        ax.plot(x[end]*ones(2), yv*ones(2), zs = [zmin, zj[end]], zdir = "z", lw = lw, color = colorline)
    end

    # Set camera view
    ax.view_init(elev = 22.5, azim = 229.5)

    # Set axes titles
    ax.set_xlabel(xlab)
    ax.set_ylabel(ylab)
    ax.set_zlabel(zlab)

    # Set the pane color white
    ax.w_xaxis.set_pane_color((1.0, 1.0, 1.0, 0.0))
    ax.w_yaxis.set_pane_color((1.0, 1.0, 1.0, 0.0))
    ax.w_zaxis.set_pane_color((1.0, 1.0, 1.0, 0.0))

    fig
end

To compute the figure and display it, you just have to type:

waterfall_py(x, y, z, xlab = "Time (s)", ylab = "Location (m)", zlab = "Amplitude")

plt.show()

TA-DA!

Waterfall plot - PyPlot.jl

Some comments have to be made here:

Drawing multicolor 3d lines is pretty tricky with matplotlib since we have to define a LineCollection (see Matplotlib documentation or Stack Overflow).
For obtaining a good looking plot, it is recommended to add some transparency to the surfaces. Indeed, when there is no transparency, waterfall_py(x, y, z, colorband = :white, alpha = 1.) gives for instance (Pretty ugly, no?)

Ugly waterfall plot - PyPlot.jl

2. PlotlyJS.jl

PlotlyJS.jl provides a Julia interface to the plotly.js plotting library. A good starting point is the documentation that gives many examples.

However, to obtain a waterfall plot a la matlab, I had to ask help to the julia community. A special thank to @empet on the julia discourse. After a long battle, the waterfall plot can be implemented as follows:

# using PlotlyJS

function waterfall_plotly(x, y, z; zmin = minimum(z), lw = 1., colorline = :blue, colorband = :white, alpha = 1., xlab = "x", ylab = "y", zlab = "z")
    # Initialisation
    nx = length(x)
    nv = Int(round(nx./2.))

    vl = range(0., 1., nv)
    v = repeat(vl, 1, nx)
    X = repeat(x', nv, 1)

    traces = GenericTrace[]
    for (j, yv) in enumerate(y)
        zj = z[j, :]
        Y = yv*ones(nx)

        # Line
        trace = scatter3d(x = x,
                       y = Y,
                       z = zj,
                       mode = "lines",
                       line = attr(color = colorline, width = lw),
                       showlegend = false)

        # Surface
        Z = zmin .+ (repeat(zj', nv, 1) .- zmin).*v
        surf = surface(x = X,
                       y = Y,
                       z = Z,
                       colorscale = [[0, colorband],  [1, colorband]],
                       opacity = alpha,
                       showscale = false)
        # Edges
        edge_start = scatter3d(x = x[1]*ones(2),
                                   y = yv*ones(2),
                                   z = [zmin, zj[1]],
                                   mode = "lines",
                                   line = attr(color = colorline, width = lw), showlegend = false)
        edge_end = scatter3d(x = x[end]*ones(2),
                                 y = yv*ones(2),
                                 z = [zmin, zj[end]],
                                 mode = "lines",
                                 line = attr(color = colorline, width = lw), showlegend = false)

        append!(traces, [edge_start, trace, edge_end, surf])
    end

    # Define camera angles
    xcam, ycam, zcam = camera_angle()

    # Define the layout
    layout = Layout(scene = attr(
        xaxis = attr(autorange = "reversed", automargin = true),
        yaxis = attr(autorange = "reversed", automargin = true),
        camera = attr(eye = attr(x = xcam, y = ycam, z = zcam)),
        aspectratio = attr(x = 1., y = 1, z = 2/3),
        xaxis_title = xlab,
        yaxis_title = ylab,
        zaxis_title = zlab))

    fig = plot(traces, layout)
    relayout!(fig, template = :plotly_white)
    fig
end

function camera_angle(azimuth = 50, elevation = 22.5; R = 2.)
    ϕ = deg2rad(azimuth)
    θ = deg2rad(elevation)
    x = R*cos(θ)*cos(ϕ)
    y = R*cos(θ)*sin(ϕ)
    z = R*sin(θ)

    return x, y, z
end

To compute the figure and display it, you just have to type:

fig = waterfall_plotly(x, y, z, xlab = "Time (s)", ylab = "Location (m)", zlab = "Amplitude")

wait(display(fig))

Et voilà!

Waterfall plot - Plotly

The salient points for obtaining this plot are:

All the traces have to be collected in a vector, hence the use of traces = GenericTrace[].
For the surface, see the explanation given by @empet here. Basically, we have to define a 3d grid of points to fill the surface going from zmin to z(x, y) for a given (x, y) set of coordinates.
The location of the camera is defined by its Cartesian coordinates (x, y, z) which seems to me unnatural, given that elevation and azimuth are generally preferred in most of plotting packages. That is why, I have defined the function camera_angles taking for arguments the azimuth, the elevation and the radius of the sphere on which the camera is set.
There is currently no solution to have multicolored lines. At the moment only the scatter mode allows this.

Of course, we can play with the color and the transparency of the surface to obtain a plot similar to that generated with PyPlot.jl.

Waterfall plot with blue and transparent surfaces - Plotly

3. Makie

Makie is a data visualization ecosystem for the Julia programming language, with high performance and extensibility. It a pure Julia plotting library (89.4 % of the code base is written in Julia).

To achieve my goal, I had a look on the Makie documentation, the Beautiful Makie website and in the sixth chapter of Julia Data Science written by Jose Storopoli, Rik Huijzer and Lazaro Alonso. To be fair, I found the master piece for implementing the waterfall plot in section 6.9.5 of the latter book.

By putting everything together, I finally obtained the following function:

# using GLMakie or CairoMakie

function waterfall_makie(x, y, z; zmin = minimum(z), lw = 1., colmap = :linear_bgy_10_95_c74_n256, colorband = (:white, 1.), xlab = "x", ylab = "y", zlab = "z")
    # Initialisation
    fig = Figure()
    ax = Axis3(fig[1,1], xlabel = xlab, ylabel = ylab, zlabel = zlab)
    for (j, yv) in enumerate(y)
        zj = z[j, :]
        lower = Point3f.(x, yv, zmin)
        upper = Point3f.(x, yv, zj)
        edge_start = [Point3f(x[1], yv, zmin), Point3f(x[1], yv, zj[1])]
        edge_end = [Point3f(x[end], yv, zmin), Point3f(x[end], yv, zj[end])]

        # Surface
        band!(ax, lower, upper, color = colorband)

        # Line
        lines!(ax, upper, color = zj, colormap = colmap, linewidth = lw)

        # Edges
        lines!(ax, edge_start, color = zj[1]*ones(2), colormap = colmap, linewidth = lw)
        lines!(ax, edge_end, color = zj[end]*ones(2), colormap = colmap, linewidth = lw)
    end

    # Set axes limits
    xlims!(ax, minimum(x), maximum(x))
    ylims!(ax, minimum(y), maximum(y))
    zlims!(ax, zmin, maximum(z))

    fig
end

To compute the figure and display it, you just have to type:

fig = waterfall_plotly(x, y, z, xlab = "Time (s)", ylab = "Location (m)", zlab = "Amplitude")

wait(display(fig))

Bingo!

Waterfall plot - Makie.jl

For the sake of comparison, Matlab vs Makie waterfall plots are presented side by side below.

Matlab vs Makie

Some comments:

It is possible to easily affect a colormap to a line and adjust the color w.r.t. the the corresponding z-value.
The surface below the line is easily drawn using the function band!.
With CairoMakie.jl, each group (lines + band) has to be drawn in a decreasing order to obtain the desired figure. This done by replacing enumerate(y) by enumerate(reverse(y)) and replacing j by length(y) - j + 1. If we draw each group in an increasing order as for PyPlot.jl and PlotlyJS.jl, the resulting figure is quite ugly. This problem doesn't appear with GLMakie.jl.

Influence of the plotting order with CairoMakie.jl

4. Final Thoughts

I hope this tutorial will help you to consider Julia as a viable alternative. What I tried to prove in this tutorial is that PyPlot.jl, PlotlyJS.jl or Makie.jl all do a good job. It all depends on your background and needs. For building interactive web applications with Dash.jl or Genie.jl you need to use PlotlyJS.jl. It is also a very good package for exploratory analysis. For Python users, PyPlot.jl (or PythonPlot.jl) is certainly the package to use. Of course, Makie.jl can cover all your needs if you give it a try.

The winner here is clearly Makie.jl, since it allows you to get the look and feel of Matlab's waterfall plot (which was the goal of this tutorial). But more than that, I find Makie.jl easier to use and very mature. This may be due to the fact that it is a plotting package designed exclusively for Julia.

Make beautiful web apps in Julia with... Genie Builder

Mathieu Aucejo — Thu, 19 Jan 2023 16:49:28 +0000

In a previous post, I tried to explain how to use Dash.jl to develop a web app to illustrate the vibration behavior of undamped/damped mass-spring oscillators.

Today, my goal is to develop the same application, but with Genie Builder, a VSCode plugin that aims to simplify the creation of the user interface by dragging and dropping interface elements. I have to admit that this is a very exciting proposition, especially for people not well versed in HTML and CSS.

First steps
Goal of the app
Let's implement the app!
Final thoughts

1. First steps

As for any framework, one of the best practice is to read the documentation. The natural entry point is the documentation section of the web site dedicated to the Genie Framework.

Genie Framework Documentation section

As you can see on the previous picture, the Genie framework is built around five modules (Genie, Stipple, SearchLight, StippleUI and StipplePlotly). At the time of writing this post (January 2023), you have to keep in mind that the documentation is still under development, meaning that all the information needed for building the present app are lacking. However, this is compensated by the active and and friendly Genie community and the existence of a discord channel (special thanks to @abhimanyuaryan for guiding my first steps with the Genie Builder). Finally, the best way I found to familiarize with the Genie Builder are the tutorial written by @pgimenez that you can find here and there.

2. Goal of the app

The app we want to develop is a 1:1 translation of the app I have previously implemented using Dash.jl and presented in the figure below.

Target application developed using Dash.jl

As shown in the previous picture is composed of:

A header
A plotting zone
A zone containing four sliders whose titles display the current value of each slider

In the rest of this tutorial, I will try to show how easy it is to create an application using Genie Builder.

3. Let's implement the app!

Before entering in the core of this tutorial, it is important to briefly explain how to create an app with Genie Builder. I suppose here that you have already install the plugin in VSCode. That being said, we can divide the process into 4 steps:

3.1. Start the server

You have to click on Start Server in the Genie Builder Server panel. This step is mandatory to open the no-code interface for building the UI.

Click on Start Server

On my machine (Dell Latitude 7410 - Intel Core i7-10610U @1.8 GHz (8 CPUs) - 32 Gb RAM), the server starts in 1min 45s on average.
Disclaimer: The elapsed time is the average of five measurements carried out by the chronometer of my cell phone!

3.2. Create a new app

To this end, you just have to click on + in the Genie Builder Apps panel

Click on + to create a new app

By default, this creates a basic app structure. One has to note that the app is actually a Julia project, which is saved in the /.julia/geniebuilder/apps folder. I have to admit that I would prefer to save the app in the folder of my choice. I hope it will be possible in a near future (but it is not very important. It just more convenient IMHO). At the very beginning, the apps folder contains four files:

app.jl containing the analysis code and the app's logic.
app.jl.html containing the HTML components defining the UI
Project.toml and Manifest.toml

On my machine, starting the app takes 1min on average. This timing include the loading of the app (detection of app.jl.html, bindings, ...) and the no-code interface (and many other things).

The code of the generic app is as follows:

for app.jl

module App

using GenieFramework
@genietools

@app begin
  @out message = "Hello World!"

  @onchange isready begin
    @show "App is loaded"
  end
end

@page("/", "app.jl.html")

end

for app.jl.html

<h1>{{message}}</h1>
<p>This is the default view for the application.</p>
<p>You can change this view by editing the file <code>app.jl.html</code>.</p>

Some comments can be made here:

A Genie app is defined as a Julia module and not a script. So, it can't be launch directly using julia MyApp.jl. See @pgimenez tutorial for instance.
The macro @genietools can be seen as a shortcut for using Genie, Stipple, StippleUI, StipplePlotly. This macro performs other operations. For more information, see GenieFramework.jl Github repo.
Any text of the app can modified programmatically. To do this, a variable mytext must be defined in the app.jl using @out mytext = "My custom text". Then, to make this text appear when the app is launched in a web browser, a reference to the variable mytext must be done in app.jl.html using {{mytext}}.
The macro @page generates the HTML code corresponding to a single page application. See Stipple.jl Documentation for details.

To start with a fresh app, you can erase the content of app.jl.html, while keeping the structure of the app.jl file, that is:

module App

using GenieFramework
@genietools

# Put/include the analysis code here

@app begin
  # Define the inputs and the outputs here

  @onchange isready begin
    # Define the interactivity here
  end
end

@page("/", "app.jl.html")

end

3.3. Create the analysis code

The analysis code is exactly the same as that explained in my post on Dash.jl. It basically contains two functions:

response that computes the free response of the mass of a mass-spring system for a given frequency $f_0$ , damping ratio $ξ\xi$ and in displacement and velocity initial conditions, $x_0$ and $v_0$ .
damping that defines the mapping between a discrete set of damping factors and the values of the slider will create later. This function allows to keep constant the gap between each value of the slider.

For the sake of completeness, the analysis code is recalled below:

const t = 0.:1e-3:2.

function response(f₀ = 10., ξ = 0.01, x₀ = 1., v₀ = 1.)
    ω₀ = 2π*f₀     
    if 0. ≤ ξ < 1. 
       Ω₀ = ω₀*√(1. - ξ^2)
      x = (x₀*cos.(Ω₀*t) + (v₀ + ξ*ω₀*x₀)*sin.(Ω₀*t)/Ω₀).*exp.(-ξ*ω₀*t)
    elseif ξ == 1.
      x = @. (x₀ + ω₀*x₀*t + v₀*t)*exp(-ω₀*t)
    else
      β = ω₀*√(ξ^2 - 1.)
      x = @. (x₀*cosh(β*t) + (v₀ + ξ*ω₀*x₀*sinh(β*t))/β)*exp(-ξ*ω₀*t)
    end
end

function damping(value)
    if value == 1
        return 0.
    elseif value == 2
        return 0.001
    elseif value == 3
        return 0.01
    elseif value == 4
        return 0.1
    elseif value == 5
        return 1.
    else
        return 1.5
    end
end

3.4. Create the UI using the no-code editor

The no-code editor allows defining the UI by dragging and dropping interface elements. For our app, the UI looks like the following picture.

View of the no-code editor

To create the interface, we have created:

A h1 environment containing the title of the app using Content -> H1. The latter will be programmatically defined through the variable title.
Two columns using the Layout -> Sidebar right element of the no-code editor. In the left column, a line plot has been inserted using the Charts -> Line element of the editor. The right column requires more work, since it contains 4 sliders, each of them having a title. Each slider is created using the following procedure:

a. Use Content -> Title + Content. This creates a h6 environment to define the title of the slider. This title must be defined programmatically if one wants to display the current value of the slider in the corresponding title. Here, the titles are created from the variables freqtitle, xititle, x0title and v0title.

b. Use Forms -> Slider to create a slider. Its complete definition can be made by clicking on the slider and filling its properties. For instance, one has for the slider related to the value of the natural frequency of the mass-spring system:

Definition of the slider properties

Finally, the decoration of the right column can be set by selecting the column, clicking on Open Style Manager (i.e. click on the pencil in the editor) and filling the Decorations section (see Figure below).

Column decoration

Thanks to the no-code editor, one obtains the following app.jl.html file:

<h1 id="iqml">{{title}}</h1>
<div class="row">
    <div class="col">
        <plotly :data="[{
      x: [2, 3, 4, 5],
      y: [16, 5, 11, 9],
      mode: 'lines',
      type: 'scatter'
    }]"></plotly>
    </div>
    <div class="col col-3">
        <div class="row">
            <div class="col col-12">
                <h6>{{freqtitle}}</h6>
                <q-slider :min="1." :max="50." :step="1." :marker-labels="{1.:'1', 10.:'10', 20.:'20', 30.:'30', 40.:'40', 50:'50'}"></q-slider>
            </div>
        </div>
        <div class="row">
            <div class="col col-12">
                <h6>{{xititle}}</h6>
                <q-slider :min="1" :max="6" :step="1" :marker-labels="{1:'0', 2:'0.001', 3:'0.01', 4:'0.1', 5:'1', 6:'1.5'}"></q-slider>
            </div>
        </div>
        <div class="row">
            <div class="col col-12">
                <h6>{{x0title}}</h6>
                <q-slider :min="-1." :max="1." :step="0.1" :marker-labels="{'-1':'-1', '-0.5':'-0.5', '0':'0', '0.5':'0.5', '1':'1'}"></q-slider>
            </div>
        </div>
        <div class="row">
            <div class="col col-12">
                <h6>{{v0title}}</h6>
                <q-slider :min="-100." :max="100." :step="1." :marker-labels="{'-100':'-100', '-50':'-50', '0':'0', '50':'50', '100':'100'}"></q-slider>
            </div>
        </div>
    </div>
</div>

As you can see in the code above:

The plotting interface is Plotly thanks to StipplePlotly.jl. By default, the editor creates a dummy line plot.
Under the hood, Genie Builder uses Quasar components under the hood (q-slider). This is interesting, since you can have a look on the Quasar website to learn how to use a particular components of the no-code editor. This avoid the Genie team duplicating the documentation. Nice idea!

To finish the app, it remains to connect the UI elements to the analysis code.

3.5 Make the app interactive!

To make the app interactive, one has to define its inputs and its outputs. It is easily done thanks to the @in and @out macros. To summarize a little bit, the inputs are the values of the sliders. Here, they are named f0, xi, x0, v0, while the outputs are the title of the app title, the titles of the sliders freqtitle, xititle, x0title, v0title and the plot plotdata and its layout plotdata_layout. The code corresponding to the initialization of this variable is:

  @in f0 = 10.
  @in xi = 3
  @in x0 = 0.5
  @in v0 = 0.

  @out title = "Free response of a mass-spring system"
  @out freqtitle = ""
  @out xititle = ""
  @out x0title = ""
  @out v0title = ""

  @out plotdata_layout = PlotLayout(
    xaxis = [PlotLayoutAxis(title_text = "Time (s)",title_font = Font(20), tickfont = Font(14))],
    yaxis = [PlotLayoutAxis(xy = "y", title_text = "Displacement (m)", ticks = "outside", ticklen = 10, tickcolor = "white", title_font = Font(20), tickfont = Font(14))]
  )
  @out plotdata = PlotData()

As a side note, the documentation of PlotLayoutAxis can found here. At the time of writing this tutorial (January 2023), the function PlotLayout was not documented. However, its basic usage can be found by exploring the example apps provided by the Genie Team.

At the stage, we have to implement the callback that allows to update the plot when the value of one the sliders changes. It is basically done thanks to the macro @onchangeany, that monitor any change in the input variables f0, xi, x0, v0. In the present case, the callback is implemented as follows:

@onchange isready, f0, xi, x0, v0 begin
    freqtitle = "Resonance frequency: $(Int(f0)) Hz"
    xititle = "Damping ratio: $(damping(xi))"
    x0title = "Initial displacement: $(round(x0, digits=1)) m"
    v0title = "Initial velocity: $(Int(v0)) m/s"

    rep = response(f0, damping(xi), x0, v0)
    plotdata = PlotData(
      x = t,
      y = rep,
      mode = "lines"
    )

It should be noted here that the function PlotData is not currently documented. However, it seems to follow a syntax similar to PlotlyJS.jl.

To complete the interactivity part of this tutorial, we have to assign the value of each slider to the corresponding variable. To do this, we have to return to the no-code interface, select each slider element and fill the Data Binding item. For instance, to assign the value of the slider to f0, we have:

Data Binding for f0

For connecting the plot area to plotdata and plotdata_layout, we have to click of the plot element and fill the Data and Layout items as follows:

Connection of the plot are to plotdata and plotdata_layout

These operations are translated into code in the following way:

# For the plot area
<div class="col">
        <plotly :data="plotdata" :layout="plotdata_layout"></plotly>
</div>

# For sliders
<q-slider v-model="f0" :min="1." :max="50." :step="1." :marker-labels="{1.:'1', 10.:'10', 20.:'20', 30.:'30', 40.:'40', 50:'50'}"></q-slider>

3.6. Let's finish the app

To finish our app, it remains to define the title appearing in the tab of the web browser. How to do this with Genie builder is no documented. However, the answer can be found on the discord channel of the Genie Framework. This done by defining our title as a constant string and by adding it as a parameter of the macro @page that generates the HTML code of the app. In more explicit terms, this code in the following way:

const apptitle = "Free response of a mass-spring system"
@page("/", "app.jl.html", Stipple.ReactiveTools.DEFAULT_LAYOUT(title = apptitle))

As indicated by @pgimenez in his post, the standard way to run the app outside of Genie Builder consists in including Server.isrunning() || Server.up(8050) (where 8050 is the port number) at the end of app.jl. Then, to launch the app, one just has to open the REPL with julia --project in the app's folder and type include("app.jl").

4. Final thoughts

Genie Builder is a fantastic tool to create an application quickly and easily. From my limited experience with Dash and Genie, both frameworks seem to be on par in terms of functionality. So the choice of framework is mainly a matter of taste. The no-code interface is a really cool feature, especially for people who are not well versed in html or ill at ease when building a UI programmatically. I think the no-code interface is a must-have feature that is not currently available for Dash.jl.

That being said, an another point of comparison is the starting time of the applications. For the present, the starting times obtains from a fresh julia session are:

2min 20s for the Genie app
50s for the Dash app Except this noticeable difference, the user experience is similar.

In conclusion, there is no good choice. Genie and Dash are two really good frameworks. They have both their own components library (included in StippleUI for Genie) or can use external library such as Quasar for Genie and Bootstrap for Dash.jl through DashBootstrapComponents.jl. For plotting, both framework use Plotly as a backend. I strongly encourage you to use both!

Make beautiful web apps with... Dash.jl

Mathieu Aucejo — Fri, 30 Dec 2022 14:54:57 +0000

Until recently, I mainly used Matlab and Python for my research and teaching activities. In the last context, I developed some apps to illustrate some concepts of mechanical vibrations such as the free vibration motion of undamped/damped spring-mass oscillators. To this end, my worflow was as follows:

Develop the apps using Ploty Dash in Python
Embed the apps in a reveal.js presentation using HTML iframe

But all of this was before I decided to move from Matlab/Python to Julia. As every Julian newcomer, I had to revise my workflow, find the right packages, think the Julian way, and so on. Everything is not perfect, but I like coding in Julia and the community is really supportive with newbies. That is why, I decided to translate my Dash.py apps into Dash.jl apps.

First steps
A little maths
Let's code this in Julia using Dash.jl
Final thoughts

1. First steps

When I want to discover a framework, I directly go to the documentation page or the dedicated website. Here, we have to visit the Plotly Dash website.

Plotly Dash welcome page

Good news! There is a Julia section. Here is a brief and non exhaustive list of what is dedicated to Julia:

How to install Dash.jl ?
Basic Dash layout. This section is ideal to start with Dash and develop static apps.
Basic callbacks or how to transform your Dash layout into an interactive app.
A section dedicated to advanced callbacks.

And that's all for the moment (Dec. 2022), since the other parts of the doc are either populated with Python examples or simply not written. For instance, in the interactive visualizations section, it is indicated:

This example has not been ported to Julia yet - showing the Python version instead.

Visit the old docs site for Julia at: https://community.plotly.com/c/dash/julia/20

In the other sections, it is mentioned:

This page is not yet available in Julia — check back soon! In the meantime, you can refer to the Python documentation on this topic or post your question in the Dash Julia forum!

Humm! It is not very engaging... But, Plotly people are right! Indeed, even if everything is not documented, the available documentation combined with the Python one is sufficient to to develop our superb web apps in Julia!

2. A little maths

The equation of motion of a damped spring-mass system is given by:

\ddot x(t) + 2\xi\omega_0\dot x(t) + \omega_0^2 = 0,

where

x (t)

is the displacement of the mass,

\xi

is the damping ratio and

\omega_0

is the natural angular frequency.

Depending on the value of the daming ratio, we can observe four distinct behavior for a given set of initial displacement $x_0$ and velocity $v_0$ .

If $ξ=0\xi = 0$ , the motion of the mass is undamped and: $x_0\cos\omega_0 t + \frac{v_0}{\omega_0}\sin\omega_0 t,$
if $ξ∈]0,1[\xi \in ]0, 1[$ , the motion of the mass is under-damped and: $\left[x_0\cos\Omega_0 t + \frac{v_0 + \xi\omega_0 x_0}{\Omega_0}\sin\Omega_0 t\right]e^{-\xi\omega_0 t},$ where $Ω0=ω01−ξ2\Omega_0 = \omega_0\sqrt{1 - \xi^2}$ is the pseudo natural angular frequency.
if $ξ>1\xi > 1$ , the motion of the mass is over-damped and: $\left[x_0\cos\beta t + \frac{v_0 + \xi\omega_0 x_0}{\Omega_0}\sin\beta t\right]e^{-\xi\omega_0 t}$ where $β=ω0ξ2−1.\beta = \omega_0\sqrt{\xi^2 - 1}.$
if where $ξ=1\xi = 1$ , the motion of the mass is critically damped and: where $(x_0 + \omega_0 x_0 t + v_0 t)e^{-\omega_0 t}$ .

The goal of the app is to plot the displacement of the mass for a given set where $(f_0, \xi, x_0, v_0)$ , where $f_0 = \frac{\omega_0}{2\pi}$ is the resonance frequency of the mass-spring system. More precisely, we want to obtain something that looks like the following picture

Picture of the app we want to obtain!

3. Let's code this in Julia using Dash.jl

To make things clearer, we will follow a step-by-step approach.

Computation of the free vibration response

In this part, we want to code the equations describing the free vibration motion of the mass-spring system. It is basically a trivial task in Julia.

const t = 0.:1e-3:2.

function response(f₀ = 10., ξ = 0.01, x₀ = 1., v₀ = 1.)
    ω₀ = 2π*f₀     # Natural angular frequency
    if 0. ≤ ξ < 1. # Undamped/Under-damped response
       Ω₀ = ω₀*√(1. - ξ^2)
      x = (x₀*cos.(Ω₀*t) + (v₀ + ξ*ω₀*x₀)*sin.(Ω₀*t)/Ω₀).*exp.(-ξ*ω₀*t)
    elseif ξ == 1.  # Critically damped response
      x = @. (x₀ + ω₀*x₀*t + v₀*t)*exp(-ω₀*t)
    else # Over-damped response
      β = ω₀*√(ξ^2 - 1.)
      x = @. (x₀*cosh(β*t) + (v₀ + ξ*ω₀*x₀*sinh(β*t))/β)*exp(-ξ*ω₀*t)
    end
end

Just a comment here. The time variable t is defined as a global variable to avoid defining it each time the application is updated.

Definition of the UI

The UI of our app contains:

A header
A plot
Four sliders

To implement our UI, we have use Dash.jl and PlotlyJS.jl packages and define a custom css to define the UI layout.

Let's first implement our custom css. The app.css file is created in a folder named assets in the root folder of our app. For the present app, the css file is defined below.

/* /assets/app.css */

html {
  font-size: 62.5%; }
body {
  font-size: 1.5em;
  font-family: "Open Sans";
  color: rgb(50, 50, 50); }

h1 {
  font-size: 3em;
}

.container {
  position: relative;
  width: 100%;
  max-width: 960px;
  margin: 0 auto;
  padding: 0 20px;
  box-sizing: border-box; }
.container:after,
.row:after,
.column,
.columns {
  width: 100%;
  float: left;
  box-sizing: border-box; }

/* Media Queries
–––––––––––––––––––––––––––––––––––––––––––––––––– */
/* Larger than mobile */
@media (min-width: 400px) {}

/* Larger than phablet (also point when grid becomes active) */
@media (min-width: 550px) {}

/* Larger than tablet */
@media (min-width: 750px) {}

/* Larger than desktop */
@media (min-width: 1000px) {}

/* Larger than Desktop HD */
@media (min-width: 1200px) {}

/* Custom */
.modebar { top: 75px !important; }

/* For devices larger than 400px */
@media (min-width: 400px) {
  .container {
    width: 85%;
    padding: 0; }
}

/* For devices larger than 550px */
@media (min-width: 550px) {
  .container {
    width: 80%; }
  .column,
  .columns {
    margin-left: 0.5%; }
  .column:first-child,
  .columns:first-child {
    margin-left: 0; }

  .three.columns                  {width: 22%;}
  .nine.columns                   {width: 74.0%;}
  .offset-by-three.column,
  .offset-by-three.columns        {margin-left: 26%;}
  .offset-by-nine.column,
  .offset-by-nine.columns         {margin-left: 78.0%;}
}

Now, we can design the application layout as depicted in the following figure.

Scheme of the application layout - HTML style

Using Dash.jl, the previous layout can be implemented as follows

using PlotlyJS
using Dash

# Paste the code to compute the vibration response here

app = dash(external_stylesheets = ["/assets/app.css"])
app.title = "Free response of a mass-spring system"
app.layout = html_div() do
    html_h1("Free response of a mass-spring system", style = Dict("margin-top" => 50)),

    html_div(className = "row") do
        html_div(className = "nine columns",
            dcc_graph(
            id = "graphic",
            animate = true,
            )
        ),

        html_div(style = Dict("border" => "0.5px solid", "border-radius" => 5, "margin-top" => 68), className = "three columns") do
            html_div(id = "freq-val",
            style = Dict("margin-top" => "15px", "margin-left" => "15px", "margin-bottom" => "5px")),
            dcc_slider(
                id = "freq-slider",
                min = 1.,
                max = 50.,
                step = 1,
                value = 10.,
                marks = Dict([i => ("$i") for i in [1, 10, 20, 30, 40, 50]])
            ),

            html_div(id = "damp-val",
            style = Dict("margin-top" => "15px", "margin-left" => "15px", "margin-bottom" => "5px")),
            dcc_slider(
                id = "damp-slider",
                min = 1,
                max = 6,
                step = nothing,
                value = 1,
                marks = Dict([i => ("$(damping(i))") for i in 1:6])
            ),

            html_div(id = "disp-val",
            style = Dict("margin-top" => "15px", "margin-left" => "15px", "margin-bottom" => "5px")),
            dcc_slider(
                id = "disp-slider",
                min = -1.,
                max = 1.,
                step = 0.1,
                value = 0.5,
                marks = Dict([i => ("$i") for i in [-1, 0, 1]])
            ),

            html_div(id = "vel-val",
            style = Dict("margin-top" => "15px", "margin-left" => "15px",  "margin-bottom" => "5px")),
            dcc_slider(
                id = "vel-slider",
                min = -100.,
                max = 100.,
                step = 1.,
                value = 0.,
                marks = Dict([i => ("$i") for i in [-100, -50, 0, 50, 100]])
            )
        end
    end
end

Some comments must be made at this stage:

The app structure using the custom css is created from the command dash(external_stylesheets = ["/path/to/your/custom/css.css"]). The type of app is Dash.DashApp.
The title appearing in the web browser tab is created from the command app.title = "Your incredible title".
The layout of our app is defined in the app.layout, whose type is Component.
- The components html_xxx can be customized by using the keyword style, which is dictionary. The keys are the standard HTML properties (such as "margin-top", "border", ...). Hence, the HTML command style = "margin-top:10px; "border:1px solid" must be implemented as style = Dict("margin-top => "10px", "border" => "1px solid").
- Custom classes are defined by the keyword className.
- A specific id is given to each Dash components, in order to implement the callbacks making the app interactive.
- The slider components are encapsulated in a div environment having a specific id (e.g. freq-val), in order to define its title and display the current value of the slider.
- The damp-slider uses a set of discrete non-linearly spaced values. In order to make the gap between each value constant (it is a matter of taste), one has to define a mapping function damping. This function is implemented as follows:

function damping(value)
    if value == 1
        return 0.
    elseif value == 2
        return 0.001
    elseif value == 3
        return 0.01
    elseif value == 4
        return 0.1
    elseif value == 5
        return 1.
    else
        return 1.5
    end
end

Make your app interactive!

To this end, it is necessary to implement the so-called callbacks. A callback has one Output and one or several Input that apply to our app and the related Component. Here, one has to define 5 callbacks: 4 to define the titles of the sliders and 1 to update the graph.

The first four callbacks are easy to implement and are defined as follows:

callback!(
    app,
    Output("freq-val", "children"),
    Input("freq-slider", "value")
) do freq_val
    "Resonance frequency : $(freq_val) Hz"
end

callback!(
    app,
    Output("damp-val", "children"),
    Input("damp-slider", "value")
) do damp_val
    "Damping ratio : $(damping(damp_val))"
end

callback!(
    app,
    Output("disp-val", "children"),
    Input("disp-slider", "value")
) do disp_val
    "Initial displacement : $(disp_val) m"
end

callback!(
    app,
    Output("vel-val", "children"),
    Input("vel-slider", "value")
) do vit_val
    "Initial velocity : $(vit_val) m/s"
end

The last callback is a little bit more complex, since it has 4 inputs, corresponding to the outputs of the sliders. This callback implement the plotting function and the plot layout. This part is almost a 1:1 translation of the Python documentation.

callback!(
    app,
    Output("graphic", "figure"),
    Input("freq-slider", "value"),
    Input("damp-slider", "value"),
    Input("disp-slider", "value"),
    Input("vel-slider", "value")
) do f₀, ξ, x₀, v₀
    rep = response(f₀, damping(ξ), x₀, v₀)
    figure = (
        data = [(
            x = t,
            y = rep,
            type = "line",
            hoverlabel = Dict(
                "font" => Dict(
                    "size" => 14
                )
            )
            )
        ],
        layout =(
            xaxis = Dict(
                "title" => "Time (s)",
                "titlefont" => Dict(
                    "size" => 20
                ),
                "tickfont" => Dict(
                    "size" => 14
                ),
            ),
            yaxis = Dict(
                "title" => "Displacement (m)",
                "titlefont" => Dict(
                    "size" => 20
                ),
                "tickfont" => Dict(
                    "size" => 14
                ),
                "range" => [minimum(rep), maximum(rep)],
                "ticks" => "outside",
                "tickcolor" => "white",
                "ticklen" => 10
            ),
        )
    )
end

Run the app

To run the app in a web browser, one has to use the run_server command with an optional port number (here 8050).

run_server(app, "0.0.0.0", 8050)

To see the result and play with the ap, you just have to visit the following address http://127.0.0.1:8050/ and voila. If you want to run your app directly without execute your app in the REPL, it is enough to execute in your terminal julia MyApp.jl.

4. Final thoughts

If you already know HTML and Python Dash, Dash.jl is a natural choice to build your web apps in Julia. If not, I hope this tutorial will help to convince you that Dash.jl is quite easy to use. However, I think that Genie Builder with its no-code VScode extension can be a game changer and I plan to make the app described in this tutorial with Genie to fairly compare both frameworks.

Version info

Julia Version 1.8.3
Commit 0434deb161 (2022-11-14 20:14 UTC)
Platform Info:
  OS: Windows (x86_64-w64-mingw32)
  CPU: 8 × Intel(R) Core(TM) i7-10610U CPU @ 1.80GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, skylake)
  Threads: 1 on 8 virtual cores

[1b08a953] Dash v1.1.2
[f0f68f2c] PlotlyJS v0.18.10

Julia Community 🟣: Mathieu Aucejo

Waterfall plot a la Matlab using PyPlot, PlotlyJS and Makie

0. Data generation

1. PyPlot.jl

2. PlotlyJS.jl

3. Makie

4. Final Thoughts

Make beautiful web apps in Julia with... Genie Builder

Table Of Contents

1. First steps

2. Goal of the app

3. Let's implement the app!

3.1. Start the server

3.2. Create a new app

3.3. Create the analysis code

3.4. Create the UI using the no-code editor

3.5 Make the app interactive!

3.6. Let's finish the app

4. Final thoughts

Make beautiful web apps with... Dash.jl

Table Of Contents

1. First steps

2. A little maths

3. Let's code this in Julia using Dash.jl

Computation of the free vibration response

Definition of the UI

Make your app interactive!

Run the app

4. Final thoughts

Version info