Read and save takane objects in Javascript

Unit tests Build docs NPM Version

Overview

The jaspagate package provides methods for reading and saving takane-formatted objects in Javascript. This enables web applications to interoperate with R and Python workflows involving complex data structures like the SummarizedExperiment. For example, kana can use jaspagate to pull datasets managed by the scRNAseq R package; conversely, analysis results can be downloaded for further inspection in Python via the dolomite framework.

Getting started

First, we have to tell jaspagate how to read and write a HDF5 file. This requires application-specific implementations of the H5Group and H5DataSet interfaces. For example, we could use the h5wasm package (as shown in tests/h5.js) or the HDF5-reading utilities in scran.js. The exact implementation is left to the application developer to ensure that only one copy of the HDF5-parsing library (typically a WebAssembly binary) is bundled into the application.

We then define a globals object that specifies how to open a "file" in our Javascript-based application. This should implement the GlobalFsInterface and GlobalH5Interface interfaces. In a backend environment like Node.js, setting up this object is pretty easy as described in tests/globals.js. For the browser, the process of acquiring a file path is more involved as direct access to the filesystem is not typically allowed; instead, we need to either return the contents of the file as a Uint8Array or write to a virtual filesystem.

Phew. Once we've done all that, we can finally read our objects.

import * as jsp from "jaspagate";
let obj = await jsp.readObject(path, /* metadata = */ null, globals);
await jsp.saveObject(obj, "new/copy/of/object", globals);

Check out the reference documentation for more details.

Supported objects

Currently, we only support a small number of takane formats.

  • list objects are loaded as List instances.
  • data_frame objects are loaded as DataFrame instances, with the following caveats:
    • Annotations on the columns are not loaded.
  • summarized_experiment objects are loaded as SummarizedExperiment instances, with the following caveats:
    • To read or save assays, each application should define and register their own functions in readObjectRegistry and saveObjectRegistry. This ensures that large datasets are directly converted to application-specific representations for optimal efficiency.
  • ranged_summarized_experiment objects are loaded as RangedSummarizedExperiment instances, with the following caveats:
    • Everything mentioned for summarized_experiment.
    • Non-empty row ranges are not loaded or saved.
  • single_cell_experiment objects are loaded as SingleCellExperiment instances, with the following caveats:
    • Everything mentioned for ranged_summarized_experiment.

If you need something for your application, make an issue and we'll see what we can do.

Links

The takane specifications, which describe the file representation of each object.

The alabaster.base R package, to read and write takane-formatted objects in R.

The dolomite-base Python package, to read and write takane-formatted objects in Python.