Contributing

If you'd like to help but can't code, we could definitely use some help documenting features!

If you'd like to make a contribution to the MicrobeTrace code base, please review the CDC's Contribution Guidelines.

Architecture

MicrobeTrace is a static web application. Accordingly, everything is written in HTML, CSS, and Javascript. There is a nodejs-based express server designed for development, testing, and deploying to Heroku, but this is purely a convenience script and not required to deploy or use MicrobeTrace.

Requirements

To develop, you're going to need a computer with:

• git
• node and npm
• yarn (optional, but preferred)

Getting Started

To jump right to development, Fork the repository. Once Github finishes, open up your terminal emulator, cd over to your favorite projects directory, and clone your fork of the repository. i.e., run

git clone https://github.com/<your-github-username>/MicrobeTRACE.git

This will download this repo. Next, enter the repository:

cd MicrobeTrace

... and install the dependencies:

yarn

(Alternately, if you didn't follow my advice and install yarn, run this:)

npm install

This will download all of the development dependencies for this project. Note that this will download several hundred megabytes. Luckily, the dev dependencies are much, much larger than the prod dependencies, so the distribution file that should be output will only take up a few tens of megabytes.

Next, issue the following command to your command prompt:

yarn start #or npm start

This will launch the server, but not your browser. Open your preferred browser and go to http://localhost:5000/ to see MicrobeTrace.

Design

The basic design of MicrobeTrace works like this: first, the browser loads the index.html file, like every other static file load at the root of a directory. That file contains the core DOM for the app, as well as link and script tags for all dependencies used by more than one widget in the app. However, most importantly, it contains an in-line Javascript which sets up this MicrobeTrace session. It also sets up the DOM components which must be procedurally constructed, rather than statically interpreted. Finally, it loads the contents of components/files.html

Each file in the components/ directory mirrors the structure of index.html. At the top are the links to the stylesheets required by the view, followed by the DOM content, followed by an in-line Javascript to set up the view's interactive features.

Note how the files in the components/ directory are not complete HTML documents by themselves. They aren't intended to be loaded in independent windows, but to loaded into panes within the same window.

Getting your feet wet

1. Check out what's going on in the issues. Try picking a feature request and seeing if you can implement it.
2. Testing - Like most good projects, we started with every intention of following best practices, and utterly failed to do so. This is never more clear than in our testing regime, which is (almost) non-existent.
3. Documentation - There's this Wiki, the Wiki from MicrobeTrace Classic, and the User Manual. It's all a bit disorganized.
4. Branding - Make a non-terrible website, please.

Diving in headfirst

Full disclosure: This project does not adhere to anything close to a set of best-practices. If you're interested in paying down some technical debt, here are some good places to start.

1. The DOM Architecture - This is a biggie. Right now, this project is mostly powered by jQuery spaghetti. It works if you (the developer) catch all the edge cases, but there are a lot of things that can go wrong. The exception to this is the table view, which is powered by Vue.js. This could just as easily be React, Angular 2, Moon, backbonejs, <whatever's popular now>, etc... Basically, we should probably transition views away from jQuery towards more MV*. Since we already have one example using Vue, that should probably be the framework we adopt, but we don't have enough committed to it to fight too hard if there's a highly compelling reason to adopt one of the others.
2. The UI - I'm no UX designer. I like to make things that look clean and friendly, but it's easy to take pot-shots at UI design without having any substantive criticism, so a lot of people do. Accordingly, I don't have a strong set of beliefs about whether the UI is good or not. My suspicion is not, but changing that is hard, when this was the best I could do to begin with. If you can take Bootstrap 4 and do amazing things with it, be my guest.
3. The Algorithm - We're computing a distance matrix, which is an O(kN^2) operation, where N is the number of sequences and k is the length of the sequences. However, all we need is actually to know whether any two nodes are within some threshold of each other, not the exact distance. Accordingly, we may be able to compute a consensus sequence and distance from each node to the consensus. Then, in lieu of computing each pairwise distance, we can compute the difference and sum of their consensus distances, and if that range covers the default threshold value, only then do we know we need to compute the actual genetic distance. (Huge Hat tip to @Sergey-Knyazev for designing this scheme). Now we just need to implement it.
4. The Output - The network is rendered to the browser using D3, generating SVG. However, SVG is extremely costly for large networks (>1e4 elements). We should transition to a blend of SVG (for selection identifiers) and Canvas (for everything else) to keep the DOM from dragging.

Other stuff

There are a few especially odd dependencies I should mention:

tn93.js

This is a javascript port I (Tony Boyles) wrote of libtn93, itself a C port of TN93 implementation used in the original HIVTrace. An earlier version of this project used hivtrace along with NetworkX to compute a bounded minimum spanning tree of tn93 distances. Unfortunately, this architecture proved much too cumbersome to ship with a viable product. The javascript alternative has its downsides (most conspicuously, it's slower than the C version). However, the Javascript solution is comparatively quick (given that it's performing an O(n^2) operation and there's literally nothing we can do about that).

Anyway, I've maintained tn93.js in a separate repository. It works well, but its much slower than the version that was transpiled from C to WebAssembly. I found the C interface to be failure-prone, but we might reconsider using it at some point in the future.

bioseq.js

This is the library that MicrobeTrace uses for gapped alignments. I didn't code it originally, but I added the scaffolding to make it work in Node and in Browser, and published it on NPM. It's generally fine, but you should know what it is (just in case).

NtSeq

This is the library that MicrobeTrace uses for ungapped alignments. It's blisteringly fast because it uses binary encoding and bitwise comparisons for nucleotides. Sadly, it doesn't do much else. We should really extend it to subsume the task of the above two libraries. I believe we could gain a substantial speed advantage.