Color Assignment File

Node Color Assignment Files

⚠️ Feature in development

Color assignment files are currently under development and are not yet available on the main MicrobeTrace site.

Node color assignment files let you assign specific colors to values in a node-data field. For example, you can consistently display a lineage, profession, location, MLST type, or node ID with the same color across datasets and sessions.

Apply a color assignment file

1. Load and launch your data in MicrobeTrace.
2. Open Global Settings.
3. Select the Styling tab.
4. Under Apply Color Assignment File, select your file.

MicrobeTrace reads the node field declared by the file and updates Color Nodes By automatically. You do not need to select the field first.

The declared field must exist as a colorable node field in the current dataset. Field matching is case-insensitive and ignores spaces, underscores, and punctuation. Common ID labels such as ID, isolate, isolate ID, sample ID, and node ID are recognized as the MicrobeTrace node ID field.

Accepted file types

The importer reads UTF-8 plain text and recognizes the format from the file contents rather than the filename extension. Common extensions include:

• .csv for comma-delimited tables
• .tsv or .txt for tab-delimited tables
• .txt for iTOL color-strip files

Files must use one of the two formats below.

Comma- or tab-delimited table

A simple assignment table must:

• Be comma-delimited or tab-delimited.
• Include a header row.
• Use the first column for the node values being colored.
• Name the first column after the corresponding node field in MicrobeTrace.
• Include a column named color. The header is case-insensitive.
• Provide a value and color on every assignment row.

Additional columns are allowed and ignored by the color importer.

CSV example

Lineage,color
B.1.617.2,#123456
B.1.617.1,#abcdef
B.1.1.7,#fedcba

This file sets Color Nodes By to Lineage. The first column contains the lineage values, and the color column contains their assigned colors.

Tab-delimited example

Profession	color
Healthcare	#3366cc
Education	#dc3912
Service industry	#ff9900

Values containing the delimiter should be quoted according to standard CSV or TSV rules.

iTOL color-strip format

MicrobeTrace also accepts the iTOL DATASET_COLORSTRIP format.

An iTOL assignment file should contain:

• DATASET_COLORSTRIP as its first non-comment content line.
• A SEPARATOR declaration using SPACE, TAB, or COMMA.
• A DATASET_LABEL naming the MicrobeTrace node field to color by.
• A DATA line followed by assignment rows.
• Three values per assignment row: sample ID, color, and field value.

Space-delimited example

DATASET_COLORSTRIP
SEPARATOR SPACE
DATASET_LABEL Lineage
COLOR #00ff00
DATA
SAMPLE-001 #123456 B.1.617.2
SAMPLE-002 #abcdef B.1.617.1
SAMPLE-003 #fedcba FUTURE.LINEAGE

This file sets Color Nodes By to Lineage.

For fields other than node ID, MicrobeTrace uses the first column to match a row to a node in the current dataset. When a matching node is found, the assignment is associated with that node's value for the field named by DATASET_LABEL. If no matching node currently exists, the third-column value is retained so it can be used with future data.

When DATASET_LABEL identifies the node ID field, the first-column sample ID is used as the assignment value.

Blank lines and lines beginning with # are ignored in iTOL files. With TAB or COMMA, each data row must contain exactly three fields; quote a value if it contains the separator.

If an older iTOL file does not contain DATASET_LABEL, MicrobeTrace uses the currently selected Color Nodes By field. If no field is selected, the file cannot be applied.

Color values

Colors must be hexadecimal values in one of these forms:

• Three digits: #09f
• Six digits: #0099ff

Three-digit colors are expanded to six digits, and stored colors are normalized to lowercase. Named colors such as red and formats such as rgb(255, 0, 0) are not accepted.

Validation and duplicate values

MicrobeTrace checks the entire file before changing the visualization.

• If every row is valid, the assignments are applied and Color Nodes By changes to the field declared by the file.
• If any row is invalid, none of the file's assignments are applied, and the existing node-color field and colors remain unchanged.
• Repeating a value with the same color is allowed.
• Assigning different colors to the same value in one file causes the file to be rejected.
• A field that is not available in the current dataset causes the file to be rejected.

Importing another valid file for the same field updates matching assignments and preserves existing assignments for values not included in the new file.

Missing and future values

A color assignment file does not need to cover every value in the current dataset. Values without an explicit assignment keep their existing MicrobeTrace colors.

Assignments for values that are not present in the current dataset are retained. They will be available if matching values appear in data loaded later in the same session or in a restored saved session.

What MicrobeTrace retains

MicrobeTrace reads and applies the file locally. The original color assignment file, its full contents, and its filename are not stored as a MicrobeTrace data file.

MicrobeTrace retains only the parsed value-to-color assignments, grouped by node field, in the active session. These assignments:

• Remain available when you switch Color Nodes By to another field and back.
• Are included when you save a .microbetrace session.
• Are restored when that saved session is opened again.

If you close or reset MicrobeTrace without saving the session, you will need to import the assignment file again.