Getting Started¶

GenomeSpy Core visualizations are defined by JSON specifications that describe the data and how it should be displayed. You can try a specification in the Playground or embed one in a web page. GenomeSpy for Python can build the same specifications from Python chart definitions. If you are analyzing an existing GenomeSpy App, see Analyzing Sample Collections.

Try a JSON specification in the Playground¶

The Playground lets you edit a JSON specification and preview the visualization in your browser. You can load data from a publicly accessible web server or from your computer. The Playground does not support saving or sharing visualizations, so keep a copy of your specification if you want to reuse it.

Embed a JSON specification in a web page¶

To use a JSON specification outside the Playground, embed GenomeSpy Core in an HTML page:

1. Create an HTML document using one of the templates below.
2. Place the specification and any local data files alongside the HTML document.
3. Serve the files from a local or remote web server and open the page in a browser.

When writing JSON, turn on editor suggestions and error checking. They catch common mistakes as you type and show the available properties and their documentation.

HTML templates¶

The templates below load GenomeSpy Core from a content delivery network. They use a specific package version so later releases do not change the library loaded by your page.

The embed function initializes a visualization into the HTML element given as the first parameter using the specification given as the second parameter. The function returns a promise that resolves into an object that provides the current public API. For details, see the JavaScript API.

Load the spec from a file¶

This template loads the spec from a separate spec.json file placed in the same directory.

<!DOCTYPE html>
<html>
  <head>
    <title>GenomeSpy</title>
  </head>
  <body>
    <script type="module">
      import { embed } from "https://cdn.jsdelivr.net/npm/@genome-spy/core@1.0.0/dist/bundle/index.es.js";

      const api = await embed(document.body, "spec.json", {});
    </script>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <title>GenomeSpy</title>
  </head>
  <body>
    <script
      type="text/javascript"
      src="https://cdn.jsdelivr.net/npm/@genome-spy/core@1.0.0"
    ></script>

    <script>
      genomeSpyEmbed.embed(document.body, "spec.json", {}).then((api) => {
        // Call API methods here.
      });
    </script>
  </body>
</html>

Embed the spec in the HTML document¶

You can alternatively provide the specification as a JavaScript object.

<!DOCTYPE html>
<html>
  <head>
    <title>GenomeSpy</title>
  </head>
  <body>
    <script type="module">
      import { embed } from "https://cdn.jsdelivr.net/npm/@genome-spy/core@1.0.0/dist/bundle/index.es.js";

      const spec = {
        data: {
          sequence: { start: 0, stop: 6.284, step: 0.39269908169, as: "x" },
        },
        transform: [{ type: "formula", expr: "sin(datum.x)", as: "sin" }],
        mark: "point",
        encoding: {
          x: { field: "x", type: "quantitative" },
          y: { field: "sin", type: "quantitative" },
        },
      };

      const api = await embed(document.body, spec, {});
    </script>
  </body>
</html>

Local web server¶

You can use any HTTP server for local development. For example, Python's standard library provides one:

python3 -m http.server --bind 127.0.0.1

Run the command from the directory containing your files. It does not require the GenomeSpy for Python package. See Python's documentation for details.

genomespy.app website examples¶

The examples on the genomespy.app home page are stored in the website-examples GitHub repository. You can clone the repository and launch the examples locally for further experimentation.

Python¶

GenomeSpy for Python is an alternative way to author Core visualizations. It builds validated JSON specifications from Python chart definitions and displays the resulting visualizations in notebooks or web pages. See its getting-started guide to install the package and create your first chart.

Analyze a configured GenomeSpy App¶

If you have access to a configured GenomeSpy App, you can analyze its sample collection without writing a specification. Start with Analyzing Sample Collections.

Observable notebooks¶

You can embed GenomeSpy into an Observable notebook. See the GenomeSpy collection for usage examples.

Using GenomeSpy as a visualization library in web applications¶

The @genome-spy/core npm package provides browser-ready bundles for use on web pages, as shown in the examples above. It also provides ESM sources for use with bundlers such as Vite and Webpack. For examples of this kind of integration, see:

• The embed-examples package contains examples of embedding GenomeSpy in web applications and using the API.
• SegmentModel Spy is an example of a complete web application that uses GenomeSpy for visualization.
• MutGlyph is an R package that embeds GenomeSpy in an htmlwidget and provides interactive counterparts to established maftools plots. See the MutGlyph documentation for examples.