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 phylogeoplot.preprocessing.format_gbif_data \
    gbif_occurrences.csv \
    node_names.csv

2 – Add trait metadata

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

3 – Build a phylogenetic tree

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

4 – Visualize the phylogeny and geographic data

from phylogeoplot.visualisation.tree_to_map_raster import PhyloGeoPlotter

plotter = PhyloGeoPlotter(
    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. PhyloGeoPlot can also generate linked phylogenetic and geographic visualizations without an environmental raster.

Input data

PhyloGeoPlot 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 phylogeoplot.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 phylogeoplot.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

PhyloGeoPlot 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.