Skip to content

Quick Start

Jump to bottom
cscully-allison edited this page Dec 7, 2021 · 8 revisions

Quickstart

If you have already tried out Roundtrip and are interested in making your own magic function based visualizations, the following guide will help you get started.

Setup

Install Roundtrip:

pip3 install roundtrip-lib

Create a directory to host your visualization files:

mkdir rt_tutorial
cd rt_tutorial

Inside of this directory create:

  1. A python file which will host the visualization's magic functions
  2. An html file which will be used as a template or stub for our javascript code to manipulate
touch rt_templ.html rt_vis.py

HTML

We will begin by modifying rt_templ.html. Using your text editor of choice, insert the following html code into our template.

<body>
  <h1>I was loaded by Roundtrip.</h1>
</body>

Making a visualization loader

Now open rt_vis.py in your favorite text editor.

Inside of rt_vis.py we are going to import the following lines of code

from IPython.core.magic import Magics, magics_class, line_magic
from roundtrip.manager import Roundtrip as RT

Since we will be creating a standard Jupyter magics class for our users to use for accessing the visualization we must import some of those libraries.

On the second line we import a singelton Roundtrip instance and giving it the RT alias.

Next, we will define our magics class:

@magics_class
class MyRTVis(Magics):
  def __init__(self, shell):
    super(MyRTVis, self).__init__(shell)
    self.shell = shell

This is standard boilerplate for defining a magics class and is explained in more detail in the Jupyter documentation.

In order to expose a magic function to our users we need to add a new member function with a line magic decorator.

@magics_class
class MyRTVis(Magics):
  def __init__(self, shell):
    super(MyRTVis, self).__init__(shell)
    self.shell = shell

  @line_magic
  def hello_rt(self, line):
      
      # load files
      RT.load_web_files(["rt_templ.html"])

      RT.initialize()
  
def load_ipython_extension(ipython):
    ipython.register_magics(MyRTVis)

In this new line magic function we provide an single line magic function call %hello_rt which will load our html in the calling notebook, using RT.load_web_files(). RT.load_web_files() expects a list of filepaths to the desired files which should be loaded, and it can support:

  1. HTML
  2. Javascript
  3. CSS

RT.initalize() will always be called after we load files and specify data bindings between our visualization and python code.

At the bottom, you will see the function load_python_extension, this is a Jupyter specific function which allows us to load our magics class using the %load_ext command in our notebook.

To see it in action we need to make a jupyter notebook.

Using our Vis in a Jupyter Notebook

Create a Jupyter notebook in this same directory

To create a jupyter server run:

jupyter-notebook

This should open your web browser automatically with a file-explorer view. From this view, create a new notebook. Name the notebook 'rt_notebook'. Inside of the notebook, in the first cell add the line:

%load_ext rt_vis

Then, create a new cell and add a call to our magic function:

%hello_rt

Now, with everything setup run the cells in this notebook. You should see the text: "I was loaded by roundtrip." in the %hello_rt cell!

Clone this wiki locally