colorByValue: Color residues by value

In NGLVieweR: Interactive 3D Visualization of Molecular Structures

Color residues by value

Description

Color residues by a numeric value computed in R, such as a conservation score, a mutation effect or a p-value. The values are mapped onto a color gradient, and the result can be used as color wherever a representation takes one: addRepresentation, addSelection, updateColor and updateRepresentation.

Usage

colorByValue(
  values,
  palette = c("blue", "white", "red"),
  domain = NULL,
  na_color = "grey"
)

Arguments

values	Either a data frame with columns resno and value, and optionally chain, inscode (insertion code) and structure (the structure number, counting from 1); or a named numeric vector with names "chain:resno", such as "A:12", "A:12B" (with insertion code B) or "12" (any chain). Without chain a row applies to that residue number in every chain, and without structure to every structure. The data frame of the Shiny input input$<outputId>_residues with an added value column can be used as is.
palette	Two or more colors (names or HEX codes) for the gradient, from the lowest to the highest value.
domain	The values at the two ends of the palette, c(min, max). Defaults to the range of values. Values outside it get the color of the nearest end.
na_color	Color for residues with a missing value (NA) and for residues not listed in values.

Details

The colors are computed in R, so the viewer shows exactly the colors that grDevices::colorRamp(palette) gives. A row for a specific chain or structure takes precedence over a row for any chain or structure. NGL.js cannot show a color legend; the returned object contains palette and domain (as HEX colors and numbers) so a legend can be drawn next to the viewer, e.g. with a plot.

Value

A NGLVieweR_colorByValue object to use as color.

See Also

addRepresentation(), updateColor(), NGLVieweR-shiny

Examples

scores <- data.frame(chain = "A", resno = 1:46, value = sin(1:46 / 5))
NGLVieweR("1CRN") %>%
  addRepresentation("cartoon",
    param = list(color = colorByValue(scores,
                                      palette = c("blue", "white", "red"),
                                      domain = c(-1, 1))))

# A named vector, for a few residues; all others are grey
NGLVieweR("1CRN") %>%
  addRepresentation("cartoon",
    param = list(color = colorByValue(c("A:10" = 1, "A:20" = 2, "A:30" = 3))))

if (interactive()) {
  library(shiny)
  ui <- fluidPage(
    sliderInput("k", "Score = sin(resno / k)", 1, 20, 5),
    NGLVieweROutput("structure")
  )
  server <- function(input, output) {
    output$structure <- renderNGLVieweR({
      NGLVieweR("1CRN") %>%
        addRepresentation("cartoon", param = list(name = "cartoon"))
    })
    observeEvent(input$k, {
      residues <- input$structure_residues
      req(residues)
      residues$value <- sin(residues$resno / input$k)
      NGLVieweR_proxy("structure") %>%
        updateColor("cartoon", colorByValue(residues, domain = c(-1, 1)))
    })
  }
  shinyApp(ui, server)
}

NGLVieweR documentation built on Oct. 20, 2026, 1:07 a.m.