Home - wtblock/ClimateSuite GitHub Wiki
Climate Suite Overview
The Climate Suite consists of three applications and one shared library.
Together they provide a complete workflow for importing, validating, querying, analyzing, and visualizing United States Historical Climatology Network (USHCN) data.
A. ImportUSHCN
Type: Command-line program
Purpose: Imports all USHCN station and temperature data and builds the relational database ClimateUSHCN.db.
Data Sources (3,655 files total)
- ushcn-v2.5-stations.txt β Metadata for all 1218 stations
- 1218 Γ .tmax files β Maximum monthly temperatures
- 1218 Γ .tmin files β Minimum monthly temperatures
- 1218 Γ .tavg files β Average monthly temperatures
Database Schema (ClimateUSHCN.db)
Table: Stations
| Column | Description |
|---|---|
| StationID | USHCN station identifier |
| GUID | Internal unique identifier |
| Latitude | GPS latitude |
| Longitude | GPS longitude |
| Elevation | Elevation in meters |
| State | Two-letter state code |
| Location | City or locality |
| Component1 | Metadata component |
| Component2 | Metadata component |
| Component3 | Metadata component |
| UTCOffset | Time zone offset |
Table: Months
| Column | Description |
|---|---|
| StationID | Station identifier |
| Year | Year of reading |
| Month | Month of reading |
| MeasurementType | tmax / tmin / tavg |
| CentigradeRaw | Raw temperature (Β°C) |
| DMFlag | Data measurement flag |
| QCFlag | Quality control flag |
| DSFlag | Data source flag |
Table: Years
| Column | Description |
|---|---|
| StationID | Station identifier |
| Year | Year of reading |
| MeasurementType | tmax / tmin / tavg |
| MaxValue | Annual maximum |
| MinValue | Annual minimum |
| AvgValue | Annual average |
| ValidReadings | Count of valid monthly readings |
Table: GreaterCounts
| Column | Description |
|---|---|
| StationID | Station identifier |
| Year | Year of reading |
| MeasurementType | tmax / tmin / tavg |
| ThresholdF | Threshold in Β°F |
| Count | Number of months exceeding threshold |
Table: Metadata
| Column | Description |
|---|---|
| Key | Metadata key |
| Value | Metadata value |
B. QueryUSHCN
Type: Command-line program
Purpose: Natural-language query engine for the ClimateUSHCN.db database.
Usage
Help Parameters
/helpβ Show help/allβ List all query examples/stationβ Station queries/statisticsβ Statistical queries/stateβ State-specific queries/monthβ Monthly queries/yearβ Annual queries/countβ Threshold-count queries/dbβ Database queries/QCβ Quality-control queries
Example Query Categories
Station Queries
QueryUSHCN List all stations.QueryUSHCN Show active stations in Colorado.QueryUSHCN Minimum monthly temperatures for station USH00419532.
State Queries
QueryUSHCN Monthly temperatures in Texas units degF.QueryUSHCN Annual averages in Colorado.QueryUSHCN Temperature trend in Texas.
Monthly Data Queries
QueryUSHCN Monthly temperatures in Utah including estimated values.QueryUSHCN Maximum monthly temperatures for station USH00419532.
Annual Data Queries
QueryUSHCN Annual maximums in Texas from 1900 through 2025.QueryUSHCN Annual minimums in Montana.
Threshold Count Queries
QueryUSHCN Show the percent of months above 100 from 1977 to 1987.
Database Queries
QueryUSHCN List your table schemas.QueryUSHCN What version of the data is in the database?
Quality Control / Reproduction Queries
QueryUSHCN Reproduce decade 1 for station USH00419532 minimums.QueryUSHCN Compare Kansas annual maximum temperatures QC vs non QC.
Verification Queries
QueryUSHCN Verify annual averages for station USH00419532 from 1900 to 1920.
C. Climate Explorer
Type: Windows desktop application
Purpose: Visualization, analysis, mapping, and publishing tool for climate data.
Core Capabilities
- Graph climate data nationally, by state, or by station
- Import images and Markdown into documents
- Save documents as:
- XML (.CEx)
- Zip (.CE)
- Export:
- All pages as JPG (scanner-friendly)
- Individual images
- Full document as PDF
- Print to any Windows-supported printer
- Layout formatted as a letter-size book, compatible with Kindle publishing
Map Generation and Station Interaction
Climate Explorer includes a full map-rendering engine based on station GPS coordinates.
Map Types
- National Map β Displays all USHCN stations
- State Map β Displays stations within a selected state
- Station Map β Displays a single station with surrounding geographic context
Interactive Features
- Right-click on any map
- Option to open the same location in Google Maps or Bing Maps
- Click on any station
- Displays station name
- Shows latitude and longitude
- Allows immediate generation of a new Climate Explorer output centered on that station
These features make Climate Explorer both a visualization tool and a geographic navigation interface for climate data.
Video Demonstration
A short YouTube video provides a quick walkthrough of Climate Explorer, showing how to navigate the database, view maps, generate graphs, and create documents. Itβs the fastest way to see the core features in action before exploring on your own.
D. Common Library
Type: Shared codebase
Purpose: Provides all applications with unified data structures, XML parsing, utilities, and climate logic.
Responsibilities
- XML parsing for USHCN data
- Shared climate data structures
- Database access helpers
- Graphing and rendering utilities
- Shared math and statistical routines
- Consistent behavior across all Climate Suite applications
Summary
The Climate Suite provides a complete pipeline:
- ImportUSHCN β Build the climate database
- QueryUSHCN β Validate and explore the data
- Climate Explorer β Visualize, map, and publish climate documents
- Common β Shared library powering all components
This architecture ensures consistency, reliability, and reproducibility across all climate analysis workflows.