MP 01: Interactive Dashboard

Be aware of the general Machine Problem Policy document.

Goal

The goal of this MP is to create an interactive dashboard that helps determine the efficacy of installing a heat pump depending on the weather in a particular location in the United States.

Deadlines

• Due: Friday, March 22, 11:59 PM

GitHub Repository

To setup your repository for this MP, use the following link:

• CS 498 MP 01: GitHub Repo Creator

Context

In short, heat pumps are a reverse air conditioner that can be used to replace a traditional gas-powered furnace through the magic of refrigerant. However, compared to gas-powered furnaces, their efficacy is potentially more dependent on temperature. In particular, heat pumps may struggle at extremely low temperatures. As a result, many potential users are discouraged from electing to install a heat pump over a traditional furnace.

Heat pump manufacturers publish performance specifications, importantly including the coefficient of performance. This information, together with local weather information, can help consumers make informed decisions.

For additional background and context:

• MIT Technology Review: Everything you need to know about the wild world of heat pumps
• YouTube Technology Connections: Heat Pumps: the Future of Home Heating
  • YouTube Technology Connections: Ground Source / Geothermal Heat Pumps and Other Info
  • YouTube Technology Connections: Why Heat Pumps are Immensely Important Right Now
  • YouTube Technology Connections: Heat Pumps are Not Hard: Here’s what it will take to start pumping

Finished Product

Rather than defining the product you must create in far too many words, instead, we will simply show you an example of what the finished product should look like.

• Daily Heat Pump Efficiency Counter

Note that this application is currently run on the “free” tier of a cloud hosting service. If for some reason it goes down, please alert the course staff! We are working in the background on a more stable long-term hosting solution.

Video Walkthrough

In addition to showing you the finished product, we also provide a video walking through the end product while comparing it to the grading rubric found below.

• ClassTranscribe: MP 01

Directory Structure

Your completed MP should contain only the following directories and files:

./heatpump-dashboard/
│
├── data/
│   └── cities.csv
├── data-raw/
│   └── uscities.csv
├── .gitignore
├── README.md
├── app.py
├── process-data.py
└── requirements.txt

Importantly, please use .gitignore to ensure other files are not included, especially your virtual environment. The following should get you started:

# byte-compiled
__pycache__/

# virtual environments
.venv

# open-meteo sqlite cache
.cache.sqlite

# macOS
.DS_Store

The process-data.py file should contain any code needed to create cities.csv from uscities.csv. The specifics of these two files are given below.

The app.py file should contain the code that defines the dashboard, and will be our entrypoint for grading.

Data Sources

To complete this MP, you will need data from two sources.

Weather Data

Weather data will be accessed via Open-Meteo using their well documented and easy-to-use Historical Weather API.

Note that within the documentation, they provide Python code for working with their API! You will need to study and use this code. You’ll want to pay close attention to the creation of the params dictionary that is then passed to the API as part of a request.

params = {
    "latitude": 52.52,               # input
    "longitude": 13.41,              # input
    "start_date": "2024-02-14",      # input
    "end_date": "2024-02-28",        # input
    "daily": "temperature_2m_min",   # fixed
    "temperature_unit": "fahrenheit" # input
}

We have provided an example above, which contains all the necessary parameters to complete the MP. We have also noted which values will need to be sent to the API on behalf of user input from the dashboard.

Note that we will be using "daily" data and in particular looking at the minimum daily temperature by requesting "temperature_2m_min".

The example code given within the documentation includes code to handle caching and retrying requests. We recommend you use this code. We have found the API to be performant, but allowing the caching cannot hurt. Also, note that above we are requesting different data based on the temperature units the user has selected. You could alternatively do unit conversion within your dashboard, but the API is fast enough that we recommend making a new request if the user changes the units. This will avoid any unit conversion rounding issues.

You do not need to store any weather day on disk. You can simply request the data as a data frame directly into memory via their API, based on user input.

Location Data

One of the main features of the dashboard is the ability for the user to input a location. To obtain location data for US City-State combinations, we recommend using SimpleMaps. Their “Basic” and free data, accessed as CSV, was used to create the above example dashboard.

You should download this data and place it in the data-raw/ directory.

Processed Data

You will want to process the location data before loading it into your dashboard. The processed data should be stored in the cities.csv file in the data/ directory. The code to generate this data from the raw data should be stored in process-data.py. However, you should include cities.csv in your final submission as we plan to run your dashboard without first running any setup files.

The format of cities.csv should be:

city_state,lat,lng
"New York, New York",40.6943,-73.9249
"Los Angeles, California",34.1141,-118.4068
"Chicago, Illinois",41.8375,-87.6866

Here, city_state is the City, State for each location, separated by a comma and a space, using the full state name. Only include cities that have a population of 10000 or above. Done correctly, this file will have approximately 4000 lines. Also, done correctly, city_state will have no duplicate values, and thus serves as a primary key.

MP Specific Technology

To create your dashboard, you are required to use Shiny for Python.

To create the interactive map, you will need some combination of:

• ipywidgets
• ipyleaflet
• shinywidgets

For data frame manipulation we recommend pandas as the Open-Meteo API will generate code for pandas. You may alterantively use polars if you like.

For plotting, we recommend matplotlib, seaborn or plotnine. Your graphics are not required to produce their own interactivity or tooltips.

DDG Only

Students registered for the DDG section will need some additional software for forecasting:

• Prophet: Forecasting at Scale

The historical data gathered from the API will be used as training data for a forecast model fit via prophet. For forecast plotting we recommend using the internal plotting functions provided by prophet.

Grading Rubric

For simplicity, the grading rubric will consist of many items, each scored one of 0, 1, or 2. These scores will generally take the meaning:

• 2: Item completed fully and successfully.
• 1: Item completed with minor issues.
• 0: Item incomplete or completed with major issues.

As much as possible, grading of each item will be done independently. However, some items are clearly dependent on others, and often those items are of extra importance. As such, we reserve the right to, when appropriate, allow important items to (negatively) effect the grading of other items.

After cloning your repository, we will grade your code and dashboard based on the following items:

File Structure

• The file data/cities.csv exists.
• The file data-raw/uscities.csv exists.
• The file .gitignore exists.
• The file README.md exists.
• The file app.py exists.
• The file process-data.py exists.
• The file requirements.txt exists.
• .gitignore is used correctly and there are no additional files.

Data

• The file data/cities.csv contains the correct data.

Environment

• Grader is able to successfully run uv pip install -r requirements.txt.
• Grader is able to successfully activate the virtual environment.

Application Launch

• Application is successfully launched using the VSCode extension or shiny run.

Application Layout

• Application includes a sidebar that contains components for user input.
• Application includes an overall title.
• Application includes a navigation bar with two (three for DDG) tabs.
• The historical tab page exists and includes both a plot and table.
• The about tab page exists and includes information about the application.
• Application includes the coordinates (latitude and longitude) for the location as text.
  • The location is specifically the location of the weather station returned by the API, not the user input location.
• Application includes an interactive map with a pin for the location.

Application Interface

• The application allows the user to input a location via a city.
  • The city input defaults to Urbana, Illinois.
  • The city and state are autocompleted as the user types.
• The application allows the user to input a date range.
  • The start date defaults to 2022-01-01.
  • The end data defaults to 2024-01-01.
  • The minimum allowable date is 2020-01-01.
  • The maximum allowable date is 2024-01-01.
• The application allows the user to select temperature units via radio buttons.
  • The allowable units are Fahrenheit and Celsius.
  • The default unit is Fahrenheit.
• The application allows the use to enter a temperature (for the corresponding plot) via a slider.
  • The default temperature is 5 (Fahrenheit).
  • The allowable range of temperatures is -15 to 50 (Fahrenheit).
• The application allows the user to add a weekly rolling average via a checkbox.
• The application allows the user to add a monthly rolling average via a checkbox.
• The application allows the use to enter a temperature range (for the corresponding table) via a slider.
  • The default temperatures are 0 to 15 (Fahrenheit).
  • The allowable range of temperatures is -25 to 60 (Fahrenheit).

Reactive Application Usage

• The historical data plot reacts to a user change in city input.
• The historical data table reacts to a user change in city input.
• The historical data plot reacts to a user change in date input.
• The historical data table reacts to a user change in date input.
• The historical data plot reacts to a user change in unit input.
• The historical data table reacts to a user change in unit input.
• The historical data plot reacts to a change in user temperature input.
• The historical data table reacts to a change in user temperature range input.
• The temperature input slider reacts to a user change in unit input.
  • Moving from Fahrenheit and Celsius, the default temperature is -15.
  • Moving from Fahrenheit and Celsius, allowable range of temperatures is -25 to 10.
  • Moving from Celsius to Fahrenheit, the original Fahrenheit defaults are set.
• The temperature range input slider reacts to a user change in unit input.
  • Moving from Fahrenheit and Celsius, the default temperatures are -20 to -10.
  • Moving from Fahrenheit and Celsius, allowable range of temperatures is -30 to 15.
  • Moving from Celsius to Fahrenheit, the original Fahrenheit defaults are set.
• The historical data plot reacts to selecting the weekly rolling average checkbox.
• The historical data plot reacts to selecting the monthly rolling average checkbox.
• The printed coordinates react to a user change in city input.
• The interactive map reacts by moving the pin to the user city input.

Analytical Correctness

• The historical data plot displays the correct data.
• The historical data plot colors points correctly by comparing to the user input temperature (one color above, one color below).
• The historical data table displays three columns of correct data: the user temperature range, the days below the temperature, and the proportion of days below the temperature.
• The historical data plot is reasonably well formatted.
• The historical data table is reasonably well formatted.

About

• The about tab page is written using markdown and reasonably well formatted.
• The about tab page includes a citation for the location data source.
• The about tab page includes a citation for the weather data source.
• The about tab page gives some context about the data and application.
• The about tab page gives some usage instructions and information.

DDG Grading Rubric

Application Layout

• The forecast tab page exists and includes both a plot and table.

Application Interface

• The application allows the user to input a number of years to forecast.
  • The default number of years is 1.
• The applications allows the user to select a trend type via radio buttons.
  • The allowable types are flat and linear.
  • The default type is flat.

Reactive Application Usage

• No forecast is given, either via a plot or table, if there is less than one year of training data.
• The forecast plot reacts to a user change in city input.
• The forecast table reacts to a user change in city input.
• The forecast plot reacts to a user change in date input.
• The forecast table reacts to a user change in date input.
• The forecast plot reacts to a user change in unit input.
• The forecast table reacts to a user change in unit input.
• The forecast plot reacts to a change in user temperature input.
• The forecast table reacts to a change in user temperature range input.
• The forecast plot reacts to a user change in years to forecast.
• The forecast table reacts to a user change in years to forecast.
• The forecast plot reacts to a user change in trend type.
• The forecast table reacts to a user change in trend type.

Analytical Correctness

• The forecast plot displays the correct data.
• The forecast plot displays the correct forecast as a trend and interval for the requested years of forecasting.
• The forecast table displays three columns of correct data: the user temperature range, the days below the temperature, and the proportion of days below the temperature. (For the forecast table, days below a given temperature are based on the lower bound of a 95% prediction interval.)
• The forecast plot is reasonably well formatted.
• The forecast table is reasonably well formatted.

Submission

Two forms of submission are required:

• Push your code to Github.
  • This is how we will access your.
• Submit your repository URL to the Canvas assignment named MP 01.
  • This is how we will know your code is ready for grading, and will allow us to track late submissions.
  • You may only submit to Canvas once. Once you have submitted, we will grade your MP.
  • Students in the DDG section will make an additional submission on Cavnas to the assignment named MP 01 DDG.
    • Failure to submit to the DDG version in addition to the regular version will result in significant point loss.