The package now includes the copyright and license notices of the
bundled NGL.js library and of the libraries compiled into it (three.js,
Mol*, chroma.js, sprintf.js, JS Signals, tslib and code adapted in
NGL.js), with the source and checksum of the bundled file, in
inst/COPYRIGHTS and
inst/htmlwidgets/lib/NGL-2.5.0/LICENSE. Their copyright
holders are listed in DESCRIPTION.
The re-export of file_ext() from ‘tools’ was added
by accident and will be removed in a future release. Packages that use
file_ext() through import(NGLVieweR) should
import it from ‘tools’ instead
(importFrom(tools, file_ext)) or call
tools::file_ext().
Fixed the Shiny examples in ?NGLVieweR and
?NGLVieweR-shiny: they used an input
input$backgroundColor that the app does not define, and the
first app named its ball+stick representation “cartoon”.
A widget saved with its files in a separate folder
(htmlwidgets::saveWidget(selfcontained = FALSE), R Markdown
or Quarto output that is not self-contained, pkgdown sites) no longer
contains NGL.js (1.3 MB) twice and extra copies of the widget files.
Self-contained output and Shiny apps were not affected.
Fixed colorByValue() when both ends of the domain
are equal (e.g. when all given values are the same): residues with a
missing value (NA or NaN) got the middle
palette color instead of na_color, and values outside the
domain (including Inf) got the middle color instead of the
nearest end.
Fixed stageParameters() ignoring
clipNear, clipFar, fogNear,
fogFar and quality: the viewer always applied
setFocus(0) and setQuality("medium")
afterwards, which overwrote them. setFocus() and
setQuality() are now only applied when used, and options
named in stageParameters() win over them
(e.g. setFocus(50) %>% stageParameters(fogFar = 60)).
Viewers that use neither look the same as before, except with
stageParameters(clipScale = "absolute"), which now starts
from the NGL.js clip and fog defaults. In Shiny, a re-render no longer
resets a focus set with updateFocus() (like other values
set with updateStage()); focus and quality set by
setFocus()/setQuality() in an earlier render
go back to the defaults.
Fixed input$<outputId>_PDB holding the
coordinates from before setSuperpose(): the PDB text was
written before the structures were superposed, so an exported target did
not overlay the reference although the viewer showed them aligned. It
now has the superposed coordinates. (setPosition(),
setRotation() and setScale() move only how a
structure is drawn and are still not in _PDB.)
Fixed input$<outputId>_rendering changing to
FALSE while the viewer was still busy, so a spinner tied to
it stopped too early. updateColor(),
updateVisibility(), updateRepresentation() and
updateStage() set it to FALSE right away, even
while a snapshot was being made or NGL.js was still rebuilding a
representation (e.g. a surface), and with several NGL.js tasks at once
(loading several structures) it changed to FALSE when the
first one finished. It now changes to FALSE only when
nothing is running.
Fixed snapShot() doing nothing, and
input$<outputId>_rendering staying TRUE,
after a representation was removed while it was still being built
(e.g. removeSelection() and addSelection() of
a surface while its sliders move, or a re-render). NGL.js kept counting
the unfinished build as a running task.
Fixed PDB entry codes without a PDB-format file not loading
(GitHub #17). RCSB only provides large entries, such as ribosomes and
other big cryo-EM structures (e.g. NGLVieweR("3J9M")), as
mmCIF, so loading them failed. A code now loads the PDB-format file as
before, and the mmCIF file if that fails. format = "pdb" or
format = "cif" now picks the file for a code (it used to be
ignored); any other format for a code is now an
error.
Updated the bundled NGL.js from 2.0.0 to 2.5.0.
New colorByValue(): color residues by a numeric
value computed in R (a conservation score, a mutation effect, B-factors,
a p-value). Values are mapped onto a color gradient
(palette, domain), residues with a missing
value or no data get na_color, and the result can be used
as color in addRepresentation(),
addSelection(), updateColor() and
updateRepresentation(). Takes a data frame
(resno, value, optionally chain,
inscode and structure, so
input$<outputId>_residues with an added
value column works as is) or a named vector such as
c("A:12" = 0.3).
Fixed color schemes piling up in NGL.js: every render,
addSelection(), updateColor() or
updateRepresentation() with a selection color
(color = list(c("red", "1-10"), ...)) registered a new
color scheme that was never removed. Color schemes are now removed once
no representation uses them.
New Shiny input input$<outputId>_residues: a
data frame with one row per residue of every loaded structure (columns
structure, chain, resno,
inscode, resname, letter). Unlike
_sequence, _resno and _chainname,
which become one joined string per structure when several structures are
loaded, it has the same shape for one or several structures and keeps
chain names of more than one character. The older inputs are
unchanged.
New Shiny input
input$<outputId>_selectionStructure: the number of
the clicked structure. With several structures, a click previously gave
no way to tell which one was clicked, so click-to-zoom or highlight code
acted on the first (or every) structure.
The click inputs _selection, _selAround
and _selectionStructure are now sent as events, so every
click triggers observeEvent(), also a click that gives the
same values as the previous one (e.g. the same residue in another copy
of a structure, or the same atom twice).
addSelection() and updateZoomMove()
have a new argument structure that counts from 1, like
setSuperpose(reference = ). structureIndex
(counting from 0) still works but is deprecated and gives a warning;
this also applies to structureIndex given inside
param. The structure number is no longer passed on to
NGL.js as a representation parameter. A structure number larger than the
number of structures is reported in the browser console instead of being
applied to all (or the first) structure.
Fixed zoomMove() being overridden when several
structures are loaded: with the default duration = 0 the
camera ended on the center of all structures, and with
setSuperpose() it aimed at a structure’s position before
superposition. The camera now moves after all structures are loaded and
superposed; if zoomMove() is used for several structures,
the last one is used.
updateSelection() without name now
gives a clear error instead of “promise already under evaluation:
recursive default argument reference”.
Removed unused per-structure setRock,
setSpin, toggleRock and
toggleSpin fields that addStructure() added
(spin and rock apply to the whole viewer), and old commented-out
code.
Fixed snapShot() setting
input$<outputId>_rendering to FALSE
before the image was made, so a spinner tied to it stopped too early. It
now changes to FALSE after the PNG is handed to the
download, and a failed snapshot is reported in the browser
console.
Structure load failures are no longer silent. A new Shiny input
input$<outputId>_error reports which structure could
not be loaded and why (e.g. a PDB code that does not exist, a network
error, or a file that contains no atoms), and is NULL after
a successful load. After a failure the viewer is empty and the
_sequence, _resno, _chainname and
_PDB inputs are cleared, instead of keeping the values of
the previous structure. Previously one failing structure also stopped
all others without any message.
NGLVieweR() and addStructure() give
clear R errors instead of an empty viewer (or a JavaScript error that
could also stop other Shiny outputs) for input they cannot use: a file
path that does not exist (“file not found”), file contents or an
extensionless file without format, a malformed
format (e.g. NA or ""),
data that is empty or not text, or a URL (not supported;
download the file first).
File contents can now also be given as a vector of lines,
e.g. NGLVieweR(readLines("1crn.pdb"), format = "pdb"). Text
with line breaks is always treated as file contents.
Structure files compressed with gzip, bzip2 or xz
(e.g. 1crn.cif.gz) can now be loaded; the format is taken
from the extension before .gz.
Formats are passed to NGL.js in lower case, so files such as
1CRN.PDB load.
Binary formats such as MMTF were listed as supported but were corrupted when read; they are removed from the documentation and now give a clear error.
Fixed addStructure() reading its input differently
from NGLVieweR(): a short file name such as
"1crn.pdb" was treated as a PDB code, and a
format with a leading dot (".pdb") was not
accepted. Both functions now use the same rules.
Fixed NGLVieweR() and addStructure()
failing with “path too long” on R-devel when given file contents
(e.g. NGLVieweR(pdb_text, format = "pdb")): file contents
are no longer passed to tools::file_ext() and
file.exists().
Fixed event handlers piling up when
renderNGLVieweR() re-runs in Shiny: each re-render added
another click, rendering-status and window-resize handler, so one click
computed _selection/_selAround once per render
so far, using the selectionParameters() of older renders.
Handlers are now registered once and always use the latest
options.
The viewer now also resizes when its container changes size without a window resize, e.g. when a tab is shown or a sidebar collapses.
Fixed setSuperpose() moving the wrong structure. The
reference structure now keeps its coordinates and every other structure
is moved onto it, as documented. Previously the reference was moved onto
the other structures, so with three or more structures only the last one
ended up aligned. Note that the superposed scene is now in the
coordinate frame of the reference.
setSuperpose() now gives an error for an invalid
reference (not a whole number of 1 or more), and the viewer
logs a clear console error when reference is larger than
the number of structures.
Fixed updateFullscreen() ignoring its
fullscreen argument: it always toggled, so
updateFullscreen(FALSE) could enter fullscreen and
updateFullscreen(TRUE) could leave it. It now only changes
the state when it differs from the requested one.
updateFullscreen() has a new element
argument: "page" (default, the whole page as before) or
"viewer" (only the viewer).
The updateFullscreen example app now also runs
outside an interactive R session.
Fixed setSpin() and setRock() not
switching off when renderNGLVieweR() re-runs with
FALSE: an animation started by an earlier render kept
running. If both are TRUE, the structure spins (now
documented).
stageParameters() options set in an earlier render
but not in the current one now return to their NGL.js defaults on
re-render, instead of staying in effect (e.g. a background color). Stage
options that no render set (for example ones changed only with
updateStage()) are left as they are.
addStructure and setSuperpose
functions to load and overlap multiple structures in the same
stage.setScale, setRotation, and
setPosition functions for controlling scale, rotation, and
position of representations.Added API call that returns a list of atoms surrounding a selection.
Added selectionParameters function to control
proximity and level for selection.
Updated addSelection and
updateRepresentation to handle color arrays
addSelection and
updateRepresentation to handle color arraysNEWS.md file to track changes to the
package.