# Visualization Guide

## Overview

taxdiv provides 7 plot types built on ggplot2, each designed to answer a specific analytical question. All plot functions return ggplot objects that can be further customized.

    library(taxdiv)

    # Mediterranean forest community
    community <- c(
      Quercus_coccifera    = 25,
      Quercus_infectoria   = 18,
      Pinus_brutia         = 30,
      Pinus_nigra          = 12,
      Juniperus_excelsa    = 8,
      Juniperus_oxycedrus  = 6,
      Arbutus_andrachne    = 15,
      Styrax_officinalis   = 4,
      Cercis_siliquastrum  = 3,
      Olea_europaea        = 10
    )

    tax_tree <- build_tax_tree(
      species = names(community),
      Genus   = c("Quercus", "Quercus", "Pinus", "Pinus",
                  "Juniperus", "Juniperus", "Arbutus", "Styrax",
                  "Cercis", "Olea"),
      Family  = c("Fagaceae", "Fagaceae", "Pinaceae", "Pinaceae",
                  "Cupressaceae", "Cupressaceae", "Ericaceae", "Styracaceae",
                  "Fabaceae", "Oleaceae"),
      Order   = c("Fagales", "Fagales", "Pinales", "Pinales",
                  "Pinales", "Pinales", "Ericales", "Ericales",
                  "Fabales", "Lamiales")
    )

## Quick Reference

Plot | Function | Question it answers
--- | --- | ---
Taxonomic Tree | `plot_taxonomic_tree()` | How are species related?
Heatmap | `plot_heatmap()` | Which species pairs are closest/farthest?
Bubble Chart | `plot_bubble()` | Which species contribute most to diversity?
Radar Chart | `plot_radar()` | How do communities compare across all indices?
Iteration Plot | `plot_iteration()` | How stable is pTO across resampling?
Rarefaction Curve | `plot_rarefaction()` | Is my sampling effort sufficient?
Funnel Plot | `plot_funnel()` | Is my community’s AvTD/VarTD significant?

## 1. Taxonomic Tree (Dendrogram)

Question: How are the species in my community taxonomically related?

Shows the hierarchical classification as a dendrogram. Species on the same branch share closer taxonomic classification.

    plot_taxonomic_tree(tax_tree, community = community,
                        color_by = "Family", label_size = 3.5,
                        title = "Mediterranean Forest - Taxonomic Tree")

How to read:

- Species emerging from the same branch share a taxonomic group
- Numbers in parentheses show abundance
- Colors indicate family membership
- Longer branches = greater taxonomic distance

When to use: At the start of any analysis, to understand the taxonomic structure of your community before computing indices.

## 2. Taxonomic Distance Heatmap

Question: How distant is each species pair in the taxonomic hierarchy?

Displays the full pairwise taxonomic distance matrix as a color grid.

    plot_heatmap(tax_tree, label_size = 2.8,
                 title = "Pairwise Taxonomic Distances")

How to read:

- Dark red cells = distant species pairs (different orders)
- Light/white cells = closely related species (same genus or family)
- Diagonal is always zero (species compared to itself)
- Symmetric matrix (distance from A to B = distance from B to A)

When to use: To identify clusters of closely related species and to understand which species pairs drive the AvTD and Delta values.

## 3. Bubble Chart

Question: Which species contribute most to taxonomic diversity?

Each bubble represents a species, positioned by abundance (x-axis) and average taxonomic distance to all other species (y-axis). Bubble size reflects the combined contribution.

    plot_bubble(community, tax_tree, color_by = "Family",
                title = "Species Contributions to Diversity")

How to read:

- Upper right: High abundance + taxonomically distinct = major contributor to diversity
- Upper left: Rare but taxonomically unique = important for taxonomic breadth despite low numbers
- Lower right: Abundant but taxonomically common = contributes to evenness but not taxonomic distinctness
- Lower left: Rare and taxonomically common = minimal contribution

When to use: To identify keystone species for conservation priority — species in the upper portion of the chart contribute most to taxonomic diversity and their loss would have the greatest impact.

## 4. Radar Chart (Spider Plot)

Question: How do two or more communities compare across all indices?

Overlays multiple communities on a single polar coordinate plot where each axis represents a different diversity index.

    # Degraded community for comparison
    dominant_community <- c(
      Quercus_coccifera   = 80, Quercus_infectoria  = 5,
      Pinus_brutia        = 3,  Pinus_nigra         = 2,
      Juniperus_excelsa   = 2,  Juniperus_oxycedrus = 1,
      Arbutus_andrachne   = 3,  Styrax_officinalis  = 1,
      Cercis_siliquastrum = 2,  Olea_europaea       = 1
    )

    communities <- list(
      Diverse  = community,
      Dominant = dominant_community
    )

    plot_radar(communities, tax_tree,
               title = "Diverse vs Dominant Community")
    #> Warning: Removed 2 rows containing missing values or values outside the scale range
    #> (`geom_point()`).

How to read:

- Each axis is one diversity index (normalized to 0–1)
- Larger polygon area = higher overall diversity
- Overlapping axes = communities score similarly on that index
- Divergent axes = communities differ on that dimension

Key insight: If polygons overlap on AvTD/VarTD but diverge on Shannon/Simpson, the communities have the same species list but different abundance distributions. If they diverge on everything, the species composition itself is different.

When to use: For publication-ready multi-community comparisons. The radar chart reveals which dimensions of diversity differ, not just whether communities are “more” or “less” diverse overall.

## 5. Iteration Plot (Run 2)

Question: How stable are pTO values across stochastic resampling?

Shows the pTO value at each iteration of Run 2, where different species subsets are randomly included or excluded.

    run2 <- ozkan_pto_resample(community, tax_tree, n_iter = 101, seed = 42)

    plot_iteration(run2, component = "TO",
                   title = "Run 2: TO Values Across Iterations")

How to read:

- Grey dots: pTO value for each random species subset
- Red line: Deterministic value (Run 1, all species included)
- Blue line: Maximum value found across all iterations

Key insight: Points above the red line indicate subcommunities that are more diverse than the full community. This happens when removing taxonomically redundant species improves the ratio of between-group to within-group diversity.

When to use: After running the Ozkan pipeline, to understand the distribution of possible diversity values and whether the maximum is an outlier or representative of many subsets.

## 6. Rarefaction Curve

Question: Is my sampling effort sufficient to capture the community’s diversity?

Shows how the diversity estimate changes as you increase the number of individuals sampled, with bootstrap confidence intervals.

    rare <- rarefaction_taxonomic(community, tax_tree,
                                   index = "shannon",
                                   steps = 10, n_boot = 50, seed = 42)

    plot_rarefaction(rare)

How to read:

- X-axis: Number of individuals sampled
- Y-axis: Estimated diversity index
- Shaded band: 95% bootstrap confidence interval
- Plateau: Curve levels off = sampling is sufficient
- Steep at right edge: More sampling needed

When to use: Before any analysis, to check whether your sampling effort is adequate. If the curve has not plateaued, additional sampling would likely reveal new species and change your diversity estimates.

## 7. Funnel Plot

Question: Is my community’s AvTD/VarTD significantly different from random expectation?

Plots observed values against simulated 95% confidence intervals from random subsamples of a master species pool.

    data(anatolian_trees)

    sim <- simulate_td(
      tax_tree = anatolian_trees,
      s_range = c(3, 15),
      n_sim = 99,
      index = "avtd",
      seed = 42
    )

    spp <- names(community)
    obs_avtd <- avtd(spp, tax_tree)

    plot_funnel(sim,
                observed = data.frame(
                  site = "Mediterranean",
                  s = length(spp),
                  value = obs_avtd
                ),
                index = "avtd",
                title = "AvTD Significance Test")

How to read:

- Blue line: Mean expected value for each species richness level
- Grey band: 95% confidence interval from simulations
- Red point: Your observed community

Inside the funnel = not significantly different from random expectation. Below the funnel = taxonomically impoverished (fewer higher-level groups than expected). Above the funnel = taxonomically enriched (unusually high distinctness).

When to use: Whenever you need to assess whether a community’s taxonomic structure is statistically unusual. This is the only test in taxdiv that provides formal significance assessment.

## Customizing Plots

All plot functions return ggplot objects. You can customize them with standard ggplot2 functions:

    library(ggplot2)
    #> Warning: package 'ggplot2' was built under R version 4.5.2

    plot_rarefaction(rare) +
      theme_minimal() +
      labs(subtitle = "Mediterranean forest community") +
      theme(plot.title = element_text(face = "bold", size = 14))

Common customizations:

    # Change theme
    p + theme_classic()

    # Modify colors
    p + scale_color_brewer(palette = "Set2")

    # Adjust text size
    p + theme(axis.text = element_text(size = 12))

    # Save to file
    ggsave("my_plot.png", p, width = 10, height = 6, dpi = 300)