@figtreejs/core 0.0.1-beta.0 → 0.0.1-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figtreejs/core",
-  "version": "0.0.1-beta.0",
+  "version": "0.0.1-beta.1",
   "description": "A react component library for phylogenetic visualization and app building",
   "repository": {
     "type": "git",

package/src/evo/tree/normalized-tree/immutable-tree.ts

@@ -143,9 +143,7 @@ export class ImmutableTree implements Tree, TaxonSetInterface {
     nexus: string,
     options?: newickParsingOptions,
   ): ImmutableTree {
-    const tree = new this();
-    return parseNexus(tree, nexus, options);
-    // throw new Error("Nexus parsing not implemented")
+    return parseNexus(nexus, options);
   }
   static fromString(
     string: string,

package/src/evo/tree/parsers/annotation-parser.ts

@@ -130,6 +130,12 @@ export function parseAnnotation(annotationString: string): ParsedAnnotationRaw {
   return annotations;
 }
 
+/**
+ * Process an annotation value and return the possibly transformed value and
+ * figtreejs annotation type
+ * @param values RawAnnotationValue
+ * @returns ClassifiedValue {type: BaseAnnotationType, value: ValueOf<BaseAnnotationType>};
+ */
 export function processAnnotationValue(
   values: RawAnnotationValue,
 ): ClassifiedValue {

package/src/evo/tree/parsers/newick-character-parser.ts

@@ -4,6 +4,10 @@ import type { NodeRef } from "../tree-types";
 import { ImmutableTree } from "../normalized-tree/immutable-tree";
 import { parseAnnotation } from "./annotation-parser";
 import { notNull, unNullify } from "../../../utils/maybe";
+/**
+ * A class that contains the logic for parsing newick strings.
+ * It the tokens of the string should be split as in
+ *   /\s*('[^']+'|"[^"]+"|\[&[^[]+]|,|:|\)|\(|;)\s\*/
 
 export class NewickCharacterParser {
   done: boolean;
@@ -52,6 +56,10 @@ export class NewickCharacterParser {
     return this.tree;
   }
 
+  /**
+   * Parse the next token
+   * @param t token
+   */
   parseCharacter(t: string): void {
     if (this.done) {
       throw new Error("Parsing is done. We have seen a ';'");

package/src/evo/tree/parsers/newick-parsing.ts

@@ -2,6 +2,12 @@ import { NewickCharacterParser } from "./newick-character-parser";
 import type { ImmutableTree, newickParsingOptions } from "..";
 import { TaxonSet } from "..";
 
+/**
+ * An internal function to parse a newick string.
+ * @param newick
+ * @param options
+ * @returns
+ */
 export function parseNewick(
   newick: string,
   options: newickParsingOptions = {},

package/src/evo/tree/parsers/nexus-parsing.ts

@@ -1,12 +1,17 @@
 /* eslint-disable */
 import { ImmutableTree } from "../normalized-tree/immutable-tree";
+import { newickParsingOptions } from "../tree-types";
 import { parseNewick } from "./newick-parsing";
 
-//ONLY parses the first tree
+/**
+ * An internal helper function that parses the first tree in a nexus string
+ * @param nexus - The nexus string to be parsed.
+ * @param options - newickParsingOptions - parseAnnotations is set to true
+ * @returns
+ */
 export function parseNexus(
-  _tree: ImmutableTree,
   nexus: string,
-  options = {},
+  options: newickParsingOptions = {},
 ): ImmutableTree {
   // odd parts ensure we're not in a taxon label
   //TODO make this parsing more robust

package/src/evo/tree/parsers/stream-reader/nexus-importer.ts

@@ -5,6 +5,10 @@ import { TaxonSet } from "../../taxa/taxon";
 import { NewickCharacterParser } from "../newick-character-parser";
 import { newickDeliminators, nexusTokenizer } from "./nexus-tokenizer";
 
+/**
+ * A nexus importing class that parses a stream and into an asynchronous
+ * iterator over trees.
+ */
 export class NexusImporter {
   reader: ReadableStreamDefaultReader<string>;
   taxonSet: TaxonSet;
@@ -27,7 +31,10 @@ export class NexusImporter {
     this.currentBlock = undefined;
     this.options = options;
   }
-
+  /**
+   * The main public api.
+   * an asynchronous iterator over the trees provided by the stream
+   */
   async *getTrees(): AsyncIterableIterator<ImmutableTree> {
     while (this.currentBlock !== "trees") {
       await this.parseNextBlock();

package/src/evo/tree/parsers/stream-reader/nexus-tokenizer.ts

@@ -7,6 +7,11 @@ export enum STATUS {
   IN_COMMENT = "in comment",
 }
 
+/**
+ * A helper function that converts an incoming stream into tokens in
+ * a nexus file.
+ * @returns A pipe string tokenizer for use in a transform stream.
+ */
 export function nexusTokenizer() {
   return {
     lastChunk: "",

package/src/evo/tree/taxa/helper-functions.ts

@@ -2,6 +2,13 @@ import type { Maybe, Undefinable } from "../../../utils";
 import { Nothing, Some, MaybeType } from "../../../utils";
 import type { Taxon, TaxonSetData } from "./taxon";
 
+/**
+ * An internal maybe safe helper function for getting a taxon's name
+ * @param data - the underlying taxon set data.
+ * @param id
+ * @returns Maybe(name)
+ */
+
 export function maybeGetNameFromIndex(
   data: TaxonSetData,
   id: Maybe<number> | number,
@@ -23,6 +30,13 @@ export function maybeGetNameFromIndex(
   return Some(name);
 }
 
+/**
+ * An internal maybe safe helper function for getting a taxon by it's name
+ * @param data - the underlying taxon set data.
+ * @param id
+ * @returns Maybe(taxon)
+ */
+
 export function maybeGetTaxonByName(
   data: TaxonSetData,
   id: Maybe<string> | string,

package/src/evo/tree/taxa/taxon.ts

@@ -1,12 +1,23 @@
 import { MaybeType } from "../../../utils";
 import { maybeGetNameFromIndex, maybeGetTaxonByName } from "./helper-functions";
 
+/**
+ * A interface for taxon.
+ * There should only be one taxon per individual sampled.
+ * The taxon is meant to be synonymous with the individual and may be shared across multiple trees.
+ */
 export interface Taxon {
   name: string;
   number: number;
   annotations: { [annotation: string]: string | string[] | number | number[] };
 }
 
+/**
+ * An internal helper function for constructing a new taxon.
+ * @param name - taxon name
+ * @param number - taxon number
+ * @returns
+ */
 function newTaxon(name: string, number: number): Taxon {
   return {
     name,
@@ -15,19 +26,47 @@ function newTaxon(name: string, number: number): Taxon {
   };
 }
 
+/**
+ * An interface for a taxon set - a group of taxa in a tree.
+ */
 export interface TaxonSetInterface {
+  /**
+   * Add a taxon the the set
+   * @param name - Add a new taxon with this name
+   */
   addTaxon(name: string): TaxonSetInterface;
-  getTaxon(id: number): Taxon | undefined;
+  /**
+   * Get a taxon by it's number
+   * @param id -taxon number
+   */
+  getTaxon(id: number): Taxon | undefined; // remove this undefined?
+  /**
+   * Get a taxon object by it's name.
+   * @param name -the taxon name
+   */
   getTaxonByName(name: string): Taxon;
+  /**
+   * Return the number of taxa in the set.
+   */
   getTaxonCount(): number;
+  /**
+   * Lock the taxa set. No taxa can be added or removed at this point. The population is fixed.
+   */
   lockTaxa(): TaxonSetInterface;
 }
 
+/**
+ * The interface for a taxon set internal data structure.
+ */
 export interface TaxonSetData {
   allNames: string[];
   byName: { [taxon: string]: Taxon };
   finalized: boolean;
 }
+
+/**
+ * A concrete implementation of the taxonset interface
+ */
 export class TaxonSet implements TaxonSetInterface {
   _data: TaxonSetData;
   constructor(taxonSetData?: TaxonSetData) {

package/src/evo/tree/traversals/preorder-traversal.ts

@@ -1,5 +1,10 @@
 import type { Tree, NodeRef } from "../tree-types";
 import type { TreeTraversal } from "./traversal-types";
+
+/**
+ * A class for a cached pre-order traversal.
+ * This needs to be revisited before it can be used.
+ */
 export class PreOrderTraversalCache implements TreeTraversal {
   _forwardCache: Map<NodeRef, NodeRef>;
   _reverseCache: Map<NodeRef, NodeRef>;

package/src/evo/tree/traversals/traversal-types.ts

@@ -1,5 +1,8 @@
 import type { NodeRef, Tree } from "../tree-types";
 
+/**
+ * An interface for tree traversals
+ */
 export interface TreeTraversal {
   getNext(tree: Tree, node: NodeRef): NodeRef | undefined;
   getPrevious(tree: Tree, node: NodeRef): NodeRef | undefined;

package/src/evo/tree/tree-types.ts

@@ -1,9 +1,17 @@
 import type { Taxon, TaxonSet } from "./taxa/taxon";
 
+/**
+ * The base interface for a node.
+ * Information about the node will be provided by the tree.
+ */
 export interface NodeRef {
   number: number;
   _id: string;
 }
+/**
+ * Types of annotations that can exist on nodes in a tree.
+ * Each type corresponds to a value type.
+ */
 export enum BaseAnnotationType {
   DISCRETE = "DISCRETE", // string  could also be stringy numbers
   BOOLEAN = "BOOLEAN", // true false
@@ -17,6 +25,8 @@ export enum BaseAnnotationType {
 }
 export type MarkovJumpValue = { from: string; to: string; time?: number };
 
+// A helper type function that returns the value type of an annotation given its
+// figtree type.
 export type ValueOf<T extends BaseAnnotationType> =
   T extends BaseAnnotationType.DISCRETE
     ? string
@@ -34,6 +44,9 @@ export type ValueOf<T extends BaseAnnotationType> =
                 ? Record<string, number>
                 : never;
 
+// A helper function that returns the raw value type that corresponds to a figtreejs annotation type.
+// This generally is the same as the value type, but some annotations such as markov jumps are transformed
+// between being read from a nexus file and stored in the tree.
 export type RawValueOf<T extends BaseAnnotationType> =
   T extends BaseAnnotationType.DISCRETE
     ? string
@@ -51,6 +64,10 @@ export type RawValueOf<T extends BaseAnnotationType> =
                 ? Record<string, number>
                 : never;
 
+/**
+ *  A helper type function that returns the domain of an annotation based on the
+ * type of an annotation.
+ */
 export type DomainOf<T extends BaseAnnotationType> =
   T extends BaseAnnotationType.DISCRETE
     ? string[]
@@ -79,25 +96,42 @@ export type Annotation = {
   [K in BaseAnnotationType]: AbstractAnnotation<K>;
 }[BaseAnnotationType];
 
+/**
+ * The type of summary information that can be provided by a tree.
+ */
 export interface AbstractAnnotationSummary<T extends BaseAnnotationType> {
   id: string;
   type: T;
   domain: DomainOf<T>;
 }
 
+/**
+ * unions across all types of annotations.
+ */
 export type AnnotationDomain = {
   [K in BaseAnnotationType]: DomainOf<K>;
 }[BaseAnnotationType];
+
 export type AnnotationValue = {
   [K in BaseAnnotationType]: ValueOf<K>;
 }[BaseAnnotationType];
+
 export type AnnotationSummary = {
   [K in BaseAnnotationType]: AbstractAnnotationSummary<K>;
 }[BaseAnnotationType];
+
 export type RawAnnotationValue = {
   [K in BaseAnnotationType]: RawValueOf<K>;
 }[BaseAnnotationType];
 
+/**
+ * A object for the parsing options available for importing a newick string.
+ * dateFormat : string if provided with date prefix the data will be parsed from the taxon label and stored in an annotation called 'date'
+ * datePrefix : string The character immediately preceding the date assuming the date is at the end of the taxon label
+ * labelName : If there are node labels they will be parsed as annotations and stored with this annotation name
+ * tipNameMap : If taxon are present as number or some other encoding this map will be used to insert the full taxon name.
+ * taxonSet : If provided this taxon set will be used to link taxa across trees.
+ */
 export interface newickParsingOptions {
   dateFormat?: string;
   datePrefix?: string;
@@ -106,92 +140,297 @@ export interface newickParsingOptions {
   tipNameMap?: Map<string, string>;
   taxonSet?: TaxonSet;
 }
+/**
+ * A representation of a phylogenetic tree.
+ * Trees may represent unrooted tree, but all trees nominally have a root node.
+ * Functions do not return 'undefined' or 'null'.
+ * If a value that does not exist is accessed the tree will throw an error.
+ * Helper functions are provided to check if a value exists.
+ */
 export interface Tree {
+  /**
+   * Return the root of the tree.
+   */
   getRoot(): NodeRef;
-  isRooted(): boolean;
+  // isRooted(): boolean;
+  /**
+   * Return the number of nodes in the tree.
+   */
   getNodeCount(): number;
+  /**
+   * Return the number of internal nodes.
+   */
   getInternalNodeCount(): number;
+  /**
+   * Return the number of tips / external nodes
+   */
   getExternalNodeCount(): number;
+  /**
+   * Get Node by name/label, taxon, or index (in full node list)
+   * @param i: string | Taxon | number
+   */
   getNode(i: string | Taxon | number): NodeRef;
+  /**
+   * Get an array of internal nodes
+   */
   getInternalNodes(): NodeRef[];
+  /**
+   * Get an array of external nodes
+   */
   getExternalNodes(): NodeRef[];
+  /**
+   * Get an array of all nodes.
+   */
   getNodes(): NodeRef[];
+  /**
+   * Get the taxon affiliated with a node or by it's index
+   * @param id: number | NodeRef
+   */
   getTaxon(id: number | NodeRef): Taxon;
-
+  /**
+   * Helper to function to determine if a node in an external node
+   * @param node
+   */
   isExternal(node: NodeRef): boolean;
+  /**
+   * A helper function to determine if an node is an internal node
+   * @param node
+   */
   isInternal(node: NodeRef): boolean;
+  /**
+   * A helper function to determine if a node is the root node.
+   * @param node
+   */
   isRoot(node: NodeRef): boolean;
-
+  /**
+   * Return the number of children an given node has.
+   * @param node
+   */
   getChildCount(node: NodeRef): number;
+  /**
+   * Access the ith child of a node
+   * @param node - NodeRef
+   * @param i - index of the child
+   */
   getChild(node: NodeRef, i: number): NodeRef;
-
+  /**
+   * An explicit function to get a node by it's Taxon
+   * @param taxon
+   */
   getNodeByTaxon(taxon: Taxon): NodeRef;
+  /**
+   * An explicit function to access a node by it's label
+   * @param label - string
+   */
   getNodeByLabel(label: string): NodeRef;
   // getLevel(node:NodeRef):number;
-
+  /**
+   * Return the distance from this node to the root.
+   * @param node -NodeRef
+   */
   getDivergence(node: NodeRef): number;
+  /**
+   * Return the distance between a node and the node furthest from the root
+   * @param node -NodeRef
+   */
   getHeight(node: NodeRef): number;
+  /**
+   * Return the length of the branch subtending a node
+   * @param node -NodeRef
+   */
   getLength(node: NodeRef): number;
-
+  /**
+   * Return a node's parent
+   * @param node -NodeRef
+   */
   getParent(node: NodeRef): NodeRef;
+  /**
+   * Get an array of the node's children
+   * @param node -NodeRef
+   */
   getChildren(node: NodeRef): NodeRef[];
-
+  /**
+   * Get the annotation value for a node.
+   * If the default value is not provided, and the node is not annotated, the function will throw an error.
+   * @param node - NodeRef
+   * @param name - string the name of the annotation
+   * @param d - AnnotationValue - The default value to return if the node does not have the provided annotation.
+   */
   getAnnotation(
     node: NodeRef,
     name: string,
     d?: AnnotationValue,
   ): AnnotationValue; // what about or undefined?
-  // getAnnotation<T extends BaseAnnotationType>(node: NodeRef, name: string, d:T): T
-
-  // getAnnotationValue<T extends BaseAnnotationType>(node:NodeRef, name:string,type:T):ValueOf<T>|undefined
-  // annotateNode<T extends BaseAnnotationType>(node:NodeRef,annotation:{name:string,value:RawValueOf<T>}):Tree
+  /**
+   * Annotate a node with a value.
+   * @param node - NodeRef
+   * @param name -string - Name of the annotation
+   * @param value - the annotation value for a node.
+   */
   annotateNode(node: NodeRef, name: string, value: RawAnnotationValue): Tree;
   annotateNode(
     node: NodeRef,
     annotation: Record<string, RawAnnotationValue>,
   ): Tree;
-
+  /**
+   * Get the label for a given node
+   * @param node
+   */
   getLabel(node: NodeRef): string;
+  /**
+   * Check if a node has a label
+   * @param node
+   */
   hasLabel(node: NodeRef): boolean;
-
+  /**
+   * Get all the names of annotations in the tree
+   */
   getAnnotationKeys(): string[];
+  /**
+   * Get the type of an annotation found in the tree.
+   * @param name string - Name of the annotation
+   */
   getAnnotationType(name: string): BaseAnnotationType;
 
+  /**
+   * Return an array of summary data for all annotations in the tree.
+   */
   getAnnotations(): AnnotationSummary[];
+  /**
+   * Return a summary of an annotation in the tree
+   * @param name - name of the annotation
+   */
   getAnnotationSummary(name: string): AnnotationSummary;
-
+  /**
+   * Add nodes to a tree.
+   * The nodes can be accessed by their indices, but have no relationships with other nodes in the tree.
+   * Returns an object with {tree: the new tree with nodes,node: An array of the new nodes}
+   * @param n - number of nodes to add default 1
+   */
   addNodes(n?: number): { tree: Tree; nodes: NodeRef[] };
+  /**
+   * Delete a node from a tree.
+   * It is not possible to delete the root node.
+   * @param n - NodeRef
+   */
   deleteNode(n: NodeRef): Tree;
+  /**
+   * Remove a child node from a parent node's descendants
+   * @param parent - The node whose child will be removed
+   * @param child - The child that is removed from the parent.
+   */
   removeChild(parent: NodeRef, child: NodeRef): Tree;
-  deleteClade(n: NodeRef): Tree;
+  // deleteClade(n: NodeRef): Tree;
   // hasNextSibling(node:Node)
+  /**
+   * Get the next sibling.
+   * This will wrap back to the first sibling if the provided node is the last sibling.
+   * @param node - NodeRef
+   */
   getNextSibling(node: NodeRef): NodeRef;
+  /**
+   * A checker function to determine if a node has a right sibling
+   * @param node - NodeRef
+   */
   hasRightSibling(node: NodeRef): boolean;
+  /**
+   * Return a node's right sibling (if it has one) or error.
+   * @param node
+   */
   getRightSibling(node: NodeRef): NodeRef;
+  /**
+   * Check if a node has a left sibling
+   * @param node
+   */
   hasLeftSibling(node: NodeRef): boolean;
+  /**
+   * Return a node's left sibling (if it has one) or throw an error.
+   * @param node
+   */
   getLeftSibling(node: NodeRef): NodeRef;
 
+  /**
+   * Set the distance between a node and the node furthest from the root.
+   * @param node
+   * @param height number - the new node height
+   */
   setHeight(node: NodeRef, height: number): Tree;
+  /**
+   * Set the distance between a node and the root node.
+   * @param node
+   * @param divergence number - new divergence
+   */
   setDivergence(node: NodeRef, divergence: number): Tree;
+  /**
+   * Set the length of the branch subtending a node
+   * @param node NodeRef
+   * @param length - number - the new length
+   */
   setLength(node: NodeRef, length: number): Tree;
+  /**
+   * Assign a taxon to a node.
+   * @param node NodRef
+   * @param taxon Taxon
+   */
   setTaxon(node: NodeRef, taxon: Taxon): Tree;
+  /**
+   * Set the label on a node.
+   * @param node Noderf
+   * @param label string
+   */
   setLabel(node: NodeRef, label: string): Tree;
-
+  /**
+   * Add a child to a node.
+   * @param parent the parent that gets a new child
+   * @param child The child added to a parent
+   */
   addChild(parent: NodeRef, child: NodeRef): Tree;
   // root(node: NodeRef,portion:number): Tree
-  unroot(node: NodeRef): Tree;
+  // unroot(node: NodeRef): Tree;
+
+  /**
+   *
+   * @param node - An optional node start writing from. If not provided the whole tree will be written.
+   * @param options { includeAnnotations: boolean } - include annotations in newick string
+   */
   toNewick(node?: NodeRef, options?: { includeAnnotations: boolean }): string;
+  /**
+   * Sort children arrays by the number of offspring.
+   * @param down Boolean to sort down or up.
+   */
   orderNodesByDensity(down: boolean): Tree;
+  /**
+   *
+   * @param node Node whose children will be sorted
+   * @param compare - A function which compares two nodes. Will be used as in an array sort
+   */
   sortChildren(
     node: NodeRef,
     compare: (a: NodeRef, b: NodeRef) => number,
   ): Tree;
-  isRoot(node: NodeRef): boolean;
+  /**
+   * Get the most recent common ancestor of two nodes
+   * @param node1
+   * @param node2
+   */
   getMRCA(node1: NodeRef, node2: NodeRef): NodeRef;
+  /**
+   * Get the most recent common ancestor of an array of nodes
+   * @param nodes
+   */
   getMRCA(nodes: NodeRef[]): NodeRef;
+  /**
+   * Rotate a node's children
+   * @param node
+   * @param recursive - rotate the children as well down the tree
+   */
   rotate(node: NodeRef, recursive: boolean): Tree;
+  /**
+   * Reroot a tree along a branch subtending a new node.
+   * @param node The root will be inserted along the branch subtending this node
+   * @param proportion - proportion along the branch to place the root.
+   */
   reroot(node: NodeRef, proportion: number): Tree;
 }
-export type TreeListener = (tree: Tree, node: NodeRef) => void;
 
-//TODO abstact Tree with parsing implementations
+export type TreeListener = (tree: Tree, node: NodeRef) => void;