(magic-command)=
# Magic commands and JSROOT
**(5 minutes)**
:::{admonition} Why are we doing magic when this is physics?
:class: note
In Jupyter, "magic" refers to additional commands added by Jupyter to
the kernel environment that aren't normally part of that kernel's
language.[^f54] 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:[^f55]
%jsroot on
:::{admonition} How we know it's magic
:class: note
As a general rule, magic commands begin with the percent sign "%".[^f56]
:::
Draw the canvas again:
my_canvas.Draw()
Move the cursor over the new plot.
:::{admonition} Interactive plots
:class: note
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:
:::{figure-md} toggle_tool_buttons-fig
:align: center
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:
:::{figure-md} classes_list-fig
:align: center
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:
:::{figure-md} canvas_menu-fig
:align: center
The full chain to get this is {menuselection}`Menu --> Canvas --> Save as`
:::
As I noted {ref}`earlier `, by default Jupyter notebooks create images in `.png` format,
and the basic way to save these plots is via a web browser's {menuselection}`Save Image As...` pop-up.
The `%jsroot` magic command allows you to pick which output format you'd prefer.[^format]
[^format]: 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.
:::{admonition} The missing option
:class: note
There's one option that's missing: the {ref}`.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.[^saveas]
:::
[^saveas]: 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 {menuselection}`File --> Save...` create a macro file with my changes.
You may now understand why I made you go through the command-line {ref}`basics ` before
introducing ROOT notebooks.
:::{admonition} More magic
:class: tip
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.[^f57]
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 {file}`filename`);
- `%%timeit` (execute the cell many times and determine the average
execution time);
- `%%sh` (execute the cell as a UNIX shell script).
:::
[^f54]: No, nothing to do with Doctor Strange or Gandalf, though you may
find yourself muttering "You shall not pass!" as you work with ROOT.
[^f55]: 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](https://github.com/root-project/jsroot/blob/master/docs/JSROOT.md) to
bring more interactivity of ROOT graphics into web browsers.
[^f56]: 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".
[^f57]: Here are more details about [magic commands](https://ipython.readthedocs.io/en/stable/interactive/magics.html).