Bioinformatics Visualization

iTOL Dataset Formats and Troubleshooting

Choosing the Right Dataset Type

DATASET_BINARY (Recommended for markers/symbols):

• More reliable than DATASET_SYMBOL
• All species must be listed with binary values (0 or 1)
• Simpler format, better iTOL compatibility
• Use for: presence/absence markers, technology indicators, categorical highlights

Format example:

DATASET_BINARY
SEPARATOR TAB

DATASET_LABEL	CLR Technology
COLOR	#ff0000

LEGEND_TITLE	Sequencing Technology
LEGEND_SHAPES	2
LEGEND_COLORS	#ff0000
LEGEND_LABELS	CLR (PacBio)

FIELD_SHAPES	2
FIELD_COLORS	#ff0000
FIELD_LABELS	CLR

DATA
Species_name_1	1
Species_name_2	0
Species_name_3	1

DATASET_SYMBOL (Less reliable):

• Can be finicky about format
• Per-species shape/size/color specifications complex
• May not display correctly even with valid format
• Avoid unless BINARY doesn't meet needs

DATASET_COLORSTRIP (Good for gradients):

• Reliable for color gradients (e.g., temporal data, continuous values)
• Only species with data need to be listed
• Good for non-binary categorical or continuous data

Common iTOL Errors and Fixes

Error: "Unknown variable 'SYMBOL_SHAPE'"

• Cause: Mixing global symbol settings with per-species data
• Fix: Switch to DATASET_BINARY format

Error: "Invalid color '1' for node X"

• Cause: DATASET_SYMBOL data format mismatch
• Fix: Use DATASET_BINARY instead, format: species<tab>0_or_1

Symbols not appearing on tree:

• Likely cause: DATASET_SYMBOL format issues
• Fix: Convert to DATASET_BINARY
• Verify: Check that all species in config exist in tree file

Species Name Compatibility

Critical: Species names must match exactly between tree and annotation files

Common issues:

1. Case sensitivity: "Alca Torda" vs "Alca_torda"
2. Spaces vs underscores: Always use underscores in tree format
3. Subspecies names: Handle three-part names carefully

Fix for case sensitivity:

# Convert scientific names to tree format with case normalization
df['species_tree'] = df['scientific_name'].str.replace(' ', '_')
# Fix uppercase after underscore (Alca_Torda -> Alca_torda)
df['species_tree'] = df['species_tree'].str.replace(
    r'_([A-Z])',
    lambda m: '_' + m.group(1).lower(),
    regex=True
)

Validation pattern:

# Always validate species compatibility
import re

# Extract species from tree
with open('tree.nwk') as f:
    tree_content = f.read()
tree_species = set(re.findall(r'([A-Z][a-z]+_[a-z]+)', tree_content))

# Check config species
config_species = set(df['species_tree'])
missing = config_species - tree_species

if missing:
    print(f"Species in config but not in tree: {missing}")

Color Gradients for Temporal Data

Effective color schemes:

Temporal progression (old → new):

• Light Yellow → Dark Red (ColorBrewer YlOrRd)
• Clearly shows progression from past to present
• Example: #ffffcc (2019) → #b10026 (2025)

Avoid:

• Blue → Yellow → Red (confusing middle point)
• Diverging palettes for sequential data

ColorBrewer palettes for sequential data:

• YlOrRd: Yellow-Orange-Red (temporal, intensity)
• YlGn: Yellow-Green (growth, vegetation)
• PuBuGn: Purple-Blue-Green (water, depth)

Debugging Workflow

1. Generate config file
2. Upload to iTOL (https://itol.embl.de)
3. If errors: Save error messages to file
4. Check format: BINARY vs SYMBOL vs COLORSTRIP
5. Validate species names: Match against tree file
6. Test with minimal dataset: 5-10 species first
7. Switch formats if needed: SYMBOL → BINARY usually works

Related Skills

• data-visualization: General visualization best practices
• bioinformatics/fundamentals: Core bioinformatics concepts
• bioinformatics/phylogenetics: Phylogenetic analysis workflows