Package 'igvShiny'

Description

Pack junction attributes into a bed name column

Usage

.packJunctionAttributes(tbl)

Arguments

Value

A character vector, one packed name field per row.

Description

Sanitize and merge track configuration options

Usage

.sanitizeAndMergeOptions(baseOptions, userOptions)

Arguments

Value

A merged and sanitized list of options ready to be sent to JavaScript.

Description

Check a chromosome color map before it reaches igv.js

Usage

.sanitizeChromosomeColorMap(map)

Arguments

Value

the map as a named list, empty if nothing was supplied

Description

Sanitize one startup track specification

Usage

.sanitizeTrack(track, depth)

Arguments

Value

The sanitized track, or NULL if it cannot be used.

Description

Sanitize a list of startup track specifications

Usage

.sanitizeTracks(tracks, depth = 1L)

Arguments

Value

A sanitized list of track configurations; invalid entries or keys are dropped with a warning.

Description

Compares contig naming conventions (e.g. UCSC chr1 vs Ensembl 1), contig lengths (e.g. hg19 vs hg38), and coordinate boundaries between a track (BAM, CRAM, VCF, BED, or Bioconductor object) and the active reference genome.

Usage

checkReferenceCompatibility(
  target,
  genomeName = NULL,
  genomeSpec = NULL,
  session = NULL,
  id = NULL
)

Arguments

Value

A list with:

• checked: logical indicating whether both inputs could be inspected

• compatible: logical indicating if no critical mismatches were found, or NA when the inputs could not be checked

• mismatches: character vector of descriptive warning messages

• details: list of specific detected anomalies (naming, length, out-of-bounds)

• targetAssembly: detected assembly of track, if recognized

• referenceAssembly: reference genome name

Examples

bamFile <- system.file(package = "igvShiny", "extdata", "tumor.bam")
# tumor.bam is GRCh38: compatible with hg38, incompatible with hg19
res1 <- checkReferenceCompatibility(bamFile, genomeName = "hg38")
res1$compatible  # TRUE

res2 <- checkReferenceCompatibility(bamFile, genomeName = "hg19")
res2$compatible  # FALSE

Description

display the already constructed and configured track

Usage

## S4 method for signature 'GWASTrack'
display(obj, session, id, deleteTracksOfSameName = TRUE)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

a helper function for basic genomes, obtains the genome codes (e.g. 'hg38')

Usage

get_basic_genomes()

Value

an list of short genome codes, e.g., "hg38", "dm6"

Examples

bs <- get_basic_genomes()

Description

a helper function for common always available stock genomes, obtains the genome codes (e.g. 'hg38')

Usage

get_cas_genomes()

Value

an list of short genome codes, e.g., "hg38", "dm6"

Examples

cas <- get_cas_genomes()

Description

a helper function for mostly internal use, obtains the genome codes (e.g. 'hg38') supported by igv.js

Usage

get_css_genomes(test = FALSE)

Arguments

Value

an list of short genome codes, e.g., "hg38", "dm6", "tair10"

Examples

css <- get_css_genomes(test = TRUE)

Description

get_tracks_dir Get the directory where tracks are stored. The directory can be defined with environmental variable. If not defined the default is a directory called "tracks" in the temp directory. We need a local directory to write files - for instance, a vcf file representing a genomic region of interest. We then tell shiny about that directory, so that shiny's built-in http server can serve up files we write there, ultimately consumed by igv.js

Usage

get_tracks_dir(env_var = "TRACKS_DIR")

Arguments

Value

string with the path to the tracks directory.

Examples

gtd <- get_tracks_dir(env_var = "TRACKS_DIR")

Description

the url of the gwas table

Usage

## S4 method for signature 'GWASTrack'
getUrl(obj)

Arguments

Value

character

Examples

file <-
  # a local gwas file
  system.file(package = "igvShiny", "extdata", "gwas-5k.tsv.gz")
tbl.gwas <- read.table(file,
                       sep = "\t",
                       header = TRUE,
                       quote = "")
track <-
  GWASTrack(
    "gwas 5k",
    tbl.gwas,
    chrom.col = 12,
    pos.col = 13,
    pval.col = 28
  )
getUrl(track)

Description

GWASTrack creates an IGV manhattan track from GWAS data

Usage

GWASTrack(
  trackName,
  data,
  chrom.col,
  pos.col,
  pval.col,
  chromosomeColorMap = list(),
  trackHeight = 50,
  autoscale = TRUE,
  minY = 0,
  maxY = 30
)

Arguments

Value

A GWASTrack object

Examples

file <-
  # a local gwas file
  system.file(package = "igvShiny", "extdata", "gwas-5k.tsv.gz")
tbl.gwas <- read.table(file,
                       sep = "\t",
                       header = TRUE,
                       quote = "")
dim(tbl.gwas)
track <-
  GWASTrack(
    "gwas 5k",
    tbl.gwas,
    chrom.col = 12,
    pos.col = 13,
    pval.col = 28
  )
getUrl(track)

# a remote gwas file: the constructor checks that the url resolves, so this
# block reaches the network and stays out of R CMD check

url <- "https://gladki.pl/igvShiny/gwas_sample.tsv.gz"
track <- GWASTrack(
  "remote url gwas",
  url,
  chrom.col = 3,
  pos.col = 4,
  pval.col = 10,
  autoscale = FALSE,
  minY = 0,
  maxY = 300,
  trackHeight = 100
)
getUrl(track)


# colors picked per chromosome, with "*" covering the rest
track <- GWASTrack(
  "gwas 5k, custom colors",
  tbl.gwas,
  chrom.col = 12,
  pos.col = 13,
  pval.col = 28,
  chromosomeColorMap = list("1" = "red", "2" = "blue", "*" = "gray")
)

Description

This function is called in the server function of your shiny app

Usage

igvShiny(
  genomeOptions,
  width = NULL,
  height = NULL,
  elementId = NULL,
  displayMode = "squished",
  tracks = list()
)

Arguments

Value

the created widget

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

This function is called in the ui function of your shiny app

Usage

igvShinyOutput(outputId, width = "100%", height = NULL)

Arguments

Value

the created widget's html

Examples

io <- igvShinyOutput("igvOut")

Description

load GenomicAlignments data as an igv.js alignment track

Usage

loadBamTrackFromLocalData(
  session,
  id,
  trackName,
  data,
  deleteTracksOfSameName = TRUE,
  displayMode = "EXPANDED",
  trackConfig = list(),
  validateReference = TRUE,
  trackHeight = NULL
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

Streams a local BAM file and its index directly from disk using HTTP 206 Partial Content requests handled by the Shiny session. This allows viewing multi-gigabyte BAM files without loading them into R memory.

Usage

loadBamTrackFromLocalFile(
  session,
  id,
  trackName,
  bamFile,
  indexFile = paste0(bamFile, ".bai"),
  deleteTracksOfSameName = TRUE,
  displayMode = "EXPANDED",
  trackConfig = list(),
  validateReference = TRUE,
  trackHeight = NULL
)

Arguments

Value

None, sends a message to the browser

Examples

## Not run: 
# Inside a Shiny server function:
bamFile <- system.file(package = "igvShiny", "extdata",
                       "A_2_A24_02_01_01.nanopore.minimap.sorted.bam")
baiFile <- paste0(bamFile, ".bai")
loadBamTrackFromLocalFile(session, "igvShiny_0", "Nanopore Reads",
                         bamFile, baiFile, displayMode = "SQUISHED",
                         trackHeight = 100)

## End(Not run)

Description

load a remote bam track

Usage

loadBamTrackFromURL(
  session,
  id,
  trackName,
  bamURL,
  indexURL,
  deleteTracksOfSameName = TRUE,
  displayMode = "EXPANDED",
  showAllBases = FALSE,
  trackConfig = list(),
  trackHeight = NULL
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a genome annotation track provided as a data.frame

Usage

loadBedGraphTrack(
  session,
  id,
  trackName,
  tbl,
  color = "gray",
  trackHeight = 30,
  autoscale,
  autoscaleGroup = -1,
  min = NA_real_,
  max = NA_real_,
  deleteTracksOfSameName = TRUE,
  quiet = TRUE,
  trackConfig = list(),
  validateReference = TRUE
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a bedgraph track provided as a data.frame

Usage

loadBedGraphTrackFromURL(
  session,
  id,
  trackName,
  url,
  color = "gray",
  trackHeight = 30,
  autoscale = TRUE,
  min = 0,
  max = 1,
  autoscaleGroup = -1,
  deleteTracksOfSameName = TRUE,
  quiet = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a bed track provided as a data.frame

Usage

loadBedTrack(
  session,
  id,
  trackName,
  tbl,
  color = "",
  trackHeight = 50,
  deleteTracksOfSameName = TRUE,
  quiet = TRUE,
  trackConfig = list(),
  validateReference = TRUE
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a local cram track. Unlike loadBamTrackFromLocalData this loader takes file paths, not an R object: no bioconductor package parses cram, so the file and its index are handed to igv.js untouched, through the directory shiny serves as "tracks".

Usage

loadCramTrackFromLocalData(
  session,
  id,
  trackName,
  cramFile,
  indexFile = paste0(cramFile, ".crai"),
  deleteTracksOfSameName = TRUE,
  trackConfig = list(),
  validateReference = TRUE,
  trackHeight = NULL
)

loadCramTrackFromLocalFile(
  session,
  id,
  trackName,
  cramFile,
  indexFile = paste0(cramFile, ".crai"),
  deleteTracksOfSameName = TRUE,
  trackConfig = list(),
  validateReference = TRUE,
  trackHeight = NULL
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a remote cram track

Usage

loadCramTrackFromURL(
  session,
  id,
  trackName,
  cramURL,
  indexURL,
  deleteTracksOfSameName = TRUE,
  trackConfig = list(),
  trackHeight = NULL
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a local GFF3 track file

Usage

loadGFF3TrackFromLocalData(
  session,
  id,
  trackName,
  tbl.gff3,
  color = "gray",
  colorTable,
  colorByAttribute,
  displayMode,
  trackHeight = 50,
  visibilityWindow,
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "demos", "local-data.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a remote GFF3 track

Usage

loadGFF3TrackFromURL(
  session,
  id,
  trackName,
  gff3URL,
  indexURL,
  color = "gray",
  colorTable,
  colorByAttribute,
  displayMode,
  trackHeight = 50,
  visibilityWindow,
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "demos", "local-data.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a GWAS (genome-wide association study) track provided as a data.frame

Usage

loadGwasTrack(
  session,
  id,
  trackName,
  tbl.gwas,
  ymin = 0,
  ymax = 35,
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a SEG track provided as a data.frame. igv "displays segmented data as a blue-to-red heatmap where the data range is -1.5 to 1.5... The segmented data file format is the output of the Circular Binary Segmentation algorithm (Olshen et al., 2004)".

Usage

loadSegTrack(
  session,
  id,
  trackName,
  tbl,
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load splice junctions held in R. The table is written as the six-column bed igv.js draws junctions from, and served from the same directory as the other local-data tracks.

Coordinates are taken as bed coordinates and written out unchanged, as the other *FromLocalData loaders take theirs. STAR reports the first and last intron base of a junction 1-based in SJ.out.tab, so a table read straight from that file needs its start shifted by one first; a bed already converted from it, which is what STAR wrappers and the igv.js test fixtures ship, is passed in as is.

Columns chrom (or chr), start and end are required. score and strand are used when present. The per-junction attributes motif, uniquely_mapped, multi_mapped, maximum_spliced_alignment_overhang and annotated_junction are packed into the bed name column, which is where the track reads its filters and labels from; supply the ones you want to filter or label on. A name column, if you have already packed it yourself, is written through untouched.

Without uniquely_mapped or an explicit score the arcs all draw at the same thickness: igv.js has nothing to size them by.

Usage

loadSpliceJunctionTrackFromLocalData(
  session,
  id,
  trackName,
  tbl,
  trackHeight = 100,
  displayMode = "COLLAPSED",
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load splice junctions from a BED file reachable by URL, as written by STAR (SJ.out.tab converted to BED). Six columns, with the per-junction attributes packed into the name column as key=value pairs separated by semicolons: motif, uniquely_mapped, multi_mapped, maximum_spliced_alignment_overhang and annotated_junction. The track reads its filters and labels from those attributes.

igv.js draws junctions from a file of that shape only - it derives none of them from a bam file, and it has no sashimi plot. Show this track above a coverage track (bigWig, bedGraph) for the same sample to get the arcs-over-coverage view sashimi plots are wanted for.

Usage

loadSpliceJunctionTrackFromURL(
  session,
  id,
  trackName,
  url,
  indexURL = "",
  trackHeight = 100,
  displayMode = "COLLAPSED",
  deleteTracksOfSameName = TRUE,
  trackConfig = list()
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

load a VCF (variant) track provided as a Bioconductor VariantAnnotation object

Usage

loadVcfTrack(
  session,
  id,
  trackName,
  vcfData,
  deleteTracksOfSameName = TRUE,
  trackConfig = list(),
  validateReference = TRUE
)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "demos", "local-data.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

a helper function for internal use by the igvShiny constructor, but possible also of use to those building an igvShiny app, to test their genome specification for validity

Usage

parseAndValidateGenomeSpec(
  genomeName,
  initialLocus = "all",
  stockGenome = TRUE,
  dataMode = NA,
  fasta = NA,
  fastaIndex = NA,
  genomeAnnotation = NA
)

Arguments

Value

an options list directly usable by igvApp.js, and thus igv.js

See Also

[get_css_genomes()] for stock genomes we support.

Examples

genomeSpec <-
  parseAndValidateGenomeSpec("hg38", "APOE")  # the simplest case
# a custom genome, read from the files shipped with the package: every
# resource is checked for existence, and "http" would check it over the
# network on each R CMD check
base.dir <-
  system.file(package = "igvShiny", "extdata", "sarsGenome")
fasta.file <-
  file.path(base.dir, "Sars_cov_2.ASM985889v3.dna.toplevel.fa")
fastaIndex.file <- paste0(fasta.file, ".fai")
annotation.file <-
  file.path(base.dir, "Sars_cov_2.ASM985889v3.101.gff3")
custom.genome.title <- "SARS-CoV-2"
genomeOptions <-
  parseAndValidateGenomeSpec(
    genomeName = custom.genome.title,
    initialLocus = "all",
    stockGenome = FALSE,
    dataMode = "localFiles",
    fasta = fasta.file,
    fastaIndex = fastaIndex.file,
    genomeAnnotation = annotation.file
  )

Description

delete tracks on the browser

Usage

removeTracksByName(session, id, trackNames)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

remove only those tracks explicitly added by your app. stock tracks (i.e., #' Refseq Genes) remain

Usage

removeUserAddedTracks(session, id)

Arguments

Value

nothing

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

This function is called in the server function of your shiny app

Usage

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

Arguments

Value

an output or render function that enables the use of the widget within Shiny applications

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

Description

Registers a local file with the active Shiny session so that igv.js can stream chunks of the file using HTTP 206 Partial Content requests. This allows random-access binary formats (such as BAM, BAI, CRAM, CRAI, BigWig, and Tabix-indexed files) of arbitrary size to be viewed in igvShiny without loading them into R memory or copying them to temporary directories.

Usage

serveLocalFile(session, filePath)

Arguments

Details

The returned URL is relative to the Shiny application root and is routed through the same HTTP port as the Shiny session, ensuring compatibility with Posit Connect, shinyapps.io, reverse proxies, and local development.

Value

A character string containing the relative URL to access the file from the browser (e.g. "session/<token>/dataobj/<filename>?...")

Examples

## Not run: 
# Inside a Shiny server function:
server <- function(input, output, session) {
  bam_url <- serveLocalFile(session, "data/sample.bam")
  bai_url <- serveLocalFile(session, "data/sample.bam.bai")

  tracks <- list(
    list(
      name = "Sample BAM",
      type = "alignment",
      format = "bam",
      url = bam_url,
      indexURL = bai_url
    )
  )
  output$igv <- renderIgvShiny({
    igvShiny(genomeOptions, tracks = tracks)
  })
}

## End(Not run)

Description

Display a short summary of a GWASTrack object

Usage

## S4 method for signature 'GWASTrack'
show(object)

Arguments

Value

nothing; called for the side effect of printing a summary

Examples

file <-
  system.file(package = "igvShiny", "extdata", "gwas-5k.tsv.gz")
tbl.gwas <- read.table(file, sep = "\t", header = TRUE, quote = "")
track <-
  GWASTrack("gwas 5k", tbl.gwas, chrom.col = 12, pos.col = 13, pval.col = 28)
track

Description

zoom in or out to show the nominated region, by chromosome locus or gene symbol

return the current region displayed by your igv instance

Usage

showGenomicRegion(session, id, region)

getGenomicRegion(session, id)

Arguments

Value

a character string of format "chrom:start-end"

Examples

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}

library(igvShiny)
demo_app_file <-
  system.file(package = "igvShiny", "showcase", "igvShinyDemo.R")
if (interactive()) {
  shiny::runApp(demo_app_file)
}