Mercury : A Cool Web Apps Visualization for VS Code

As data scientists, have you ever had trouble communicating your findings and insights to your clients? Either your PowerPoint presentation is time-consuming or your reports are just not interesting enough to look at.

While these methods are preferred by many, sometimes they are just not attractive enough to make your clients want to give all their attention to.

But what if you can present your findings in an interactive and more attractive way? What if you don’t have to create PowerPoints or reports after spending hours in your Jupyter Notebook? What if you can share your findings straight out of Jupyter Notebook? And no, we are not talking about Streamlit, we are talking about another open-source tool. We are talking about Mercury.

First developed at the Cambridge Crystallographic Data Centre in 2001, Mercury was originally designed as a tool to visualize a crystal structure. But over the years, Mercury has been developed to be a more advanced and sophisticated structural analysis tool. It is now one of the most powerful analysis, design, and prediction platform being used by Data Scientists.

How does it work? How to install Mercury? What structures or visualizations Mercury can make? To find out the answer, keep reading this article and behold, Mercury.

What is Mercury?

Mercury is an open-source tool used by Data Scientists to create a platform for them to show their analysis and prediction to clients. Starting out as only a visualizer, Mercury has since then evolved into a platform that can show not only visualizations, but also analysis, designs, and also predictions functionality. You can also hide codes and use interactive widgets to make the presentation more interesting.

Example of Mercury use from a Jupyter Notebook

What are The Differences with Streamlit?

The main difference between Mercury and Streamlit is:

1. Mercury works with Jupyter Notebook, Streamlit works with Python scripts. With Mercury you don’t have to rewrite your analysis from Jupyter Notebook to Python scripts.
2. Mercury provides OutputDir to download files created on the notebook.
3. You can create interactive presentations with Mercury.
4. Mercury has authentication built in.
5. Mercury provides easy PDF/HTML notebook export.
6. You can schedule notebook execution automatically .

Prerequisites Mercury

There are several requirements before diving into Mercury.

1. Python

Python is the most popular language due to its simple and easy code to understand. By definition, python is an interpreted high-level object-oriented dynamically type scripting language.

In data analysis, python can quickly create and manage data structures, allowing the users to analyze and manipulate complex data sets. One of the the main focus in mercury is utilizing python as a bridge to perform data visualization.

Setting up python requires a few simple steps. First of all, install the library with pip:

pip install python

And done! Now we can go to the next step!

2. Jupyter Notebook

Jupyter Notebook is a free web application that enables the creation and sharing of documents with live code, equations, visualizations, and narrative text. It enables a single canvas, called notebook, to be combined by Python code or another language with your Markdown text.

Installing the Jupyter Extension

To install the Jupyter Notebook, you can use Visual Studio Code (VS code). First, launch your VS code, go to your extension toolbar, type “jupyter notebook” in the extension search box. Select the first result (Jupyter) and click on the Install button displayed in the middle of the screen:

Visual Studio Code Jupyter Extension

And that’s all! Congratulations! Now let’s go to the next steps!

Getting Started with Mercury

Two things are primarily responsible for the development of web applications created by Mercury, Jupyter Notebook and Mercury Server.

Image from https://runmercury.com/

1. Jupyter Notebook

This is where all the magic comes from. To develop the web app, you need to enable interactivity using Mercury’s input and output widgets.

Input widgets are used for user input and interaction with an application, which provides a trigger action in the notebook. These components will appear in the sidebar when running the notebook in Mercury.

Input Widgets

On the other hand, output widgets are used to control execution flow and present the results. Mercury will generate the Jupyter’s cell output. Thus, plots or prints of DataFrame will appear in your web application’s Output Panel.

Output Widgets

Additionally, Mercury also provides Custom Widgets with the Mercury Framework.

Custom Widgets

2. Mercury Server

To render the notebook, it only requires a single command that is created in your web app in a notebook.

Install Mercury

To install mercury, let’s utilize the library with pip.

pip install mercury

And done! Now you can create your own web app using input, output, or custom widgets.

Start Developing

As mentioned, we can start creating a web app from a notebook right away. All development will be done in jupyter notebook.

Import libraries

Import what’s important. Other than mercury, we also need tools for data visualization for the app. Here we will use seaborn and matplotlib as well.

# Mercury main tools
import mercury as mr

# Dataframe
import pandas as pd
# Visualization
import seaborn as sns
from matplotlib import pyplot as plt

That’s all the tools required, our mercury journey has just begun.

Initialize the app

First thing first, we set seaborn theme.

# Setup seaborn theme
sns.set()

Then we initialize the app with the title and the description.

app = mr.App(title="Employee Data Analysis", 
             description="Employee Report in Mercury")

You need to run the app from the command line. Navigate to where the notebook directory and run this command:

mercury run

That’s it! mercury will automatically find the notebook with initiated app and run it. Don’t worry if you have more than one notebook files with the app, mercury will let you choose which app to run in the browser.

And this is how the simple app looks like.

It’s kind of empty currently, we’ll add some contents later. What you need to know is how the template goes. On the left you can see a tab saying employee data analysis, that’s where our widgets will be placed. There are also download and share button which were already provided by mercury default view.

On the right side it’s currently an empty space and will be filled with content as we write on the notebook markdown or plots we have generated. Awesome right?

Alright, all set! But wait, before we create the app, let’s dive a bit into the mercury widgets.

Introducing: mercury widgets

Like any other web app, mercury also provide several widgets for us to make our app more functional, and also prettier. See how easy it is to generate widgets with mercury.

• Markdown

Use markdown to display text.

# Markdown text
mr.Md("This is a text")
mr.Md("### Bigger text")
mr.Md("# Even bigger text")

• Inputs

With mercury, we can input text, number, and data upload with the widgets.

# Text input
text_input = mr.Text(value="John Doe", label="Input text")

# Number input
number_input = mr.Numeric(
    label="This is number input",
    value=5,
    min=0,
    max=10,
    step=0.5
)
# File input
data_file = mr.File(label="Upload Data")

You can adjust the widget parameters such as default value, minimum and maximum number value, and number steps. This is how the inputs look like.

• Select and checkbox

Most app interaction requires selecting, in this tutorial we specifically use them to filter data. Mercury have several widgets available.

# Select
select = mr.Select(
    value="Mercury",
    choices=["Mercury", "Is", "Awesome"],
    label="This is a select widget"
)

# Multiple select
multiselect = mr.MultiSelect(value=["Mercury"], 
                         choices=["Mercury", "Is", "Awesome"],
                         label="This is multiple select widget")
# Checkbox
checkbox = mr.Checkbox(
    value=True,
    label="This is a checkbox"
)

You can arrange choices for the selection and the default selected choice. Here is the result.

• Sliders

Typing is kind of boring right? no worries, mercury have slider widgets to make our app more interactive.

# Basic slider
slider = mr.Slider(
    value=5,
    min=0,
    max=10,
    label="This is a slider",
    step=1,
)

# Range slider
range_slider = mr.Range(
    value=[3,7],
    min=0,
    max=10,
    label="This is a range slider",
    step=1,
)

Same as number input, we can also arrange for maximum and minimum value, and the steps. For range slider, the value is set to be a two length list.

That’s all it takes to create widgets, neat!

Now we are ready to create our first app with a sample dataset.

Get the data

Let’s check our data using pandas.

# Read dataset with pandas
df = pd.read_csv('./employee_dataset.csv')

So here are what we’re going to build:

1. An upload widget for csv file
2. Select widgets for the user to filter what they want to see in the data frame
3. A text input to query the name. No regex for now so the user must input the right name
4. Range slider for additional filtering of numerical data

And then we will display the data to our beloved users:

1. A scatter plot of Employee_Salary and Employee_Rating
2. Employment_Status shown as a barplot

We defined what we want to build, and we have already initiated the app. Without further ado, let’s start building.

Create widgets

The most important aspect of data analysis is well…, the data!

So here we give our users a way to upload the data with file upload widget.

# Read dataset with pandas
data_file = mr.File(label="Upload CSV")

We also want the app to run its display only when the data have been uploaded.

# Data uploaded
file_read = False

# Only run if data_file is not empty
if data_file.filepath:
    
    # Start reading the data with pandas
    emp_df = pd.read_csv(data_file.filepath)
    
    # Activates file_read variable
    file_read = True

The code activates file_read variable only if data_file.filepath value is not empty. The file_read variable will then activates the display.

# When file_read value is true, activate all widgets and displays
if file_read:
    
    # Company selection with multi select
    company = mr.MultiSelect(value=emp_df.Company_Name.unique(), 
                             choices=emp_df.Company_Name.unique(),
                             label="Select Companies")
    
    # Credit filter with slider
    credits_filter = mr.Range(value=[1,3], min=emp_df.Credits.min(), 
                               max=emp_df.Credits.max(), label="Credits Filter", step=1)
    
    # Returns dataset with selected company and credit card range
    new_df = emp_df[(emp_df.Company_Name.isin(company.value)) & (emp_df.Credits>=int(credits_filter.value))]

    # Print the shape of the dataset with markdown widget
    mr.Md(f"The DataFrame has {new_df.shape[0]} rows and {new_df.shape[1]} columns.")
    
    # Plot graph only when new_df has a certain length
    if len(new_df):
        fig, ax = plt.subplots(1, 2, figsize = (16, 9))
        sns.scatterplot(data = new_df, ax = ax[0], x = "Employee_Rating", y = "Employee_Salary")
        sns.countplot(x = new_df.Employment_Status, ax = ax[1])
        plt.show()

That’s all we had to do to build this app. Now for the climax.

Run the app!

Brace yourself as we run our first mercury app. Just a simple command to do it.

mercury run

And here we go…

Looks alright, let’s upload the data.

Works like a charm, we instantly see all the display after uploading the data. And this is how the filtering process works.

A simple, interactive web app created directly from the notebook. Great!

If you’re wondering how the building process work after each change you made to the app, rest assured because mercury automatically refresh the code every time you save the notebook and you can just navigate to the open browser page. Go try it yourself!

Deploying on Huggingface

You can deploy mercury app on heroku, hugginface, or with docker. Here we will briefly show how to deploy with docker.

1. Create a new space with Gradio SDK app type
2. Add this to your requirements.txt file

mljar-mercury

3. Create app.py file with this code to run the mercury app

import os
from dotenv import load_dotenv
from subprocess import Popen
load_dotenv()

command = ["mercury", "run", f"0.0.0.0:{os.environ.get('PORT', 7860)}"] 
worker = Popen(command) 
worker.wait()

4. Create Mercury YAML configuration in the first RAM cell. This is the trickier part where you have to define the widgets in YAML parameters. Pretty much look like this.

5. Wait for huggingface to build the app, and voila! your web app is ready for use.

Conclusion

So what do you think about Mercury? Pretty cool, right? We now have the understanding that presentations can be, or should be, both informative and interesting to look at.

And who knows? Maybe Mercury will be even better in the future. We just have to wait and see. But right now, Mercury is already one of the best Web App tool out there.

If you want to have a better idea of what Mercury is, please click on this link to see our YouTube video talking about Mercury.

Thanks for reading and Go Mercury!