Skip to contents

Export data to static files

Source: vignettes/export_files.Rmd
export_files.Rmd

After configuring a Vitessce widget, you may want to obtain the static files associated and deploy the same Vitessce configuration as a static website. This page demonstrates this process for an example dataset from SeuratData.

First, install the dependencies:

install.packages("devtools")
devtools::install_github("satijalab/seurat-data")
devtools::install_github("vitessce/vitessceAnalysisR")

Create the Vitessce configuration:

library(vitessceR)
library(vitessceAnalysisR)
library(SeuratData)

SeuratData::InstallData("pbmc3k")
data("pbmc3k.final")
force(pbmc3k.final)

adata_path <- file.path("data", "seurat", "pbmc3k.final.h5ad.zarr")

vitessceAnalysisR::seurat_to_anndata_zarr(pbmc3k.final, adata_path)

vc <- VitessceConfig$new(schema_version = "1.0.16", name = "My config")
dataset <- vc$add_dataset("My dataset")
dataset <- dataset$add_object(
  AnnDataWrapper$new(
    adata_path=adata_path,
    obs_embedding_paths = c("obsm/X_pca", "obsm/X_umap"),
    obs_embedding_names = c("PCA", "UMAP"),
    obs_set_paths = c("obs/seurat_annotations", "obs/seurat_clusters")
  )
)
scatterplot <- vc$add_view(dataset, Component$SCATTERPLOT, mapping = "PCA")
vc$layout(scatterplot)

Export files for serving locally

Run the export function on the VitessceConfig. Specify the directory in which to store the exported files with out_dir.

vc$export(out_dir = "./my_vitessce_files")

The directory ./my_vitessce_files should now contain three files:

  • cells.json
  • cell-sets.json
  • clusters.json

Serve the exported files

Now that the files have been saved to the ./my_vitessce_files directory, they can be served by any static web server.

If you would like to serve the files locally, we recommend http-server which can be installed with NPM or Homebrew:

http-server ./my_vitessce_files/ --cors -p 3000

View on vitessce.io

The returned view config dict can be converted to a URL, and if the files are served on the internet (rather than locally), this URL can be used to share the interactive visualizations with colleagues.

vc_list <- vc$to_list(base_url = "http://localhost:3000")
vitessce_url <- paste0("http://vitessce.io/?url=data:,", URLencode(jsonlite::toJSON(vc_list, auto_unbox = TRUE)))
print(vitessce_url)

Export files for serving from AWS S3

Rather than serving the data files locally, you may want to upload the files to a remote static file hosting service such as AWS S3, allowing the Vitessce URL to be shared with others. Visit our data hosting documentation page to learn more about configuring file hosting services for use with Vitessce. Install the AWS S3 command-line interface by following the instructions here.

Confirm that the CLI has been installed:

aws --version

Configure the AWS CLI by using any of the configuration methods, such as the environment variable method.

In the case of AWS S3, you know ahead of time that the data files will ultimately be served from your S3 bucket, so you can include the base_url and with_config = TRUE parameters when calling the export function. For instance, if you intend to upload the files to an AWS S3 bucket called my_bucket:

vc$export(with_config = TRUE, base_url = "https://my_bucket.s3.amazonaws.com", out_dir = "./my_vitessce_files")

The directory ./my_vitessce_files should now contain the three data files, plus the view config as a JSON file (config.json):

  • cells.json
  • cell-sets.json
  • clusters.json
  • config.json (the file URLs in this config will include the base_url for the bucket)

Upload exported files to S3

Upload all four files to your bucket:

aws s3 cp --recursive ./my_vitessce_files s3://my_bucket

In this case, rather than including the configuration as url-encoded JSON in the URL, you can simply point to the configuration JSON file in the bucket:

http://vitessce.io/?url=https://my_bucket.s3.amazonaws.com/config.json