feat: add base pair proportional scaling to spine

[jazi2018]

Overview

Nodes in the spine now scale in length proportional to the number of base pairs they contain. A desired spine width (TARGET_SPINE_WIDTH) determines how each node is scaled. OFF_SPINE_MIN_WIDTH_FRACTION determines the minimum width of nodes which are off the assembly spine. Both are constants within the file. This could be adjusted in future work.

adaptagrams_converter.py

Relatively minimal changes. Keeps track of a few extra variables (_bp_scale is the most relevant) to manage the scaling of the spine.

_node_width() was modified to scale nodes using TARGET_SPINE_WIDTH and OFF_SPINE_MIN_WIDTH_FRACTION, or the legacy method if bp scaling is disabled in the request.

_spine_width() and _spine_segment() are new functions for scaling specifically the spine. They are utilized in seed_linear_layout().

Also notable is spine_report(). This attaches info about the linearized assembly to the response. This enables debugging, but also allows the frontend to recognize dragged & dropped files as linear and correctly label the spine.

main.py

bp_scaled_spine has been added as a parameter to the /json endpoint, and function calls have been updated to account for this. A spine report is also included to the response, as previously mentioned.

Future work

Currently, all spines are scaled to TARGET_SPINE_WIDTH, so a megabase region and a kilobase region would visually have the same spine length. In the future, this will probably be scaled hyperbolically or logarithmically, but I wanted to make the change available ASAP.

[jazi2018]

Added scaling of target spine width. Uses a power law, shown below:

$\text{total width} = \text{ref width (2000)} \times \left(\frac{\text{total bp of spine}}{\text{ref bp (100 kb)}}\right)^{\alpha}$

Where $\alpha$ is currently set to $0.5$. An $\alpha$ of $1$ would represent 1:1 scaling between basepairs and spine length, and an $\alpha$ of $0$ would set the length of every spine to $2000$ regardless of number of basepairs.

If, in practice, small loci are difficult to read because they are scaled too small, a padding could be added to smooth out the scaling in the low end, like this:

$\text{total width} = \text{ref width (2000)} \times \left(\frac{\text{total bp of spine}\mathbf{+ padding (e.g. 5 kb)}}{\text{ref bp (100 kb)}}\right)^{\alpha}$

This should let big loci have more room to display structure than small loci, without getting outrageously big. All of these parameters are tunable!