Overview
In lab this week, we began discussing building a dashboard for the operations manager at a Bikeshare company. In this week's assignment, you'll finish building the dashboard. Specifically, your dashboard will report on some data from the day and recommend how many bikes the company should move between various stations to be ready for operations the next day.
You can have Claude write the code, but you are responsible for decisions about constraints on the data, how to select the moves, and for how you'll check the accuracy of what Claude has built.
After you turn this in, you will review the decisions made by one of your (anonymous) classmates. After we get back from Thanksgiving break, you will do your final code review of the semester on your work (with both Kathi and one of the TAs).
As with the maze project, there are options for both the full project and less-featured one that earns fewer points, but still amounts to passing.
Learning Objectives
- Apply what we've been learning this semester to build an actual tool
AI and collaboration policy for this assignment
You may use an agent as much as you want for the coding portion of the assignment. You can iterate with the agent on the design components (dashboard page, testing plan, how to make recommendations), but you shouldn't just hand that full task over to the agent (otherwise you might not be prepared for the code review later). You are expected to write your own answers to the reflection questions in your worksheet (no AI assistance).
Setup
- Make a copy of the written answer worksheet and submit the link to it in the worksheet submission form (you can do this before filling anything in).
- In VS Code, create a new folder named
bikeshare-hw. Inside it, make a folder namedbikeshare. Downloadbikeshare-data.zip, unzip it, and put the files it contains inbikeshare. They are described in the next section. All of your code will go inbikeshare. - Create a Python environment with the libraries we need (pytest, Flask, and matplotlib). The commands are below.
Commands for setting up and using the Python environment
Open the VS Code terminal (Terminal menu, then New Terminal). It opens inside bikeshare-hw. Create the environment once, here:
On a Mac:
python3 -m venv .venv
.venv/bin/pip install pytest flask matplotlib
On Windows:
py -m venv .venv
.venv\Scripts\pip install pytest flask matplotlib
This takes a minute. It makes a folder named .venv next to bikeshare. You never edit it, and because it is outside bikeshare, it won't end up in your zip file.
Then do all of your work from a terminal inside the bikeshare folder (cd bikeshare). The environment is one folder up, so reach it through ... To run your tests:
On a Mac:
../.venv/bin/python -m pytest
On Windows:
..\.venv\Scripts\python -m pytest
To start your Flask page (this assumes your file is named app.py; then open the address it prints, usually http://127.0.0.1:5000, in your browser, and press Control-C in the terminal to stop it):
On a Mac:
../.venv/bin/python -m flask --app app run
On Windows:
..\.venv\Scripts\python -m flask --app app run
To run any other Python file, use the same python as above, for example ../.venv/bin/python myfile.py on a Mac. If you get "file not found" or "no module named", you are probably in the wrong folder or using your computer's own Python instead of the environment's. When you ask an agent to write code, tell it to use these commands.
Part 1The Data
The bikeshare data come in three csv files:
- a table of stations where bikes are parked
- a table of how many bikes were at each station at the start of the day
- a table of rides taken during a single day.
You downloaded both a set of small files that should be useful for testing (their names start with "tiny") and a set of realistic-size files for a single day of rides (the trips file contains 8,885 rides from a single day).
The larger files of stations and trips are real data from one day at Bluebikes in Boston. We made up the larger file of the inventory of bikes at a station at the start of the day (Bluebikes doesn't publish that information).
Part 2Determining the Constraints and Loading the Data
In lab, you began looking at sample data and identifying issues that needed to be cleaned up. The real dataset might have more issues. Write your set of desired constraints in your worksheet (ones from lab plus others you think of). After you've written your initial set, you can give them to an agent and ask for feedback. Update the set of constraints in the worksheet when you and Claude are done iterating on them.
Do not have an agent simply clean up the files. Instead, have it write code to (a) report where constraints have been violated in the original data, and (b) clean the data. Copy the report to your worksheet.
In your worksheet, answer the question about why asked you to use code to identify issues, rather than have an agent clean up the files directly.
Have an agent write the code that takes in the three csv files, loads them, cleans up the data, and converts the data into whatever format or data structures you need for the rest of the project (you may need to edit this later as you figure out later parts of the assignment).
Part 3Two Metrics and Two Assignment Levels
There are many metrics one could use to help decide where to move bikes around. This assignment considers two:
- The net flow of a station is its arrivals minus its departures over the day. If a station ends the day with more bikes than it started with, its net flow will be positive.
- The time near empty or full of a station is the number of minutes during the day that a station has two or fewer bikes, or two or fewer open docks. Either one could leave a customer unable to borrow or return a bike.
A full solution will work with both metrics. If you wish to do the lower-functionality version, you can skip the second metric and just work with the first (net flow).
A worked example: both metrics
Here is the tiny example. Stations B = Kenmore Square, M = Central Square, D = Chinatown, A = South Station; all six trips are on the same day.
trip from to departs arrives station docks start stock
---------------------------------------- ---------------------------
t1 B M 08:00 08:10 B 27 3
t2 B M 08:05 08:20 M 19 16
t3 M B 09:00 09:15 D 19 5
t4 D A 08:00 08:30 A 47 20
t5 A D 08:40 09:00
t6 B B 10:00 10:20
station net flow lowest/highest end-of-day minutes near minutes near Level 1 Level 2
stock stock empty (<=2) full (<=2 open) (end only) (lowest/highest)
---------------------------------------------------------------------------------------------------------
B -1 1 / 3 2 960 (16 hrs) 0 DELIVER 1 DELIVER 2
M +1 16 / 18 17 0 950 (~16 hrs) REMOVE 1 REMOVE 2
D 0 4 / 5 5 0 0 none none
A 0 20 / 21 20 0 0 none none
Both levels agree on direction (deliver to Kenmore, remove from Central), but Level 2 asks for twice as many bikes, because it reacts to the station's lowest or highest point during the day, not just where it ends. Kenmore spends two-thirds of the day (960 of 1440 minutes) with two or fewer bikes; Central spends almost as long with two or fewer open docks.
Part 4Making Recommendations
Based on the metrics, you'll provide a recommendation about which moves to make. The detail depends on which level of the assignment you are doing:
Level 1. Recommend the stations to visit. The truck can visit at most 18 stations. Each entry must say:
- the station (name and id),
- the direction:
REMOVE(it is over) orDELIVER(it is short), - the number of bikes to remove or deliver, which is how far short or over it is, and
- the largest problems first.
On the tiny example, the Level 1 recommendation could be: DELIVER 1 to Kenmore Square and REMOVE 1 from Central Square.
Level 2. Recommend moves: take N bikes from station A and deliver them to station B. Each move must say the two stations (name and id) and the number of bikes, and each must follow these rules:
- no move carries more than 20 bikes (split larger transfers into several moves);
- the plan visits at most 18 different stations;
- a station never both gives and receives bikes in the same plan;
- a station never gives away more bikes than it is over by, nor more than it has at its lowest point during the day;
- a station never receives more bikes than it is short by, nor more than it has free docks at its highest point during the day.
On the tiny example, the only sensible plan is one move: 2 bikes from Central
Square to Kenmore Square.
Which moves you recommend, and in what order, is up to you. Many different plans are valid. Your task is choose criteria (then get Claude to implement it for you).
In the worksheet, describe your policy on which stations or moves to recommend, in plain English. Someone who has not seen your code should be able to predict what it will recommend on a small example based on the description. You don't need to know how to create code for the policy (your tests will check that).
Part 5The Dashboard
Build a dashboard page using Flask. The layout is up to you. Your page must show (a) a chart for each metric that you implemented, and (b) your set of recommended moves.
Part 6Develop a Testing Plan and Tests
Write a testing plan in the worksheet. Describe the situations you will test and, for each, what the right answer is and how you know. Consider each of boundary, core, and constraint tests. Consider property-based tests.
See this guide to testing plans for a sample structure for a testing plan
Work with an agent to develop a good set of tests. The tests can be based on the problem description, your testing plan, and/or cases that arise as you are developing your solution.
Consider strategies like what we covered in class on Friday, 11/13: Do multiple sessions with Claude (and/or Gemini) to end up with both a testing plan and a set of concrete tests that you feel confident in.
Document how you are working with agents in your worksheet. Tell us what you asked agents to do (e.g., "I gave Claude the handout and asked it for tests", or "I gave Claude my testing plan and asked it for feedback") and what happened as a result. Your narrative should have enough info that Kathi can use it to grade your process of working with agents to get to a robust testing file.
Part 7Preparing Your Code to be Used on New Data
Ask an agent to generate a file named README.md with:
- instructions for how to run your code on a new set of three csv files
- instructions on how to run your tests
We will use this information to test your code against our own new data after you turn it in.
Part 8Reflecting on Working with an Agent
In the worksheet, discuss how confident you are in your bikeshare dashboard and what does or does not contribute to that assessment. What guidelines would you adopt going forward to help you have confidence when working with agents to produce a program or analyze data.
Grading
Grading on this assignment will look at:
- The quality of your constraints, testing plan, and tests: are they accurate, thorough, and auditable by a human?
- Whether the recommendation is based on the data in a reasonable way. By "reasonable", we simply mean that your recommendation derives from at least one of the computed metrics, prioritizes stations that the metrics suggest are out of balance, and has been explained in ways that we (human readers) can understand. There is no one "right" answer here: think it through, explain your choice, and you'll be fine.
- Whether your code has made use of types and helper functions to help someone navigate through it (it's okay if you have an agent do this annotating, but you should review that the annotations were done reasonably well)
- Whether your implementation can handle different datasets (ours, during testing)
- Whether you are able to explain your choices during code review; we want to know that you were actively and appropriately involved in the design of the dashboard
There is no autograder (since we gave you all flexibility in the design). We'll be grading this manually on our end.
Handin
Hand in this file:
bikeshare.zip
Submit to Gradescope. You may submit as many times as you like before the deadline; we grade the last submission.
Create a zip file of your bikeshare folder and submit that to Gradescope. Don't zip your entire bikeshare-hw folder, as that has a large amount of Python configuration data. We just want the folder where your work lives.
Comments or concerns?
If you have comments or concerns, submit them on the anonymous feedback form. Sign in with your Brown Google account to open it; your email address is not recorded.