figaro_example_script.R

# =============================================================================
# Figaro — Ecology Example Script
# =============================================================================
#
# This script walks ecologists through installing Figaro and composing a
# publication-ready 3-panel figure from simulated survey data:
#
#   Panel A  Species richness along an elevation gradient  (scatter + LOESS)
#   Panel B  Species abundance distribution                (histogram)
#   Panel C  Bird community composition by habitat         (stacked bar)
#
# All data are simulated so the script runs without any external files.
# =============================================================================


# ── 0.  INSTALLATION  ─────────────────────────────────────────────────────────
#
# Run this section once, then skip it on future runs.
#
# Step 1 — clone the repository (run in a terminal, not in R):
#
#     git clone https://github.com/yuvalbloch/figaro-.git
#
# Step 2 — set your R working directory to the cloned folder:
#
#     setwd("C:/path/to/figaro-")   # Windows  — adjust to where you cloned it
#     setwd("~/path/to/figaro-")    # macOS / Linux
#
# Step 3 — install required packages and the figaro R package:

# install.packages(c("jsonlite", "httpuv", "ggplot2"))   # CRAN dependencies
source("install.R")                                     # installs figaro itself

# After installation you should see:
#   Done! Load the package in any R session with:
#     library(figaro)
# =============================================================================


# ── 1.  Load packages  ────────────────────────────────────────────────────────

library(figaro)
library(ggplot2)


# ── 2.  Simulate ecological survey data  ──────────────────────────────────────

set.seed(42)

# 2a. Elevation-gradient survey
#     150 vegetation plots sampled across an altitudinal gradient (200–3 000 m).
#     Species richness follows a mid-domain / hump-shaped response peaking near
#     1 400 m, a classic pattern in mountain biogeography.

n_plots   <- 150
elevation <- runif(n_plots, 200, 3000)

richness <- pmax(
  round(40 * exp(-((elevation - 1400) / 700)^2) + rnorm(n_plots, 0, 3)),
  1L
)

veg_zone <- cut(
  elevation,
  breaks = c(0, 800, 1600, 2400, 3100),
  labels = c("Lowland forest", "Montane forest", "Subalpine", "Alpine")
)

gradient_df <- data.frame(
  elevation_m      = elevation,
  species_richness = richness,
  vegetation_zone  = veg_zone
)


# 2b. Species abundance distribution (SAD)
#     200-species community following a log-normal SAD — the canonical "hollow
#     curve" seen in real communities (Preston 1948; McGill et al. 2007).

n_sp  <- 200
sad_df <- data.frame(
  log10_abundance = rnorm(n_sp, mean = 3.5, sd = 1.2)
)


# 2c. Bird community composition across five habitat types
#     Counts of individuals assigned to five foraging guilds, reflecting
#     well-known habitat-filtering patterns (e.g. frugivores dominate forest,
#     insectivores peak in wetlands and riparian zones).

habitats <- c("Riparian", "Grassland", "Shrubland", "Forest", "Wetland")
guilds   <- c("Insectivores", "Granivores", "Frugivores",
              "Nectarivores", "Omnivores")

counts <- c(
  30, 18, 12, 25, 15,   # Riparian
  45,  8,  5, 10, 12,   # Grassland
  20, 15,  8, 18, 19,   # Shrubland
  12, 10, 22, 30, 26,   # Forest
  38, 12,  6, 20, 24    # Wetland
)

composition_df <- data.frame(
  habitat = factor(rep(habitats, each  = length(guilds)), levels = habitats),
  guild   = factor(rep(guilds,   times = length(habitats)), levels = guilds),
  count   = counts
)


# ── 3.  Build ggplot2 panels  ─────────────────────────────────────────────────

# Colour palettes — colourblind-friendly
zone_pal  <- c("Lowland forest" = "#4caf50",
               "Montane forest" = "#1b5e20",
               "Subalpine"      = "#8d6e63",
               "Alpine"         = "#90a4ae")

guild_pal <- c("Insectivores" = "#e53935",
               "Granivores"   = "#fb8c00",
               "Frugivores"   = "#43a047",
               "Nectarivores" = "#8e24aa",
               "Omnivores"    = "#1e88e5")


# Panel A — Species richness × elevation
#   Two layers (geom_point + geom_smooth) → Figaro renders as an image panel
#   with the R Plot Style editor for live re-styling.

panel_a <- ggplot(gradient_df,
                  aes(elevation_m, species_richness, colour = vegetation_zone)) +
  geom_point(alpha = 0.65, size = 2.2) +
  geom_smooth(method = "loess", se = TRUE, span = 0.5,
              colour = "black", linewidth = 0.9, linetype = "dashed") +
  scale_colour_manual(values = zone_pal, name = "Vegetation zone") +
  labs(title = "A   Species richness along an elevation gradient",
       x     = "Elevation (m a.s.l.)",
       y     = "Vascular plant species richness") +
  theme_classic(base_size = 12) +
  theme(legend.position = "right")


# Panel B — Species abundance distribution
#   Single geom_histogram layer → Figaro extracts as a native histogram panel
#   (column mappings and axis labels are editable in the Inspector).

panel_b <- ggplot(sad_df, aes(log10_abundance)) +
  geom_histogram(bins = 22, fill = "#1565c0", colour = "white", alpha = 0.85) +
  labs(title = "B   Species abundance distribution",
       x     = "log₁₀(abundance)",
       y     = "Number of species") +
  theme_classic(base_size = 12)


# Panel C — Community composition (proportional stacked bar)
#   Single geom_col layer → Figaro extracts as a native bar/stacked-bar panel.

panel_c <- ggplot(composition_df, aes(habitat, count, fill = guild)) +
  geom_col(position = "fill") +
  scale_fill_manual(values = guild_pal, name = "Foraging guild") +
  scale_y_continuous(labels = \(x) paste0(round(x * 100), "%")) +
  labs(title = "C   Bird community composition by habitat",
       x     = "Habitat type",
       y     = "Relative abundance") +
  theme_classic(base_size = 12) +
  theme(axis.text.x = element_text(angle = 35, hjust = 1))


# ── 4.  Open Figaro  ──────────────────────────────────────────────────────────
#
# Layout: Panel A spans the full top row; B and C share the bottom row.
#
#   ┌─────────────────────────┐
#   │           A             │  ← elevation gradient (wider)
#   ├────────────┬────────────┤
#   │     B      │     C      │  ← SAD histogram | composition bar
#   └────────────┴────────────┘

layout_m <- matrix(c(1, 1,
                     2, 3), nrow = 2, byrow = TRUE)

fig <- figaro(
  elevation_gradient = panel_a,
  abundance_dist     = panel_b,
  community_comp     = panel_c,
  layout    = layout_m,
  row_sizes = c(1.3, 1),      # give the scatter a bit more vertical space
  canvas    = "A4_landscape"
)

# Your browser will open with the three panels pre-loaded.
#
# Things to try in the browser
# ─────────────────────────────
#   • Click any panel → the Inspector on the right lets you change titles,
#     axis labels, colours, and chart type.
#   • Panels B and C are native Figaro charts: map different columns, switch
#     chart types, or link their x-axes from the Inspector.
#   • Panel A opened with the R Plot Style editor (bottom of the Inspector):
#     change the base font size or legend position and click "Apply style" to
#     re-render the ggplot2 object live.
#   • Drag the dividers between panels to adjust proportions.
#   • Export → SVG / PNG (1× 2× 3×) / PDF / HTML via the ↓ icon in the toolbar.
#   • Save → writes a .figaro.json session file you can reopen later with:
#       figaro(session = "my_figure.figaro.json")


# ── 5.  Stop the server when you are done  ────────────────────────────────────

# figaro_stop()