Getting started with Explorer

Setting up your environment and a quick intro to Livebook

Let's get you set up with Explorer and Livebook! We'll walk through installation and the basics of Livebook for an interactive learning experience.

This page is for those beginning their Livebook and Explorer journey. For the seasoned Elixir developer, feel free to skip to the next page.

Getting started with Explorer

Before we dive into data wrangling, let's set up your environment and get acquainted with Livebook, your interactive coding companion for this guide.

There are a couple of ways of installing Explorer, depending if you are using it within an existing Elixir project or within Livebook.

Installing in an existing Elixir project

Adding Explorer to your Elixir project is a breeze. Just add it as a dependency in your mix.exs file:

def deps do
	[
		{:explorer, "~> 0.9.2"}
	]
end

Then, run mix deps.get in your terminal to fetch the package.

For the remainder of this guide, we will be using a Livebook environment. In Livebook, we'll install Explorer using an alternative approach: Mix.install().

But first, what is Livebook?

Introducing Livebook

Livebook provides an interactive and engaging way to write and execute Elixir code, visualise data, and create dynamic documents. Think of it as a blend of Jupyter Notebook and a collaborative workspace, all within your browser.

If you're coming from a Python background and have used Jupyter Notebooks, you'll find Livebook quite familiar.

Livebook offers some advantages, particularly for Elixir development:

Real-time Collaboration: Work on the same notebook with others simultaneously.
Interactive Outputs: Explore data visualisations and interact with running processes.
Elixir-Specific Features: Seamless integration with Elixir tools and libraries.

If you haven't yet installed Livebook, follow the guides at the official Livebook website.

At the time of writing this guide, there are a number of ways to install or launch Livebook:

download the official Windows and Mac installers
run in the cloud, such as through Hugging Face or Fly.io
run via your CLI an escript
run using Docker (useful if you don't have Elixir installed).

Your first Explorer code in Livebook

Let's start with a simple example to get you comfortable with Explorer in Livebook.

Step 1: Create a new Livebook notebook.

Step 2: In a code cell, type the following:

Mix.install([{:explorer, "~> 0.9.2"}])

df = Explorer.DataFrame.new(
  city: ["New York", "Los Angeles", "Chicago"],
  population: [8_419_000, 3_979_000, 2_716_000]
)

Step 3: Run the cell. You should see a formatted response displaying your dataframe, something like this:

#Explorer.DataFrame<
  Polars[3 x 2]
  city string ["New York", "Los Angeles", "Chicago"]
  population s64 [8_419_000, 3_979_000, 2_716_000]
>

Don't worry too much what this response means (you can probably guess!) and we'll cover it in more detail later.

By using Mix.install() you Livebook will fetch Explorer and install it, and you have already got your first taste of using Explorer's API by creating a new dataframe with Explorer.DataFrame.new().

A handy shortcut

To make our code a bit more concise, we can create a shorter alias for the Explorer.DataFrame module. We'll use DF throughout this guide:

require Explorer.DataFrame, as: DF

df = DF.new(
  city: ["New York", "Los Angeles", "Chicago"],
  population: [8_419_000, 3_979_000, 2_716_000]
)

This will save us some typing and make our code a bit easier to read.

Require vs alias

In Elixir, we usually use alias to create an alias for a module. For example:

alias Explorer.DataFrame, as: DF

But with Explorer, its recommended to use require instead, like the following:

require Explorer.DataFrame, as: DF

The reason for this is that require will load Explorer's macro features which make for a friendly way to query dataframes. The macros compile regular Elixir code to a form for efficient dataframes operations.

Running the examples in Livebook

Throughout this guide, you will see the following "Run in Livebook" button:

That will allow you to launch the code related to this page in your Livebook environment. If you haven't tried it before, click the button above and give it a go!

Summary

In this section, we've covered the essentials of getting started with Explorer and Livebook. Next, we'll explore how to import data from various sources into your dataframes.