Using Buttons in {r3dmol}

Brady Johnston

2021-08-18

library(r3dmol)

Setting up a basic scene

Before we start adding buttons, lets set up a basic molecular viewer.

viewer <- r3dmol() %>% 
  m_add_model(pdb_1j72) %>% 
  m_set_style(m_style_cartoon("spectrum")) %>% 
  m_zoom_to()

viewer

Now that we have a viewer set up, let’s add some user interactions with buttons!

Basics of Buttons

{r3dmol} provides a framework for creating buttons that will appear in the viewer for the user to click on. When clicked - the button will execute some pre-determied javascript code. If you want to create your own custom buttons, use the m_button_manual() function and supply your own javascript, like in the example below.

viewer %>% 
  m_button_manual(
    name = "cartoon",
    label = "Cartoon",
    align_items = "flex-end",
    justify_content = "center",
    func = "
      function() {
        viewer.setStyle({cartoon:{color:\"spectrum\"}});
        viewer.render();
      }
    "
  ) %>%
  m_button_manual(
    name = "stick",
    label = "Stick",
    func = "
      function() {
        viewer.setStyle({stick:{}});
        viewer.render();
      }
    "
  )

The viewer is executing the javascript code that is defined inside of the func variable. The problem with this is that it requires you to learn some javascript, but also that writing javascript inside of a string inside of R isn’t the most pleasant thing in the world.

To help out {r3dmol} has some pre-defined buttons for convenience.

Default Buttons

The m_button_*() family of functions allow for the quick creation of buttons to do a range of common user input tasks that you might want to set up inside of the viewer.

Changing the style, zooming in and out of a particular selection, spinning and playing animations are currently pre-defined. If you feel the need for other buttons, please feel free to open a feature request on github.

Let’s recreate the viewer above to allow changing of the style, with a few less lines of code.

viewer %>% 
  m_button_set_style(m_style_cartoon("spectrum"), 
                     label = "Cartoon") %>% 
  m_button_set_style(m_style_stick(), 
                     label = "Stick")

We can also allow spinning / stopping of spinning.

viewer %>% 
  m_button_spin()

You’ll notice that the m_button_spin() function automatically also created a Stop button as well as the spin button. Several m_button_*() functions automatically create a complimentary button (start / stop animation, show / hide labels etc), but the creation of this button can be disabled inside the function with stopButton = FALSE.

Of course now when we start the model spinning with the button, we have no way of stopping it. This feature is useful however when you wish to have multiple buttons that spin the model different directions and speeds, and not create a new Stop button each time you add a button.

viewer %>% 
  m_button_spin(stopButton = FALSE)

Buttons to Change Style

To change the styling of the protein in the scene between two options, we can use the m_button_*_style() functions to either add or set new styles.

viewer <- viewer %>% 
  m_button_set_style(m_style_cartoon("spectrum"),
                     label = "Cartoon") %>% 
  m_button_set_style(m_style_stick(), 
                     label = "Sticks")

viewer

Enhance!

To zoom in and out of a particular section, use the m_button_zoom_to() functions, to bring the attention of the viewer to a particular section of the scene with the click of a button.

viewer %>% 
  m_button_zoom_to(m_sel(resi = 100:110))

Checkout the documentation for the other m_button_* functions to see what support has been added. If you would like a particular button to exist, open an issue or a pull request and we can help make it happen!