Interactive Genome Browser for Misha Tracks • misha.browser

An interactive genome browser for misha genomic tracks. Built on ggplot2 and patchwork, with YAML-based configuration and a Shiny application for interactive exploration.

Features

YAML Configuration: Define your entire browser setup in a single YAML file
Virtual Tracks: Full support for misha virtual tracks with expressions, aggregation functions, and filters
Track Expressions: Arithmetic operations on tracks (e.g., "track1 / track2")
Multiple Panel Types: Data panels, gene annotations, intervals, and ideograms
Data Transforms: Smooth, log2, log10, zscore, clip, quantile normalization, and custom expressions
Horizontal/Vertical Lines: Add reference lines (fixed values or computed statistics) and region markers
Faceting & Grouping: Group tracks by metadata with regex pattern matching
Interactive Shiny App: Navigate, zoom, highlight, and explore your data
File Uploads: Upload intervals and PSSM files directly in the Shiny app
Caching: Efficient data extraction with automatic memory and disk caching

Installation

# Install from GitHub
remotes::install_github("tanaylab/misha.browser")

TL;DR Workflow

library(misha.browser)

# 1) Create a browser rooted at the mm10 misha database
browser <- browser_create(misha_root = "/net/mraid20/export/data4/db/tgdb/mm10/trackdb/") %>%
    browser_add_panel(
        name = "signal",
        tracks = c("jk.epipcg.pcg.CRJK_0364_k27me3_eb_j1_d4_a", "jk.epipcg.pcg.CRJK_0411_k4me3_wt_to_wt_eb_d3"),
        plot_type = "line",
        height = 3
    ) %>%
    browser_add_panel(
        name = "genes",
        type = "annotation"
    )

# 2) Save a YAML config for deployment
browser_save_config(browser$cfg, "config.yaml")

# 3a) Deploy to a local Shiny Server app directory
#     (creates the destination directory if needed)
browser_deploy_local(
    dest_dir = "/net/mraid20/export/tgdata/db/tgdb/tanaywiz/apps/my_user/app",
    config = "config.yaml",
    profile = "server",
    server_root = "/misha_dbs/mm10/trackdb/",  # Optional: override misha root on server
    overwrite = TRUE,
    touch_restart = TRUE
)

# 3b) Or run locally (Shiny)
browser_run(browser)

# 4) Plot a region from the CLI / script
browser_plot(browser, region = gintervals(1, 1e6, 2e6))

Quick Start

From YAML Configuration

library(misha.browser)

# Create browser from config file
browser <- browser_create(config = "my_browser.yaml")

# Plot current region
browser_plot(browser)

# Navigate to a gene
browser_plot(browser, gene = "Tbx5", span = 2e6)

# Launch interactive Shiny app
browser_run(browser)

Programmatic Setup

library(misha.browser)

# Create browser programmatically
browser <- browser_create(misha_root = "/path/to/misha") %>%
    browser_add_panel(
        name = "signal",
        tracks = c("chip.h3k27me3", "chip.h3k4me3"),
        plot_type = "line",
        colors = c(h3k27me3 = "blue", h3k4me3 = "red")
    ) %>%
    browser_add_transform("signal", type = "smooth", window = 10) %>%
    browser_add_transform("signal", type = "log2", offset = 1) %>%
    browser_set_region("chr5:118000000-121000000")

browser_plot(browser)

YAML Configuration

Basic Structure

# Profile settings (for different environments)
profiles:
  local:
    misha_root: /path/to/local/misha
  server:
    misha_root: /path/to/server/misha

# Starting position
start:
  gene: Tbx5
  span_bp: 2000000

# UI settings
ui:
  title: "My Genome Browser"
  smooth_window_default: 10

# Plot settings
plot:
  iterator: 32
  extraction_mode: fixed  # or "dynamic" or "dynamic_smooth"
  theme: bw

# Navigator for gene selection
navigator:
  source: intervs.global.tss
  label_field: geneSymbol

# Virtual track definitions
vtracks:
  - name: signal.k27
    src: chip.h3k27me3_track
    func: sum
    sshift: -140
    eshift: 140

# Panel definitions
panels:
  - name: signal
    type: data
    tracks: [signal.k27, signal.k4]
    transforms:
      - type: smooth
        window: 10
      - type: log2
        offset: 1
    plot_type: line
    height: 3

# Vertical lines
vlines:
  - name: regions
    source: file
    file: regions.csv
    color: grey50

Virtual Tracks

misha.browser supports the full misha virtual track system:

vtracks:
  # Standard vtrack with aggregation
  - name: signal_sum
    src: chip.track
    func: sum
    sshift: -100    # Extend aggregation window
    eshift: 100

  # Quantile aggregation
  - name: signal_median
    src: chip.track
    func: quantile
    params: 0.5

  # Vtrack with expression wrapper (e.g., pmax, log2)
  # With src + func present, expression wraps the created vtrack
  - name: norm.k27
    src: at.EB4_norm_300
    func: sum
    expression: "pmax(norm.k27, 0)"  # Clamp to >= 0

  # Sequence-based vtrack (no src needed)
  - name: gc_content
    func: kmer.frac
    params:
      kmer: "GC"

  # PWM motif scoring
  - name: motif_score
    func: pwm.max
    params:
      pssm: motif.csv
      bidirect: true

  # Pure track expression (no misha vtrack created)
  - name: normalized
    expression: "track1 - background"

  # Vtrack with filter
  - name: unmasked
    src: chip.track
    func: avg
    filter: masked_regions

The expression field defaults to the vtrack name but can be any valid misha expression.

The behavior is inferred:

If src/func are present, expression wraps the created vtrack during extraction.
If no src or func are given, expression defines a pure expression vtrack.

For example, this is correct:

browser <- browser_create(misha_root = .misha$GROOT) %>%
  browser_add_vtrack(
    "chipseq_q",
    src = "chipseq.ctcf.LCL.hsa81.3",
    func = "global.percentile.max",
    expression = "-log2(1 - chipseq_q)"
  ) %>%
  browser_add_panel(
    name = "chipseq",
    tracks = "chipseq_q",
    plot_type = "line",
    height = 2
  )

This creates chipseq_q with global.percentile.max and then extracts -log2(1 - chipseq_q).

Panel Types

Data Panels

panels:
  - name: chip_signal
    type: data
    tracks:
      - track1
      - track2
      # Inline expression
      - expr: "track1 / track2"
        name: ratio
    grouping:
      color_by: source
      pattern: "^(?<source>.+)\\.(?<mark>.+)$"
    facet_by: mark
    transforms:
      - type: smooth
        window: 10
      - type: log2
        offset: 1
    plot_type: line      # line, area, point, histogram
    colors:
      source1: "#E41A1C"
      source2: "#377EB8"
    ylim: [0, 10]
    height: 3
    show_legend: true

Annotation Panels

panels:
  - name: genes
    type: annotation
    exon_source: intervs.global.exon
    tss_source: intervs.global.tss
    gene_label_field: geneSymbol
    color: navy
    show_strand_arrows: true
    height: 1

Intervals Panels

Display genomic intervals from misha interval sets or files:

panels:
  - name: repeats
    type: intervals
    intervals: intervs.global.rmsk
    color_by: class
    filter_field: class
    filter_values: [LINE, LTR]
    colors:
      LINE: "#E41A1C"
      LTR: "#377EB8"
    outline_color: grey20
    label_field: name
    show_labels: true
    height: 1.5

For directional intervals (e.g. CTCF motifs), use arrows to show orientation:

panels:
  - name: ctcf_motifs
    type: intervals
    intervals: intervs.ctcf_motifs
    show_direction: true
    height: 1

Parameter	Description
`intervals`	Misha intervals name (e.g., `intervs.global.rmsk`)
`source`	Alternative: `file` to load from a file
`file`	Path to BED/TSV file (when `source: file`)
`color_by`	Column to map to fill color
`colors`	Named color mapping
`outline_color`	Border color for rectangles
`filter_field`	Column to filter on
`filter_values`	Values to include (list)
`filter_regex`	Regex pattern to match
`label_field`	Column for text labels
`show_labels`	Whether to display labels
`show_direction`	Draw intervals as arrows by strand (e.g. CTCF motifs)
`direction_field`	Column name for strand (default: `strand`)

Ideogram Panels

panels:
  - name: ideogram
    type: ideogram
    cytoband_track: intervs.cytoband
    highlight_current: true
    height: 0.3

Horizontal Lines (hlines)

Add reference lines to data panels:

panels:
  - name: signal
    type: data
    tracks: [chip.k27me3]
    hlines:
      # Fixed y-value
      - y: 6
        color: black
        linetype: solid
        linewidth: 0.5
        label: "Threshold"
      # Computed from data statistics
      - stat: mean
        color: blue
        linetype: dashed
        label: "Mean"
      - stat: median
        color: green
        linetype: dotted
      - stat: quantile
        q: 0.95
        color: red
        label: "95th percentile"

Parameter	Description
`y`	Fixed y-position for the line
`stat`	Compute from data: `mean`, `median`, or `quantile`
`q`	Quantile value (when `stat: quantile`)
`color`	Line color
`linetype`	Line type: `solid`, `dashed`, `dotted`, etc.
`linewidth`	Line width
`label`	Optional text label (placed at right edge)

Data Transforms

Available transform types:

Transform	Parameters	Description
`smooth`	`window`, `align`	Rolling mean smoothing
`log2`	`offset`	Log2 transformation with offset
`log10`	`offset`	Log10 transformation with offset
`sqrt`	-	Square root transformation
`zscore`	-	Z-score normalization
`minmax`	-	Min-max scaling to 0..1
`clip`	`min`, `max`	Clip values to range
`quantile`	`probs`	Quantile normalization
`expr`	`expr`	Custom R expression

Example:

transforms:
  - type: smooth
    window: 10
    align: center
  - type: log2
    offset: 1
  - type: clip
    min: 0
    max: 10
  - type: expr
    expr: "pmax(x, 0)"  # Custom expression (x = values)

Vertical Lines

vlines:
  # From file (CSV/TSV with chrom, start, end columns)
  - name: peaks
    source: file
    file: peaks.csv
    color: red
    linetype: solid

  # From misha intervals
  - name: genes
    source: misha
    intervals: intervs.global.tss
    color: blue

  # Inline coordinates
  - name: markers
    source: inline
    intervals:
      - chrom: chr1
        start: 1000000
        end: 1000000
      - "chr1:2000000-2000000"  # String format also works
    color: green

  # Current region (useful for highlighting)
  - name: highlight
    source: current
    color: yellow
    alpha: 0.3

Extraction Modes

Control how data is extracted from misha:

plot:
  extraction_mode: fixed  # Options: fixed, dynamic, dynamic_smooth
  iterator: 32            # Base iterator (bin size in bp)
  target_points: 4000     # Target points for dynamic modes
  smoothing_bp: 3200      # Smoothing window for dynamic_smooth mode

Mode	Description
`fixed`	Fixed iterator + rollmean smoothing. Best for vtracks with `func=sum`.
`dynamic`	Adjusts iterator based on view span. More efficient for large regions.
`dynamic_smooth`	Dynamic iterator + dynamic vtrack sshift/eshift. Combines resolution with proper value scaling.

API Reference

Browser Creation

browser_create(config = NULL, misha_root = NULL, title = "Genome Browser", profile = NULL)
browser_load(file)
browser_save(browser, file)
browser_deploy_local(dest_dir,
    config = NULL, config_name = "config.yaml", profile = "server",
    server_root = NULL, overwrite = FALSE, write_env = TRUE,
    extra_files = NULL, touch_restart = TRUE
)

Panel Management

browser_add_panel(browser, name, type = "data", tracks = NULL, ...)
browser_add_transform(browser, panel_name, type, ...)
browser_set_tracks(browser, panel_name, tracks)
browser_set_ylim(browser, panel_name, ylim)

browser_set_region(browser, region)
browser_get_region(browser)
browser_zoom_in(browser, factor = 2)
browser_zoom_out(browser, factor = 2)
browser_move_left(browser, fraction = 0.5)
browser_move_right(browser, fraction = 0.5)

Visualization

browser_plot(browser, region = NULL, gene = NULL, span = NULL)
browser_set_highlight(browser, start, end)
browser_clear_highlight(browser)

Vertical Lines

browser_add_vlines(browser, name, source, file = NULL, intervals = NULL, ...)

Interactive App

browser_run(browser, port = 8911, host = "0.0.0.0", launch.browser = TRUE)
browser_launch(config, port = 8911, host = "0.0.0.0", profile = NULL)

Local Deployment Helper

browser_deploy_local(
  dest_dir = "/srv/shiny-server/misha-browser",
  config = "inst/examples/silicus.yaml",
  profile = "server",
  server_root = "/misha_dbs/mm10",  # Optional: override misha root on server
  overwrite = TRUE,
  extra_files = c("data/mm10_cgdom.csv", "data/ctcf_hits_1bp.tsv")
)

Configuration

browser_load_config(file, profile = NULL)
browser_save_config(cfg, file)
browser_create_config(misha_root = NULL, title = "Genome Browser")
browser_clear_cache()

Migration

# Convert misha.vis configuration to misha.browser format
browser_convert_vis_config(vis_config_file, output_file, misha_root = NULL)

Examples

Multi-track Comparison with Faceting

panels:
  - name: histone_marks
    type: data
    tracks:
      - wt.h3k27me3
      - wt.h3k4me3
      - ko.h3k27me3
      - ko.h3k4me3
    grouping:
      color_by: condition
      pattern: "^(?<condition>\\w+)\\.(?<mark>.+)$"
    facet_by: mark
    transforms:
      - type: smooth
        window: 20
      - type: log2
        offset: 1
    colors:
      wt: black
      ko: red
    height: 4

Computed Tracks

vtracks:
  - name: ratio
    expr: "chip.signal / input.signal"
  - name: log_fc
    expr: "log2((treatment + 1) / (control + 1))"

panels:
  - name: enrichment
    type: data
    tracks: [ratio, log_fc]
    plot_type: line

Custom Color Scheme

colors:
  h3k27me3: "#1f77b4"
  h3k4me3: "#ff7f0e"
  h3k27ac: "#2ca02c"
  input: "#7f7f7f"
  _default: grey50  # Fallback color

Colors are matched by name. If a value ends with .k4 or .k27, the base name without the suffix is also checked (for example, silicus.k27 falls back to silicus).

Shiny App Features

The interactive Shiny application provides:

Navigation: Pan left/right, zoom in/out, history back/forward
Gene Search: Quick navigation to genes via dropdown or search
Coordinate Input: Direct coordinate entry (e.g., “chr5:100000-200000”)
Brush Selection: Zoom or highlight by brushing on the plot
Smooth Window Control: Adjust smoothing in real-time
Span Control: Quick span presets
Vertical Line Toggles: Enable/disable vertical line layers
Cache Management: Clear cache when needed
Configuration Editor: Edit vtracks and panels in real-time
File Uploads: Upload intervals and PSSM files for use in vtracks

Uploading Files

The Shiny app allows uploading intervals and PSSM files through the configuration editor:

Intervals Files

Upload BED or TSV files containing genomic intervals for use in vtracks with distance or coverage functions:

BED format: Tab-separated, no header (columns: chrom, start, end, …)
TSV format: Tab/comma-separated with header (requires chrom, start, end columns)

Uploaded intervals appear in dropdowns prefixed with @uploaded: and can be used as: - Filter sources for vtracks - Source for intervals-based vtrack functions (distance, coverage, neighbor.count)

PSSM Files

Upload Position-Specific Scoring Matrices for PWM-based vtracks:

TSV format: Tab/comma-separated with A, C, G, T columns
MEME format: Standard MEME motif format
JASPAR format: JASPAR matrix format

The app also integrates with the prego package for access to pre-built motif databases.

Uploaded PSSMs can be used with vtrack functions: pwm, pwm.max, pwm.max.pos, pwm.count

Requirements

R >= 4.0
misha
ggplot2 >= 3.4.0
patchwork
shiny, shinyWidgets, shinyjs, shinycssloaders
dplyr, tidyr, zoo, yaml

License

MIT

misha.browser

Features

Installation

TL;DR Workflow

Quick Start

From YAML Configuration

Programmatic Setup

YAML Configuration

Basic Structure

Virtual Tracks

Panel Types

Data Panels

Annotation Panels

Intervals Panels

Ideogram Panels

Horizontal Lines (hlines)

Data Transforms

Vertical Lines

Extraction Modes

API Reference

Browser Creation

Panel Management

Navigation

Visualization

Vertical Lines

Interactive App

Local Deployment Helper

Configuration

Migration

Examples

Multi-track Comparison with Faceting

Computed Tracks

Custom Color Scheme

Shiny App Features

Uploading Files

Intervals Files

PSSM Files

Requirements

License