Getting started

Import the library

uchimata is hosted on NPM, and can be installed with typical dependency management tools (npm, yarn, pnpm) just like any other Javascript library.

For use in Observable notebooks, we can import using:

import * as uchi from "https://esm.sh/uchimata@0.3.1";

Load data

We designed the library to accept genome structures stored as Apache Arrow tables. There are two options: loadFromURL and load

const urlStevens = "https://pub-5c3f8ce35c924114a178c6e929fc3ac7.r2.dev/Stevens-2017_GSM2219497_Cell_1_model_5.arrow";

const model = await uchi.loadFromURL(urlStevens, {
  center: true,
  normalize: true,
});

The load functions also accept an options object where we can specify whether the coordinates should be normalized and centered.

display(model)

Define the visual encodings

At its core, 3D genome structure data only specifies discrete positions in space, and it is up to us how will these points be represented. This is what a viewConfig object does.

const viewConfig = ({
  scale: 0.005,
  color: "lightgreen",
  links: true,
});

Render the data

To display the data, we bind the loaded model with a view config and place both in a ’scene’.

//~ create a scene
let chromatinScene = uchi.initScene();
chromatinScene = uchi.addStructureToScene(chromatinScene, model, viewConfig);

const [renderer, canvas] = uchi.display(chromatinScene, { alwaysRedraw: false});

//~ ObservableHQ mechanism for clean-up after cell re-render
invalidation.then(() => renderer.endDrawing());

display(renderer.getCanvasElement());