Add project README

2026-06-11 15:35:15 -04:00
parent ce9672a734
commit 016f7386d8
1 changed files with 157 additions and 0 deletions
@@ -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.