ghcnh / docs /user_guide.md
alexdum's picture
docs: add architecture and user guide documentation and update .gitignore to track markdown files
281e438

GHCNh Explorer User Guide

Access the Application: https://alexdum-ghcnh.hf.space/

1. Introduction

The GHCNh Explorer is an interactive dashboard for exploring Global Historical Climatology Network hourly (GHCNh) data. It allows you to visualize detailed weather records from thousands of stations worldwide, including temperature, precipitation, wind, and pressure data.

2. Global Navigation (Sidebar)

The sidebar on the left controls the global view of the application.

  • Select Country: Filter the displayed stations by country. Leave empty to see all stations.
  • Select Date Selection: Define the "Global Window" for analysis.
    • Max Window: The range is limited to 366 days to ensure performance with high-resolution hourly data.
    • Smart Sliding:
      • Dragging the Start Date backward moves the entire window back (Anchor Start).
      • Dragging the End Date forward moves the entire window forward (Anchor End).
  • Download Stations: Exports a CSV list of all currently visible stations (filtered by country/bounds).

3. Map Interface

Application Map View

The main view is an interactive map showing available weather stations.

  • Blue Dots: Represent stations available within your selected filters.
  • Selection: Click any blue dot to select a station.
    • Red Highlight: The selected station is highlighted with a red ring.
    • Persistence: Note that even if you change global filters (like the date range) that might hide the station from the general list, the selected station remains highlighted so you never lose your place.

4. Station Details Panel

Station Details Panel

When a station is selected, a floating details panel appears.

Header Controls

  • Station Info: Name, ID, Country, Elevation, and Data Period.
  • Date Window: You can fine-tune the date range for this specific station here.
    • Synchronization: Changes here update the main sidebar, and vice-versa.
  • Export CSV: Download the parsed hourly data for the currently viewed period.
  • Close (X): Hides the panel.
    • Note: Closing the panel keeps the station selected. The data remains available in the "Data" tab until you select a new station.
    • Cancelling: If you close the panel while a download is still in progress, the download is cancelled.

Visualization Tabs

  1. Overview: A comprehensive 5-panel timeline showing:
    • Temperature & Dew Point
    • Wind Speed & Gusts
    • Pressure (MSL & Station)
    • Relative Humidity
    • Visibility
  2. Precipitation: Stacked bar charts showing precipitation accumulations across different intervals (1h, 3h, 6h, 24h).
  3. Wind: A Wind Rose diagram showing the frequency distribution of wind speed and direction.
  4. Weathergami: A heatmap of Daily Max vs. Daily Min temperatures, visualizing the station's climate signature.
  5. Diurnal: Shows the daily temperature cycle.
    • Red Line: The median hourly temperature across all selected days.
    • Grey Lines: Individual daily traces (sampled) to show variability.

5. Station Info & Data Tabs

Located at the top of the main dashboard:

  • Stations Info: A tabular list of all visible stations. Clicking a row selects that station on the map.
  • Data: Provides raw data access. Data Tab View
    • Hourly: The detailed hour-by-hour dataset.
    • Daily: A generated daily summary table.
    • Exports: Both tables include dedicated "Export CSV" buttons.