TaxonomyMakie — API Reference

TaxonomyMakie

Package extension for PaleobiologyDB.jl that activates when both Makie and PhyloPicMakie are loaded. Provides the full tree-visualization API (moved from the former TaxonomyTreeMakie source submodule) and the PBDB–PhyloPic bridge (vendored from the former PhyloPicPBDB source submodule).

Activated by:

using CairoMakie  # or any Makie backend
using PaleobiologyDB

Public API — tree visualization:

Public API — PBDB–PhyloPic bridge (re-exported from PhyloPicPBDB):

TaxonomyTreePlot

Makie plot type for rendering a TaxonomyTree as a rectangular dendrogram. Produced by taxonomytreeplot (standalone figure) or taxonomytreeplot! (existing axis).

Attributes

Examples

using PaleobiologyDB, PaleobiologyDB.Taxonomy
using CairoMakie
using PaleobiologyDB.TaxonomyTreeMakie

tree = taxon_subtree("Carnivora"; leaf_rank = "family")

# Add to an existing Makie axis
fig = Figure(size = (900, 600))
ax  = Axis(fig[1, 1])
taxonomytreeplot!(ax, tree; showtips = true, color_by_rank = true)
set_rank_axis_ticks!(ax, tree)
display(fig)

See also taxonomytreeplot, taxonomytreeplot!, set_rank_axis_ticks!.

taxonomytreeplot(
    tree::TaxonomyTree;
    show_rank_ticks::Bool = true,
    figure_kwargs::NamedTuple = (;),
    axis_kwargs::NamedTuple = (;),
    kwargs...,
) -> Tuple{Makie.Figure, Makie.Axis, TaxonomyTreePlot}

Create a standalone Makie figure containing a dendrogram of tree.

Returns (fig, ax, plot_object), which can be destructured:

fig, ax, p = taxonomytreeplot(tree; showtips = true)
display(fig)
save("tree.png", fig)

Arguments

• tree: the TaxonomyTree to visualise.
• show_rank_ticks (default true): when true, calls set_rank_axis_ticks! to label the x-axis with rank names.
• figure_kwargs: keyword arguments forwarded to Makie.Figure(; ...).
• axis_kwargs: keyword arguments forwarded to Makie.Axis(; ...).
• All remaining keyword arguments are forwarded to TaxonomyTreePlot attributes (see taxonomytreeplot!).

Examples

using PaleobiologyDB, PaleobiologyDB.Taxonomy
using CairoMakie
using PaleobiologyDB.TaxonomyTreeMakie

tree = taxon_subtree("Carnivora"; leaf_rank = "family")

# Basic dendrogram with tip labels
fig, ax, p = taxonomytreeplot(tree; showtips = true)
save("carnivora_families.png", fig)

# Coloured by rank, ladderized
fig2, ax2, p2 = taxonomytreeplot(tree;
    color_by_rank = true,
    ladderize     = true,
    showtips      = true,
)

# Custom figure and axis sizes
fig3, ax3, p3 = taxonomytreeplot(tree;
    figure_kwargs = (; size = (1200, 800)),
    axis_kwargs   = (; title = "Carnivora families", yreversed = false),
)

See also taxonomytreeplot!, TaxonomyTreePlot, set_rank_axis_ticks!.

taxonomytreeplot(
    taxon_name::AbstractString;
    leaf_rank::Union{AbstractString, Nothing} = nothing,
    strict_leaf_rank::Bool = true,
    show_rank_ticks::Bool = true,
    figure_kwargs::NamedTuple = (;),
    axis_kwargs::NamedTuple = (;),
    kwargs...,
) -> Tuple{Makie.Figure, Makie.Axis, TaxonomyTreePlot}

Convenience method: look up taxon_name in the PBDB, build its subtree, and render it as a dendrogram in a standalone figure.

Calls taxon_subtree with leaf_rank and strict_leaf_rank, then delegates to taxonomytreeplot. All remaining keyword arguments (recipe attributes such as ladderize, showtips, row_spacing, show_phylopic, etc.) are forwarded unchanged. See TaxonomyTreePlot for the full attribute reference.

Arguments

• taxon_name: PBDB taxon name (e.g. "Carnivora", "Canidae").
• leaf_rank: prune the subtree at this rank (e.g. "family", "genus"). nothing (default) keeps all descendants.
• strict_leaf_rank: when true (default), only taxa whose rank exactly matches leaf_rank become leaves; pass false to also include shallower terminals.
• show_rank_ticks, figure_kwargs, axis_kwargs: forwarded to taxonomytreeplot.

Examples

using PaleobiologyDB, CairoMakie
using PaleobiologyDB.Taxonomy.TaxonomyTreeMakie

fig, ax, p = taxonomytreeplot("Carnivora"; leaf_rank = "family")
save("carnivora.png", fig)

fig2, _, _ = taxonomytreeplot("Canidae"; leaf_rank = "genus", ladderize = true, row_spacing = 1.5)

set_rank_axis_ticks!(ax::Makie.Axis, tree::TaxonomyTree) -> Nothing

Configure the x-axis tick labels on ax to display rank names at their dendrogram x-depth positions.

Only ranks that are present in tree and whose depth is known (i.e. present in _RANK_DEPTH) are labelled. Tick labels are rotated 45° to prevent overlap.

Typically called immediately after taxonomytreeplot!:

p = taxonomytreeplot!(ax, tree; showtips = true)
set_rank_axis_ticks!(ax, tree)

taxonomytreeplot (standalone) calls this automatically when show_rank_ticks = true (the default).

Arguments

• ax: the Makie.Axis on which to set ticks.
• tree: the TaxonomyTree whose ranks determine the tick positions.

augment_tip_phylopic!(
    ax::Makie.Axis,
    tree::TaxonomyTree,
    xs::AbstractVector{<:Real},
    ys::AbstractVector{<:Real};
    anchor::Symbol                 = :tip,
    align::Bool                    = false,
    column_x::Union{Nothing, Real} = nothing,
    tip_xoffset::Real              = 0.0,
    placement::Symbol              = :left,
    xoffset::Real                  = 0.0,
    yoffset::Real                  = 0.0,
    glyph_size::Real               = 0.4,
    aspect::Symbol                 = :preserve,
    rotation::Real                 = 0.0,
    mirror::Bool                   = false,
    image_rendering::Symbol        = :thumbnail,
    on_missing::Symbol             = :skip,
) -> Nothing

Add one PhyloPic silhouette per leaf tip of tree to ax.

This is the primary tree-aware overlay API. It computes anchor positions from the dendrogram layout and delegates all rendering to augment_phylopic!.

See also the convenience overload augment_tip_phylopic! which reads tree and layout directly from a TaxonomyTreePlot.

Arguments

• ax: the Makie.Axis to annotate.
• tree: source TaxonomyTree.
• xs, ys: layout vectors from _compute_dendrogram_layout, one value per vertex in tree.graph.

Keyword arguments

Anchor selection

• anchor (default :tip) — how to compute the x-anchor for each leaf:
  • :tip — the leaf node's x coordinate xs[v]
  • :tip_label_origin — xs[v] + tip_xoffset
• tip_xoffset (default 0.0) — label-start offset used when anchor = :tip_label_origin. Set to match the tip_xoffset attribute of the corresponding TaxonomyTreePlot (recipe default 0.2).

Alignment

• align (default false) — when true, all silhouettes share a single x-column. The column x equals maximum(anchors) unless column_x is set.
• column_x (default nothing) — explicit x position for the alignment column; ignored when align = false.

Rendering (forwarded to augment_phylopic!)

• placement (default :left) — anchor position on the glyph relative to the data coordinate. One of :center, :left, :right, :top, :bottom, :topleft, :topright, :bottomleft, :bottomright.
• xoffset (default 0.0) — additional rightward shift in data units applied after anchoring. This is the parameter to tune when the silhouettes overlap the text labels.
• yoffset (default 0.0) — additional vertical shift in data units.
• glyph_size (default 0.4) — half-height of each silhouette in data units (total height = 2 × glyph_size).
• aspect (default :preserve) — :preserve maintains the original image aspect ratio; :stretch renders as a square.
• rotation (default 0.0) — clockwise rotation in degrees (multiples of 90° only).
• mirror (default false) — flip the silhouette horizontally.
• image_rendering (default :thumbnail) — PhyloPic image variant to fetch.
• on_missing (default :skip) — behaviour when no PhyloPic image is found: :skip (omit silently), :placeholder (grey rectangle), :error (throw).

Returns

Nothing. Silhouettes are added as side-effects to ax.

Examples

using PaleobiologyDB, PaleobiologyDB.Taxonomy, CairoMakie
using CairoMakie
using PaleobiologyDB

tree = taxon_subtree("Panthera")
fig, ax, p = taxonomytreeplot(tree)

# Silhouettes 1.0 data unit right of each leaf tip
augment_tip_phylopic!(ax, p; xoffset = 1.0)

# Anchor at tip-label origin so silhouettes appear after the text
augment_tip_phylopic!(ax, p;
    anchor      = :tip_label_origin,
    tip_xoffset = 0.2,   # match recipe tip_xoffset attribute
    xoffset     = 0.5,
)

# Aligned column
augment_tip_phylopic!(ax, p; align = true, xoffset = 0.2)

See also tip_positions, taxonomytreeplot.

augment_tip_phylopic!(ax::Makie.Axis, p::TaxonomyTreePlot; kwargs...) -> Nothing

Convenience overload of augment_tip_phylopic! that reads tree and layout from a TaxonomyTreePlot.

All keyword arguments are forwarded unchanged to the primary method. See augment_tip_phylopic! for full documentation.

Examples

fig, ax, p = taxonomytreeplot(taxon_subtree("Panthera"))
augment_tip_phylopic!(ax, p; xoffset = 1.0)

tip_positions(tree::TaxonomyTree, xs, ys) -> NamedTuple

Extract leaf-tip coordinates from a pre-computed dendrogram layout.

Returns a NamedTuple with fields:

• vertices::Vector{Int} — leaf vertex indices into tree.graph
• names::Vector{String} — accepted taxon name for each leaf
• x::Vector{Float64} — x coordinate in data units for each leaf
• y::Vector{Float64} — y coordinate in data units for each leaf

All four vectors are the same length and are aligned by index.

xs and ys are the layout vectors returned by _compute_dendrogram_layout.

Examples

using PaleobiologyDB, PaleobiologyDB.Taxonomy
using CairoMakie
using PaleobiologyDB.TaxonomyTreeMakie

tree = taxon_subtree("Panthera")
fig, ax, p = taxonomytreeplot(tree)
tips = tip_positions(p)   # convenience overload
# tips.names, tips.x, tips.y  — one entry per leaf

See also augment_tip_phylopic!.

tip_positions(p::TaxonomyTreePlot) -> NamedTuple

Extract leaf-tip coordinates from a TaxonomyTreePlot object.

Convenience overload of tip_positions that reads the tree and ladderize attribute from p and recomputes the dendrogram layout.

Returns a NamedTuple with fields:

• vertices::Vector{Int} — leaf vertex indices into p[:taxonomytree][].graph
• names::Vector{String} — accepted taxon name for each leaf
• x::Vector{Float64} — x coordinate in data units for each leaf
• y::Vector{Float64} — y coordinate in data units for each leaf

Examples

using PaleobiologyDB, PaleobiologyDB.Taxonomy, CairoMakie
using CairoMakie
using PaleobiologyDB

fig, ax, p = taxonomytreeplot(taxon_subtree("Panthera"))
tips = tip_positions(p)
# tips.names  — Vector{String} of leaf taxon names
# tips.x      — x positions in data space
# tips.y      — y positions in data space

See also tip_positions, augment_tip_phylopic!.