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

``bash
yarn add react-phylogeny-tree-gl
`

Components

$3

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:

`typescript
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.

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

$3

Hooks

$3

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

$3

instantiate phylocanvas.gl

phylocanvas.gl Plugins

phylocanvas.gl supported plugins of type:

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

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

)[MethodName],
args: Parameters<(PhylocanvasMethods

& M)[MethodName]>
) => unknown
) => void;
`

$3

Shows scalebar at right corner

$3

factories for phylocanvas.gl Plugins

$3

$3

react-phylogeny hooks

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

`typescript
type Hooks

= ((
getTree: () => Phylocanvas | null,
props: P & PhylocanvasProps
) => void)[];
`

$3

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

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

$3

react hook for autoresizing canvas when window size changes.

Example

`typescript
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;

const hooks = [useAutoResize, useLeafSubtree];
export const Tree = React.forwardRef(TreeComponent);
function TreeComponent(
{
newick,
rootId,
leafColors,
selectedLeafs,
subtreeBaseLeaf,
noLevelsUp,
minBranchLength,
}: TreeProps,
ref?: React.RefObject
): 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 (


const tuple = (...args: T): T => args;
``