(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 the hard-to-find tool button 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 a list of classes used in the canvas 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 canvas menu 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).