Server Mode Guide for bettr

Version 1.6.0 and later

Overview

Version 1.6.0 introduces server mode, a new way to deploy and use bettr that enables browser-based JSON file uploads, automatic caching, and programmatic data loading via URLs. This makes bettr suitable for:

  • Multi-user server deployments where different users need to visualize their own data
  • Web-based workflows without requiring R programming knowledge
  • Data sharing through portable JSON files and direct links

What’s New in Version 1.6.0

Server Mode for JSON Uploads

The bettr() function now supports a serverMode parameter that launches the app in a special mode where users upload JSON files through the browser.

Benefits:

  • No R programming required for end users
  • Multiple users can use the same server instance with their own data
  • Data is isolated per user session
  • Automatic browser caching for quick reload

JSON Serialization

New functions for converting bettr data to/from JSON format:

  • bettrToJSON() - Export SummarizedExperiment to JSON
  • bettrFromJSON() - Import JSON back to SummarizedExperiment

Benefits:

  • Portable data format (language-agnostic)
  • Easy data sharing between users and systems
  • Preserves all metadata, colors, weights, and transformations
  • Enables web-based workflows

Browser localStorage Caching

Automatic client-side caching of uploaded JSON data in server mode.

What gets cached:

  • Uploaded JSON data

Benefits:

  • Page refresh doesn’t lose your work
  • Survives browser restarts
  • No manual saving required
  • Automatic caching after upload

Cache Versioning

Administrators can force cache invalidation when deploying updates.

Use cases:

  • Deploy schema changes that require fresh data
  • Force all users to re-upload after breaking changes
  • Manage cache in multi-tenant environments
  • Troubleshooting cache-related issues

URL Parameters for Programmatic Loading

Load JSON data automatically via URL query parameters.

Benefits:

  • Create direct links to specific visualizations
  • Integrate with external tools and pipelines
  • Automate opening visualizations after benchmark runs
  • Share analysis results with a simple URL

Server Mode Basics

Starting a Server

library(bettr)

# Basic server mode
bettr(serverMode = TRUE)

# With cache versioning
bettr(serverMode = TRUE, cacheVersion = "v1.0")

# Custom theme
bettr(serverMode = TRUE, bstheme = "flatly")

What Happens When You Start Server Mode

  1. The app starts listening on a local port (e.g., http://127.0.0.1:4567)
  2. Users navigate to this URL in their browser
  3. The upload interface is displayed
  4. Users can:
    • Upload JSON files manually
    • Have data loaded automatically via URL parameters (if provided)
  5. Once data is uploaded, the full bettr interface appears
  6. All interactions are automatically cached in the browser

User Interface

Upload Mode Interface:

  • Clean, simple upload area
  • “Choose JSON File” button
  • Information about browser caching
  • No “Close app” button (for multi-user safety)

After Upload:

  • Full bettr visualization interface
  • All standard features available
  • “Load Data” panel for uploading new files
  • “Clear Cached Data” button

JSON Serialization

Creating JSON Files

From Data Frames

library(bettr)

# Create benchmark data
benchmark_data <- data.frame(
    Method = c("AlgorithmA", "AlgorithmB", "AlgorithmC"),
    Accuracy = c(0.95, 0.92, 0.89),
    Speed = c(120, 150, 100),
    Memory = c(256, 512, 128)
)

# Add metric metadata
metric_info <- data.frame(
    Metric = c("Accuracy", "Speed", "Memory"),
    Type = c("Quality", "Performance", "Resource"),
    Unit = c("Proportion", "ms", "MB")
)

# Define initial transformations
transforms <- list(
    Speed = list(flip = TRUE, transform = "[0,1]"),
    Memory = list(flip = TRUE, transform = "[0,1]")
)

# Create SummarizedExperiment
bettrSE <- assembleSE(
    df = benchmark_data,
    idCol = "Method",
    metricInfo = metric_info,
    initialTransforms = transforms
)

# Export to JSON
json_file <- tempfile(fileext = ".json")
bettrToJSON(bettrSE, file = json_file)
Click to view example JSON structure

The exported JSON file has the following structure:

{
  "idCol": "Method",
  "data": [
    {
      "Method": "AlgorithmA",
      "Accuracy": 0.95,
      "Speed": 120,
      "Memory": 256,
      "_row": "AlgorithmA"
    },
    {
      "Method": "AlgorithmB",
      "Accuracy": 0.92,
      "Speed": 150,
      "Memory": 512,
      "_row": "AlgorithmB"
    },
    {
      "Method": "AlgorithmC",
      "Accuracy": 0.89,
      "Speed": 100,
      "Memory": 128,
      "_row": "AlgorithmC"
    }
  ],
  "metricInfo": [
    {
      "Metric": "Accuracy",
      "Type": "Quality",
      "Unit": "Proportion"
    },
    {
      "Metric": "Speed",
      "Type": "Performance",
      "Unit": "ms"
    },
    {
      "Metric": "Memory",
      "Type": "Resource",
      "Unit": "MB"
    }
  ],
  "idInfo": {},
  "initialWeights": {},
  "initialTransforms": {
    "Speed": {
      "flip": true,
      "transform": "[0,1]"
    },
    "Memory": {
      "flip": true,
      "transform": "[0,1]"
    }
  }
}

Key components:

  • idCol: Name of the identifier column
  • data: Array of objects, one per method with all metric values
  • metricInfo: Metadata about each metric (optional classifications, units, etc.)
  • idInfo: Additional metadata about methods (optional)
  • initialWeights: Default metric weights (optional)
  • initialTransforms: Transformations to apply to metrics (flip for “lower is better”, transform for normalization)

From Existing SummarizedExperiment

# If you already have a SummarizedExperiment
json_file <- tempfile(fileext = ".json")
bettrToJSON(my_existing_SE, file = json_file)

# Get JSON as string (for programmatic use)
json_string <- bettrToJSON(my_existing_SE, file = NULL)

Reading JSON Files

# Read from file
bettrSE <- bettrFromJSON(file = "benchmark_results.json")

# Read from JSON string
bettrSE <- bettrFromJSON(json = json_string)

# Use in non-server mode
bettr(bettrSE = bettrSE)

URL Parameters for Programmatic Loading

Overview

URL query parameters allow you to automatically load JSON data when users open the app.

Two Loading Methods

Load from URL (jsonUrl)

http://localhost:4567/?jsonUrl=https://example.com/data.json

Use cases:

  • Data hosted on web servers
  • GitHub raw file URLs
  • Cloud storage (S3, Google Cloud Storage, etc.)
  • Internal company servers

Example:

# Start server
bettr(serverMode = TRUE)

# Construct URL
base_url <- "http://localhost:4567"
data_url <- "https://raw.githubusercontent.com/user/repo/main/results.json"
full_url <- paste0(base_url, "/?jsonUrl=", URLencode(data_url, reserved = TRUE))

# Open in browser
browseURL(full_url)

Load from File Path (jsonFile)

http://localhost:4567/?jsonFile=/absolute/path/to/data.json

Use cases:

  • Local server deployments
  • Internal network file shares
  • Automated pipelines on same machine
  • Development and testing

Example:

# Start server
bettr(serverMode = TRUE)

# Construct URL
base_url <- "http://localhost:4567"
file_path <- "/Users/username/benchmarks/latest_results.json"
full_url <- paste0(base_url, "/?jsonFile=", URLencode(file_path, reserved = TRUE))

# Open in browser
browseURL(full_url)

Using the included example data:

The bettr package includes a pre-exported JSON file from the DuoClustering2018 dataset that can be used for testing and examples.

# Start server
bettr(serverMode = TRUE)

# Get path to included example JSON file
json_path <- system.file("extdata", "duo2018_bettr.json", package = "bettr")

# Construct URL
base_url <- "http://localhost:4567"
full_url <- paste0(base_url, "/?jsonFile=", URLencode(json_path, reserved = TRUE))

# Open in browser
browseURL(full_url)

Browser Cache Management

How Caching Works

  1. Automatic Save:
    • When you upload a JSON file, it’s saved to browser localStorage
    • Happens immediately after successful upload
    • No manual action required
  2. Automatic Restore:
    • When you reload the page, cached data is automatically restored
    • A notification confirms the restoration
  3. Cache Storage:
    • Stored in browser’s localStorage (typically 5-10MB limit)
    • Specific to your browser and domain
    • Persists across browser restarts
    • Not shared across different browsers or devices

Manual Cache Control

Clear Cache Button

Located in the “Load Data” accordion panel:

Load Data
├── Choose JSON File
└── Clear Cached Data (button)

Click to:

  • Remove all cached data
  • Start fresh with a new dataset
  • Free up browser storage

Cache Versioning (Administrators)

Setting Up Versioning

# Deploy version 1.0
bettr(serverMode = TRUE, cacheVersion = "v1.0")

# Later, deploy version 1.1 with breaking changes
bettr(serverMode = TRUE, cacheVersion = "v1.1")

Version String Format

Any string works - choose what makes sense for your workflow:

# Semantic versioning
cacheVersion = "v1.2.3"

# Date-based
cacheVersion = "2025-10-07"

# Build numbers
cacheVersion = "build-456"

# Custom
cacheVersion = "production-release-oct2025"

User Experience

When version changes:

  1. User opens the app
  2. Browser detects version mismatch
  3. Cache is automatically cleared
  4. User sees: “Cache was cleared due to version update. Please upload your data.”
  5. User uploads their JSON file again
  6. New cache is created with current version

Session info

sessionInfo()
#> R version 4.5.2 (2025-10-31)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.3 LTS
#> 
#> Matrix products: default
#> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3 
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=C              
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats4    stats     graphics  grDevices utils     datasets  methods  
#> [8] base     
#> 
#> other attached packages:
#>  [1] dplyr_1.1.4                 tibble_3.3.0               
#>  [3] SummarizedExperiment_1.41.0 Biobase_2.71.0             
#>  [5] GenomicRanges_1.63.0        Seqinfo_1.1.0              
#>  [7] IRanges_2.45.0              S4Vectors_0.49.0           
#>  [9] BiocGenerics_0.57.0         generics_0.1.4             
#> [11] MatrixGenerics_1.23.0       matrixStats_1.5.0          
#> [13] bettr_1.7.1                 BiocStyle_2.39.0           
#> 
#> loaded via a namespace (and not attached):
#>  [1] gridExtra_2.3         rlang_1.1.6           magrittr_2.0.4       
#>  [4] clue_0.3-66           GetoptLong_1.0.5      otel_0.2.0           
#>  [7] compiler_4.5.2        png_0.1-8             vctrs_0.6.5          
#> [10] stringr_1.6.0         pkgconfig_2.0.3       shape_1.4.6.1        
#> [13] crayon_1.5.3          fastmap_1.2.0         backports_1.5.0      
#> [16] XVector_0.51.0        labeling_0.4.3        utf8_1.2.6           
#> [19] learnr_0.11.6         shinyjqui_0.4.1       promises_1.5.0       
#> [22] rmarkdown_2.30        purrr_1.2.0           xfun_0.54            
#> [25] cachem_1.1.0          jsonlite_2.0.0        later_1.4.4          
#> [28] DelayedArray_0.37.0   parallel_4.5.2        cluster_2.1.8.1      
#> [31] R6_2.6.1              bslib_0.9.0           stringi_1.8.7        
#> [34] RColorBrewer_1.1-3    rpart_4.1.24          jquerylib_0.1.4      
#> [37] Rcpp_1.1.0            assertthat_0.2.1      iterators_1.0.14     
#> [40] knitr_1.50            base64enc_0.1-3       httpuv_1.6.16        
#> [43] Matrix_1.7-4          nnet_7.3-20           tidyselect_1.2.1     
#> [46] rstudioapi_0.17.1     abind_1.4-8           yaml_2.3.10          
#> [49] doParallel_1.0.17     codetools_0.2-20      lattice_0.22-7       
#> [52] shiny_1.11.1          withr_3.0.2           S7_0.2.1             
#> [55] evaluate_1.0.5        foreign_0.8-90        circlize_0.4.16      
#> [58] pillar_1.11.1         BiocManager_1.30.27   checkmate_2.3.3      
#> [61] DT_0.34.0             foreach_1.5.2         rprojroot_2.1.1      
#> [64] ggplot2_4.0.1         scales_1.4.0          xtable_1.8-4         
#> [67] glue_1.8.0            Hmisc_5.2-4           maketools_1.3.2      
#> [70] tools_4.5.2           sys_3.4.3             data.table_1.17.8    
#> [73] buildtools_1.0.0      cowplot_1.2.0         grid_4.5.2           
#> [76] tidyr_1.3.1           sortable_0.5.0        colorspace_2.1-2     
#> [79] htmlTable_2.4.3       Formula_1.2-5         cli_3.6.5            
#> [82] S4Arrays_1.11.0       ComplexHeatmap_2.27.0 gtable_0.3.6         
#> [85] sass_0.4.10           digest_0.6.38         SparseArray_1.11.1   
#> [88] rjson_0.2.23          htmlwidgets_1.6.4     farver_2.1.2         
#> [91] htmltools_0.5.8.1     lifecycle_1.0.4       GlobalOptions_0.1.2  
#> [94] mime_0.13