Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,6 @@
+__pycache__
+*.pyc
+.git
+.env
+*.egg-info
+.DS_Store

.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.DS_Store
+.venv/
+venv/
+.env
+*.log

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies needed by Folium/Streamlit
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+EXPOSE 7860
+
+HEALTHCHECK CMD curl --fail http://localhost:7860/_stcore/health || exit 1
+
+ENTRYPOINT ["streamlit", "run", "app.py", "--server.port=7860", "--server.address=0.0.0.0"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Tia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,10 +1,271 @@
+<h1 align="center">🦴 PaleoData Explorer</h1>
+
+<p align="center">
+  <strong>A professional-grade Streamlit dashboard for querying, cleaning, visualising,<br>and exporting fossil occurrence data from the Paleobiology Database.</strong>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#architecture">Architecture</a> •
+  <a href="#usage-guide">Usage Guide</a> •
+  <a href="#data-sources">Data Sources</a> •
+  <a href="#license">License</a>
+</p>
+
+---
+
+## Overview
+
+PaleoData Explorer turns the messy, raw JSON from the [Paleobiology Database (PBDB)](https://paleobiodb.org) API into an interactive dashboard with paleogeographic maps, deep-time timelines, and Wikipedia-powered taxon profiles. It is designed for **paleontologists**, **geology students**, and **science communicators** who need to explore fossil records without writing code.
+
+### What Problem Does It Solve?
+
+The PBDB is the gold-standard repository for fossil occurrence data, but its API returns abbreviated field names, incomplete records, and no visualisation layer. Researchers typically spend hours writing one-off scripts just to see their data on a map.
+
+PaleoData Explorer provides a **zero-code pipeline**:
+- Query the PBDB by taxon name and geological time window
+- Automatically clean and standardise the data
+- Visualise results on paleocoordinate maps and stratigraphic range charts
+- Browse Wikipedia summaries and images for any taxon
+- Export a clean CSV for further analysis in R, Python, or Excel
+
+---
+
+## Features
+
+### 🔍 Intelligent PBDB Queries
+- Search by any taxonomic rank — clade, family, genus, or species
+- PBDB resolves parent clades hierarchically (e.g. "Tyrannosauridae" returns all subordinate taxa)
+- Filter by geological time window (Ma) with a slider
+- Configurable record limit (100–5000)
+
+### 🧹 Automated Data Cleaning
+- Drops records missing temporal bounds (`max_ma` / `min_ma`) or paleocoordinates
+- Imputes single-bound age estimates
+- Computes `middle_age = (max_ma + min_ma) / 2` for point plotting
+- Transparent pipeline statistics showing records dropped at each stage
+
+### 🗺️ Paleogeographic Map
+- **MarkerCluster** rendering for smooth performance with thousands of points
+- Plotted on **paleocoordinates** — showing where organisms lived millions of years ago, accounting for continental drift
+- Click any marker to jump to that organism's Wikipedia profile
+- Tooltips showing `matched_name`, geological interval, and age range
+
+### 📈 Deep-Time Timeline
+- Horizontal stratigraphic range chart (Gantt-style)
+- **X-axis reversed** — older on the left, younger on the right (geological convention)
+- Top‑50 taxa by oldest age, sorted by midpoint
+
+### 🔍 Taxon Profile Viewer
+- Select any taxon from the cleaned dataset via dropdown
+- Fetches **Wikipedia summary** and **thumbnail image** via the Wikimedia REST API
+- Results cached for 1 hour (no redundant API calls)
+- Falls back from genus-level to species-level lookup
+
+### 📥 CSV Export
+- One-click download of the fully cleaned DataFrame
+- Ready for import into R, Python, Excel, or GIS tools
+
+### 📚 Built-in Taxon Reference
+- 130+ pre-listed taxa across 7 categories (Dinosaurs, Marine Reptiles, Mammals, Invertebrates, Plants, etc.)
+- **Clickable buttons** auto-fill the search bar — no typing needed
+- Always visible below results
+
+---
+
+## Quick Start
+
+### Docker (Recommended)
+
+```bash
+# Clone the repository
+git clone https://github.com/BenjaminTia/PaleoPedia.git
+cd PaleoPedia
+
+# Build and start
+docker compose up --build -d
+
+# Open in browser
+open http://localhost:8501
+```
+
+### Local Installation
+
+```bash
+# Clone and install
+git clone https://github.com/BenjaminTia/PaleoPedia.git
+cd PaleoPedia
+pip install -r requirements.txt
+
+# Run
+streamlit run app.py
+```
+
+Open **http://localhost:8501** in your browser.
+
+---
+
+## Architecture
+
+```
+PaleoPedia/
+├── app.py                 # Streamlit entry point — sidebar, tabs, export, UI
+├── api_client.py          # PBDB & Wikipedia API wrappers with error handling
+├── data_processor.py      # JSON → DataFrame, cleaning pipeline, statistics
+├── visualizations.py      # Folium MarkerCluster map + Plotly timeline chart
+├── requirements.txt       # Pinned Python dependencies
+├── Dockerfile             # Python 3.11-slim, multi-stage-friendly
+├── docker-compose.yml     # Single-service orchestration
+└── .dockerignore
+```
+
+### Module Responsibilities
+
+| Module | Role |
+|---|---|
+| `api_client.py` | `fetch_occurrences()` — queries PBDB with `base_name`, `max_ma`/`min_ma`, and `show=paleoloc,phylo,time,ident`. Returns raw JSON list. `fetch_wikipedia_profile()` — fetches page summary and thumbnail from Wikimedia REST API. Handles timeouts, HTTP errors, and empty responses gracefully. |
+| `data_processor.py` | `clean_occurrence_data()` — 5-step pipeline: temporal filter → impute lone bounds → spatial filter → compute `middle_age` → time-window filter. Returns `(DataFrame, stats_dict)`. `get_dataframe_statistics()` — summary metrics for the UI. Includes a `PBDB_COLUMN_MAP` that normalises abbreviated field names (`eag` → `max_ma`, `tna` → `matched_name`, etc.). |
+| `visualizations.py` | `build_paleo_map()` — Folium map with `MarkerCluster`, `CircleMarker`s, tooltips, and clickable popups. `build_timeline()` — Plotly horizontal range chart with reversed X-axis. |
+| `app.py` | Full Streamlit dashboard: sidebar controls (taxon input, Ma slider, record limit), educational guide expander, summary metrics, pipeline stats, 4-tab layout (Map, Timeline, Taxon Profile, Raw Data & CSV export), persistent tab state, map-click-to-profile integration, and 130+ clickable reference buttons. |
+
+### Data Flow
+
+```
+User Input (sidebar)
+    │
+    ▼
+api_client.fetch_occurrences()  ──►  PBDB API
+    │
+    ▼
+data_processor.records_to_dataframe()
+    │
+    ▼
+data_processor.clean_occurrence_data()  ──►  Cleaned DataFrame
+    │
+    ├──► visualizations.build_paleo_map()  ──►  Folium map
+    ├──► visualizations.build_timeline()   ──►  Plotly chart
+    ├──► api_client.fetch_wikipedia_profile()  ──►  Wikipedia
+    └──► CSV export
+```
+
+---
+
+## Usage Guide
+
+### 1. Search for Fossils
+
+1. Open the sidebar (☰)
+2. Type a taxon name — or click any name in the **Taxon & Clade Reference** at the bottom of the page
+3. Adjust the **Geological Time Window** slider (default: 65–250 Ma, the Mesozoic)
+4. Click **🚀 Search PBDB**
+
+### 2. Explore the Results
+
+| Tab | What You See |
+|---|---|
+| 🗺️ Paleogeographic Map | Clustered markers on paleocoordinates. Zoom in to see individual fossils. Click a marker to jump to its Taxon Profile. |
+| 📈 Deep-Time Timeline | Horizontal range chart. Older on the left, younger on the right. Hover for details. |
+| 🔍 Taxon Profile | Select any taxon from the dropdown. View Wikipedia summary, image, and link to full article. |
+| 📋 Raw Data & Export | Full cleaned dataset as a sortable table. Click **Download as CSV** to export. |
+
+### 3. Export for Research
+
+The CSV export contains all cleaned columns: `matched_name`, `max_ma`, `min_ma`, `middle_age`, `paleolat`, `paleolng`, `early_interval`, `family`, `genus`, `phylum`, `class`, `order`, and more. Ready for:
+
+```r
+# R
+df <- read.csv("paleodata_Ceratopsidae_65_250Ma.csv")
+```
+
+```python
+# Python
+import pandas as pd
+df = pd.read_csv("paleodata_Ceratopsidae_65_250Ma.csv")
+```
+
+### Example Queries
+
+| Search Term | Expected Records | Notes |
+|---|---|---|
+| `Tyrannosauridae` | ~50–200 | T. rex family and relatives |
+| `Ceratopsidae` | ~100–1000 | Horned dinosaurs |
+| `Ammonoidea` | ~1000+ | Ammonites — huge dataset |
+| `Trilobita` | ~1000+ | Trilobites — wide temporal range |
+| `Homo` | ~100+ | Human lineage |
+| `Mammuthus` | ~50–200 | Mammoths |
+| `Megalodon` | ~10–50 | Giant extinct shark |
+
+---
+
+## API & Domain Notes
+
+### PBDB Field Mapping
+
+The PBDB API returns abbreviated keys. PaleoData Explorer normalises them:
+
+| PBDB Key | Meaning | Canonical Name |
+|---|---|---|
+| `eag` | Early age (older bound) | `max_ma` |
+| `lag` | Late age (younger bound) | `min_ma` |
+| `tna` | Taxon name | `matched_name` |
+| `oei` | Early interval name | `early_interval` |
+| `pla` | Paleolatitude | `paleolat` |
+| `pln` | Paleolongitude | `paleolng` |
+| `phl` | Phylum | `phylum` |
+| `cll` | Class | `class` |
+| `odl` | Order | `order` |
+| `fml` | Family | `family` |
+| `gnl` | Genus | `genus` |
+
+### Geological Time Convention
+
+- **Ma** = Mega-annum (millions of years ago)
+- **Larger numbers** = further back in time
+- All temporal charts display with the **X-axis reversed** (older ← left, younger → right)
+
+### Paleocoordinates vs. Modern Coordinates
+
+Modern GPS coordinates tell you where a fossil was *found*. Paleocoordinates tell you where the organism actually *lived*, reconstructed by reversing tectonic plate movements. This app exclusively plots paleocoordinates from the PBDB's GPlates model.
+
 ---
-title: PaleoData Explorer
-emoji: 🐢
-colorFrom: yellow
-colorTo: yellow
-sdk: docker
-pinned: false
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Frontend / UI | [Streamlit](https://streamlit.io) 1.58+ |
+| Data Processing | [Pandas](https://pandas.pydata.org) 3.0+, [NumPy](https://numpy.org) 2.4+ |
+| API Requests | [Requests](https://requests.readthedocs.io) 2.34+ |
+| Map Visualisation | [Folium](https://python-visualization.github.io/folium/) 0.20+ |
+| Charts | [Plotly](https://plotly.com/python/) 6.8+ |
+| Containerisation | [Docker](https://docker.com), Python 3.11-slim |
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Contributing
+
+Contributions are welcome. Areas of interest:
+
+- Adding Macrostrat geological period overlays
+- Supporting additional PBDB output formats
+- Adding stratigraphic column visualisations
+- Improving test coverage
+- i18n / translations
+
+Please open an issue or pull request on GitHub.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgements
+
+- Fossil occurrence data via the [Paleobiology Database](https://paleobiodb.org) (CC BY 4.0)
+- Taxon summaries and images via the [Wikimedia REST API](https://www.mediawiki.org/wiki/API:REST_API) (CC BY-SA 3.0 / various)
+- Paleocoordinates reconstructed using the [GPlates](https://www.gplates.org) model
+- Built with [Streamlit](https://streamlit.io), [Folium](https://python-visualization.github.io/folium/), and [Plotly](https://plotly.com)

api_client.py

@@ -0,0 +1,233 @@
+"""
+PaleoData Explorer — PBDB & Macrostrat API Client
+==================================================
+Provides robust, cached-friendly wrappers around the Paleobiology Database
+(PBDB) occurrence endpoint and (optionally) the Macrostrat interval
+endpoint.  Every function handles timeouts, HTTP errors, and empty
+responses gracefully.
+
+Domain notes
+------------
+* Geological time is in "Ma" (Mega-annum, millions of years ago).
+* The "show" parameter must include `paleoloc` (paleocoordinates),
+  `phylo` (phylogeny / taxonomy) and `time,ident` so the returned JSON
+  carries `paleolat`, `paleolng`, taxonomic hierarchies and temporal
+  bounds (`max_ma`, `min_ma`).
+* The PBDB API returns `records` inside a top-level key; we safely
+  unwrap that in `fetch_occurrences`.
+"""
+
+import logging
+from typing import Any, Dict, List, Optional
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+PBDB_OCCURRENCE_URL: str = "https://paleobiodb.org/data1.2/occs/list.json"
+MACROSTRAT_INTERVALS_URL: str = "https://macrostrat.org/api/v2/defs/intervals"
+
+DEFAULT_LIMIT: int = 1000
+DEFAULT_SHOW: str = "paleoloc,phylo,time,ident"
+REQUEST_TIMEOUT: int = 30  # seconds
+
+
+# ---------------------------------------------------------------------------
+# Public helpers
+# ---------------------------------------------------------------------------
+
+def _safe_get(url: str, params: Dict[str, Any]) -> requests.Response:
+    """Perform a GET request with standardised error handling.
+
+    Raises
+    ------
+    requests.exceptions.Timeout
+        When the request hangs past *REQUEST_TIMEOUT*.
+    requests.exceptions.HTTPError
+        On 4xx / 5xx responses.
+    ValueError
+        When the response body is not valid JSON.
+    """
+    logger.debug("GET %s | params=%s", url, params)
+    resp = requests.get(url, params=params, timeout=REQUEST_TIMEOUT)
+    resp.raise_for_status()
+    return resp
+
+
+# ---------------------------------------------------------------------------
+# PBDB Occurrence fetch
+# ---------------------------------------------------------------------------
+
+def fetch_occurrences(
+    base_name: str,
+    *,
+    max_ma: Optional[float] = None,
+    min_ma: Optional[float] = None,
+    limit: int = DEFAULT_LIMIT,
+    show: str = DEFAULT_SHOW,
+) -> List[Dict[str, Any]]:
+    """Fetch fossil occurrence records from the PBDB API.
+
+    Parameters
+    ----------
+    base_name : str
+        Taxonomic clade or genus name, e.g. ``"Ceratopsidae"`` or
+        ``"Tyrannosaurus"``.  PBDB resolves this hierarchically so all
+        subordinate taxa are included automatically.
+    max_ma, min_ma : float or None
+        Optional temporal window in Ma.  When supplied the API filters
+        occurrences to those whose age range overlaps this window.
+    limit : int
+        Maximum number of records to return (default 1 000).
+    show : str
+        Comma-separated list of PBDB "show" fields.  Must include at
+        least ``paleoloc,phylo,time,ident`` for the downstream pipeline.
+
+    Returns
+    -------
+    list[dict]
+        List of raw occurrence records.  Returns an empty list when the
+        API returns no records or the response is malformed.
+
+    Raises
+    ------
+    requests.exceptions.Timeout
+        If the PBDB API does not respond within *REQUEST_TIMEOUT*.
+    requests.exceptions.HTTPError
+        If the API returns a non-200 status.
+    ValueError
+        If the response body cannot be parsed as JSON.
+    """
+    params: Dict[str, Any] = {
+        "base_name": base_name,
+        "show": show,
+        "limit": limit,
+    }
+    if max_ma is not None:
+        params["max_ma"] = max_ma
+    if min_ma is not None:
+        params["min_ma"] = min_ma
+
+    logger.info("Querying PBDB with base_name=%r", base_name)
+
+    try:
+        resp = _safe_get(PBDB_OCCURRENCE_URL, params)
+    except requests.exceptions.Timeout:
+        logger.error("PBDB request timed out after %d s", REQUEST_TIMEOUT)
+        raise
+    except requests.exceptions.HTTPError as exc:
+        logger.error("PBDB request failed (HTTP %s)", exc.response.status_code if exc.response is not None else "unknown")
+        raise
+    except requests.exceptions.RequestException as exc:
+        logger.error("PBDB request failed: %s", exc)
+        raise
+
+    try:
+        data = resp.json()
+    except ValueError:
+        logger.error("PBDB response body is not valid JSON")
+        raise
+
+    records: List[Dict[str, Any]] = data.get("records", [])
+    if not records:
+        logger.warning("PBDB returned zero records for base_name=%r", base_name)
+
+    logger.info("PBDB returned %d records", len(records))
+    return records
+
+
+# ---------------------------------------------------------------------------
+# Wikipedia profile fetch (optional helper)
+# ---------------------------------------------------------------------------
+
+WIKIPEDIA_SUMMARY_URL: str = "https://en.wikipedia.org/api/rest_v1/page/summary"
+
+
+def fetch_wikipedia_profile(taxon_name: str) -> Dict[str, Any]:
+    """Fetch a short summary and thumbnail for a taxon from Wikipedia.
+
+    Uses the Wikimedia REST API ``/page/summary/{title}`` endpoint.
+    Failures are caught silently and an empty dict (or dict with an
+    ``"error"`` key) is returned so callers never crash.
+
+    Parameters
+    ----------
+    taxon_name : str
+        The Wikipedia article title, e.g. ``"Triceratops"`` or
+        ``"Tyrannosaurus"``.
+
+    Returns
+    -------
+    dict
+        On success: ``{"extract": str, "image_url": str|None, "page_url": str}``.
+        On failure: ``{"error": str}`` or ``{}``.
+    """
+    import urllib.parse
+
+    safe_title = urllib.parse.quote(taxon_name.strip(), safe="")
+    url = f"{WIKIPEDIA_SUMMARY_URL}/{safe_title}"
+
+    logger.info("Fetching Wikipedia summary for %r", taxon_name)
+
+    try:
+        resp = requests.get(
+            url,
+            timeout=REQUEST_TIMEOUT,
+            headers={"User-Agent": "PaleoDataExplorer/1.0 (educational tool; https://github.com/anomalyco/opencode)"},
+        )
+        if resp.status_code == 404:
+            logger.warning("Wikipedia page not found for %r", taxon_name)
+            return {"error": f"No Wikipedia article found for '{taxon_name}'."}
+        resp.raise_for_status()
+    except requests.exceptions.Timeout:
+        logger.error("Wikipedia request timed out for %r", taxon_name)
+        return {"error": "Wikipedia request timed out."}
+    except requests.exceptions.RequestException as exc:
+        logger.error("Wikipedia request failed for %r: %s", taxon_name, exc)
+        return {"error": f"Wikipedia request failed: {exc}"}
+
+    try:
+        data = resp.json()
+    except ValueError:
+        logger.error("Wikipedia response is not valid JSON for %r", taxon_name)
+        return {"error": "Invalid response from Wikipedia."}
+
+    extract = data.get("extract", "")
+    thumbnail = data.get("thumbnail", {})
+    image_url = thumbnail.get("source") if isinstance(thumbnail, dict) else None
+    page_url = data.get("content_urls", {}).get("desktop", {}).get("page", "")
+
+    return {
+        "extract": extract,
+        "image_url": image_url,
+        "page_url": page_url,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Macrostrat interval fetch (optional helper)
+# ---------------------------------------------------------------------------
+
+def fetch_macrostrat_intervals() -> List[Dict[str, Any]]:
+    """Fetch the Macrostrat interval definitions (geological periods).
+
+    Useful for mapping absolute Ma values to named periods.  Returns an
+    empty list on failure so callers can fall back gracefully.
+
+    Returns
+    -------
+    list[dict]
+        Each dict contains keys such as ``name``, ``t_age``, ``b_age``,
+        ``color``, etc.
+    """
+    logger.info("Querying Macrostrat interval definitions")
+    try:
+        resp = _safe_get(MACROSTRAT_INTERVALS_URL, {"all": True, "format": "json"})
+        return resp.json()  # type: ignore[no-any-return]
+    except Exception:
+        logger.exception("Failed to fetch Macrostrat intervals")
+        return []

app.py

@@ -0,0 +1,743 @@
+"""
+PaleoData Explorer — Streamlit Application
+===========================================
+Professional-grade dashboard for querying, cleaning, visualising, and
+exporting fossil occurrence data from the Paleobiology Database (PBDB).
+
+Run with::
+
+    streamlit run app.py
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+
+import pandas as pd
+import streamlit as st
+from streamlit_folium import st_folium
+
+from api_client import fetch_macrostrat_intervals, fetch_occurrences, fetch_wikipedia_profile
+from data_processor import (
+    clean_occurrence_data,
+    get_dataframe_statistics,
+    records_to_dataframe,
+)
+from visualizations import build_paleo_map, build_timeline
+
+# ---------------------------------------------------------------------------
+# Logging
+# ---------------------------------------------------------------------------
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Cached helpers
+# ---------------------------------------------------------------------------
+
+@st.cache_data(ttl=3600, show_spinner=False)
+def cached_fetch_wikipedia_profile(taxon_name: str) -> dict:
+    """Streamlit-cached wrapper around :func:`fetch_wikipedia_profile`.
+
+    Results are cached for 1 hour so repeated selections of the same
+    taxon do not re-hit the Wikipedia API.
+    """
+    return fetch_wikipedia_profile(taxon_name)
+
+
+# ---------------------------------------------------------------------------
+# Reference-list helper: render clickable taxon buttons
+# ---------------------------------------------------------------------------
+
+def _clickable_taxon(taxon: str, desc: str = "") -> None:
+    """Render a small clickable button that auto-fills the search bar.
+
+    Uses an intermediary ``_pending_taxon`` session-state key to avoid
+    Streamlit's restriction on modifying a widget's key after the widget
+    has already been instantiated during the same render pass.
+    """
+    label = f"{taxon}"
+    if desc:
+        label += f"  — {desc}"
+    if st.button(label, key=f"refbtn_{taxon}", help=f'Search PBDB for "{taxon}"', use_container_width=True):
+        st.session_state["_pending_taxon"] = taxon
+        st.rerun()
+
+
+def _clickable_taxa_section(header: str, taxa: list[tuple[str, str]], num_cols: int = 3) -> None:
+    """Render a labelled group of :func:`_clickable_taxon` buttons in columns.
+
+    Parameters
+    ----------
+    header : str
+        Bold markdown heading for the group.
+    taxa : list[tuple[str, str]]
+        Each tuple is ``(taxon_name, short_description)``.
+    num_cols : int
+        Number of button columns.
+    """
+    st.markdown(f"**{header}**")
+    cols = st.columns(num_cols)
+    for i, (taxon, desc) in enumerate(taxa):
+        with cols[i % num_cols]:
+            _clickable_taxon(taxon, desc)
+
+
+# ---------------------------------------------------------------------------
+# Page config
+# ---------------------------------------------------------------------------
+st.set_page_config(
+    page_title="PaleoData Explorer",
+    page_icon="🦴",
+    layout="wide",
+    initial_sidebar_state="expanded",
+)
+
+# ---------------------------------------------------------------------------
+# Intermediary state: allow downstream buttons to request a taxon change
+# or active-tab switch without violating Streamlit's widget-key immutability rule.
+# ---------------------------------------------------------------------------
+if st.session_state.get("_pending_taxon"):
+    st.session_state["taxon_input"] = st.session_state.pop("_pending_taxon")
+if st.session_state.get("_pending_active_tab"):
+    st.session_state["active_tab"] = st.session_state.pop("_pending_active_tab")
+
+# ---------------------------------------------------------------------------
+# Sidebar — Query controls
+# ---------------------------------------------------------------------------
+st.sidebar.title("🔍 Query Controls")
+
+# Initialise session state for the taxon input if not already set
+if "taxon_input" not in st.session_state:
+    st.session_state["taxon_input"] = "Ceratopsidae"
+
+taxon_input = st.sidebar.text_input(
+    "Taxon / Clade",
+    key="taxon_input",
+    help="Enter a taxonomic name, e.g. 'Tyrannosauridae', 'Mammalia', or 'Triceratops'.",
+)
+
+st.sidebar.markdown("---")
+st.sidebar.subheader("Geological Time Window (Ma)")
+
+ma_min, ma_max = st.sidebar.slider(
+    "Select age range (millions of years ago)",
+    min_value=0.0,
+    max_value=500.0,
+    value=(65.0, 250.0),
+    step=5.0,
+    help="Older = larger number.  The PBDB will return fossils whose age ranges overlap this window.",
+)
+
+max_records = st.sidebar.number_input(
+    "Max records",
+    min_value=100,
+    max_value=5000,
+    value=1000,
+    step=100,
+    help="Maximum number of occurrence records to fetch from the PBDB API.",
+)
+
+st.sidebar.markdown("---")
+
+search_clicked = st.sidebar.button(
+    "🚀 Search PBDB",
+    type="primary",
+    use_container_width=True,
+)
+
+st.sidebar.markdown("---")
+st.sidebar.caption(
+    "Data sourced from the [Paleobiology Database](https://paleobiodb.org) "
+    "and [Macrostrat](https://macrostrat.org)."
+)
+
+# ---------------------------------------------------------------------------
+# App title
+# ---------------------------------------------------------------------------
+st.title("🦴 PaleoData Explorer")
+st.markdown(
+    "Query, clean, visualise, and export fossil occurrence records from "
+    "the **Paleobiology Database** (PBDB).  Paleocoordinates are mapped "
+    "on the paleogeographic globe; timelines follow geological convention "
+    "(older → younger = left → right)."
+)
+
+# ---------------------------------------------------------------------------
+# Educational Guide (collapsed by default)
+# ---------------------------------------------------------------------------
+with st.expander("📖 Welcome to PaleoData Explorer: Guide & Glossary", expanded=False):
+    st.markdown(
+        """
+### What is PaleoData Explorer?
+
+This is a professional data-wrangling dashboard that connects to the real
+**[Paleobiology Database (PBDB)](https://paleobiodb.org)** — the same
+database used by working paleontologists worldwide.  Instead of browsing
+static tables, you can search, visualise, and download fossil occurrence
+records in seconds.
+
+---
+
+### Key Concepts & Glossary
+
+| Term | Meaning |
+|---|---|
+| **Ma (Mega-annum)** | Millions of years ago.  *Larger numbers = further back in time.*  All timelines in this app flow **backwards** (older on the left, younger on the right), following geological convention. |
+| **Paleocoordinates** | The reconstructed latitude/longitude of a fossil **at the time the organism lived**, accounting for millions of years of tectonic plate movement.  This map shows where the animal actually lived — *not* where its bones happen to sit today. |
+| **Clade / Taxon** | A group of organisms sharing a common ancestor.  Searching for a family name (e.g. "Tyrannosauridae") automatically includes all subordinate genera and species. |
+| **Stratigraphic Range** | The span of geological time during which a taxon is known to have existed, bounded by its oldest (*max_ma*) and youngest (*min_ma*) fossil occurrences. |
+| **Middle Age** | The midpoint of a fossil's stratigraphic range: `(max_ma + min_ma) / 2`.  Used as a single-point estimate for temporal plotting. |
+| **PBDB** | The Paleobiology Database — a public, community-driven repository of fossil occurrence data curated by hundreds of research scientists. |
+
+---
+
+### How to Use This App
+
+1. **Enter a taxon name** in the sidebar (e.g. *Ceratopsidae*, *Tyrannosaurus*, *Mammalia*).
+2. **Adjust the time slider** to narrow the geological window (default: 65–250 Ma, the Mesozoic).
+3. Click **Search PBDB** to fetch records.
+4. Explore the results across three tabs:
+   - 🗺️ **Paleogeographic Map** — clustered markers on paleocoordinates.
+   - 📈 **Deep-Time Timeline** — stratigraphic range chart.
+   - 🔍 **Taxon Profile** — Wikipedia summary and image for any taxon in the results.
+5. 📥 **Download** the cleaned dataset as a CSV for your own analysis.
+        """
+    )
+
+# ---------------------------------------------------------------------------
+# Session state initialisation
+# ---------------------------------------------------------------------------
+DEFAULT_STATE = {
+    "df_clean": pd.DataFrame(),
+    "stats_raw": {},
+    "query_taxon": "",
+    "query_ma_min": None,
+    "query_ma_max": None,
+    "last_error": "",
+    "has_searched": False,
+}
+for key, default in DEFAULT_STATE.items():
+    if key not in st.session_state:
+        st.session_state[key] = default
+
+# ---------------------------------------------------------------------------
+# Fetch & process logic
+# ---------------------------------------------------------------------------
+def run_query() -> None:
+    """Execute the full fetch → clean pipeline and store results in session."""
+    st.session_state["last_error"] = ""
+    st.session_state["has_searched"] = True
+    st.session_state["query_taxon"] = taxon_input.strip()
+    st.session_state["query_ma_min"] = ma_min
+    st.session_state["query_ma_max"] = ma_max
+
+    with st.spinner(f"Querying PBDB for '{st.session_state['query_taxon']}' …"):
+        try:
+            raw_records = fetch_occurrences(
+                base_name=st.session_state["query_taxon"],
+                max_ma=ma_max,
+                min_ma=ma_min,
+                limit=int(max_records),
+            )
+        except Exception as exc:
+            logger.exception("PBDB query failed")
+            st.session_state["last_error"] = f"API error: {exc}"
+            st.session_state["df_clean"] = pd.DataFrame()
+            st.session_state["stats_raw"] = {}
+            return
+
+    if not raw_records:
+        st.session_state["last_error"] = (
+            f"No records found for '{st.session_state['query_taxon']}' "
+            f"within {ma_min:.0f}–{ma_max:.0f} Ma."
+        )
+        st.session_state["df_clean"] = pd.DataFrame()
+        st.session_state["stats_raw"] = {}
+        return
+
+    df_raw = records_to_dataframe(raw_records)
+    df_clean, pipeline_stats = clean_occurrence_data(df_raw, max_ma=ma_max, min_ma=ma_min)
+
+    st.session_state["df_clean"] = df_clean
+    st.session_state["stats_raw"] = pipeline_stats
+
+
+if search_clicked:
+    run_query()
+
+# ---------------------------------------------------------------------------
+# Results area
+# ---------------------------------------------------------------------------
+if st.session_state.get("last_error"):
+    st.error(st.session_state["last_error"])
+
+if st.session_state.get("has_searched") and not st.session_state.get("last_error"):
+    st.success(
+        f"Query: **{st.session_state['query_taxon']}**  |  "
+        f"Time window: {st.session_state['query_ma_min']:.0f}–{st.session_state['query_ma_max']:.0f} Ma"
+    )
+
+    df = st.session_state["df_clean"]
+
+    if df.empty:
+        st.warning("No records survived the cleaning pipeline.  Try broadening your search.")
+        st.stop()
+
+    # ---- Summary stats --------------------------------------------------
+    summary = get_dataframe_statistics(df)
+    cols = st.columns(5)
+    cols[0].metric("Records", summary.get("record_count", 0))
+    cols[1].metric("Unique Taxa", summary.get("unique_taxa", 0))
+    cols[2].metric("Oldest (Ma)", f"{summary.get('oldest_ma', 0):.1f}")
+    cols[3].metric("Youngest (Ma)", f"{summary.get('youngest_ma', 0):.1f}")
+    cols[4].metric("Time Span (Ma)", f"{summary.get('time_span_ma', 0):.1f}")
+
+    # ---- Pipeline stats -------------------------------------------------
+    with st.expander("📊 Data Pipeline Details", expanded=False):
+        stats = st.session_state.get("stats_raw", {})
+        c1, c2, c3, c4 = st.columns(4)
+        c1.metric("Fetched", stats.get("raw", 0))
+        c2.metric("Has temporal", stats.get("has_temporal", 0))
+        c3.metric("Has spatial", stats.get("has_spatial", 0))
+        c4.metric("In time window", stats.get("in_window", 0))
+
+    # ---- Tab selector (radio, so it persists across reruns) -------------
+    TAB_OPTIONS = [
+        "🗺️ Paleogeographic Map",
+        "📈 Deep-Time Timeline",
+        "🔍 Taxon Profile",
+        "📋 Raw Data & Export",
+    ]
+    if "active_tab" not in st.session_state:
+        st.session_state["active_tab"] = TAB_OPTIONS[0]
+
+    active_tab = st.radio(
+        "",
+        TAB_OPTIONS,
+        horizontal=True,
+        key="active_tab",
+        label_visibility="collapsed",
+    )
+
+    # ------------------------------------------------------------------
+    # Tab 1: Paleogeographic Map
+    # ------------------------------------------------------------------
+    if active_tab == TAB_OPTIONS[0]:
+        st.subheader("Fossil Occurrences — Paleocoordinates")
+        st.caption(
+            "Points are plotted at their **paleocoordinates** — where the "
+            "organism lived millions of years ago, accounting for continental drift.  "
+            "🖱️ **Click a marker** to jump to its Taxon Profile."
+        )
+        paleo_map = build_paleo_map(df, height=600)
+        map_data = st_folium(paleo_map, height=600, width=700)
+
+        # Detect map-marker click → switch to Taxon Profile tab
+        if map_data and map_data.get("last_object_clicked_popup"):
+            clicked_taxon = str(map_data["last_object_clicked_popup"]).strip()
+            if clicked_taxon:
+                st.session_state["profile_taxon"] = clicked_taxon
+                st.session_state["_pending_active_tab"] = TAB_OPTIONS[2]
+                st.rerun()
+
+    # ------------------------------------------------------------------
+    # Tab 2: Deep-Time Timeline
+    # ------------------------------------------------------------------
+    elif active_tab == TAB_OPTIONS[1]:
+        st.subheader("Stratigraphic Range Chart")
+        st.caption("X‑axis is **reversed** (older on left, younger on right) — geological convention.")
+        fig_timeline = build_timeline(df, max_taxa=50)
+        st.plotly_chart(fig_timeline, use_container_width=True)
+
+    # ------------------------------------------------------------------
+    # Tab 3: Taxon Profile
+    # ------------------------------------------------------------------
+    elif active_tab == TAB_OPTIONS[2]:
+        st.subheader("Taxon Profile Viewer")
+        st.caption(
+            "Select a taxon from the dropdown to view a summary and image "
+            "sourced from Wikipedia."
+        )
+
+        unique_taxa = sorted(df["matched_name"].dropna().unique())
+        if len(unique_taxa) == 0:
+            st.info("No named taxa available in the current results.")
+        else:
+            # Honour a map-click pre-selection
+            if "profile_taxon" not in st.session_state:
+                st.session_state["profile_taxon"] = unique_taxa[0]
+            default_index = 0
+            if st.session_state["profile_taxon"] in unique_taxa:
+                default_index = unique_taxa.index(st.session_state["profile_taxon"])
+
+            selected_taxon = st.selectbox(
+                "Choose a taxon",
+                options=unique_taxa,
+                index=default_index,
+                key="profile_selectbox",
+                help="Taxa are drawn from the matched_name field in the cleaned dataset.",
+            )
+            # Sync the pick back to session state
+            st.session_state["profile_taxon"] = selected_taxon
+
+            if selected_taxon:
+                genus_candidate = df.loc[
+                    df["matched_name"] == selected_taxon, "genus"
+                ]
+                lookup_name = selected_taxon
+                if not genus_candidate.empty and genus_candidate.notna().any():
+                    genus_val = str(genus_candidate.iloc[0])
+                    if genus_val and genus_val != "nan":
+                        lookup_name = genus_val
+
+                with st.spinner(f"Fetching Wikipedia summary for '{lookup_name}' …"):
+                    profile = cached_fetch_wikipedia_profile(lookup_name)
+
+                if profile.get("error"):
+                    if lookup_name != selected_taxon:
+                        with st.spinner(f"Trying '{selected_taxon}' …"):
+                            profile = cached_fetch_wikipedia_profile(selected_taxon)
+
+                if profile.get("error"):
+                    st.warning(profile["error"])
+                else:
+                    col_img, col_text = st.columns([1, 2])
+                    with col_img:
+                        image_url = profile.get("image_url")
+                        if image_url:
+                            st.image(image_url, caption=lookup_name, use_container_width=True)
+                        else:
+                            st.info("No image available.")
+                    with col_text:
+                        extract = profile.get("extract", "")
+                        if extract:
+                            st.markdown(extract)
+                        else:
+                            st.info("No summary text available.")
+                    page_url = profile.get("page_url")
+                    if page_url:
+                        st.caption(f"[Read more on Wikipedia]({page_url})")
+
+    # ------------------------------------------------------------------
+    # Tab 4: Raw Data & Export
+    # ------------------------------------------------------------------
+    elif active_tab == TAB_OPTIONS[3]:
+        st.subheader("Cleaned Occurrence Data")
+        st.dataframe(
+            df,
+            use_container_width=True,
+            column_config={
+                "paleolat": st.column_config.NumberColumn("Paleolat (°)", format="%.4f"),
+                "paleolng": st.column_config.NumberColumn("Paleolng (°)", format="%.4f"),
+                "max_ma": st.column_config.NumberColumn("Max Age (Ma)", format="%.2f"),
+                "min_ma": st.column_config.NumberColumn("Min Age (Ma)", format="%.2f"),
+                "middle_age": st.column_config.NumberColumn("Middle Age (Ma)", format="%.2f"),
+            },
+            hide_index=True,
+        )
+
+        # -- CSV export ---------------------------------------------------
+        csv_buffer = io.StringIO()
+        df.to_csv(csv_buffer, index=False)
+        st.download_button(
+            label="📥 Download as CSV",
+            data=csv_buffer.getvalue(),
+            file_name=f"paleodata_{st.session_state['query_taxon']}_{ma_min:.0f}_{ma_max:.0f}Ma.csv",
+            mime="text/csv",
+            type="primary",
+        )
+
+else:
+    # Landing state — show instructions
+    st.info(
+        "Enter a taxon name in the sidebar (e.g. **Ceratopsidae**, "
+        "**Tyrannosauridae**, **Mammalia**) and click **Search PBDB** "
+        "to begin exploring the fossil record."
+    )
+    st.markdown(
+        """
+        ### What this app does
+        1. **Queries** the Paleobiology Database for fossil occurrences.
+        2. **Cleans** the raw data (drops records missing age or coordinates).
+        3. **Visualises** results on a paleogeographic map and a deep-time timeline.
+        4. **Exports** the cleaned dataset as a CSV for your own analysis.
+        """
+    )
+
+# ---------------------------------------------------------------------------
+# 📚 Taxon & Clade Reference (always visible)
+# ---------------------------------------------------------------------------
+st.markdown("---")
+st.subheader("📚 Taxon & Clade Reference")
+st.caption(
+    "Click any name below to auto-fill the sidebar search box.  "
+    "Larger clades (families, orders) return more records; individual genera return more focused results."
+)
+
+with st.expander("🦖 Dinosauria — Dinosaurs", expanded=False):
+    col_a, col_b, col_c = st.columns(3)
+
+    with col_a:
+        _clickable_taxa_section("Theropoda (meat-eaters)", [
+            ("Tyrannosauridae", "T. rex family"),
+            ("Tyrannosaurus", ""),
+            ("Spinosauridae", ""),
+            ("Spinosaurus", ""),
+            ("Allosauridae", ""),
+            ("Allosaurus", ""),
+            ("Dromaeosauridae", "raptors"),
+            ("Velociraptor", ""),
+            ("Troodontidae", ""),
+            ("Coelophysoidea", ""),
+            ("Abelisauridae", ""),
+            ("Carcharodontosauridae", ""),
+            ("Giganotosaurus", ""),
+            ("Compsognathidae", ""),
+            ("Ornithomimidae", ""),
+            ("Oviraptoridae", ""),
+            ("Therizinosauridae", ""),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Sauropodomorpha (long-necks)", [
+            ("Sauropoda", ""),
+            ("Titanosauria", ""),
+            ("Brachiosauridae", ""),
+            ("Brachiosaurus", ""),
+            ("Diplodocidae", ""),
+            ("Diplodocus", ""),
+            ("Apatosaurus", ""),
+            ("Camarasauridae", ""),
+            ("Dicraeosauridae", ""),
+        ], num_cols=1)
+
+        _clickable_taxa_section("Ornithischia (bird-hipped)", [
+            ("Stegosauridae", ""),
+            ("Stegosaurus", ""),
+            ("Ankylosauridae", ""),
+            ("Ankylosaurus", ""),
+            ("Nodosauridae", ""),
+        ], num_cols=1)
+
+    with col_c:
+        _clickable_taxa_section("Marginocephalia", [
+            ("Ceratopsidae", "horned dinos"),
+            ("Triceratops", ""),
+            ("Centrosaurus", ""),
+            ("Styracosaurus", ""),
+            ("Pachycephalosauridae", ""),
+            ("Pachycephalosaurus", ""),
+        ], num_cols=1)
+
+        _clickable_taxa_section("Ornithopoda", [
+            ("Hadrosauridae", "duck-bills"),
+            ("Edmontosaurus", ""),
+            ("Parasaurolophus", ""),
+            ("Iguanodontidae", ""),
+            ("Iguanodon", ""),
+            ("Hypsilophodontidae", ""),
+        ], num_cols=1)
+
+with st.expander("🦕 Other Mesozoic Reptiles", expanded=False):
+    col_a, col_b, col_c = st.columns(3)
+
+    with col_a:
+        _clickable_taxa_section("Pterosauria (flying reptiles)", [
+            ("Pterosauria", ""),
+            ("Pterodactylidae", ""),
+            ("Pteranodon", ""),
+            ("Azhdarchidae", ""),
+            ("Quetzalcoatlus", ""),
+            ("Rhamphorhynchidae", ""),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Marine Reptiles", [
+            ("Ichthyosauria", ""),
+            ("Ichthyosaurus", ""),
+            ("Plesiosauria", ""),
+            ("Plesiosaurus", ""),
+            ("Elasmosauridae", ""),
+            ("Pliosauridae", ""),
+            ("Mosasauridae", ""),
+            ("Mosasaurus", ""),
+        ], num_cols=1)
+
+        _clickable_taxa_section("Other Diapsids", [
+            ("Crocodylomorpha", ""),
+            ("Choristodera", ""),
+        ], num_cols=1)
+
+    with col_c:
+        _clickable_taxa_section("Synapsids (mammal ancestors)", [
+            ("Therapsida", ""),
+            ("Dicynodontia", ""),
+            ("Cynodontia", ""),
+            ("Dimetrodon", ""),
+            ("Lystrosaurus", ""),
+        ], num_cols=1)
+
+with st.expander("🐘 Mammalia — Mammals", expanded=False):
+    col_a, col_b, col_c = st.columns(3)
+
+    with col_a:
+        _clickable_taxa_section("Primates & Relatives", [
+            ("Primates", ""),
+            ("Hominidae", ""),
+            ("Homo", ""),
+            ("Australopithecus", ""),
+            ("Plesiadapiformes", ""),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Ungulates & Large Herbivores", [
+            ("Proboscidea", "elephants"),
+            ("Mammuthus", "mammoths"),
+            ("Mammut", "mastodons"),
+            ("Perissodactyla", "horses, rhinos"),
+            ("Equidae", "horses"),
+            ("Equus", ""),
+            ("Rhinocerotidae", ""),
+            ("Brontotheriidae", ""),
+            ("Artiodactyla", "even-toed"),
+            ("Camelidae", ""),
+            ("Bovidae", ""),
+            ("Cervidae", "deer"),
+        ], num_cols=1)
+
+    with col_c:
+        _clickable_taxa_section("Carnivora & Others", [
+            ("Carnivora", "meat-eaters"),
+            ("Felidae", "cats"),
+            ("Smilodon", "sabre-tooth"),
+            ("Canidae", "dogs"),
+            ("Ursidae", "bears"),
+            ("Cetacea", "whales"),
+            ("Basilosauridae", ""),
+            ("Chiroptera", "bats"),
+            ("Rodentia", "rodents"),
+            ("Xenarthra", "sloths, armadillos"),
+            ("Megatherium", "giant sloth"),
+            ("Marsupialia", ""),
+        ], num_cols=1)
+
+with st.expander("🦈 Marine Life & Invertebrates", expanded=False):
+    col_a, col_b, col_c = st.columns(3)
+
+    with col_a:
+        _clickable_taxa_section("Fish", [
+            ("Chondrichthyes", "sharks & rays"),
+            ("Carcharodon", "great white"),
+            ("Megalodon", ""),
+            ("Osteichthyes", "bony fish"),
+            ("Actinopterygii", ""),
+            ("Sarcopterygii", "lobe-finned"),
+            ("Coelacanthiformes", ""),
+            ("Placodermi", ""),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Molluscs", [
+            ("Ammonoidea", "ammonites"),
+            ("Nautiloidea", ""),
+            ("Bivalvia", "clams, oysters"),
+            ("Gastropoda", "snails"),
+            ("Belemnitida", ""),
+            ("Coleoidea", "squid, octopus"),
+        ], num_cols=1)
+
+        _clickable_taxa_section("Other Invertebrates", [
+            ("Trilobita", "trilobites"),
+            ("Eurypterida", "sea scorpions"),
+        ], num_cols=1)
+
+    with col_c:
+        _clickable_taxa_section("Corals, Sponges & More", [
+            ("Rugosa", "horn corals"),
+            ("Tabulata", ""),
+            ("Scleractinia", "stony corals"),
+            ("Porifera", "sponges"),
+            ("Stromatoporoidea", ""),
+            ("Brachiopoda", ""),
+            ("Bryozoa", ""),
+            ("Echinodermata", ""),
+            ("Crinoidea", "sea lilies"),
+            ("Echinoidea", "sea urchins"),
+            ("Graptolithina", ""),
+            ("Foraminifera", ""),
+        ], num_cols=1)
+
+with st.expander("🦴 Early Vertebrates & Transitional Forms", expanded=False):
+    col_a, col_b = st.columns(2)
+
+    with col_a:
+        _clickable_taxa_section("Early Tetrapods & Amphibians", [
+            ("Tiktaalik", ""),
+            ("Ichthyostega", ""),
+            ("Acanthostega", ""),
+            ("Temnospondyli", ""),
+            ("Lepospondyli", ""),
+            ("Lissamphibia", "modern amphibians"),
+            ("Anura", "frogs"),
+            ("Caudata", "salamanders"),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Reptiles & Birds", [
+            ("Testudines", "turtles"),
+            ("Squamata", "lizards & snakes"),
+            ("Aves", "birds"),
+            ("Archaeopteryx", ""),
+            ("Enantiornithes", ""),
+            ("Ichthyornis", ""),
+            ("Sphenisciformes", "penguins"),
+            ("Phorusrhacidae", "terror birds"),
+            ("Dromornithidae", ""),
+        ], num_cols=1)
+
+with st.expander("🌿 Plants", expanded=False):
+    col_a, col_b, col_c = st.columns(3)
+
+    with col_a:
+        _clickable_taxa_section("Early Plants", [
+            ("Lycopodiophyta", "club mosses"),
+            ("Sphenopsida", "horsetails"),
+            ("Pteridophyta", "ferns"),
+            ("Progymnospermopsida", ""),
+            ("Ginkgophyta", ""),
+            ("Ginkgo", ""),
+        ], num_cols=1)
+
+    with col_b:
+        _clickable_taxa_section("Seed Plants & Conifers", [
+            ("Pinophyta", "conifers"),
+            ("Pinaceae", ""),
+            ("Cycadophyta", "cycads"),
+            ("Bennettitales", ""),
+            ("Cordaitales", ""),
+            ("Glossopteridaceae", ""),
+            ("Corystospermaceae", ""),
+        ], num_cols=1)
+
+    with col_c:
+        _clickable_taxa_section("Flowering Plants", [
+            ("Angiospermae", "flowering plants"),
+            ("Magnoliopsida", ""),
+            ("Arecaceae", "palms"),
+            ("Poaceae", "grasses"),
+            ("Nymphaeaceae", "water lilies"),
+            ("Proteaceae", ""),
+        ], num_cols=1)
+
+st.markdown("---")
+st.caption(
+    "Tip: Click any button above to auto-fill the search bar, then click **Search PBDB**.  "
+    "Higher-level clades (e.g. *Theropoda*, *Ammonoidea*, *Trilobita*) yield large datasets; "
+    "individual genera (e.g. *Triceratops*, *Megalodon*, *Archaeopteryx*) give focused results."
+)

data_processor.py

@@ -0,0 +1,218 @@
+"""
+PaleoData Explorer — Data Processor
+====================================
+Takes the raw JSON list returned by :mod:`api_client` and transforms it
+into a clean, analysis-ready ``pandas.DataFrame``.
+
+Key responsibilities
+--------------------
+1. Parse PBDB JSON records into a flat DataFrame.
+2. Filter out records that lack temporal bounds (``max_ma`` / ``min_ma``)
+   or paleocoordinates (``paleolat`` / ``paleolng``).
+3. Derive a ``middle_age`` column (``(max_ma + min_ma) / 2``) for point
+   plotting on temporal charts.
+4. Optionally filter by a user-supplied geological time window.
+5. Surface statistics (record counts at each stage) so the UI can show
+   the user what was discarded and why.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional, Tuple
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# PBDB raw field → canonical field name mapping.
+# The PBDB API returns abbreviated keys; we normalise them here so the
+# rest of the pipeline works with descriptive names.
+PBDB_COLUMN_MAP: Dict[str, str] = {
+    "eag": "max_ma",          # early age  → older bound
+    "lag": "min_ma",          # late age   → younger bound
+    "tna": "matched_name",    # taxon name
+    "oei": "early_interval",
+    "oli": "late_interval",
+    "pla": "paleolat",
+    "pln": "paleolng",
+    "phl": "phylum",
+    "cll": "class",
+    "odl": "order",
+    "fml": "family",
+    "gnl": "genus",
+}
+
+# Canonical field names used after renaming.
+FIELDS_TEMPORAL = ("max_ma", "min_ma")
+FIELDS_SPATIAL = ("paleolat", "paleolng")
+FIELDS_TAXONOMIC = (
+    "matched_name",
+    "early_interval",
+    "late_interval",
+    "phylum",
+    "class",
+    "order",
+    "family",
+    "genus",
+)
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def records_to_dataframe(records: List[Dict[str, Any]]) -> pd.DataFrame:
+    """Convert raw PBDB occurrence records into a :class:`pandas.DataFrame`.
+
+    Parameters
+    ----------
+    records : list[dict]
+        The list returned by :func:`api_client.fetch_occurrences`.
+
+    Returns
+    -------
+    pd.DataFrame
+        A DataFrame where each row is one occurrence.  The columns
+        include all keys present in the raw JSON, subject to Pandas'
+        internal flattening of nested structures when possible.
+        Returns an empty DataFrame (0 rows) if the input list is empty.
+    """
+    if not records:
+        logger.warning("records_to_dataframe called with empty list")
+        return pd.DataFrame()
+
+    df = pd.DataFrame(records)
+    logger.debug("Raw DataFrame shape: %s", df.shape)
+    return df
+
+
+def clean_occurrence_data(
+    df: pd.DataFrame,
+    *,
+    min_ma: Optional[float] = None,
+    max_ma: Optional[float] = None,
+) -> Tuple[pd.DataFrame, Dict[str, int]]:
+    """Clean a raw occurrence DataFrame and optionally subset it to a time window.
+
+    Cleaning steps (in order)
+    -------------------------
+    1. Remove rows where **both** ``max_ma`` and ``min_ma`` are missing
+       (records without any age information are unusable).
+    2. Impute missing ``max_ma`` / ``min_ma`` where only one is
+       available by taking the available value (conservative estimate).
+    3. Remove rows where ``paleolat`` **or** ``paleolng`` is missing
+       (cannot plot on a map).
+    4. Derive ``middle_age`` = ``(max_ma + min_ma) / 2``.
+    5. If ``min_ma`` and/or ``max_ma`` are supplied, filter the
+       DataFrame to occurrences whose ``middle_age`` falls within the
+       requested window.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Raw DataFrame from :func:`records_to_dataframe`.
+    min_ma, max_ma : float or None
+        Optional temporal boundaries in Ma.  Only occurrences whose
+        ``middle_age`` lies **between** *max_ma* (older bound) and
+        *min_ma* (younger bound) are kept.
+
+    Returns
+    -------
+    df : pd.DataFrame
+        Cleaned, filtered DataFrame.  May be empty.
+    stats : dict
+        Counts at each pipeline stage for transparency:
+        ``{"raw": n, "has_temporal": n, "has_spatial": n, "in_window": n}``
+    """
+    n_raw = len(df)
+    stats: Dict[str, int] = {"raw": n_raw}
+
+    if df.empty:
+        logger.warning("Input DataFrame is empty; nothing to clean.")
+        stats.update(has_temporal=0, has_spatial=0, in_window=0)
+        return df, stats
+
+    # ---- Step 0: normalise PBDB abbreviated column names ---------------
+    rename_map = {k: v for k, v in PBDB_COLUMN_MAP.items() if k in df.columns}
+    df = df.rename(columns=rename_map)
+    logger.debug("Renamed %d columns: %s", len(rename_map), list(rename_map.keys()))
+
+    # ---- Step 1: require at least one temporal field -------------------
+    temporal_mask = df[list(FIELDS_TEMPORAL)].notna().any(axis=1)
+    df = df.loc[temporal_mask].copy()
+    stats["has_temporal"] = len(df)
+    logger.debug("After temporal filter: %d rows (dropped %d)",
+                 stats["has_temporal"], n_raw - stats["has_temporal"])
+
+    # ---- Step 2: impute lone temporal values ---------------------------
+    # If max_ma is NaN but min_ma exists, set max_ma = min_ma (point date)
+    max_null = df["max_ma"].isna()
+    if max_null.any():
+        df.loc[max_null, "max_ma"] = df.loc[max_null, "min_ma"]
+
+    # If min_ma is NaN but max_ma exists, set min_ma = max_ma
+    min_null = df["min_ma"].isna()
+    if min_null.any():
+        df.loc[min_null, "min_ma"] = df.loc[min_null, "max_ma"]
+
+    # ---- Step 3: require both paleocoordinates -------------------------
+    spatial_mask = df[list(FIELDS_SPATIAL)].notna().all(axis=1)
+    df = df.loc[spatial_mask].copy()
+    stats["has_spatial"] = len(df)
+    logger.debug("After spatial filter: %d rows (dropped %d)",
+                 stats["has_spatial"], stats["has_temporal"] - stats["has_spatial"])
+
+    # ---- Step 4: compute middle_age ------------------------------------
+    df["middle_age"] = (df["max_ma"].astype(float) + df["min_ma"].astype(float)) / 2.0
+
+    # ---- Step 5: optional time-window filter ---------------------------
+    if max_ma is not None or min_ma is not None:
+        in_window = pd.Series(True, index=df.index)
+
+        if max_ma is not None:
+            in_window &= df["middle_age"] <= float(max_ma)
+        if min_ma is not None:
+            in_window &= df["middle_age"] >= float(min_ma)
+
+        df = df.loc[in_window].copy()
+        stats["in_window"] = len(df)
+        logger.debug("After time-window filter: %d rows (dropped %d)",
+                     stats["in_window"], stats["has_spatial"] - stats["in_window"])
+    else:
+        stats["in_window"] = stats["has_spatial"]
+
+    # ---- Ensure consistent float types for critical columns ------------
+    for col in ("max_ma", "min_ma", "middle_age", "paleolat", "paleolng"):
+        if col in df.columns:
+            df[col] = pd.to_numeric(df[col], errors="coerce")
+
+    logger.info("Cleaning pipeline done: raw=%d → has_temporal=%d → has_spatial=%d → in_window=%d",
+                stats["raw"], stats["has_temporal"], stats["has_spatial"], stats["in_window"])
+    return df, stats
+
+
+def get_dataframe_statistics(df: pd.DataFrame) -> Dict[str, Any]:
+    """Return a small summary dict for display in the UI.
+
+    Includes unique taxa counts, time span, and geographic extent.
+    """
+    if df.empty:
+        return {"unique_taxa": 0, "time_span_ma": None}
+
+    stats = {
+        "record_count": len(df),
+        "unique_taxa": int(df["matched_name"].nunique()),
+        "unique_families": int(df["family"].nunique()) if "family" in df.columns else 0,
+        "unique_genera": int(df["genus"].nunique()) if "genus" in df.columns else 0,
+        "oldest_ma": float(df["middle_age"].max()),
+        "youngest_ma": float(df["middle_age"].min()),
+        "time_span_ma": float(df["middle_age"].max() - df["middle_age"].min()),
+        "lat_extent": float(df["paleolat"].max() - df["paleolat"].min()) if "paleolat" in df.columns else None,
+        "lng_extent": float(df["paleolng"].max() - df["paleolng"].min()) if "paleolng" in df.columns else None,
+    }
+    return stats

docker-compose.yml

@@ -0,0 +1,6 @@
+services:
+  paleopedia:
+    build: .
+    ports:
+      - "8501:7860"
+    restart: unless-stopped

requirements.txt

@@ -0,0 +1,7 @@
+streamlit>=1.28.0
+pandas>=2.0.0
+numpy>=1.24.0
+requests>=2.28.0
+plotly>=5.15.0
+folium>=0.15.0
+streamlit-folium>=0.15.0

visualizations.py

@@ -0,0 +1,218 @@
+"""
+PaleoData Explorer — Visualizations
+====================================
+Produces two core scientific visuals from a cleaned occurrence DataFrame:
+
+1. **Paleogeographic Map** (Folium + streamlit-folium)
+   Plots fossil localities using paleocoordinates (``paleolat`` /
+   ``paleolng``), i.e. where the organism lived accounting for
+   tectonic drift.
+
+2. **Deep-Time Timeline** (Plotly)
+   A horizontal range chart showing the stratigraphic lifespan of
+   each taxon.  The X‑axis (geological time in Ma) is **reversed**
+   so that older dates appear on the left and younger dates on the
+   right, as is standard in geology.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Dict, List, Optional
+
+import folium
+from folium.plugins import MarkerCluster
+import numpy as np
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DEFAULT_MAP_ZOOM = 3
+MAX_MARKERS_MAP = 1500  # cap markers for performance
+
+
+# ---------------------------------------------------------------------------
+# 1. Paleogeographic Map (Folium)
+# ---------------------------------------------------------------------------
+
+def build_paleo_map(
+    df: pd.DataFrame,
+    *,
+    height: int = 550,
+    zoom: int = DEFAULT_MAP_ZOOM,
+) -> folium.Map:
+    """Create a Folium map of fossil paleocoordinates.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Cleaned occurrence DataFrame.  Must contain at least
+        ``paleolat``, ``paleolng``, ``matched_name``.
+    height : int
+        Height in pixels passed to ``st_folium``.
+    zoom : int
+        Initial zoom level.
+
+    Returns
+    -------
+    folium.Map
+        The ready-to-render Folium map object.
+    """
+    if df.empty:
+        logger.warning("Empty DataFrame passed to build_paleo_map")
+        return folium.Map(location=[0, 0], zoom_start=zoom, tiles="OpenStreetMap")
+
+    # Centre on the median paleocoordinate
+    center_lat = float(df["paleolat"].median())
+    center_lng = float(df["paleolng"].median())
+
+    m = folium.Map(
+        location=[center_lat, center_lng],
+        zoom_start=zoom,
+        tiles="CartoDB positron",
+        control_scale=True,
+    )
+
+    # Sample if too many points (keeps the map snappy)
+    work_df = df
+    if len(work_df) > MAX_MARKERS_MAP:
+        logger.info("Sampling %d points down to %d for map rendering",
+                    len(work_df), MAX_MARKERS_MAP)
+        work_df = work_df.sample(n=MAX_MARKERS_MAP, random_state=42)
+
+    cluster = MarkerCluster(name="Fossil Occurrences").add_to(m)
+
+    for _, row in work_df.iterrows():
+        lat = float(row["paleolat"])
+        lng = float(row["paleolng"])
+        if not (np.isfinite(lat) and np.isfinite(lng)):
+            continue
+
+        name = row.get("matched_name", "Unknown")
+        early = row.get("early_interval", "")
+        max_ma_val = row.get("max_ma", np.nan)
+        min_ma_val = row.get("min_ma", np.nan)
+
+        tooltip_lines = [f"<b>{name}</b>"]
+        if early and isinstance(early, str):
+            tooltip_lines.append(f"Interval: {early}")
+        if np.isfinite(max_ma_val) and np.isfinite(min_ma_val):
+            tooltip_lines.append(f"Age: {max_ma_val:.1f}–{min_ma_val:.1f} Ma")
+
+        folium.CircleMarker(
+            location=[lat, lng],
+            radius=5,
+            color="#c0392b",
+            fill=True,
+            fill_color="#e74c3c",
+            fill_opacity=0.7,
+            tooltip=folium.Tooltip("<br>".join(tooltip_lines)),
+            popup=folium.Popup(name, parse_html=False, max_width=200),
+        ).add_to(cluster)
+
+    folium.LayerControl().add_to(m)
+    return m
+
+
+# ---------------------------------------------------------------------------
+# 2. Deep-Time Timeline (Plotly)
+# ---------------------------------------------------------------------------
+
+def build_timeline(
+    df: pd.DataFrame,
+    *,
+    max_taxa: int = 50,
+    height: int = 700,
+) -> go.Figure:
+    """Build a Plotly horizontal range chart of taxon stratigraphic ranges.
+
+    Geological convention: the X‑axis (Time, Ma) is **reversed** so
+    that older dates sit on the left.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Cleaned occurrence DataFrame (requires ``matched_name``,
+        ``max_ma``, ``min_ma``, ``middle_age``).
+    max_taxa : int
+        Maximum number of unique taxa to display (top‑N by oldest age).
+    height : int
+        Figure height in pixels.
+
+    Returns
+    -------
+    go.Figure
+        Plotly figure ready for ``st.plotly_chart``.
+    """
+    if df.empty:
+        logger.warning("Empty DataFrame passed to build_timeline")
+        fig = go.Figure()
+        fig.update_layout(
+            title="No data to display",
+            xaxis_title="Time (Ma)",
+            yaxis_title="Taxon",
+            height=300,
+        )
+        fig.update_xaxes(autorange="reversed")
+        return fig
+
+    # Aggregate to unique taxa: take the overall max_ma / min_ma per name
+    agg: pd.DataFrame = (
+        df.groupby("matched_name", as_index=False)
+        .agg(max_ma=("max_ma", "max"), min_ma=("min_ma", "min"))
+        .dropna(subset=["max_ma", "min_ma"])
+    )
+
+    if agg.empty:
+        logger.warning("No taxa with valid temporal data remain after aggregation")
+        fig = go.Figure()
+        fig.update_layout(title="No taxa with valid age data", height=300)
+        fig.update_xaxes(autorange="reversed")
+        return fig
+
+    agg["middle_age"] = (agg["max_ma"] + agg["min_ma"]) / 2.0
+
+    # Keep top-N by oldest age (largest max_ma)
+    agg = agg.nlargest(max_taxa, "max_ma")
+    agg = agg.sort_values("middle_age", ascending=False)
+
+    fig = go.Figure()
+
+    # Draw horizontal line segments for each taxon
+    for _, row in agg.iterrows():
+        fig.add_trace(
+            go.Scatter(
+                x=[row["max_ma"], row["min_ma"]],
+                y=[row["matched_name"], row["matched_name"]],
+                mode="lines+markers",
+                line={"color": "#2c3e50", "width": 6},
+                marker={"size": 6, "color": "#e74c3c"},
+                name=row["matched_name"],
+                hovertemplate=(
+                    f"<b>{row['matched_name']}</b><br>"
+                    f"Range: {row['max_ma']:.2f}–{row['min_ma']:.2f} Ma<br>"
+                    f"<extra></extra>"
+                ),
+                showlegend=False,
+            )
+        )
+
+    fig.update_layout(
+        title="Fossil Taxon Stratigraphic Ranges",
+        xaxis_title="Time (Ma)",
+        yaxis_title="",
+        height=max(height, 100 + 25 * len(agg)),
+        margin={"l": 10, "r": 20, "t": 40, "b": 40},
+        hovermode="closest",
+    )
+
+    # Reverse X-axis (older → younger = left → right)
+    fig.update_xaxes(autorange="reversed")
+
+    return fig