PBDBMakie — API Reference

PBDBMakie

Unconditional compile-time submodule of PaleobiologyDB.

This submodule is always present, regardless of whether a Makie backend is loaded. It declares the public API for taxonomy-tree visualization and the PBDB-PhyloPic bridge without depending on Makie or any optional package.

When a Makie backend is loaded, the PBDBMakieExt extension adds concrete method implementations to these declarations through normal Julia dispatch. TaxonomyTreePlot is not declared here because Makie's @recipe macro requires Makie to be loaded before that plot type can exist.

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

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; show_leaf_labels = 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...,
) -> Makie.FigureAxisPlot

Create a standalone Makie figure containing a dendrogram of tree.

Returns a Makie.FigureAxisPlot object containing the figure, axis, and plot:

fig, ax, plt = taxonomytreeplot(tree; show_leaf_labels = 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.PBDBMakie

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

# Basic dendrogram with leaf labels
fig, ax, plt = taxonomytreeplot(tree; show_leaf_labels = true)
save("carnivora_families.png", fig)

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

# Custom figure and axis sizes
fig3, ax3, plt3 = 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...,
) -> Makie.FigureAxisPlot

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, show_leaf_labels, 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.PBDBMakie

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

fig2, ax2, plt2 = 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; show_leaf_labels = 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_leaf_phylopic!(
    ax::Makie.Axis,
    tree::TaxonomyTree,
    xs::AbstractVector{<:Real},
    ys::AbstractVector{<:Real};
    anchor::Symbol                 = :leaf,
    align::Bool                    = false,
    column_x::Union{Nothing, Real} = nothing,
    leaf_label_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 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_leaf_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 :leaf) — how to compute the x-anchor for each leaf:
  • :leaf — the leaf node's x coordinate xs[v]
  • :leaf_label_origin — xs[v] + leaf_label_xoffset
• leaf_label_xoffset (default 0.0) — label-start offset used when anchor = :leaf_label_origin. Set to match the leaf_label_xoffset attribute of the corresponding TaxonomyTreePlot (recipe default 0.1).

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 (placeholder glyph image), :error (throw).

Returns

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

Examples

using CairoMakie
using PaleobiologyDB
using PaleobiologyDB.Taxonomy
using PaleobiologyDB.PBDBMakie

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

# Silhouettes 1.0 data unit right of each leaf
augment_leaf_phylopic!(ax, plt; xoffset = 1.0)

# Anchor at leaf-label origin so silhouettes appear after the text
augment_leaf_phylopic!(ax, plt;
    anchor             = :leaf_label_origin,
    leaf_label_xoffset = 0.1,   # match recipe leaf_label_xoffset attribute
    xoffset            = 0.5,
)

# Aligned column
augment_leaf_phylopic!(ax, plt; align = true, xoffset = 0.2)

See also leaf_positions, taxonomytreeplot.

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

Convenience overload of augment_leaf_phylopic! that reads tree and layout from a TaxonomyTreePlot. When anchor = :leaf_label_origin and no fixed column_x override is requested, this overload reuses the plotted leaf labels so the explicit two-step overlay follows the same label-aware placement contract as show_phylopic = true.

ax must belong to the same Makie parent scene as p. If they differ, this method throws ArgumentError instead of silently attaching the overlay to a different scene than the caller requested.

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

Examples

fig, ax, plt = taxonomytreeplot(taxon_subtree("Panthera"))
augment_leaf_phylopic!(ax, plt; xoffset = 1.0)

leaf_positions(p::TaxonomyTreePlot) -> NamedTuple

Extract leaf-node coordinates from a TaxonomyTreePlot object.

Convenience overload of leaf_positions that reads the tree, ladderize, and row_spacing attributes 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 CairoMakie
using PaleobiologyDB
using PaleobiologyDB.Taxonomy
using PaleobiologyDB.PBDBMakie

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

See also leaf_positions, augment_leaf_phylopic!.