Magic commands and JSROOT

(5 minutes)

Why are we doing magic when this is physics?

In Jupyter, “magic” refers to additional commands added by Jupyter to the kernel environment that aren’t normally part of that kernel’s language.1 I’m going to start with a magic command that’s unique to ROOT.

In a new cell in the notebook we just worked with, execute this command:2

%jsroot on

How we know it’s magic

As a general rule, magic commands begin with the percent sign “%”.3

Draw the canvas again:

my_canvas.Draw()

Move the cursor over the new plot.

Interactive plots

Ah, that’s more like it! The plot is now interactive, though not quite in the same way as in X-Windows ROOT. Play around a bit, looking at tooltips and right-clicking. In particular, if you right-click on the axes you’ll be able to set their titles in a way that’s much more intuitive than before.

Did you spot the faint square below the lower left-hand corner of the plot? It’s easy to miss:

the hard-to-find tool button

Figure 26: Click on this button to bring up more icons.

Explore by clicking the other icons you’ll see. For me, the most interesting result is when you click on the icon that looks like a question mark “?” within a circle:

a list of classes used in the canvas

Figure 27: You’ll see a list of classes that are used in the plot.

Each one of the items you see on that menu has a sub-menu with options to control aspects of the plot. For me, the most interesting options are found in the Canvas sub-menu:

the canvas menu

Figure 28: The full chain to get this is Menu ‣ Canvas ‣ Save as

As I noted earlier, by default Jupyter notebooks create images in .png format, and the basic way to save these plots is via a web browser’s Save Image As… pop-up. The %jsroot magic command allows you to pick which output format you’d prefer.4

The missing option

There’s one option that’s missing: the .C format. If that were present, you could create a complex plot within a notebook, adjust it interactively using the above menus, then save the plot as a macro to learn the ROOT commands needed to create plots with your favorite colors, line widths, etc.

Hopefully this feature will be added in a future version of ROOT.5

More magic

If you execute %lsmagic in a cell you’ll see a list of available magic commands. There’s probably more than you can absorb right now.6 These are examples of magic commands I find to be the most useful:

%mkdir subdirectory
%cp ~seligman/root-class/jsroot-test.ipynb subdirectory
%ls subdirectory
%less c1.C
%man root
%cd subdirectory

The above commands are “line magics,” which are executed line-by-line within a cell. There are also “cell magics” that affect the contents of the entire cell in which they appear; they must appear as the first line in a cell. They begin with a double “%”. Examples:

  • %%writefile filename (write the cell to file filename);

  • %%timeit (execute the cell many times and determine the average execution time);

  • %%sh (execute the cell as a UNIX shell script).

1

No, nothing to do with Doctor Strange or Gandalf, though you may find yourself muttering “You shall not pass!” as you work with ROOT.

2

Note that the %jsroot magic command is only available in Python-based notebooks after you’ve executed import ROOT or from ROOT import... In ROOT C++ notebooks it’s built-in.

“JSROOT” is short for “Javascript ROOT”; it’s an evolving project to bring more interactivity of ROOT graphics into web browsers.

3

Well… not really. There’s an option (%automagic on|off) that allows you to omit the leading %. In this tutorial I’ll always include the % prefix to make it clear when a command is “magic”.

4

This may seem like an unnecessary frill. What’s wrong with .png? In general, nothing. However, when it comes to professional publication of your plots in high resolution, you probably want the plots to be in .svg (Scalable Vector Graphics) format, so your plots won’t depend on the resolution of the viewer’s screen.

5

In theory, if you’ve drawn something to my_canvas, you can write a corresponding ROOT macro with

my_canvas.SaveAs("filename.C");

where filename.C can be any name you want. Don’t forget to use -> if your canvas variable is a C++ pointer instead of an object!

However, when you do this within a notebook, the ROOT macro only contains the commands needed to recreate the original canvas. It doesn’t include any changes you made interactively.

The only work-around I’ve found is:

  • Work in the notebook to create the data and an initial plot.

  • Save that plot’s canvas; assume it’s something like canvas.SaveAs("myplot.C")

  • Go to the UNIX window and run ROOT on the macro I’ve just created:

    root myplot.C

  • Use the ROOT editing tools to adjust the appearance of the plot.

  • With the menu File ‣ Save… create a macro file with my changes.

You may now understand why I made you go through the command-line basics before introducing ROOT notebooks.

6

Here are more details about magic commands.