worldclim-extract

Version Compatibility#

Reference examples tested with: Python 3.10+, rasterio 1.4+, pandas 2.0+

Before using code patterns, verify installed versions match. If versions differ:

• pip show rasterio pandas openpyxl

If code throws ImportError, install missing packages:

bash

pip install rasterio pandas openpyxl

Overview#

WorldClim provides global climate data as GeoTIFF raster files. Each .tif file is a grid covering the entire Earth, where each grid cell stores a climate value (e.g., temperature in °C or precipitation in mm). This skill automates the process of extracting climate values for specific geographic coordinates.

How It Works#

1. Input: Excel or CSV file containing sample coordinates (longitude, latitude)
2. Data: WorldClim 2.1 bioclimatic GeoTIFF files (19 BIO variables, 1970-2000 average)
3. Process: For each coordinate, find the corresponding grid cell and read its value
4. Output: Original data plus extracted climate columns appended

Grid Resolution#

ResolutionCell SizeApprox. AreaFile Size10m0.167°18.5 km²48 MB zip5m0.083°9.3 km²170 MB zip2.5m0.042°4.6 km²650 MB zip

Default: 10m — sufficient for most ecological/population genetics studies.

Quick Start#

Using the CLI Script#

A reusable Python script is provided at {baseDir}/extract_worldclim.py:

bash

# Extract BIO1 (annual mean temp) and BIO12 (annual precipitation) — default
python3 {baseDir}/extract_worldclim.py \
  -i samples.xlsx \
  -o samples_with_climate.xlsx

# Extract all 19 bioclimatic variables
python3 {baseDir}/extract_worldclim.py \
  -i samples.xlsx \
  -o samples_all_bio.xlsx \
  --bios 1-19

# Extract specific variables with custom column names
python3 {baseDir}/extract_worldclim.py \
  -i coords.csv \
  -o result.xlsx \
  --bios 1,5,6,12,13 \
  --res 2.5m \
  --lon longitude \
  --lat latitude

Using Python Directly#

For custom integration or programmatic use:

python

import pandas as pd
import rasterio

def extract_bio(tif_path, lon, lat):
    """Extract a single value from a GeoTIFF at given coordinates."""
    with rasterio.open(tif_path) as src:
        value = next(src.sample([(lon, lat)]))[0]
    return value

# Read sample coordinates
df = pd.read_excel("samples.xlsx")
coords = list(zip(df["经度"], df["纬度"]))

# Extract BIO1 (Annual Mean Temperature)
with rasterio.open("wc2.1_10m_bio_1.tif") as src:
    df["年均温度_C"] = [v[0] for v in src.sample(coords)]

# Extract BIO12 (Annual Precipitation)
with rasterio.open("wc2.1_10m_bio_12.tif") as src:
    df["年降水量_mm"] = [v[0] for v in src.sample(coords)]

df.to_excel("samples_with_climate.xlsx", index=False)

WorldClim Data Download#

Automatic (script handles it)#

The CLI script auto-downloads data on first run to the --cache directory (default: ./worldclim_data).

Manual Download#

If automatic download fails (e.g., network issues):

bash

# 10m resolution (~48 MB)
curl -O https://geodata.ucdavis.edu/climate/worldclim/2_1/base/wc2.1_10m_bio.zip
unzip wc2.1_10m_bio.zip -d ./worldclim_data/

# 2.5m resolution (~650 MB)
curl -O https://geodata.ucdavis.edu/climate/worldclim/2_1/base/wc2.1_2.5m_bio.zip
unzip wc2.1_2.5m_bio.zip -d ./worldclim_data/

BIO Variable Reference#

BIONameUnitDescriptionBIO1Annual Mean Temperature°C年均温度BIO2Mean Diurnal Range°C昼夜温差月均值BIO3Isothermality%等温性 (BIO2/BIO7 × 100)BIO4Temperature SeasonalitySD × 100温度季节性BIO5Max Temp of Warmest Month°C最暖月最高温BIO6Min Temp of Coldest Month°C最冷月最低温BIO7Temperature Annual Range°C年温度范围 (BIO5−BIO6)BIO8Mean Temp of Wettest Quarter°C最湿季均温BIO9Mean Temp of Driest Quarter°C最干季均温BIO10Mean Temp of Warmest Quarter°C最暖季均温BIO11Mean Temp of Coldest Quarter°C最冷季均温BIO12Annual Precipitationmm年降水量BIO13Precipitation of Wettest Monthmm最湿月降水量BIO14Precipitation of Driest Monthmm最干月降水量BIO15Precipitation SeasonalityCV降水季节性BIO16Precipitation of Wettest Quartermm最湿季降水量BIO17Precipitation of Driest Quartermm最干季降水量BIO18Precipitation of Warmest Quartermm最暖季降水量BIO19Precipitation of Coldest Quartermm最冷季降水量

Data Source: WorldClim 2.1 (1970-2000, 30-year average)

Input Format Requirements#

Required Columns#

• Longitude column: Decimal degrees, range [-180, 180]. Default column name: 经度 (override with --lon)
• Latitude column: Decimal degrees, range [-90, 90]. Default column name: 纬度 (override with --lat)

Supported Input Formats#

• .xlsx — Excel workbook (recommended, handles Chinese headers well)
• .csv — Comma-separated values

Common Issues#

IssueCauseSolutionCoordinates read as textHidden special characters (e.g., \xa0 non-breaking space)Script auto-cleans with pd.to_numeric(errors='coerce'); check for NA after conversionNegative longitudes rejectedUsing East/West format instead of decimalConvert to decimal: 东经 117° → 117.0; 西经 117° → -117.0Missing extracted valuesCoordinate falls in ocean or outside raster boundsCheck coordinate validity; WorldClim covers land globally

Output Format#

The output file contains all original columns plus extracted BIO columns:

text

名称    经度        纬度        年均温度_C    年降水量_mm
NFAL10  117.214052  31.270421   16.15        1325.0
NFBJ1   116.591445  40.032115   11.88        542.0

Using R (terra) for Cross-Validation#

If you need to validate results with R:

r

library(terra)

# Read raster stack
bio <- rast(list.files("./worldclim_data", pattern = "\\.tif$", full.names = TRUE))

# Read and clean coordinates
pts <- readxl::read_excel("samples.xlsx")
pts$经度 <- as.numeric(gsub("\\s+", "", pts$经度))  # Remove hidden spaces
pts$纬度 <- as.numeric(pts$纬度)
pts <- pts[!is.na(pts$经度) & !is.na(pts$纬度), ]

# Extract
v <- vect(pts, geom = c("经度", "纬度"), crs = "EPSG:4326")
result <- extract(bio, v)
write.csv(cbind(pts, result[, -1]), "output.csv", row.names = FALSE)

Note: R's as.numeric() is stricter than Python's pandas and may fail on hidden whitespace. Always clean coordinates before conversion.

Decision Tree#

text

Need to extract climate data for sample coordinates?
├── Have coordinates in Excel/CSV?
│   └── Use the CLI script: python3 extract_worldclim.py -i input.xlsx -o output.xlsx
├── Need only temperature and precipitation?
│   └── Default: --bios 1,12 (no need to specify)
├── Need all 19 bioclimatic variables?
│   └── Use: --bios 1-19
├── Need higher spatial resolution?
│   ├── ~9 km cells → --res 5m
│   └── ~4.6 km cells → --res 2.5m
└── Need to integrate into a Python pipeline?
    └── Use the direct Python code pattern with rasterio.sample()

Related Skills#

• bio-geo-data — For general geospatial data operations
• bio-read-sequences — For biological sequence file parsing
• bio-batch-processing — For processing multiple files in batch