HyPhy Vision

Visualize HyPhy results in your browser.

This repository holds visualizations written in React and D3 for JSON results generated by HyPhy. Reading raw numerical data can be tedious, and would oftentimes require a number of post-processing steps in your favorite scripting language to make sense of it. While you definitely can still do that, we provide custom, interactive, web-based visualizations to help facilitate making inferences about your results and less time data munging.

Start viewing your results now

Visit the associated site for this page at here.

I don't have results though, and I'm not sure where to begin

If you want to start exploring various ways of detecting selection on your sequence data now, please visit Datamonkey or Datamonkey Test with your multiple sequence alignment ready (in FASTA or NEXUS format). You can also run our methods locally by installing HyPhy.

Linking to results (URL parameters)

Any results page (/busted, /absrel, /meme, /fel, /relax, ...) accepts these query parameters. All are optional; a page with none of them behaves as it always has.

Parameter	Effect	Pages
json=<url> (alias resultsUrl=)	Load the results JSON from <url> (.json or .json.gz). The host must allow cross-origin requests.	all
section=<name> (alias tab=, or #<name>)	Scroll to that part of the page once the results have rendered.	all
tree=<option>	Choose an entry of the "Tree to view" menu, e.g. tree=Partition 2 or tree=Codon 12.	BUSTED, aBSREL, MEME, FEL
partition=<n>	Shorthand for tree=Partition <n>.	BUSTED, MEME, FEL
site=<n> (alias codon=)	Shorthand for tree=Codon <n>; shows the tree for that codon. Only results that include substitution maps offer codon trees.	BUSTED, aBSREL, MEME
branch=<name>	Highlight the branch (and its tip label) called <name> in the tree and scroll to it. On BUSTED and MEME, whose tree is hidden until a tree is chosen, the first partition is selected automatically.	pages that draw a tree

tree, partition, site and branch also scroll to the tree, unless a section is given. section understands the names summary, plot, table, tree and fits, but only where the page actually has that kind of section: not every page has all five. For example, Multi-Hit draws no tree, GARD and Slatkin-Maddison have no table, and FEL, NRM, GARD, Multi-Hit and SLAC have no separate model-fits section. section also accepts any element id on the page (e.g. tree-tab) or, on the Observable-based pages (BUSTED, aBSREL, MEME, FEL, NRM, GARD, Multi-Hit), any notebook cell name, e.g. figure1 or table1.

These parameters apply to vision.hyphy.org (the standalone app) only. When Vision is embedded in another site through the library exports, only json is read from the host page's URL.

Remember to URL-encode the json value when it has its own query string:

https://vision.hyphy.org/busted?json=https%3A%2F%2Fexample.org%2Fgene.BUSTED.json&branch=Node12
https://vision.hyphy.org/meme?json=https%3A%2F%2Fexample.org%2Fgene.MEME.json&site=42&section=tree
https://vision.hyphy.org/fel?json=https%3A%2F%2Fexample.org%2Fgene.FEL.json&tab=table

An unknown section, tree option or branch name (including a section name the page has nothing for) is ignored: the page stays where it is and, after about 20 seconds, a warning is logged to the browser console. Rows inside a table, and plot zoom, cannot be linked to yet.

Using Vision as a library

npm install hyphy-vision installs the library bundle (lib/hyphyvision.js, the package main), plus lib/application.scss and lib/variables.scss. It is a UMD bundle (global hyphyVision) that exports one component per method (busted, fel, absrel, ...) and renderHyPhyVision. Build it from a checkout with yarn build:library; this writes to lib/ and never touches the dist/ folder that yarn build produces for the standalone app.

Everything that is a package dependency is left external (webpack.config.library.js), so the embedding site's bundler must resolve them, and one extra setting is needed:

• A webpack alias for phylotree.css: the bundle contains require("phylotree.css"), which must resolve to the stylesheet shipped by the phylotree package.
• The dependencies in Vision's package.json (react, react-dom, jquery, d3 3.x, underscore, phylotree, @spond/*, ...) must be installable by the host; npm install hyphy-vision does this. Free references to $, jQuery, d3 and _ inside the bundle are bound to those packages at build time, so the host does not have to define these globals itself.

A minimal webpack host configuration:

const path = require("path");

module.exports = {
  entry: "./host.js", // import { fel } from "hyphy-vision"; fel(json, "root");
  resolve: {
    alias: {
      "phylotree.css": path.resolve(__dirname, "node_modules/phylotree/phylotree.css"),
    },
  },
  module: {
    rules: [{ test: /\.css$/, use: ["style-loader", "css-loader"] }],
  },
};

The render functions take the results JSON and the id of the element to render into, e.g. fel(json, "root", fasta, originalFile, analysisLog).

Contributing

Read our contributing guide to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes.

Development

Installation

HyPhy Vision uses yarn for package management.

git clone https://github.com/veg/hyphy-vision
cd hyphy-vision
yarn

Dev Server

Start the development server:

yarn start

Deployment

Merging to master does not update the hosted site. See DEPLOY.md for how vision.hyphy.org is built, deployed, smoke-tested and rolled back, and for the release checklist.

Electron

Start the desktop application:

yarn run electron