Workflow

Basic workflow

A typical workflow consists of preparing occurrence data, optionally adding metadata, building or loading a phylogenetic tree, and generating the linked tree-map visualization.

1 – Format GBIF occurrence data

python -m phylocartoplot.preprocessing.format_gbif_data \
    gbif_occurrences.csv \
    node_names.csv

2 – Add trait metadata

python -m phylocartoplot.preprocessing.add_metadata \
    gbif_occurrences_formatted.csv \
    trait_metadata.csv

3 – Build a phylogenetic tree

python -m phylocartoplot.preprocessing.build_phylogenetic_tree \
    sequences.fasta

4 – Visualize the phylogeny and geographic data

from phylocartoplot.visualisation.tree_to_map_raster import PhyloCartoPlotter

plotter = PhyloCartoPlotter(
    nwk_file="sequences_tree.nwk",
    gps_file="coordinates.csv",
    offset_file="offsets.csv",
    raster_file="enviro.tif",
    raster_band=1,
)

plotter.plot()
plotter.save(output_dir="output")

Raster input is optional. PhyloCartoPlot can also generate linked phylogenetic and geographic visualizations without an environmental raster.

Input data

PhyloCartoPlot works with standard biological and geospatial data formats.

Phylogenetic tree

Phylogenetic trees are supplied in Newick (.nwk) format.

Trees may be generated externally or created from aligned sequence data using:

python -m phylocartoplot.preprocessing.build_phylogenetic_tree sequences.fasta

Geographic occurrence data

Geographic occurrence data are supplied as CSV files containing taxon or specimen identifiers and geographic coordinates.

GBIF occurrence exports can be reformatted using:

python -m phylocartoplot.preprocessing.format_gbif_data

Trait metadata

Additional quantitative traits can be associated with occurrence records and represented using a continuous color scale in the visualization.

Examples include:

• caffeine concentration;
• environmental measurements;
• morphological traits;
• ecological measurements.

Raster data

Environmental raster data can be supplied as GeoTIFF files.

Examples include:

• elevation;
• precipitation;
• temperature;
• vegetation indices;
• other continuous environmental variables.

Raster support is provided through Rasterio.

Trait-based visualization

PhyloCartoPlot can apply the same trait-based color encoding to phylogenetic elements, mapped occurrences, and connecting lines.

This allows phylogenetic relationships, geographic distributions, and quantitative traits to be examined together within a single figure.