vitessce: A JavaScript repository from hkmoon

Visual Integration Tool for Exploration of Spatial Single-Cell Experiments

Screenshot of Vitessce with Linnarsson data

Why Vitessce

Interactive

Vitessce consists of reusable interactive views including a scatterplot, spatial+imaging plot, genome browser tracks, statistical plots, and control views, built on web technologies such as WebGL.

Integrative

Vitessce enables visual analysis of multi-modal assay types which probe biological systems through techniques such as microscopy, genomics, and transcriptomics.

Serverless

Visualize large datasets stored in static cloud object stores such as AWS S3. No need to manage or pay for expensive compute infrastructure for visualization purposes.

Usage

Vitessce can be used in React projects by installing the package from NPM:

npm install vitessce

For more details, please visit the documentation.

Development

First install PNPM v7. We develop and test against NodeJS v18.6.0 and NPM 8.13.2.

Note NodeJS may require the max_old_space_size value to be increased.

. ./set-node-options.sh

Checkout the project, cd, and then:

pnpm install
pnpm run build # for @vitessce/icons and @vitessce/workers
pnpm run start-demo

The development server will refresh the browser as you edit the code.

Monorepo organization

Meta-updater script

pnpm run meta-dryrun
pnpm run meta-update

Testing

For the end-to-end tests, they depend on

pnpm run build-demo

To run all the tests, both unit and e2e: ./test.sh
To run just the unit tests: pnpm run test

Deployment

Before running any of the deployment scripts, confirm that you have installed the AWS CLI and are in the appropriate AWS account:

$ aws iam list-account-aliases --query 'AccountAliases[0]'
"gehlenborglab"

Staging

To build the current branch and push the "minimal" demo and docs sites to S3, run this script:

./push-demos.sh

This will build the demo and docs, push both to S3, and finally open the docs deployment in your browser.

Release

To make a release of the dev site, docs site, and NPM package:

./create-release.sh patch

This script does the following:

Checks out a new branch for the release
Runs npm version (major | minor | patch) (depending on the first argument passed to the script)
Pushes staging demos via ./push-demos.sh
Updates the CHANGELOG.md
Makes a pull request using the GitHub CLI gh pr create

Publish staged development site

After doing a manual test of the deployment of the dev site, if it looks good, copy it to dev.vitessce.io:

./copy-dev.sh https://{url returned by create-release.sh or push-demos.sh}

Note: if you need to obtain this URL later:

Copy dev to https://s3.amazonaws.com/vitessce-data/demos/$DATE/$HASH/index.html

Publish staged docs to vitessce.io

After doing a manual test of the deployment of the docs, if it looks good, copy it to vitessce.io:

./copy-docs.sh https://{url returned by create-release.sh or push-demos.sh}

Note: if you need to obtain this URL later:

Copy docs to https://s3.amazonaws.com/vitessce-data/docs-root/$DATE/$HASH/index.html

Publish the NPM package

From GitHub Actions:

The vitessce package is published to the NPM registry by GitHub Actions when the version in package.json has been updated and pushed to the main branch. To perform this update, make a pull request to merge from the release branch into main.

From local machine:

pnpm run build
pnpm publish --filter='./packages/**' --no-git-checks --tag beta --access public --dry-run

Version bumps

In this project we try to follow semantic versioning. The following are examples of things that would require a major, minor, or patch type of bump.

Patch version bumps

Bug fixes, minor feature improvements, additional view types, additional coordination types, and additional file type implementations are possible in a patch version bump.

When a coordination type is added, it must be reflected by a new view config JSON schema with an incremented version property, and a new view config upgrade function to enable previous view config versions to remain compatible. The default schema version parameter of the VitessceConfig constructor may also change to reflect the new schema version.

Minor version bumps

An exported helper function or React component for plugin views had a change in props or function signature. Major feature improvements or additions.

Major version bumps

The exported constant values changed, such as view types and coordination types, such that previous code using these values may no longer run successfully. React props of the main <Vitessce /> component changed. Major behavior changes or interface updates. Changes to the directory structure or filenames in the dist/ directory that could result in broken import statements.

Related repositories

Viv: A library for multiscale visualization of high-resolution multiplexed tissue data on the web.
HiGlass: A library for multiscale visualization of genomic data on the web.
vitessce-python: Python API and Jupyter widget.
vitessce-r: R API and R htmlwidget.
vitessce-data: Scripts to generate sample data

hkmoon/vitessce