Package 'JBrowseR'

Describe a genome assembly from a FASTA URL

Description

Builds an assembly config for a custom genome using the flat ⁠{ name, uri }⁠ shorthand: JBrowse itself picks the concrete adapter type (IndexedFastaAdapter/BgzipFastaAdapter/TwoBitAdapter) from the extension, derives the .fai/.gzi index locations, and fills in the reference sequence track when the config loads, so only the FASTA URL is required and no adapter-type table lives in R.

Usage

assembly(fasta, name = NULL, aliases = NULL, refname_aliases = NULL)

Arguments

fasta	URL to the sequence: a .fa/.fasta (optionally bgzipped) or a ⁠.2bit⁠. The adapter type is inferred from the extension by JBrowse.
name	Assembly name. Defaults to the FASTA file's base name.
aliases	Reference-name aliases for the assembly (e.g. "GRCh37").
refname_aliases	URL to a reference-name alias table mapping e.g. 1 to chr1.

Details

For common human/model genomes you do not need this at all — pass a hub name straight to JBrowseR() (e.g. JBrowseR("hg38")) and the assembly, reference name aliases, cytobands, and gene-name search all come preconfigured.

Value

an assembly config list for JBrowseR()

Examples

assembly(
  "https://jbrowse.org/genomes/hg19/fasta/hg19.fa.gz",
  aliases = "GRCh37"
)

---

Describe a dotplot view comparing two assemblies

Description

Describe a dotplot view comparing two assemblies

Usage

dotplot_view(assemblies, tracks = NULL, ...)

Arguments

assemblies	Assembly names (or panel lists).
tracks	Synteny track ids.
...	Extra fields merged onto the view's init blob.

Value

a view spec list

---

Embed a JBrowse 2 linear genome view

Description

Renders an interactive, GPU-accelerated JBrowse 2 linear genome view as an htmlwidget for use in R Markdown documents, Shiny apps, or the interactive R console.

Usage

JBrowseR(
  assembly = NULL,
  tracks = NULL,
  location = NULL,
  default_session = NULL,
  text_search = NULL,
  theme = NULL,
  plugins = NULL,
  config = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

assembly	A hub name understood by jbrowse.org (e.g. "hg38", "hg19", or a GenArk accession like "GCF_000001405.40"), a sequence-file URL the view builds an assembly from (".../hg38.fa.gz", ⁠.2bit⁠), or an assembly config list from assembly() (needed only for aliases or a non-sibling index).
tracks	A list of track entries: a bare data-file URL, a spec from track() / track_data_frame(), or a full track config. Entries missing assemblyNames are backfilled with the assembly's name by the view.
location	A region string ("chr1:1-1000") or, when the assembly hub provides a gene-name search index, a gene name ("BRCA1").
default_session	An optional serialized session (advanced); when given it owns the initial track layout instead of tracks.
text_search	One or more aggregate text-search adapters from text_index(), enabling gene-name search.
theme	A theme config from theme().
plugins	A list of JBrowse plugin specs (name + url) to load at runtime.
config	Escape hatch: a whole JBrowse config forming the payload base that explicit arguments override — a list, or the path, URL, or JSON text of a config.json.
width, height, elementId	Standard htmlwidget sizing arguments.

Details

The API is declarative: describe the browser with plain values and the helper constructors (assembly(), track(), tracks(), text_index(), theme()). Nothing is imperative and no JSON strings are assembled by hand.

Value

an htmlwidget of the JBrowse 2 linear genome view

Examples

# a whole human genome browser in one line (gene search included)
JBrowseR("hg38", location = "BRCA1")

---

Shiny bindings for JBrowseR

Description

Output and render functions for using JBrowseR within Shiny applications and interactive Rmd documents.

Usage

JBrowseROutput(outputId, width = "100%", height = "400px")

renderJBrowseR(expr, env = parent.frame(), quoted = FALSE)

Arguments

outputId	output variable to read from
width	Must be a valid CSS unit or a number, which will be coerced to a string and have 'px' appended.
height	Must be a valid CSS unit or a number, which will be coerced to a string and have 'px' appended.
expr	An expression that generates a JBrowseR
env	The environment in which to evaluate expr.
quoted	Is expr a quoted expression (with quote())? This is useful if you want to save an expression in a variable.

Details

Clicking a feature sets input[[paste0(outputId, "_selected_feature")]], which is namespaced per output and so is safe with several browsers on a page or inside a Shiny module. It also sets the global input$selectedFeature for backwards compatibility; prefer the per-output id in new apps.

Value

the Shiny UI bindings for a JBrowseR htmlwidget

the Shiny server bindings for a JBrowseR htmlwidget

---

Embed the full JBrowse 2 app (multiple views of any type)

Description

Where JBrowseR() shows a single linear genome view, JBrowseRApp() drives the whole app engine, so views can mix a linear view, a synteny view, a dotplot, and more. Each views entry is a list(type = ..., init = ...) spec — the same vocabulary JBrowse Web serializes into its ⁠?session=spec-…⁠ URLs — built most easily with linear_view(), synteny_view(), and dotplot_view().

Usage

JBrowseRApp(
  assemblies = NULL,
  tracks = NULL,
  views = NULL,
  plugins = NULL,
  theme = NULL,
  config = NULL,
  width = NULL,
  height = NULL,
  elementId = NULL
)

Arguments

assemblies	A list of assembly configs (each from assembly(), or a plain config list). A synteny/dotplot view needs two or more.
tracks	A list of full track config lists. Because a synteny track spans two assemblies there is no single-assembly shorthand; synteny_track() builds the common PAF case.
views	A list of view specs, e.g. from synteny_view() / linear_view().
plugins	A list of JBrowse plugin specs (name + url) to load at runtime.
theme	A theme config from theme().
config	Escape hatch: a whole JBrowse config forming the payload base that explicit arguments override — a list, or the path, URL, or JSON text of a config.json.
width, height, elementId	Standard htmlwidget sizing arguments.

Value

an htmlwidget of the JBrowse 2 app

Examples

## Not run: 
JBrowseRApp(
  assemblies = list(assembly(hg38_fa), assembly(mm39_fa)),
  tracks = list(synteny_track(paf_url, "hg38", "mm39")),
  views = list(synteny_view(c("hg38", "mm39"), tracks = "hg38-mm39"))
)

## End(Not run)

---

Describe a linear genome view for JBrowseRApp(views = ...)

Description

Describe a linear genome view for JBrowseRApp(views = ...)

Usage

linear_view(assembly, loc = NULL, tracks = NULL, ...)

Arguments

assembly	Assembly name.
loc	A region string ("chr1:1-1000") or a gene name.
tracks	Track ids to show (referencing JBrowseRApp's tracks).
...	Extra fields merged onto the view's init blob (e.g. colorByCDS = TRUE).

Value

a view spec list

---

Build a synteny (PAF) track config spanning two assemblies

Description

Build a synteny (PAF) track config spanning two assemblies

Usage

synteny_track(
  uri,
  target_assembly,
  query_assembly,
  name = NULL,
  track_id = NULL,
  ...
)

Arguments

uri	URL to a .paf file.
target_assembly, query_assembly	The two assembly names (PAF target is the first assembly of a synteny_view()).
name	Track display name. Defaults to the file's base name.
track_id	Track id. Defaults to a slug of name.
...	Extra config merged onto the track.

Value

a track config list

---

Describe a linear synteny view comparing two (or more) assemblies

Description

Describe a linear synteny view comparing two (or more) assemblies

Usage

synteny_view(assemblies, tracks = NULL, cigar_mode = NULL, ...)

Arguments

assemblies	Assembly names (or list(assembly=, loc=) panels to focus each side on a region).
tracks	Synteny track ids tying the assemblies together.
cigar_mode	"full", "matches", or "off".
...	Extra fields merged onto the view's init blob.

Value

a view spec list

---

Describe a gene-name text-search index

Description

Builds an aggregate Trix text-search adapter so users can search the browser by gene name. Pass the result as text_search to JBrowseR().

Usage

text_index(ix, ixx, meta, assembly)

Arguments

ix	URL to the .ix file.
ixx	URL to the .ixx file.
meta	URL to the meta.json file.
assembly	Name of the assembly the index applies to.

Details

Hub assemblies (e.g. JBrowseR("hg38")) already include gene search, so this is only needed for custom assemblies with your own Trix index.

Value

an aggregate text-search adapter list

Examples

text_index(
  "https://jbrowse.org/genomes/hg19/trix/hg19.ix",
  "https://jbrowse.org/genomes/hg19/trix/hg19.ixx",
  "https://jbrowse.org/genomes/hg19/trix/meta.json",
  "hg19"
)

---

Build a custom color theme

Description

Creates a theme config with up to four palette colors. Pass the result as theme to JBrowseR(). See https://jbrowse.org/jb2/docs/config_guide#configuring-the-theme.

Usage

theme(primary, secondary = NULL, tertiary = NULL, quaternary = NULL)

Arguments

primary	the primary palette color (hex)
secondary	the secondary palette color (hex)
tertiary	the tertiary palette color (hex)
quaternary	the quaternary palette color (hex)

Value

a theme config list

Examples

theme("#311b92", "#0097a7")

---

Describe a data track by its URL

Description

Builds a loose track spec — list(uri = url) plus whatever you pass — that the view expands into a full track config when it loads, inferring the track type and adapter from the file extension with JBrowse's own format plugins (the same inference the "Add track" flow uses). No extension table lives in R, so every format a bundled plugin recognizes works: .bam/.cram (alignments), .vcf (variants), .gff/.gff3/.gtf/.bed (features), .bb/.bigBed (features), .bw/.bigWig (quantitative), .hic (Hi-C), and more. A bgzipped file (.gff.gz, …) resolves to its indexed tabix adapter, a plain one to the whole-file adapter. JBrowse derives index locations (.bai/.crai/.tbi) and, for CRAM, the reference from the assembly, so only the data URL is required.

Usage

track(
  url,
  name = NULL,
  track_id = NULL,
  assembly_names = NULL,
  index = NULL,
  ...
)

Arguments

url	URL to the track data.
name	Track display name. Left NULL, the view derives it from the file's base name.
track_id	A unique id for the track. Left NULL, the view derives one.
assembly_names	Assembly name(s) the track belongs to. Usually left NULL — JBrowseR() backfills it from the loaded assembly.
index	URL of the index file when it isn't the conventional sibling of url (.bai/.crai/.tbi). A .csi index is detected by extension.
...	Extra config merged onto the track, overriding the inferred defaults (e.g. category = list("Genes"), or a type = "AlignmentsTrack" override).

Value

a loose track spec list

Examples

track("https://jbrowse.org/genomes/hg19/gencode.v19.sorted.gff.gz", name = "Genes")

---

Build a track from an R data frame

Description

Turns a data frame of features into an in-browser track (a FromConfigAdapter), no files or web server required. This is the natural way to view results you computed in R — peaks, windows, hits — directly on the genome.

Usage

track_data_frame(data, name, assembly_name = NULL, ...)

Arguments

data	A data frame with columns chrom, start, end, name. An optional score column makes it a quantitative track; every other column rides along as a feature attribute, shown in the feature details.
name	Track display name.
assembly_name	Assembly the track belongs to. Usually left NULL — JBrowseR() backfills it from the loaded assembly.
...	Extra config merged into the track.

Value

a track config list

Examples

df <- data.frame(
  chrom = c("1", "2"),
  start = c(123, 456),
  end = c(789, 101112),
  name = c("feature1", "feature2")
)
track_data_frame(df, "my_features")

---

Collect tracks into a list for JBrowseR

Description

A thin readability wrapper around list() that gathers track() configs into the list JBrowseR() expects.

Usage

tracks(...)

Arguments

...	track configs, e.g. from track()

Value

a list of track configs

Examples

tracks(
  track("https://example.com/genes.gff.gz", name = "Genes"),
  track("https://example.com/reads.bam", name = "Reads")
)

---

Describe a view for JBrowseRApp(views = ...)

Description

The general form behind linear_view(), synteny_view(), and dotplot_view(): builds the list(type = ..., init = ...) spec any view type understands, where init is the declarative session-spec init for that type. Use it for view types those helpers don't cover, including any a runtime plugins entry registers — its init fields are the plugin's own, so nothing here has to keep up with them:

Usage

view(type, ...)

Arguments

type	The view type (e.g. "LinearGenomeView", "LinearSyntenyView", "ProteinView").
...	Fields of the view's init blob; NULL fields are dropped.

Details

view("ProteinView",
     url = "https://alphafold.ebi.ac.uk/files/AF-P04637-F1-model_v6.cif",
     height = 600)

Value

a view spec list

---