tech4housing/kcrha_weather

KCRHA Weather Alert System

This repo maintains the logic to scrape publicly available data, as well as notify personnel about any upcoming severe weather patterns that require activation of public outreach resources

Table of Contents

• Installation
  • Prerequisites
  • Dependencies
  • Setup
• Usage
  • Examples
• Contributing

Installation

Prerequisites

• OpenJDK 17

Dependencies

TBD

Setup

There are a few configuration files, each with different purposes:

File	Purpose
alertRules.json	Rules for alerts
regions.json	Region aggregate definitions
style.css	Style for HTML-formatted emails
secrets.properties	Secrets specific to each user

Most of these files are prepared already for the KCRHA uses. However, the secrets.properties file is excluded from the Git repo. This is for privacy and security concerns. It's a simple implementation, but requires users to configure this file themselves before using this application.

The properties that must be set are as follows:

Property	Value	Source
AIRNOW_API_KEY	API Key able to connect to the AirNow API services	Create an AirNow account
MAIL_HOST_SERVER_PROPERTY	Mail server hostname	See admin
MAIL_HOST_PORT_PROPERTY	Mail server port	See admin
MAIL_HOST_USER_PROPERTY	Mail server user	See admin
MAIL_HOST_PASS_PROPERTY	Mail server pass	See admin
MAIL_TO_PROPERTY	Mail server recipient name	List of names/emails to notify
MAIL_FROM_NAME_PROPERTY	Mail server "from" name	See admin
MAIL_FROM_EMAIL_PROPERTY	Mail server "from" email	See admin

Here's an example of what your secret.properties might look:

AIRNOW_API_KEY=ABCDEF12-3456-7890-ABCD-0123456789AB

MAIL_HOST_SERVER=smtp.gmail.com
MAIL_HOST_PORT=587
[email protected]
MAIL_HOST_PASS=thisIsntARealPassword
MAIL_TO=Escalation Team,[email protected];Admin,[email protected]
MAIL_FROM_NAME=Automated Weather Alerts
[email protected]

Usage

./weather [task] [options]

Examples

# get the current weather in your current location
$ ./weather alerts

Contributing

Please do!

kcrha_weather's Issues

Explore extended forecast options

Background

When determining whether or not to activate resources and open emergency shelters, they need as much lead time as possible. More lead time allows them to better manage expectations with various coordinating organizations that can help acquire and set up emergency shelters for those who would be exposed to harmful weather conditions.

Issue

While the applications reports are currently capable of producing up to 7 days of forecast data (depending on the data type), more lead time is better ultimately. Users are currently supplementing this applications reports with additional forecasting information from sources such as weather.com.

Proposed Solution

We should investigate finding additional (or alternative) public data sources that may be able to provide us with forecasting data beyond the 7-day horizon. While this data does not need to be extremely accurate (as is the nature of forecasting), we should note any accuracy measurements that are available for any sources we identify as capable of fulfilling this need.

Improve nested command line task/option support

The current implementation only uses Apache Commons CLI to accomplish multiple task options. However this library seems very limited in its support for multiple command task/option combinations. One alternative library may be the JCommander library: http://jcommander.org

Email appearance

Best option: use an email builder service
e.g https://unlayer.com/

If we handwrite it

• find out what email clients KCRHA uses
• See which css features are supported by clients: https://www.campaignmonitor.com/css/
• Basic reading https://myemma.com/blog/css-in-html-emails-what-you-need-to-know-to-get-started/

Create new "triggered" alerts summary

Background

A major portion of this applications purpose is to highlight any "triggered" alert for KCRHA users, such as any day with a forecast containing a daily low below 30 degrees would be a tier 3 alert. Today, alerts identified as "triggered" are highlighted in this applications reports (yellow for tier 1, orange for tier 2, red for tier 3).

Issue

However, this information is not necessarily clear without reading a key such as this. Furthermore, KCRHA rules that define a "triggered" alert state range across various indices and could theoretically compound. One example of this would be an extreme heat wave that could prompt a tier 1 alert, while also air quality conditions could be bad enough for a tier 3 alert.

Proposed Solution

When discussing this issue with KCRHA users, a feature was proposed to summarize all "triggered" alerts and their tiers at the beginning of the report. This data would be very straight-forward to gather, as it could be aggregated while calculating if any alerts are "triggered".

Once gathered, we could display this as a "snapshot" or summary at the top of the report, listing which type of alert was identified, which tier was "triggered", and for which location this was triggered.

A primitive display option would be as such:

Location	Date	Alert Type	Tier
Bothell	2024-02-29	Cold Weather	1
Bothell	2024-03-01	Cold Weather	1
Seattle	2024-02-29	Cold Weather	1

We should err on the side of robustness, rather than simplicity. If the users return to us with feedback such as "can we provide date ranges for activated alerts/tiers", we can adjust this summary to reflect those asks then.

Lastly, while adding this to the beginning of the report would prove helpful, I would also like to make note that we could add this information to the email body itself. This may prove useful for users, as they'll know whether or not the application identified any potentially "triggered" alerts before opening the PDF copy of the report. This will prevent them from overlooking any particular highlighted portion of the report, as well as possibly save them time when reviewing the report.

AQI data source is unreliable

Background

The KCRHA team requires Air Quality Index (AQI) in their determination for whether or not they activate volunteer resources and coordinate with other organizations.

Issue

We have utilized the AirNow.gov programs web services to gather the AQI for various locations & dates. However, we regularly run into issues with the responses from AirNow. There's little information on how, when, or why the responses are failing to be gathered/parsed/etc.

Proposed Solution

Before moving entirely to a new data source, we should add better monitoring/logging options to the application. These monitors/logs should be recorded locally on the machine running the application until we have a cloud deployment or other monitoring periphery system available to record these logs.

Any monitoring/logging solution should be extensible and allow for various different types of logs and monitors to be recorded across different components in the application, such as data collectors, data aggregators, data formatter, or notification service.

Add precipitation metric collection

KCRHA expects this alert to be able to collect information on precipitation (measurements in inches) for both predicted rainfall and snowfall forecasts.