SpectraViewer2D

SpectraViewer2D renders 2D NMR spectra (e.g. 1H-13C HSQC) as contour plots, with the summed 1D projections drawn along the top and left edges. Positive contours are blue and negative contours red. Initialize it with a container selector and an options object; the spectrum is drawn as soon as the viewer is constructed. It supports area zoom, a contour-level scroll control, a download menu and an assignment table with cross-peak markers and a 3D structure viewer.

Note: SpectraViewer2D uses flat, snake_case option names (e.g. axis_x_title), unlike the nested options of SpectraViewer1D.

Usage:

Pass the x (direct dimension), y (indirect dimension) and z (intensity) arrays from the DataParser ( dataType: "2D-NMR").

import { DataParser, SpectraViewer2D } from 'jsv2';
let dataParser = new DataParser("#file-selector", {
  dataType: "2D-NMR",
  expectedDataTag: "spectrumDataArray2dIntensities",
});
dataParser.addEventListener("fileParsed", (event) => {
  let viewer = new SpectraViewer2D("#graph-container", {
    width: 800,
    height: 800,
    dataset: { dataArray: { x: event.detail.x, y: event.detail.y, z: event.detail.z } },
    assignmentTable: event.detail.assignmentData ? {
      containerID: "#assignments",
      data: [event.detail.assignmentData],
      structure: {},
    } : undefined,
  });
});

Options:

id

A unique identifier for this viewer instance.

string | default: generated ("jsv-1", "jsv-2", ...)

title

Optional title rendered as a heading above the plot.

string | default: undefined

width / height

Size of the viewer canvas in pixels. A square viewer suits most 2D spectra.

number | default: 800 / 400

dataset

dataset.dataArray

The spectrum data. z is a flat, row-major grid: the intensity at x[col], y[row] is z[row * x.length + col], so its length must be x.length × y.length.

object | required

Axes

axis_x_title / axis_y_title

Axis labels. The y label is only drawn if it fits in axis_y_gutter.

string | default: "ppm"

axis_x_show / axis_y_show

Show or hide each axis.

boolean | default: true

axis_x_reverse

Reverse the x-axis so values decrease from left to right (the NMR convention). The y-axis always increases downward.

boolean | default: true

axis_x_grid / axis_y_grid

Draw grid lines.

boolean | default: false

x_tick_count / tick_count

Approximate number of ticks on the x-axis / y-axis.

number | default: 10

axis_x_tick_format / axis_y_tick_format

d3-format string for the tick labels.

string | default: "~g"

tick_length

Tick length in pixels.

number | default: 10

axis_x_gutter / axis_y_gutter

Space reserved for each axis in pixels.

number | default: 150 / 14% of the width

axis_y_lock

True locks the y-axis minimum to its lowest boundary while zooming; a number locks it that fraction of the visible y range below 0.

boolean or number | default: false

Zoom and contours

zoom_max

Maximum zoom level of the axes, and the highest contour threshold reachable with the scroll wheel.

number | default: 25

zoom_min

Lowest contour threshold reachable with the scroll wheel.

number | default: 0.25

assignmentTable

Shows a cross-peak assignment table, marks each cross peak on the plot and (with structure) a 3D structure. Requires event.detail.assignmentData from a 2D nmrML file with an <atomAssignment> block. See the Assignment Table page for the columns and interactions.

assignmentTable.containerID

CSS selector of the element that will contain the table.

string | required

assignmentTable.data

[event.detail.assignmentData] from the DataParser.

array | required

assignmentTable.structure

Include this key (e.g. structure: {}) to show the 3D structure in the element with id="mol-3d".

object | default: undefined

assignmentTable.show_hydrogen / show_atom_numbers

3D structure display options.

boolean | default: false

Controls

Methods

draw()

Redraws the viewer. Called automatically when the viewer is constructed.

viewer.draw();

move_to(domains, duration)

Animates the view to the given x and y ranges, each given as [min, max].

viewer.move_to([[3.0, 4.5], [45, 70]], 500);

zoom_out_completely()

Animates back to the full spectrum.

viewer.zoom_out_completely();

assignment_table.select_row(row, zoom)

Selects a cross peak (an element of viewer.assignment_table.rows), highlighting it in the table, on the plot and in the structure; zooms to it when zoom is true.

viewer.assignment_table.select_row(viewer.assignment_table.rows[0], true);

Generating 2D nmrML

The library can write 2D spectra as nmrML files that this viewer reads. The 2D nmrML Generator page uses these functions.

predict_hsqc(proton, carbon, options)

Predicts a 1H-13C HSQC spectrum from an assigned 1D 1H spectrum and an assigned 1D 13C spectrum of the same compound (the event.detail objects from DataParser's fileParsed event). Each assigned carbon with bonded hydrogens gives one cross peak at the shifts of those hydrogens and that carbon; quaternary carbons give none. Both files must contain the same structure with the same atom numbering. options can set points_1h (default 1024), points_13c (512), and the Gaussian peak widths width_1h (0.02 ppm) and width_13c (0.5 ppm).

const hsqc = jsv2.predict_hsqc(protonDetail, carbonDetail);

build_2d_nmrml(spectrum)

Returns nmrML text for { x, y, z, id, name, experiment, assignment }: the F2 and F1 axes in ppm and the row-major intensity grid (one row per y value), with optional structure and cross-peak assignments. The result of predict_hsqc can be passed in directly.

const nmrml = jsv2.build_2d_nmrml(hsqc);

Raw 2D data (FIDs) is processed on the website's server with nmrglue before the nmrML file is written. Accepted datasets: a zipped Bruker experiment folder (processed pdata/N/2rr is used when present, otherwise the raw ser file is Fourier transformed), a zipped Agilent/Varian experiment folder, an NMRPipe spectrum (.ft2) or a Sparky spectrum (.ucsf).

Notes