Using Continuous Color Palettes

⚠️ Feature in development: This feature is in development and is not yet available on the main MicrobeTrace site.

Continuous color ramps and color assignment files support three types of tasks:

1. Color nodes or links by a numeric field.
2. Apply the same continuous color ramp again from a CSV or TSV file.
3. Export a view with labeled color legends that do not cover the visualization.

Use case 1: Color nodes or links with a continuous ramp

Use this workflow when color should show the size of a numeric value, such as risk score, age, viral load, genetic distance, contact duration, or transmission probability.

Before you begin

• The node or link field should contain numbers or empty values.
• Text such as unknown makes Auto treat the field as categorical. Remove the text or explicitly choose Continuous when that option is available.
• Continuous node colors appear in 2D Network, Map, Bubble, Phylogenetic Tree, and Epi Curve.
• Continuous link colors appear in 2D Network and Map.

Steps

1. Load the node data and, if needed, the link data.
2. Open Settings > Styling.
3. Under Color Nodes By or Color Links By, select the numeric field.
4. Under Node Color Scale or Link Color Scale, select Auto (Continuous) or Continuous.
5. Under Domain, keep Automatic (full data) or select Custom bounds and enter the low and high values.
6. Change the color stops, select Add Stop, select Reverse, or choose a different Missing / invalid color as needed.
7. Set the color legend to Show, Dock, or Hide.

MicrobeTrace applies the ramp across the selected field. Values between stops are interpolated, and values outside a custom domain use the nearest endpoint color.

The legend identifies the field being displayed, for example, Node Color: Degree or Link Color: Distance. It also shows the numeric stops and the color used for missing or invalid values.

Use case 2: Apply a continuous color assignment file

Use this workflow when you want to reuse a specific node or link ramp without rebuilding it in the Styling panel.

Download Node Color Ramp Example (Right-click to save)

Download Link Color Ramp Example (Right-click to save)

Prepare the assignment file

Create a comma-separated (.csv) or tab-separated (.tsv) file. The first row contains the field name, color, and mode:

FieldName,color,mode

For a continuous ramp:

• The first header must exactly match a field in the loaded node or link data.
• Each value in the first column is a numeric color-stop position.
• Colors must use #RGB or #RRGGBB hexadecimal format.
• At least one data row must contain continuous in the mode column. The remaining mode cells can be empty.
• The file must contain at least two different numeric stops.
• The smallest and largest stops become the custom domain bounds.
• The rows do not need to be sorted; MicrobeTrace sorts the stops by value.
• Applying the file keeps the currently selected missing/invalid color.

Example node assignment file:

RiskScore,color,mode
5,#440154,continuous
35,#31688e,
60,#35b779,
96,#fde725,

Example link assignment file:

ContactMinutes,color,mode
5,#000004,continuous
45,#721f81,
180,#f1605d,
480,#fcfdbf,

Apply a node color assignment file

1. Open Settings > Styling.
2. Find Apply Color Assignment File in the node color section.
3. Select the CSV or TSV file.
4. Confirm that MicrobeTrace selects the field named in the first column and displays its continuous ramp.

Apply a link color assignment file

1. Open Settings > Styling.
2. Find Apply Link Color Assignment File in the link color section.
3. Select the CSV or TSV file.
4. Confirm that MicrobeTrace selects the field named in the first column and displays its continuous ramp.

If MicrobeTrace finds an invalid stop, color, mode, or field, it rejects the complete file and leaves the current colors unchanged.

Use case 3: Export a view with continuous color legends

Use this workflow when you want the exported visualization to explain its node and link colors.

Steps

1. Configure the node and link colors.
2. Set each color legend that should be included to Show or Dock.
3. Select Export Screen in the view toolbar.
4. Enter a filename and choose PNG or SVG.
5. Select Export.

MicrobeTrace places the visible legends beside the visualization instead of covering it. Each exported legend includes its node or link field label, the complete gradient and stop values, and the missing/invalid key. SVG exports also include an accessible title that describes the ramp.

Helpful controls

• Auto chooses continuous coloring when all populated field values are valid numbers; otherwise, it uses categorical coloring.
• Custom bounds keeps the same low and high values while filters, timelines, or visibility settings change.
• Add Stop adds an intermediate color to the ramp.
• Reverse reverses the stop colors without changing the numeric domain.
• Missing / invalid sets the fallback color for empty or nonnumeric values.
• Show opens a floating legend, Dock places it in the key tables panel, and Hide removes it from the screen and exports.
• Saving a MicrobeTrace style or session preserves the continuous node and link settings.

Categorical color assignment files

Existing categorical assignment files continue to work.

• A file without a mode column uses categorical assignment behavior.
• A file can explicitly use categorical in the mode column.
• Categorical node colors, categorical link colors, continuous node ramps, and continuous link ramps are saved independently.
• iTOL color strip files remain categorical. Use CSV or TSV for a continuous ramp.

Quick troubleshooting

• The field is not found: Confirm that the first column header exactly matches a field in the loaded node or link data.
• Continuous is unavailable: Confirm that the field contains finite numbers or empty values. Remove text values or use categorical coloring.
• The mode is missing: Add a mode column and enter continuous in at least one data row.
• The file reports conflicting modes: Use the same mode in every populated mode cell.
• A stop is invalid: Use a finite number such as 0, 12.5, -4, or 1e3.
• The ramp needs more stops: Add at least two different numeric stop values.
• A color is invalid: Use a three- or six-digit hexadecimal color beginning with #.
• A stop appears twice with different colors: Remove the duplicate or use the same color for both rows.
• An iTOL file does not create a ramp: iTOL color strip files are categorical; use a CSV or TSV assignment table.