phylotree 2.2.1 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,433 @@
1
+ // Type definitions for phylotree
2
+ // Project: https://github.com/veg/phylotree.js
3
+
4
+ import { HierarchyNode, HierarchyLink } from 'd3-hierarchy';
5
+
6
+ /**
7
+ * Node data stored in the phylogenetic tree
8
+ */
9
+ export interface PhylotreeNodeData {
10
+ name: string;
11
+ attribute?: string;
12
+ annotation?: string;
13
+ [key: string]: any;
14
+ }
15
+
16
+ /**
17
+ * A node in the phylogenetic tree (D3 hierarchy node with phylotree data)
18
+ */
19
+ export type PhylotreeNode = HierarchyNode<PhylotreeNodeData> & {
20
+ selected?: boolean;
21
+ tag?: boolean;
22
+ collapsed?: boolean;
23
+ hidden?: boolean;
24
+ notshown?: boolean;
25
+ screen_x?: number;
26
+ screen_y?: number;
27
+ text_angle?: number;
28
+ text_align?: string;
29
+ angle?: number;
30
+ radius?: number;
31
+ };
32
+
33
+ /**
34
+ * A link/branch in the phylogenetic tree
35
+ */
36
+ export type PhylotreeLink = HierarchyLink<PhylotreeNodeData> & {
37
+ source: PhylotreeNode;
38
+ target: PhylotreeNode;
39
+ };
40
+
41
+ /**
42
+ * Options for rendering a phylogenetic tree
43
+ */
44
+ export interface RenderOptions {
45
+ /** CSS selector or DOM element for the container */
46
+ container?: string | HTMLElement;
47
+ /** Width of the SVG in pixels */
48
+ width?: number;
49
+ /** Height of the SVG in pixels */
50
+ height?: number;
51
+ /** Enable zoom/pan behavior */
52
+ zoom?: boolean;
53
+ /** Tree layout: "left-to-right" or "right-to-left" */
54
+ layout?: 'left-to-right' | 'right-to-left';
55
+ /** Use radial/circular layout */
56
+ 'is-radial'?: boolean;
57
+ /** Align tip labels */
58
+ 'align-tips'?: boolean;
59
+ /** Show node labels */
60
+ 'show-labels'?: boolean;
61
+ /** Show scale bar */
62
+ 'show-scale'?: boolean;
63
+ /** Draw size bubbles on nodes */
64
+ 'draw-size-bubbles'?: boolean;
65
+ /** Show internal node names */
66
+ 'internal-names'?: boolean | ((node: PhylotreeNode) => boolean);
67
+ /** Enable node selection */
68
+ selectable?: boolean;
69
+ /** Enable collapsing of clades */
70
+ collapsible?: boolean;
71
+ /** Enable brushing for selection */
72
+ brush?: boolean;
73
+ /** Left offset in pixels */
74
+ 'left-offset'?: number;
75
+ /** Spacing mode for top-bottom */
76
+ 'top-bottom-spacing'?: 'fixed-step' | 'fit';
77
+ /** Spacing mode for left-right */
78
+ 'left-right-spacing'?: 'fixed-step' | 'fit';
79
+ /** Font size for labels */
80
+ 'font-size'?: number;
81
+ /** Maximum label width in characters */
82
+ 'max-label-width'?: number;
83
+ /** Bubble styler function */
84
+ 'bubble-styler'?: (node: PhylotreeNode) => number;
85
+ /** Restrict which nodes can be selected */
86
+ 'restricted-selectable'?: string | ((link: PhylotreeLink) => boolean);
87
+ /** Logger instance */
88
+ logger?: Console;
89
+ }
90
+
91
+ /**
92
+ * Options for parsing tree input
93
+ */
94
+ export interface ParseOptions {
95
+ /** Enable bootstrap value parsing */
96
+ bootstrap_values?: boolean;
97
+ /** Format type: "newick", "phyloxml", "nexus" */
98
+ type?: string | ((input: string, options: ParseOptions) => any);
99
+ /** Logger instance */
100
+ logger?: Console;
101
+ }
102
+
103
+ /**
104
+ * The TreeRender class handles visualization of the tree
105
+ */
106
+ export class TreeRender {
107
+ /** The phylotree instance this renderer belongs to */
108
+ phylotree: Phylotree;
109
+ /** The SVG element */
110
+ svg: d3.Selection<SVGSVGElement, unknown, null, undefined>;
111
+ /** Rendering options */
112
+ options: RenderOptions;
113
+ /** Current zoom transform */
114
+ currentZoomTransform: d3.ZoomTransform | null;
115
+ /** Label width in pixels */
116
+ label_width: number;
117
+ /** Rightmost leaf x position */
118
+ right_most_leaf: number;
119
+
120
+ constructor(phylotree: Phylotree, options?: RenderOptions);
121
+
122
+ /** Get the SVG element */
123
+ show(): SVGSVGElement;
124
+
125
+ /** Update the tree display */
126
+ update(): this;
127
+
128
+ /** Update layout coordinates */
129
+ update_layout(tree: PhylotreeNode): this;
130
+
131
+ /** Get/set radial mode */
132
+ radial(value?: boolean): boolean | this;
133
+
134
+ /** Get/set align tips mode */
135
+ alignTips(value?: boolean): boolean | this;
136
+
137
+ /** Get/set selection label */
138
+ selectionLabel(label?: string): string | this;
139
+
140
+ /** Get/set node label accessor */
141
+ nodeLabel(accessor?: (node: PhylotreeNode) => string): ((node: PhylotreeNode) => string) | this;
142
+
143
+ /** Get/set node styler function */
144
+ nodeStyler(styler?: (element: d3.Selection<any, PhylotreeNode, any, any>, node: PhylotreeNode) => void): this;
145
+
146
+ /** Get/set edge styler function */
147
+ edgeStyler(styler?: (element: d3.Selection<any, PhylotreeLink, any, any>, link: PhylotreeLink) => void): this;
148
+
149
+ /** Collapse a node */
150
+ collapse_node(node: PhylotreeNode): this;
151
+
152
+ /** Modify selection based on a callback */
153
+ modifySelection(callback: (link: PhylotreeLink, callback: (selected: boolean) => void) => boolean): this;
154
+
155
+ /** Get selected nodes */
156
+ getSelection(): PhylotreeNode[];
157
+
158
+ /** Get selected branches */
159
+ getSelectedBranches(): PhylotreeLink[];
160
+
161
+ /** Register event listener */
162
+ on(event: string, callback: (...args: any[]) => void): this;
163
+
164
+ /** Emit an event */
165
+ emit(event: string, ...args: any[]): this;
166
+
167
+ /** Selection callback setter */
168
+ selectionCallback(callback: (selection: PhylotreeNode[]) => void): this;
169
+ }
170
+
171
+ /**
172
+ * Main Phylotree class for creating and manipulating phylogenetic trees
173
+ */
174
+ export class phylotree {
175
+ /** Hierarchical tree structure (D3 hierarchy) */
176
+ nodes: PhylotreeNode;
177
+ /** Links between nodes */
178
+ links: PhylotreeLink[];
179
+ /** Parsed annotation tags */
180
+ parsed_tags: string[];
181
+ /** The tree renderer (set after calling render()) */
182
+ display: TreeRender | null;
183
+ /** Original Newick string */
184
+ newick_string: string;
185
+ /** Selection attribute name */
186
+ selection_attribute_name: string;
187
+
188
+ /**
189
+ * Create a new phylogenetic tree
190
+ * @param nwk Newick string, PhyloXML string, or hierarchical JSON
191
+ * @param options Parsing options
192
+ */
193
+ constructor(nwk: string | object, options?: ParseOptions);
194
+
195
+ /**
196
+ * Render the tree to an SVG
197
+ * @param options Rendering options
198
+ * @returns TreeRender instance
199
+ */
200
+ render(options?: RenderOptions): TreeRender;
201
+
202
+ /**
203
+ * Traverse the tree and compute values at each node
204
+ * @param callback Function called on each node
205
+ * @param traversal_type "pre-order", "post-order", or "in-order"
206
+ * @param root_node Optional starting node
207
+ * @param backtrack Optional function to stop traversal
208
+ */
209
+ traverse_and_compute(
210
+ callback: (node: PhylotreeNode) => void,
211
+ traversal_type?: 'pre-order' | 'post-order' | 'in-order',
212
+ root_node?: PhylotreeNode,
213
+ backtrack?: (node: PhylotreeNode) => boolean
214
+ ): void;
215
+
216
+ /** Export tree to JSON string */
217
+ json(traversal_type?: string): string;
218
+
219
+ /** Get parsed annotation tags */
220
+ get_parsed_tags(): string[];
221
+
222
+ /** Update tree from JSON */
223
+ update(json: object): this;
224
+
225
+ /** Check if tree has branch lengths */
226
+ hasBranchLengths(): boolean;
227
+
228
+ /** Get all branch lengths */
229
+ getBranchLengths(): number[];
230
+
231
+ /** Set branch length accessor */
232
+ setBranchLength(accessor: (node: PhylotreeNode) => number): this;
233
+
234
+ /** Normalize branch lengths */
235
+ normalizeBranchLengths(attr?: string): this;
236
+
237
+ /** Scale branch lengths by a factor */
238
+ scaleBranchLengths(scale: number): this;
239
+
240
+ /** Get branch name accessor */
241
+ branchName(accessor?: (node: PhylotreeNode) => string): string | this;
242
+
243
+ /** Get Newick representation of tree */
244
+ getNewick(annotator?: (node: PhylotreeNode) => string): string;
245
+
246
+ /** Get tagged Newick representation */
247
+ getTaggedNewick(): string;
248
+
249
+ /** Find most recent common ancestor of nodes */
250
+ mrca(nodes: (PhylotreeNode | string)[]): PhylotreeNode;
251
+
252
+ /** Check if a node is a leaf */
253
+ isLeafNode(node: PhylotreeNode): boolean;
254
+
255
+ /** Get all tip/leaf nodes */
256
+ getTips(): PhylotreeNode[];
257
+
258
+ /** Get all internal nodes */
259
+ getInternals(): PhylotreeNode[];
260
+
261
+ /** Get root node */
262
+ getRootNode(): PhylotreeNode;
263
+
264
+ /** Get all nodes */
265
+ getNodes(): PhylotreeNode[];
266
+
267
+ /** Get node by name */
268
+ getNodeByName(name: string): PhylotreeNode | undefined;
269
+
270
+ /** Select all descendants of a node */
271
+ selectAllDescendants(node: PhylotreeNode, terminal?: boolean, internal?: boolean): PhylotreeNode[];
272
+
273
+ /** Reroot the tree at a node */
274
+ reroot(node: PhylotreeNode, fraction?: number): this;
275
+
276
+ /** Get path from a node to the root */
277
+ pathToRoot(node: PhylotreeNode): PhylotreeNode[];
278
+
279
+ /** Resort children of nodes */
280
+ resortChildren(comparator: (a: PhylotreeNode, b: PhylotreeNode) => number): this;
281
+
282
+ /** Graft a new node */
283
+ graftANode(graftAt: PhylotreeNode, newChild: PhylotreeNode, newParent?: PhylotreeNode, lengths?: { new_child: number; new_parent: number }): void;
284
+
285
+ /** Add a child node */
286
+ addChild(parent: PhylotreeNode, child: PhylotreeNode): void;
287
+
288
+ /** Delete a node */
289
+ deleteANode(index: number): void;
290
+
291
+ /** Assign attributes to nodes */
292
+ assignAttributes(attributes: object): this;
293
+
294
+ /** Get tip lengths for date extraction */
295
+ getTipLengths(): { [name: string]: number };
296
+
297
+ /** Maximum parsimony ancestral state reconstruction */
298
+ maxParsimony(attr: string, states: string[]): this;
299
+
300
+ /** Clear internal node selections */
301
+ clearInternalNodes(respect?: boolean): this;
302
+ }
303
+
304
+ // Utility functions
305
+
306
+ /**
307
+ * Parse a Newick format string
308
+ */
309
+ export function newickParser(newick: string, options?: ParseOptions): { json: object; error: string | null };
310
+
311
+ /**
312
+ * Get Newick string from tree
313
+ */
314
+ export function getNewick(tree: PhylotreeNode, annotator?: (node: PhylotreeNode) => string): string;
315
+
316
+ /**
317
+ * Compute pairwise distances between nodes
318
+ */
319
+ export function pairwise_distances(tree: phylotree): number[][];
320
+
321
+ /**
322
+ * Compute pairwise distances between nodes (camelCase alias)
323
+ */
324
+ export function pairwiseDistances(tree: phylotree): number[][];
325
+
326
+ /**
327
+ * Compute Sackin's index (tree balance measure)
328
+ */
329
+ export function sackin(tree: phylotree): number;
330
+
331
+ /**
332
+ * Find center of tree
333
+ */
334
+ export function centerOfTree(tree: phylotree): PhylotreeNode;
335
+
336
+ /**
337
+ * Compute midpoint for rooting
338
+ */
339
+ export function computeMidpoint(tree: phylotree): { node: PhylotreeNode; fraction: number };
340
+
341
+ /**
342
+ * Root to tip regression
343
+ */
344
+ export function rootToTip(tree: phylotree, attr?: string): {
345
+ slope: number;
346
+ intercept: number;
347
+ r2: number;
348
+ data: Array<{ date: number; distance: number; name: string }>;
349
+ };
350
+
351
+ /**
352
+ * Fit root to tip (find optimal root)
353
+ */
354
+ export function fitRootToTip(tree: phylotree, attr?: string): {
355
+ node: PhylotreeNode;
356
+ fraction: number;
357
+ r2: number;
358
+ };
359
+
360
+ /**
361
+ * Extract dates from tip names
362
+ */
363
+ export function extract_dates(tree: phylotree, pattern?: RegExp): { [name: string]: number };
364
+
365
+ /**
366
+ * Extract dates from tip names (camelCase alias)
367
+ */
368
+ export function extractDates(tree: phylotree, pattern?: RegExp): { [name: string]: number };
369
+
370
+ /**
371
+ * Cluster Picker algorithm
372
+ */
373
+ export function clusterPicker(tree: phylotree, options?: {
374
+ bootstrap_threshold?: number;
375
+ distance_threshold?: number;
376
+ }): PhylotreeNode[][];
377
+
378
+ /**
379
+ * PhyloPart clustering algorithm
380
+ */
381
+ export function phylopart(tree: phylotree, options?: {
382
+ bootstrap_threshold?: number;
383
+ }): PhylotreeNode[][];
384
+
385
+ /**
386
+ * Parse FASTA format
387
+ */
388
+ export function parseFasta(fasta: string): Array<{ name: string; seq: string }>;
389
+
390
+ /**
391
+ * Neighbor joining tree construction
392
+ */
393
+ export function neighborJoining(matrix: number[][], labels: string[]): object;
394
+
395
+ /**
396
+ * Get distance matrix from sequences
397
+ */
398
+ export function getDistanceMatrix(sequences: Array<{ name: string; seq: string }>): {
399
+ matrix: number[][];
400
+ labels: string[];
401
+ };
402
+
403
+ /**
404
+ * Load annotations from NEXUS file
405
+ */
406
+ export function loadAnnotations(nexus: string): object;
407
+
408
+ /**
409
+ * Parse annotations from NEXUS
410
+ */
411
+ export function parseAnnotations(nexus: string): object;
412
+
413
+ // Tree traversal functions
414
+
415
+ /**
416
+ * In-order traversal
417
+ */
418
+ export function inOrder(node: PhylotreeNode, callback: (node: PhylotreeNode) => void, backtrack?: (node: PhylotreeNode) => boolean): void;
419
+
420
+ /**
421
+ * Pre-order traversal
422
+ */
423
+ export function preOrder(node: PhylotreeNode, callback: (node: PhylotreeNode) => void, backtrack?: (node: PhylotreeNode) => boolean): void;
424
+
425
+ /**
426
+ * Post-order traversal
427
+ */
428
+ export function postOrder(node: PhylotreeNode, callback: (node: PhylotreeNode) => void, backtrack?: (node: PhylotreeNode) => boolean): void;
429
+
430
+ /**
431
+ * Left-child right-sibling traversal
432
+ */
433
+ export function leftChildRightSibling(node: PhylotreeNode, callback: (node: PhylotreeNode) => void): void;