zForDevelopers – API

API

Please note that this page is intended for developers and system administrators. It is unlikely to contain information relevant to general MicrobeTrace users.

This document describes the current MicrobeTrace programming interface. The application is built with Angular and most low level operations are exposed through the CommonService class. Components inject this service (typically as commonService) and call its methods to manipulate data, perform calculations in Web Workers and manage application state.

In general these methods are stateless but a few maintain internal state or modify the session object. Those are marked with an asterisk (*).

Utility Functions

• ab2str(buf) – convert an ArrayBuffer to a string.
• str2ab(str) – convert a string to an ArrayBuffer.
• capitalize(value) – capitalize a string.
• contrastColor(hexcolor) – return black/white text color for the provided background color.
• haversine(a, b) – compute the great circle distance between two coordinates.
• r01() – thin wrapper around Math.random used for security scanner compliance.
• titleize(title) – convert a string to Title Case.

Data & Session Management

• dataSkeleton() – return a blank data structure used when creating a new session.
• sessionSkeleton() – return the default session object.
• tempSkeleton() – return the default temporary workspace object.
• applySession(data, startTime)* – load a saved session into the application state.
• applyStyle(style)* – update the current visual style settings.
• reset() – clear the application state and return to a fresh session.
• finishUp(oldSession)* – finalise data import and initialise views.
• updateNetwork(hideSingletons) – refresh the network after data changes.

Node & Link Operations

• defaultNode() – generate a default node object.
• defaultLink() – generate a default link object.
• addNode(newNode, check) – add or merge a node in the current session.
• addLink(newLink, check) – add or merge a link in the current session.
• setNodeVisibility() – recompute node visibility based on current filters.
• setLinkVisibility() – recompute link visibility based on current filters.
• getVisibleNodes(copy) – return an array of currently visible nodes.
• getVisibleLinks(copy) – return an array of currently visible links.
• getVisibleClusters(copy) – return an array of currently visible clusters.

Computation Helpers

Most heavy computations are off‑loaded to Web Workers via WorkerComputeService.

• align(params) – align sequences using the selected algorithm.
• computeConsensus(nodes) – build a consensus sequence from provided nodes.
• computeConsensusDistances() – compute per‑node distance from the consensus sequence.
• computeAmbiguityCounts() – count ambiguous sites per sequence.
• computeLinks(subset) – compute pairwise genetic distances and populate links.
• computeTree() – compute a phylogenetic tree (NJ/UPGMA) from current data.
• computeDirectionality() – infer directionality by comparing tree paths.
• computeMST() – compute the minimum spanning tree and mark nn edges.
• computeNN() – mark nearest neighbour edges based on genetic distance.
• computeTriangulation() – infer missing edges via triangulation of the distance matrix.
• generateSeqs(idPrefix, count, snps, seed) – generate random test sequences.
• geoDM() – compute geographic distance matrix from lat/long data.
• tagClusters() – depth‑first search to assign cluster memberships.

Import/Export Utilities

• parseFASTA(text) – parse FASTA formatted text into node objects.
• unparseFASTA(nodes) – convert node sequences back to FASTA text.
• unparseMEGA(nodes) – export sequences in MEGA format.
• unparseDM(dm) – convert a distance matrix back to TSV.
• unparseSVG(svgNode) – serialise an SVG element to a string.
• blobifySVG(svgString, width, height, callback) – convert an SVG string to a downloadable Blob.
• processJSON(json, extension) – handle JSON/CSV file imports.
• exportHIVTRACE() – export the session in a format compatible with the HIVTRACE tool.

Map and View Helpers

• getMapData(type) – lazily load map/GeoJSON data used by map visualisations.
• loadLayout(component, parent) – load a GoldenLayout component configuration.
• launchView(view, callback) – programmatically open a visualisation tab.
• cacheLayout(contentItem) – store layout configuration in componentCache*.
• createNodeColorMap() – build a color mapping function for nodes.
• createLinkColorMap() – build a color mapping function for links.
• updateStatistics() – recompute statistics displayed in the UI.
• updateThresholdHistogram() – update the genetic distance histogram.

Miscellaneous

• watermark* – data encoded MicrobeTrace logo used on exported images.
• decoder* – TextDecoder instance used by various parsing functions.
• manifest* – parsed contents of package.json providing version info.
• mapData* – cached GeoJSON data loaded for map and globe views.

This list is not exhaustive but covers the primary entry points within CommonService and its associated helpers. Developers should consult the service source (src/app/contactTraceCommonServices/common.service.ts) and worker implementation (src/app/contactTraceCommonServices/worker-compute.service.ts) for full details on parameters and returned data types.