[Sprint 5a]: Heatmap Heat Layer 🌡️ - Anne & Elki & Steven

[danglorioso]

💻 Summary

For this sprint, you’ll build upon the heat map created last week by adding a heat layer that displays intensities of a given attribute (e.g. student, teacher, project counts). To do this, you will use a heatmap layer from MapLibre, our map provider. Each dot will represent a school, and the size of the dot is dependent on the quantity of the measured statistic.

Goals of this sprint:

• Learn how to add a layer to the map that is responsive to the view of the map (zoom in and out), and properly displays useful intensity data.
• Retrieve school data from the database, and place a dot at the school’s longitude and latitude of appropriate size depending on the total counts for that school (# students, teachers, projects).

⚙️ Setup

Before starting:

1. PLEASE: **Pull the latest changes from main: git pull
2. Create a new branch for this sprint.
3. Install dependencies.
4. Run the dev server and verify the site builds.
5. Confirm everything runs.
   If you experience problems, check your .env is up to date!

🧭 Implementation

Step 1: Study MapLibre’s heatmap documentation & our existing map

• Look through our codebase and learn how the previous group implemented the map component. It may be useful to look at how the county borders are drawn on the map as you will need to add your own layer to this map for your sprint.
• For reference, we are using mapcn for our map systems, which is built using MapLibre maps. mapcn is very well-integrated with React, Tailwind, and shadcn, which is the primary reason that we decided to go with it instead of mapbox. It may be useful to look over the code examples that can be found in the mapcn documentation to see how to use the map’s features. Also refer to the specific API documentation.

Step 2: Retrieve school data

• Thanks to a previous team’s work, every school in our database has corresponding longitude and latitude values for each entry. You can find this in the schools table. We’re enforcing that every school that’s uploading has a matching longitude and latitude coordinate pair.
• For your heat map, there will be two settings for the data that is displayed: counts and year.
  • Counts: dropdown that adjust what exactly the intensity is displaying for each school. This may be the number of students, number of teachers, or number of projects at a given school.
  • Year: dropdown that allows the user to select which year of data they want to display on the heat map. Pretty straightforward and similar to the line/bar chart visualizations.
• For a selected year, you’ll fetch all of the schools that have entries for that year (which includes their longitude and latitude for plotting on the map) and their respective counts for the selected count type. For example, if I select “2025” and “# of students,” the query should return all of the schools that participated in 2025 and the number of students that participated at each of those schools in 2025.
• Note which branch of the Neon database you are using. Make sure that there are entries for schools across multiple years and also participation data for those schools for each of the types of counts (students, teachers, projects).

Step 3: Implement the heat layer

• Pull up the MapLibre heatmap documentation again. In order to display the data you just fetched from the database on the map, you’ll need to convert this data into a geojson format. Here’s the geojson data from the earthquake example shown on MapLibre’s site.
• Either figure out a way to easily convert this data or find a simple library that will accomplish this for you. We don’t anticipate this being too tricky.
• Once you have the schools data in a geojson object, you’ll be able to add it to the heat layer. Again, look at the documentation for how they inputted this data.
  • You may want to adjust the circle radiuses/weight to different values so that we’re able to display a wide enough range of data, and so that the heat map is a usual insight into the number of participants at one school versus another.

Step 4: Finishing touches

• After your heat layer is displaying intensities, check that it works for every type of count over multiple different years. As you zoom out, the school dots should become colored regions of heat that correspond to the intensity of participants in a region.
• Double-check that the schools are plotted correctly on the map. If something is off, determine if it’s an issue with the long/lat stored in the database or with your heatmap layer. And if the latter, please fix it.

🙌 Acceptance Criteria

• UI matches Figma exactly
• Code runs locally without errors and builds successfully
• Map displays the entirety of Massachusetts with view controls
• Heat layer repositions as the user adjusts the window
• The size of a school’s dot represents the count for that school
• Schools are plotted in the correct spots according to their long/lat stored in the database
• Heatmap layer displays meaningful and accurate information about all school for a given year
• Merge via PR

⁉️ Questions

If you get stuck or have questions:

• DM Dan or Shayne on Slack
• Come to office hours or ask during a hack night
• Ask questions during team meetings – we’re here to help!

📝 Resources

• Figma:
• Tailwind CSS
• shadcn/ui
• npm package manager
• mapcn
• MapLibre heatmap layer