react-phylogeny-tree-gl v1.0.0-beta

react-phylogeny-tree-gl

React integration of phylocanvas.gl. Components (and hooks) for phylogenetic tree visualisation for Newick tree format.

It handles up to 100 000+ leaves.

Install

yarn add react-phylogeny-tree-gl

Components

PhylogenyTree

It includes zoom buttons, context menu (adds context menu plugin to plugins array) and support redoUndo plugin with control buttons.

Props:

• initProps: phylocanvas.gl properties used for initialisation. Should be ref. stable (eg. memoized), if changes phylocanvas instance is reinitialised
• controlledProps: phylocanvas.gl properties, when change phylocanvas.gl tree.setProps method is called with new value. During initialisation props initProps and controlledProps are merged {...initProps, ...controlledProps}.
• plugins: array of phylocanvas.gl plugins, viz section Plugins bellow
  • should be Should be ref stable (eg. memoized), if changes phylogeny-tree instance is reinitialised
• hooks: array of hooks, viz section Hooks bellow. Should be ref stable.
• zoomButtons: boolean, when interactive (in initProps) and zoomButtons are true buttons for zoom appears.
• zoomButtonsStyle: CSSProperties object passed to zoom buttons container.
• ref reference which expose getTree function which returns phylocanvas.gl instance and allows us to perform imperative operations on it.

There have to be source prop in either in initProps or controlledProps. The source type is:

type Newick = string;
type BiojsTree = {
  children: BiojsTree[];
  name: string | number;
  branch_length: number;
};
type Source =
  | Newick
  | {
      type: 'newick';
      data: Newick;
      original?: Source;
    }
  | {
      type: 'biojs';
      data: BiojsTree;
      original?: Source;
    };

CSS

For correct function of zoom buttons, context menu and redo-undo control buttons it is necessary.

import 'react-phylogeny-tree-gl/styles.css';

PhylogenyTreeWithoutMenu

Hooks

usePhylogenyTreeWithMenu

used by PhylogenyTree component. Utilise usePhylogenyTree to instantiate phylocanvas.gl.

usePhylogenyTree

instantiate phylocanvas.gl

phylocanvas.gl Plugins

phylocanvas.gl supported plugins of type:

export type Plugins<
  P extends PhylocanvasInitProps,
  M extends Record<string, (...args: unknown[]) => unknown>
> = ((tree: Phylocanvas<P, M>, decorate: Decorate<P, M>) => void)[];

export type Decorate<
  P extends PhylocanvasInitProps = PhylocanvasInitProps,
  M extends Record<string, (...args: unknown[]) => unknown> = Record<
    string,
    (...args: unknown[]) => unknown
  >
> = <MethodName extends keyof (M & PhylocanvasMethods<P>)>(
  fnName: MethodName,
  fn: (
    delegate: (M & PhylocanvasMethods<P>)[MethodName],
    args: Parameters<(PhylocanvasMethods<P> & M)[MethodName]>
  ) => unknown
) => void;

scalebar

Shows scalebar at right corner

onClickHighlightOffsprings

factories for phylocanvas.gl Plugins

createOnSelectPlugin

createOnViewSubtreePlugin

react-phylogeny hooks

import from react-phylogeny-tree.gl/hooks. Pass in array with stable reference between rerenders (memoize). Their type is:

type Hooks<P extends PhylocanvasProps, M> = ((
  getTree: () => Phylocanvas<P, M> | null,
  props: P & PhylocanvasProps
) => void)[];

useLeafSubtree

react hook which wraps setRootNLevelsUp. Needs to receive folowing object under key leafSubtree from props.

leafSubtree: {
    leafID?: string;
    noLevels?: number;
    minLeafToRootLength?: number;
    setLeafLabels?: (ids: (string | number)[]) => void;
  };

useAutoResize

react hook for autoresizing canvas when window size changes.

Example

import React from 'react';
import PhylogenyTree from 'react-phylogeny-tree-gl';
import { useLeafSubtree, useAutoResize } from 'react-phylogeny-tree-gl/hooks';
import {
  createOnSelectPlugin,
  createOnViewSubtreePlugin,
  createOnRedrawReRootTreePlugin,
  createRedoUndoPlugin,
  onClickHighlightOffsprings,
  scalebar,
} from 'react-phylogeny-tree-gl/plugins';
import { PhylogenyTreeRef, UndoRedoMethods } from 'react-phylogeny-tree-gl/types';

type TreeNodeColors = {
  [id: string]: { fillColour: string } | null;
};
type TreeProps = {
  newick: string;
  leafColors: TreeNodeColors;
  selectedLeafs: string[];
  subtreeBaseLeaf: string | undefined;
  rootId?: string;
  noLevelsUp: number;
  minBranchLength: number;
};

export type RefProps = {
  source: string;
  interactive: boolean;
  nodeSize: number;
  haloRadius: number;
  haloWidth: number;
  scalebar: boolean;
  highlightColour: [number, number, number, number];
  rootId: string;
  selectedIds: string[];
  styles: TreeNodeColors;
  leafSubtree: {
    leafID: string;
    noLevels: number;
    minLeafToRootLength: number;
  };
};

export type TreeRef = PhylogenyTreeRef<RefProps, UndoRedoMethods>;

const hooks = [useAutoResize, useLeafSubtree];
export const Tree = React.forwardRef(TreeComponent);
function TreeComponent(
  {
    newick,
    rootId,
    leafColors,
    selectedLeafs,
    subtreeBaseLeaf,
    noLevelsUp,
    minBranchLength,
  }: TreeProps,
  ref?: React.RefObject<TreeRef>
): JSX.Element {
  const showHelp = React.useContext(ShowHelpContext);

  const initOptions = React.useMemo(
    () => ({
      source: newick,
      rootId: null,
      interactive: true,
      nodeSize: 7,
      haloRadius: 6,
      haloWidth: 2,
      scalebar: true,
      highlightColour: tuple(52, 182, 199, 255),
    }),
    [newick]
  );
  const controlledOptions = React.useMemo(
    () => ({
      selectedIds: selectedLeafs,
      styles: leafColors,
      leafSubtree: {
        leafID: subtreeBaseLeaf,
        noLevels: noLevelsUp,
        minLeafToRootLength: minBranchLength,
      },
    }),
    [leafColors, minBranchLength, noLevelsUp, selectedLeafs, subtreeBaseLeaf]
  );
  const plugins = React.useMemo(() => {
    return [
      createRedoUndoPlugin(),
      createOnSelectPlugin((_tree, selectedLeafLabels) => {
        if (selectedLeafLabels && selectedLeafLabels.length) {

          console.log(selectedLeafLabels)
        }
      }),
      createOnViewSubtreePlugin((tree, leafsInTree) => {
        console.log(leafsInTree)
      }),
      createOnRedrawReRootTreePlugin((tree, leafsInTree) => {
        console.log(leafsInTree, tree.props.rootId, false);
      }),
      onClickHighlightOffsprings,
      scalebar,
    ];
  }, []);

  React.useEffect(() => {
    if (ref.current) {
      const tree = ref.current.getTree();
      if (tree.props.rootId !== rootId) {
        tree.setRoot(rootId);
      }
    }
  }, [rootId, ref]);


  return (
    <div style={position: 'relative'}>
      <PhylogenyTree
        ref={ref}
        initProps={initOptions}
        controlledProps={controlledOptions}
        hooks={hooks}
        plugins={plugins}
      />
    </div>
  );
}

const tuple = <T extends unknown[]>(...args: T): T => args;