Artificial Intelligence

👁 Photo by AltumCode on Unsplash

Documentation – undoubtedly one of the crucial tasks of every data scientist, yet most likely also in the lowest ranks in terms of how enjoyable it is. I will not try to persuade you about the benefits of keeping an up-to-date documentation, that is a topic for another time.

In this article, I will show you a tool that can help with making the process much faster, more efficient, and even enjoyable. After all, a picture is worth a thousand words. And to bring it closer to home, the picture can be a flowchart in your README file or other markdown-like documentation.

Mermaid

Recently a colleague introduced me to a tool called Mermaid. I think the following sentence from the documentation does a great job in describing what Mermaid is:

It is a Javascript-based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically.

For me, the key arguments that speak in Mermaid’s favor are:

• free and open-source,
• almost no installation is required (only plugins for viewing the charts),
• easy to use and has extensive documentation,
• can be easily integrated into current documentation workflow -> storing the graphs as code in markdown files.

Mermaid in practice

I think for tools such as Mermaid, the easiest way to learn is by doing. That is why we will first create a simple flowchart. For those not familiar with it, it is a type of a diagram representing a process or a workflow.

Two resources that we will be using in this article are:

• Mermaid’s documentation — by browsing it we can see how to use the available building blocks to create even very complex diagrams,
• Mermaid Live Editor — this tool offers a live preview of the output of our diagram, it will come in very handy while building something from scratch.

Let’s start with something very simple.

graph TD
 A-->B
 A-->C
 B-->D
 C-->D

In the live editor, we can see the following preview:

👁 Image by author

As you can see, the syntax is quite straightforward. We specified we want to create a Top-Down graph and provided the nodes and connections between them.

Now, let’s move to something more complex and resembling real-life scenarios. Imagine that you have a data science project in which you have an ensemble of models predicting something. The details are not relevant. To make the documentation easier to understand, you create the following graph showing how all the pieces are connected, from getting the raw data to storing the predictions of the ensemble.

👁 Image by author

As you can see, this graph is definitely more complex. Some things to notice about the syntax:

• we used a Left-Right graph this time.
• we can name the nodes by providing the name by any of its instances. A nice feature is that we do not have to name all of them, which definitely saves some time.
• by using the |text| after the arrow, we can provide a description that will be displayed on the given arrow.
• using the id object we can create a shape representing a database. There are many different node shapes available in Mermaid, please refer to the documentation for more information on what is available and how to create them.
• we can use Font Awesome’s icons combined with text.

Those two examples should show enough syntax for you to be able to pick it up and experiment yourself! That is when the Live Editor shines, as it makes drafting and debugging very easy.

Other kinds of available charts

Mermaid is by no means restricted to flowcharts. You can also create the following types of graphs:

• sequence diagram
• class diagram
• state diagram
• entity relationship diagram
• user journey
• Gannt chart
• pie chart

👁 Example of a Gannt chart created in Mermaid. Source

Integrating Mermaid into the current workflow

How difficult is it to integrate Mermaid graphs into your workflow? Not very, though there are still some rough edges you might want to consider.

Let’s start with embedding your graphs in your markdown files. It is as simple as adding a special block around your code. You can see a very simple example of a README.md file below.

You might also want to install a VS Code plugin to enable viewing the charts in markdown preview. PyCharm also handles Mermaid easily, you just need to turn on that option in the settings.

If you ask me, those small changes to the workflow are definitely worth it.

Bonus: Python integration

You can also visualize your Mermaid graphs using Python. In this short example, we will visualize the same data science flowchart we have used above. To do so, we start by importing the required libraries.

Then, we run the following snippet.

Which generates the same chart we have seen before.

👁 Image by author

Takeaways

• Mermaid is a tool to create various kinds of charts using a markdown-like syntax.
• there is no special installation required for using Mermaid. You can play around with the syntax in a Live Editor.
• the tool is not natively integrated with GitHub, but you can visualize the graphs using plugins for your IDE of choice or browser extensions.

You can find the code used for this article on my GitHub. Also, any constructive feedback is welcome. You can reach out to me on Twitter or in the comments.

If you liked this article, you might also be interested in one of the following:

9 Useful Pandas Methods You Might Have Not Heard About

Embed your interactive visualizations in Medium posts using datapane

Beautiful decision tree visualizations with dtreeviz

Share This Article

• Share on Facebook
• Share on LinkedIn
• Share on X