Pvjs

JavaScript-based biological pathway diagram viewer. Used in WikiPathways.

Beta

The beta tag given to this version means that it is not advisable to use it in production. There are some known issues and it has not been fully cross browser tested.

Having said that, most of the desired functionality does work as intended in most modern browsers.

Note: If you need to use the stable version of Pvjs see this README.

Contents

• Installation
  • Using a Module Bundler (Webpack)
  • Using the UMD bundle
• React Usage
  • Basic Example
  • Props
  • Advanced Example
• Web Component
  • Example
  • Attributes
  • Properties
  • Events
  • Manipulating
    • Example
    • Methods
• Contributions & Bug Reports
• Funding

Installation

Using a Module Bundler (Webpack)

We recommend using a module bundler like Webpack in your project. If you're doing this, just install and import Pvjs. All examples will assume you are using this method and not the UMD bundle.

Note that Pvjs does come with some styles which will be automatically picked up by Webpack.

npm install @wikipathways/pvjs --save

// Somewhere in your project
import { Pvjs } from "@wikipathways/pvjs";

Using the UMD bundle

Pvjs comes with a UMD bundle that you can include in your HTML page. It's available under dist/index.js. Once you've included the bundle, Pvjs is available under the Pvjs namespace.

### <a name="umd"></a>Using the UMD bundle
Pvjs comes with a UMD bundle that you can include in your HTML page. It's available under `dist/index.js`. Once you've included the bundle, Pvjs is available under the `Pvjs` namespace.

1. Copy `dist/index.js`, `dist/style.css`, and all of `dist/assets` into your project assets (tip: use a task runner like gulp)
2. Include `index.js` and `style.css` in your project's head tag:

```html
<script src="assets/pvjs/index.js"></script>
<link rel="stylesheet" href="assets/pvjs/style.css" />

Alternatively, just use it from the unpkg CDN:

<script src="https://unpkg.com/@wikipathways/pvjs/dist/index.js"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/@wikipathways/pvjs/dist/style.css"
/>

React Usage

If you are already using React then you can directly use the React component.

Basic Example

Use the component as below. Pvjs will fill whatever container it is in, so it is a good idea to place it inside a container with set dimensions.

import React from "react";
import ReactDOM from "react-dom";
import { Pvjs } from "@wikipathways/pvjs";

ReactDOM.render(<Pvjs wpId="WP4" />, document.getElementById("root"));

Props

• wpId: Required. A string for the WikiPathways ID of the desired pathway. E.g. 'WP4'.
• version: Default = 0. A number for the version of the pathway. 0 is latest.
• onReady: Function that is called with the list of entities in the diagram when the diagram has finished loading. You can use this to get the entityIds for other props.
• onEntityClick: Function that is called with the entity whenever a diagram entity has been clicked.
• onPanZoomChange: Function that is called whenever the diagram is panned or zoomed. It is called with an object with the form: { x: number, y: number, zoomLevel: number }. The coordinates in the object are relative to the diagram dimensions.
• detailPanelEnabled: Default = true. Indicates whether the annotations pop-up will be shown when an entity is clicked.
• panZoomLocked: Default = false. Indicates whether the user can manually pan and zoom the diagram. Note, changes to pannedEntities and zoomedEntities will still have an effect if this is true.
• showPanZoomControls: Default = true. Indicates whether the controls for panning and zooming are shown.
• highlightedEntities: Default = []. Array of objects for highlighted diagram entities. Objects in this array look like { entityId: string, color: string }. Color can be any CSS color. See the advanced example.
• hiddenEntities: Default = []. Array of entityIds. See the advanced example.
• pannedEntities: Default = []. Array of entityIds. See the advanced example.
• zoomedEntities: Default = []. Array of entityIds. See the advanced example. Note, that zoomed does not also mean panned. In most cases, an entityId in zoomedEntities should also be in pannedEntities.
• zoomLevel: Default = 1. Number indicating the level of zoom the diagram should be at. 1 = no zoom in/out.
• panCoordinates: Default: {x: 0, y: 0}. Relative coordinates to pan to. x is relative to the diagram width and y the diagram height. E.g. {x: 0.5, y: 0.5} will pan half way across the x and y axis.

Note that pannedCoordinates and zoomLevel take precedence over pannedEntities and zoomedEntities.

Advanced Example

import React, { Component } from "react";
import { Pvjs } from "@wikipathways/pvjs";

class MyPvjsComponent extends Component {
  constructor(props) {
    super(props);

    this.state = {
      highlightedEntities: [],
      hiddenEntities: [],
      zoomedEntities: [],
      pannedEntities: []
    };
  }

  onEntityClick = entity => {
    // This will highlight an entity red, whenever it is clicked
    this.setState(state => {
      return {
        highlightedEntities: state.highlightedEntities.concat([
          {
            entityId: entity.id,
            color: "red" // Color can be any CSS color
          }
        ])
      };
    });
  };

  onPvjsReady = entityList => {
    // Find the entity with TCA cycle as the node text
    const TCA = entityList.find(
      singleEntity => singleEntity.textContent === "TCA Cycle"
    );
    const BRCA1 = entityList.find(
      singleEntity => singleEntity.textContent === "BRCA1"
    );

    this.setState({
      highlightedEntities: [{ entityId: TCA.id, color: "blue" }],
      pannedEntities: [TCA.id],
      zoomedEntities: [TCA.id],
      hiddenEntities: ["daafb"]
    });
  };

  render() {
    const {
      highlightedEntities,
      hiddenEntities,
      zoomedEntities,
      pannedEntities
    } = this.state;

    return (
      <div style={{ width: "100vw", height: "100vh" }}>
        <Pvjs
          wpId="WP4"
          version={0}
          onReady={this.onPvjsReady}
          onEntityClick={this.onEntityClick}
          highlightedEntities={highlightedEntities}
          hiddenEntities={hiddenEntities}
          zoomedEntities={zoomedEntities}
          pannedEntities={pannedEntities}
          detailPanelEnabled={false}
        />
      </div>
    );
  }
}

Web Component

The web component allows you to use Pvjs without React. To use it, first make sure that Pvjs is available on the page in which you're using it. The easiest way to do this is to include the UMD bundle in your pages head. If you're using a module bundler, just make sure Pvjs is included in your build process (normally in index.js).

Example

An example is served at this gist.

Attributes

• wp-id: Required. A string for the WikiPathways ID of the desired pathway. E.g. 'WP4'.
• version: Default = 0. A number for the version of the pathway. 0 is latest.
• detail-panel-enabled: Indicates whether the annotations pop-up will be shown when an entity is clicked.
• pan-zoom-locked: Indicates whether the user can manually pan and zoom the diagram. Note, changes via the Manipulation API will still take effect.
• show-pan-zoom-controls: Indicates whether the controls for panning and zooming are shown.
• ready: Indicates when the diagram is fully loaded and ready for manipulating. You cannot set this.
• highlighted-entities: Comma separated list of entityId:color maps. E.g. d8bae:red. You may set this using the API.
• panned-entities: Comma separated list of entity IDs that are panned to. You may set this using the API.
• zoomed-entities: Comma separated list of entity IDs that are zoomed to. You may set this using the API.
• hidden-entities: Comma separated list of entity IDs that are hidden. You may set this using the API.

Properties

These properties are not reflected in the DOM attributes.

• entities: The list of entity objects in the diagram. This is null until the diagram is ready.

Events

• ready: This is fired when the diagram is ready. entities is provided in the detail object for convenience. See this gist.

Manipulating

The custom element provides a custom API that allows you to programmatically manipulate the diagram.

Example

An example is served at this gist.

Methods

zoomOn

This method accepts a single entity ID or an array of entity IDs. If a single entity is given then the diagram will zoom and pan to that entity. If an array is given, the diagram will zoom and pan to the area defined by all of those entities.

zoomOn(entity_id: string | string[])

panTo

Basically the same as zoomOn but without the zooming.

panTo(entity_id: string | string[])

highlightOn

Attributes

highlightOn(entity_id: string, color: string)

highlightOff

highlightOff(entity_id: string)

toggleHighlight

toggleHighlight(entity_id: string)

hide

hide(entity_id: string)

show

show(entity_id: string)

toggleHidden

toggleHidden(entity_id: string)

resetPan

resetPan()

##### toggleHidden
```javascript
toggleHidden(entity_id: string)

resetPan

resetPan();

resetZoom

resetZoom();

resetHighlighted

Un-highlight all highlighted entities. Accepts an optional exclude array that will exclude the given entities from being reset.

resetHighlighted(exclude?: string[])

resetHidden

Show all hidden entities. Accepts an optional exclude array that will exclude the given entities from being reset.

resetHidden(exclude?: string[])

reset

Reset the pan, zoom, hidden, and highlighted entities

reset();

Contributions & Bugs

We love pull requests! If you want to contribute to Pvjs then please feel free to make a pull request. The GitHub page is available here.

If you find a bug please check the issue tracker to see if it hasn't already been reported. If not, then please create a new issue. If you can then we would love for you to make a fix for it in a pull request.

peer dependencies

The dependencies babel-preset-es2016 and babel-preset-es2016 are required by pvjs dependency collit.

Funding

• The National Institute for General Medical Sciences R01-GM100039
• The BioRange program of the Netherlands Bioinformatics Centre
• University Maastricht: Broad Research Strategy Program Part 2 (BOS2)