From 016f7386d8cebb4e91f2fe8b32e28e33794c50d7 Mon Sep 17 00:00:00 2001 From: Justin Fisher Date: Thu, 11 Jun 2026 15:35:15 -0400 Subject: [PATCH] Add project README --- README.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..146410f --- /dev/null +++ b/README.md @@ -0,0 +1,157 @@ +# Temperature-Based Analysis + +Temperature-Based Analysis is an exploratory project for studying how local +climate conditions vary across the United States and, eventually, whether those +conditions show any relationship with mood-based metrics. + +The project currently provides the **US County Climate Explorer**, an +interactive county-level map for viewing and filtering climate data. The mood +dataset and climate-to-mood correlation analysis are **not implemented yet**. +At this stage, the project is focused on building, validating, and presenting +the climate side of the analysis. + +## Current Features + +- Interactive Leaflet map with county boundaries and county selection +- Metric groups for climate classification, temperature, precipitation, + moisture, and solar exposure +- Numeric range filters and categorical filters +- County detail panel showing all available climate metrics +- Legends and in-app source descriptions +- Local CSV-based data loading with no application backend or build step +- Offline Python scripts for assembling and updating county climate data + +The browser currently loads 3,221 county-level records from +`data/climate-data.csv`. + +## Available Climate Metrics + +| Group | Metrics | +| --- | --- | +| Koppen-Geiger Classification | Majority county climate class | +| Temperature & Extremes | Annual average temperature, diurnal temperature range, absolute extreme days per year, and heat-index days | +| Precipitation & Moisture | Annual precipitation, precipitation seasonality, wettest month, driest month, and summer specific humidity | +| Solar Exposure | Average daily global horizontal irradiance (GHI) and cloudiness index | + +Most long-term climate metrics use a 1991-2020 reference period. The absolute +extreme-days metric currently uses 1991-2025 data. Definitions and time periods +are shown in the application's **Sources** dialog and documented in more detail +in [`scripts/county_data_sources.md`](scripts/county_data_sources.md). + +## Run the Explorer + +### Requirements + +- A modern web browser +- Python 3 +- PowerShell for the included convenience script +- An internet connection for Leaflet, map tiles, and hosted fonts + +No Node.js installation or frontend build is required. + +From the project root, run: + +```powershell +.\serve.ps1 +``` + +Then open: + +```text +http://localhost:8000/ +``` + +To use another port: + +```powershell +.\serve.ps1 -Port 8080 +``` + +The site must be served over HTTP because the browser loads the climate CSV and +county GeoJSON with `fetch()`. Opening `index.html` directly as a local file +will not work. + +## Using the Map + +1. Choose a metric group and metric from the control panel. +2. Adjust the value range or category filter to highlight matching counties. +3. Click a county to zoom to it and inspect all available metrics. +4. Use **Reset Country View** or **Clear Selection** to return to the broader + map. +5. Open **Sources** for metric definitions and data provenance. + +## Project Structure + +| Path | Purpose | +| --- | --- | +| `index.html` | Application structure and controls | +| `styles.css` | Layout and visual styling | +| `app.js` | Map rendering, filtering, county details, and source metadata | +| `serve.ps1` | Local HTTP server launcher | +| `data/climate-data.csv` | Browser-ready county climate records | +| `data/geojson-counties-fips.json` | County geometry keyed by FIPS code | +| `scripts/` | Climate-data download, aggregation, and update tools | +| `tests/` | Tests for the NSRDB polygon request and download workflow | + +## Climate Data Pipeline + +The checked-in browser assets are the final outputs needed to run the explorer. +The scripts directory contains the larger offline workflow used to derive those +outputs from sources including: + +- Beck et al. Koppen-Geiger climate classification data +- NOAA NCEI Climate Normals and nClimGrid data +- gridMET humidity data +- NREL National Solar Radiation Database data +- U.S. Census Bureau county geometry + +To work on the Python data pipeline, create a virtual environment and install +the ETL dependencies: + +```powershell +python -m venv .venv +.\.venv\Scripts\Activate.ps1 +python -m pip install -r scripts\requirements_county_etl.txt +``` + +Some data-generation workflows download large files or require NREL/NSRDB API +credentials. Generated source datasets are intentionally excluded from Git; +only the browser-ready CSV and GeoJSON are tracked. + +Run the current automated tests with: + +```powershell +python -m unittest discover -s tests +``` + +## Planned Mood Analysis + +The longer-term goal is to add mood-based metrics and investigate whether +patterns in those metrics are associated with climate characteristics such as +temperature, sunlight, cloudiness, humidity, precipitation, or extreme-weather +frequency. + +That phase still requires decisions about: + +- How mood data will be collected or sourced +- Geographic and temporal granularity +- Privacy, consent, and aggregation requirements +- Confounding variables and missing-data handling +- Appropriate statistical and visualization methods + +No mood records, mood visualizations, or correlation results are currently part +of the application. Any future relationship found by the project should be +treated as an association to investigate, not evidence that climate alone +causes changes in mood. + +## Current Limitations + +- The application presents long-term county summaries rather than live weather. +- Climate values aggregate conditions within county boundaries and do not + represent every location inside a county. +- Source datasets use different methods and, in some cases, different time + periods. +- Some solar metrics use representative-point values where county polygon + summaries are unavailable. +- The current interface is an exploratory visualization, not a completed + climate-and-mood research analysis.