Climate-Mood-Analysis/README.md

# 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.