Package {RBMRB}

Title:	Interface to the Biological Magnetic Resonance Data Bank ('BMRB')
Version:	3.0.0
Date:	2026-10-01
Description:	A comprehensive interface to the Biological Magnetic Resonance Data Bank ('BMRB') https://bmrb.io, mirroring all functionality of the 'PyBMRB' 'Python' package (v3.0). Provides four modules: (1) 'ChemicalShift' for fetching per-entry chemical shift data from the 'BMRB' 'REST' 'API' or local 'NMR-STAR' files; (2) 'ChemicalShiftStatistics' for database-wide statistical queries; (3) Spectra for simulating '1H-15N' 'HSQC', '1H-13C' 'HSQC', '1H-1H' 'TOCSY', and generic 2D 'NMR' spectra as interactive plots; and (4) Histogram for chemical shift distribution visualizations with optional filtering by pH, temperature, and ambiguity code. All interactive plots are rendered via 'plotly'. Uses the 'BMRB' REST API v2 https://api.bmrb.io/v2/.
License:	GPL-3
URL:	https://github.com/bmrb-io/RBMRB
BugReports:	https://github.com/bmrb-io/RBMRB/issues
Encoding:	UTF-8
Depends:	R (≥ 4.1.0)
Imports:	httr2 (≥ 1.0.0), jsonlite (≥ 1.8.0), plotly (≥ 4.10.0), cli (≥ 3.4.0)
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown, htmlwidgets, withr
Config/testthat/edition:	3
VignetteBuilder:	knitr
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-10-01 22:47:03 UTC; kumaranbaskaran
Author:	Kumaran Baskaran [aut, cre]
Maintainer:	Kumaran Baskaran <baskaran@uchc.edu>
Repository:	CRAN
Date/Publication:	2026-10-14 15:22:12 UTC

RBMRB: R Interface to the Biological Magnetic Resonance Data Bank ('BMRB')

Description

A comprehensive R interface to the Biological Magnetic Resonance Data Bank ('BMRB') https://bmrb.io, mirroring all functionality of the 'PyBMRB' 'Python' package (v3.0). Provides four modules: (1) 'ChemicalShift' for fetching per-entry chemical shift data from the 'BMRB' 'REST' 'API' or local 'NMR-STAR' files; (2) 'ChemicalShiftStatistics' for database-wide statistical queries; (3) Spectra for simulating '1H-15N' 'HSQC', '1H-13C' 'HSQC', '1H-1H' 'TOCSY', and generic 2D 'NMR' spectra as interactive plots; and (4) Histogram for chemical shift distribution visualizations with optional filtering by pH, temperature, and ambiguity code. All interactive plots are rendered via 'plotly'. Uses the 'BMRB' REST API v2 https://api.bmrb.io/v2/.

Author(s)

Maintainer: Kumaran Baskaran baskaran@uchc.edu (ORCID)

Authors:

• Kumaran Baskaran baskaran@uchc.edu (ORCID)

See Also

Useful links:

• https://github.com/bmrb-io/RBMRB

• Report bugs at https://github.com/bmrb-io/RBMRB/issues

Get the installed RBMRB version

Description

Returns the version of the installed RBMRB package as a string.

Usage

RBMRB_version()

Value

A character string with the package version.

Examples

RBMRB_version()

Get the citation for a BMRB entry

Description

Get the citation for a BMRB entry

Usage

bmrb_citation(bmrb_id, format = "bibtex")

Arguments

Value

A character string containing the citation.

Examples

## Not run: 
cat(bmrb_citation(15060, format = "text"))

## End(Not run)

Diagnose BMRB entry fetch problems

Description

Fetches a BMRB entry using both the zlib-compressed and plain JSON endpoints and reports what is found at each step. Run this when cs_from_bmrb returns no data.

Usage

bmrb_debug_entry(bmrb_id)

Arguments

Value

Invisibly, the parsed entry JSON list, or NULL on failure.

Examples

## Not run: 
bmrb_debug_entry(15060)

## End(Not run)

Fetch raw metadata for a BMRB entry

Description

Fetch raw metadata for a BMRB entry

Usage

bmrb_fetch_entry(bmrb_ids)

Arguments

Value

A named list of raw entry metadata (API JSON as R list).

Examples

## Not run: 
meta <- bmrb_fetch_entry(15060)
names(meta[["15060"]])

## End(Not run)

Get BMRB IDs associated with a PDB entry

Description

Get BMRB IDs associated with a PDB entry

Usage

bmrb_from_pdb(pdb_id)

Arguments

Value

A data.frame with columns bmrb_id, match_type, and comment.

Examples

## Not run: 
bmrb_from_pdb("2JM0")

## End(Not run)

List all BMRB entry IDs

Description

Returns all public entry IDs in the specified BMRB database.

Usage

bmrb_list_entries(database = "macromolecules")

Arguments

Value

A character vector of BMRB entry IDs.

Examples

## Not run: 
ids <- bmrb_list_entries()
length(ids)

## End(Not run)

Get PDB IDs associated with a BMRB entry

Description

Get PDB IDs associated with a BMRB entry

Usage

bmrb_pdb_ids(bmrb_id)

Arguments

Value

A data.frame with columns pdb_id, match_type, and comment.

Examples

## Not run: 
bmrb_pdb_ids(15000)

## End(Not run)

Search BMRB using the instant-search endpoint

Description

Searches BMRB by title, author name, organism, amino-acid sequence, InChI string, or other terms.

Usage

bmrb_search(term, database = "combined")

Arguments

Value

A data.frame with columns value, label, sub_date, authors, and link.

Examples

## Not run: 
bmrb_search("ubiquitin human")
bmrb_search("GB3", database = "macromolecules")

## End(Not run)

Get BMRB API server status

Description

Returns current server information including entry counts and database last-update timestamps from the BMRB REST API.

Usage

bmrb_status()

Value

A list with server status information.

Examples

## Not run: 
bmrb_status()

## End(Not run)

Run a connectivity self-test

Description

Performs three checks: BMRB API status, entry fetch and parse for entry 15060, and the chemical shift search endpoint. Useful for verifying that the BMRB API is reachable from your network. Progress is reported with message(), so it can be silenced with suppressMessages().

Usage

bmrb_test()

Value

A named logical vector with elements api_status, entry_fetch, and search_query (invisibly).

Examples

## Not run: 
bmrb_test()

## End(Not run)

Upload an NMR-STAR file to BMRB for temporary access

Description

Uploads a local NMR-STAR file to the BMRB server. The entry is stored for 7 days. The returned token can be used as a BMRB ID in all other package functions.

Usage

bmrb_upload_entry(file_path)

Arguments

Value

A character string token usable as a BMRB ID (invisibly).

Examples

## Not run: 
token <- bmrb_upload_entry("my_protein.str")
n15hsqc(bmrb_ids = token)

## End(Not run)

Simulate a ¹H-¹³C HSQC spectrum

Description

Equivalent to 'pybmrb.Spectra.c13hsqc()'. See [n15hsqc()] for parameter descriptions.

Usage

c13hsqc(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  legend = NULL,
  draw_trace = FALSE,
  peak_list = NULL,
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with the simulated peak list.

Examples

## Not run: 
c13hsqc(bmrb_ids = 15060, legend = "residue")

## End(Not run)

Plot a conditional chemical shift histogram

Description

Shows the CS distribution of 'atom' in 'residue' before and after filtering by known chemical shifts of other atoms in the same residue. Mirrors 'pybmrb.Histogram.conditional_hist()'.

Usage

conditional_cs_hist(
  residue,
  atom,
  filtering_rules,
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL,
  h_tolerance = 0.1,
  c_tolerance = 2,
  n_tolerance = 2,
  standard_amino_acids = TRUE,
  histnorm = NULL,
  plot_type = "histogram",
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with 'all_values', 'filtered_values', 'labels'.

Examples

## Not run: 
  conditional_cs_hist("SER", "N",
    filtering_rules = list(CA = 55.5, HA = 4.3))

## End(Not run)

Build a generic 2D peak list for any two atoms

Description

Equivalent to 'pybmrb.Spectra.create_2d_peaklist()'.

Usage

create_2d_peaklist(
  atom_x,
  atom_y,
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  draw_trace = FALSE,
  include_preceding = FALSE,
  include_next = FALSE
)

Arguments

Value

Same structure as [create_n15hsqc_peaklist()].

Build a 1H-13C HSQC peak list

Description

Equivalent to 'pybmrb.Spectra.create_c13hsqc_peaklist()'.

Usage

create_c13hsqc_peaklist(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  draw_trace = FALSE
)

Arguments

Value

Same structure as [create_n15hsqc_peaklist()].

Build a 1H-15N HSQC peak list

Description

Extracts backbone amide (and optionally sidechain NH) chemical shifts from BMRB entries / NMR-STAR files and returns the 2D peak coordinates. Equivalent to 'pybmrb.Spectra.create_n15hsqc_peaklist()'.

Usage

create_n15hsqc_peaklist(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  draw_trace = FALSE,
  include_sidechain = TRUE
)

Arguments

Value

A list with elements: 'x' (H ppm), 'y' (N ppm), 'dataset', 'residue', 'info', 'seq_id', 'cs_track' (if 'draw_trace = TRUE').

Build a 1H-1H TOCSY peak list

Description

Pairs all protons within each residue (full spin-system). Both diagonal and off-diagonal peaks are included. Equivalent to 'pybmrb.Spectra.create_tocsy_peaklist()'.

Usage

create_tocsy_peaklist(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  draw_trace = FALSE
)

Arguments

Value

Same structure as [create_n15hsqc_peaklist()].

Extract chemical shifts from BMRB database entries

Description

Fetches assigned chemical shift data for one or more BMRB entries. Uses the same zlib-compressed JSON endpoint as PyBMRB / pynmrstar. Mirrors 'pybmrb.ChemicalShift.from_bmrb()'.

Usage

cs_from_bmrb(bmrb_ids, auth_tag = FALSE)

Arguments

Value

A nested named list: 'list(dataset_id = list(chain = list(seq_id = list(atom = cs_value), seq_ids = integer_vector)))'.

Examples

## Not run: 
  cs <- cs_from_bmrb(15060)
  cs_peek(cs)
  cs_from_bmrb(c(17076, 17077))

## End(Not run)

Extract chemical shifts from local NMR-STAR files

Description

Mirrors 'pybmrb.ChemicalShift.from_file()'.

Usage

cs_from_file(file_paths, auth_tag = FALSE, data_set_ids = NULL)

Arguments

Value

Same nested-list structure as [cs_from_bmrb()].

Examples

## Not run: 
  cs <- cs_from_file("my_protein.str")

## End(Not run)

Plot a chemical shift distribution histogram

Description

Fetches database-wide chemical shift data and renders an interactive distribution plot. Mirrors 'pybmrb.Histogram.hist()'.

Usage

cs_hist(
  residue = NULL,
  atom = NULL,
  list_of_atoms = NULL,
  filtered = TRUE,
  sd_limit = 10,
  ambiguity = "*",
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL,
  standard_amino_acids = TRUE,
  histnorm = NULL,
  plot_type = "histogram",
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with elements 'values' and 'labels'.

Examples

## Not run: 
  cs_hist("ALA", "CA")
  cs_hist(list_of_atoms = c("ALA-CB","GLY-CA","SER-CB"))
  cs_hist("ALA", "CA", histnorm = "probability density",
          plot_type = "violin")

## End(Not run)

Plot a 2D chemical shift correlation map

Description

Mirrors 'pybmrb.Histogram.hist2d()'.

Usage

cs_hist2d(
  residue,
  atom1,
  atom2,
  filtered = TRUE,
  sd_limit = 10,
  ambiguity1 = "*",
  ambiguity2 = "*",
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL,
  histnorm = NULL,
  plot_type = "heatmap",
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with elements 'atom1' and 'atom2'.

Examples

## Not run: 
  cs_hist2d("CYS", "CB", "N")
  cs_hist2d("ALA", "CA", "CB", plot_type = "contour")

## End(Not run)

Peek at a nested CS structure

Description

Reports the first few residues of each chain with message(), so the output can be silenced with suppressMessages().

Usage

cs_peek(cs_data, n_res = 5L)

Arguments

Value

cs_data, invisibly.

Examples

## Not run:  cs <- cs_from_bmrb(15060); cs_peek(cs) 

Compute summary statistics for a set of chemical shifts

Description

Compute summary statistics for a set of chemical shifts

Usage

cs_stats(x)

Arguments

Value

A named numeric vector: n, mean, sd, median, min, max.

Examples

cs_stats(c(55.1, 55.3, 56.0, 54.8))

Summarise a nested chemical shift list

Description

Builds a tidy summary of datasets, chains, and atom coverage. The summary is returned rather than printed, so it prints automatically at the console and can also be assigned and reused.

Usage

cs_summary(cs_data)

Arguments

Value

A data.frame with one row per dataset and chain.

Examples

## Not run:  cs <- cs_from_bmrb(15060); cs_summary(cs) 

Get a flat data.frame of chemical shifts for one or more BMRB entries

Description

Get a flat data.frame of chemical shifts for one or more BMRB entries

Usage

cs_table(bmrb_ids, auth_tag = FALSE)

Arguments

Value

A data.frame suitable for use with ggplot2 or dplyr.

Examples

## Not run:  df <- cs_table(c(15060, 17076)) 

Convert a nested CS list to a tidy data.frame

Description

Convert a nested CS list to a tidy data.frame

Usage

cs_to_df(cs_data)

Arguments

Value

A data.frame with columns Dataset, Chain, Seq_ID, Atom_ID, Val.

Examples

## Not run:  cs <- cs_from_bmrb(15060); df <- cs_to_df(cs) 

Export a peak list to CSV or Sparky format

Description

Converts the output of any 'create_*_peaklist()' function to a file or a data.frame. Equivalent to 'pybmrb.Spectra.export_peak_list()'.

Usage

export_peak_list(
  peak_list,
  output_file_name = NULL,
  output_format = "csv",
  include_side_chain = TRUE
)

Arguments

Value

Invisibly, a data.frame with the exported peak list.

Examples

## Not run: 
pl <- create_n15hsqc_peaklist(bmrb_ids = 15060)
export_peak_list(pl, "peaks.csv", output_format = "csv")
export_peak_list(pl, "peaks.sparky", output_format = "sparky")

## End(Not run)

Remove outliers from a numeric vector

Description

Remove outliers from a numeric vector

Usage

filter_cs_outliers(x, sd_limit = 10)

Arguments

Value

Numeric vector with outliers removed.

Examples

filter_cs_outliers(c(52, 55, 56, 54, 300), sd_limit = 2)

Plot a generic 2D NMR correlation spectrum

Description

Generates a 2D spectrum for any two atom types. Supports sequence-walk tracing, preceding/next-residue peaks, and all the same overlay options as the other spectrum functions. Equivalent to 'pybmrb.Spectra.generic_2d()'.

Usage

generic_2d(
  atom_x,
  atom_y,
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  legend = NULL,
  draw_trace = FALSE,
  peak_list = NULL,
  include_preceding = FALSE,
  include_next = FALSE,
  seq_walk = FALSE,
  full_walk = FALSE,
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, the peak list.

Examples

## Not run: 
generic_2d("N", "CA", bmrb_ids = 15000, legend = "residue")
generic_2d("N", "CA", bmrb_ids = 15000, include_next = TRUE,
           seq_walk = TRUE)

## End(Not run)

Fetch paired 2D chemical shift data for two atoms in the same residue

Description

Mirrors 'pybmrb.ChemicalShiftStatistics.get_2d_chemical_shifts()'.

Usage

get_2d_cs_data(
  residue,
  atom1,
  atom2,
  filtered = TRUE,
  sd_limit = 10,
  ambiguity1 = "*",
  ambiguity2 = "*",
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL
)

Arguments

Value

Named list with 'atom1' and 'atom2' numeric vectors.

Examples

## Not run:  paired <- get_2d_cs_data("ALA", "CA", "CB") 

Fetch chemical shift data from the BMRB database

Description

Downloads chemical shifts for the given residue and atom combination from the BMRB database. Mirrors 'pybmrb.ChemicalShiftStatistics.get_data()'.

Usage

get_cs_data(
  residue = "*",
  atom = "*",
  filtered = TRUE,
  sd_limit = 10,
  ambiguity = "*",
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL,
  standard_amino_acids = TRUE,
  database = "macromolecules"
)

Arguments

Value

A data.frame with columns Val, Comp_ID, Atom_ID, Ambiguity_code, Entry_ID, Comp_index_ID, pH, Temperature_K and others.

Examples

## Not run: 
  df <- get_cs_data("ALA", "CA")
  df <- get_cs_data("*", "HB*")

## End(Not run)

Fetch raw BMRB chemical shift data (no outlier filtering)

Description

Mirrors 'pybmrb.ChemicalShiftStatistics.get_data_from_bmrb()'.

Usage

get_cs_from_bmrb_db(
  residue = "*",
  atom = "*",
  list_of_atoms = NULL,
  ambiguity = "*",
  ph_min = NULL,
  ph_max = NULL,
  t_min = NULL,
  t_max = NULL,
  standard_amino_acids = TRUE,
  database = "macromolecules"
)

Arguments

Value

A data.frame of raw chemical shift records.

Examples

## Not run: 
  df  <- get_cs_from_bmrb_db("ALA", "CB")
  df2 <- get_cs_from_bmrb_db(list_of_atoms = c("ALA-CB","GLY-CA"))

## End(Not run)

Simulate a ¹H-¹⁵N HSQC spectrum

Description

Plots an interactive 1H-15N HSQC spectrum for one or more BMRB entries and/or NMR-STAR files. Overlay multiple datasets as scatter plots; optionally draw trace lines connecting peaks from the same residue position across datasets. Equivalent to 'pybmrb.Spectra.n15hsqc()'.

Usage

n15hsqc(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  legend = NULL,
  draw_trace = FALSE,
  include_sidechain = TRUE,
  peak_list = NULL,
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with elements 'x' (H ppm), 'y' (N ppm), 'dataset', 'residue', 'info', and (when 'draw_trace = TRUE') 'cs_track'.

Examples

## Not run: 
# Single entry
n15hsqc(bmrb_ids = 15060, legend = "residue")

# Compare two entries with trace lines
n15hsqc(bmrb_ids = c(17076, 17077), legend = "dataset", draw_trace = TRUE)

# Overlay user's own NMR-STAR file with BMRB entry
n15hsqc(bmrb_ids = 15060, input_file_names = "MyData.str",
        legend = "dataset")

## End(Not run)

List the 20 standard amino acid codes

Description

List the 20 standard amino acid codes

Usage

standard_amino_acids()

Value

Character vector of 3-letter amino acid codes.

Examples

standard_amino_acids()

List standard nucleic acid residue codes

Description

List standard nucleic acid residue codes

Usage

standard_nucleic_acids()

Value

Character vector of RNA and DNA residue codes.

Examples

standard_nucleic_acids()

Simulate a ¹H-¹H TOCSY spectrum

Description

Equivalent to 'pybmrb.Spectra.tocsy()'. See [n15hsqc()] for shared parameter descriptions.

Usage

tocsy(
  bmrb_ids = NULL,
  input_file_names = NULL,
  auth_tag = FALSE,
  legend = NULL,
  draw_trace = FALSE,
  peak_list = NULL,
  output_format = "html",
  output_file = NULL,
  output_image_width = 800,
  output_image_height = 600,
  show_visualization = TRUE
)

Arguments

Value

Invisibly, a list with the simulated peak list.

Examples

## Not run: 
tocsy(bmrb_ids = 15060, legend = "residue")
tocsy(bmrb_ids = c(17074, 17076, 17077), legend = "dataset",
      draw_trace = TRUE)

## End(Not run)