A Standings Bump Chart: Visualizing a Season's Twists

A final standings table tells you who won the division. It says nothing about the journey - the April team that faded, the club that surged from last to first, the September week when two rivals traded the lead. A bump chart restores all of that: it ranks every team at every point in the season and draws their rise and fall as crossing lines. So pick the messiest race you can find and watch the lines knot up. The 2023 AL East is my pick here - four of the five teams won 82 or more games, and reconstructing it week by week from raw game results gives you one of the most satisfying charts in sports.

This is a capstone, and it earns the label by reusing nearly everything the site taught: a polite live API session, cumulative sums and ranking in pandas, time resampling, and a custom matplotlib chart. It leans hardest on rolling averages and form: time-series basics - the same comfort with a date-indexed DataFrame and resample - so make sure that's solid before you start. The data is the MLB Stats API, retrieved June 2026.

1. Set up and name the division

   We hit the same MLB Stats API used elsewhere on the site, through the polite session that adds browser headers and retries flaky responses automatically. Then we list the five AL East teams by their numeric team IDs and give each a color for the chart - real club colors so the lines read at a glance.

   import matplotlib.pyplot as plt
   import pandas as pd
   
   import sdt_common as sdt
   
   sdt.init("a-standings-bump-chart")
   session = sdt.polite_session()
   
   AL_EAST = {147: "NYY", 110: "BAL", 139: "TBR", 141: "TOR", 111: "BOS"}
   TEAM_COLORS = {"NYY": "#1C2841", "BAL": "#DF4601", "TBR": "#092C5C",
                  "TOR": "#134A8E", "BOS": "#BD3039"}

   That session = sdt.polite_session() is the same well-behaved client we use for every live API on the site - a requests session with a real User-Agent and automatic retry-with-backoff on 429/503 errors, so a season's worth of requests never hammers the server. Each MLB team has a stable numeric ID (the Yankees are 147, the Orioles 110); mapping them to abbreviations now keeps the rest of the code readable.

2. Turn one team's games into a cumulative win total

   The core of the whole program is a function that asks the schedule endpoint for one team's full regular season and returns its running win total, indexed by date. We walk every game, keep only finals, figure out whether our team was home or away, and record a 1 for a win or 0 for a loss.

   def cumulative_wins(team_id):
       """A team's cumulative win total, indexed by date."""
       data = session.get("https://statsapi.mlb.com/api/v1/schedule",
                          params={"sportId": 1, "season": 2023, "teamId": team_id,
                                  "gameType": "R"}, timeout=30).json()
       recs = []
       for day in data["dates"]:
           for g in day["games"]:
               if g["status"]["abstractGameState"] != "Final":
                   continue
               home, away = g["teams"]["home"], g["teams"]["away"]
               us, them = (home, away) if home["team"]["id"] == team_id else (away, home)
               if us.get("score") is None or them.get("score") is None:
                   continue
               recs.append((g["gameDate"][:10], int(us["score"] > them["score"])))
       s = pd.DataFrame(recs, columns=["date", "win"]).groupby("date")["win"].sum()
       return s.sort_index().cumsum()

   Three details carry this function. The line us, them = (home, away) if home["team"]["id"] == team_id else (away, home) is a tidy conditional unpacking - it points us at whichever side is our team, so the win test reads the same whether we played at home or on the road. int(us["score"] > them["score"]) turns the boolean comparison into a clean 1 or 0. And the closing .cumsum() is the magic: it converts a column of per-day wins into the running total that a standings race is really made of. Filtering on gameType: "R" and an abstractGameState of "Final" keeps us to completed regular-season games only.

3. Combine all five teams onto one timeline

   We call that function once per team and stitch the results into a single DataFrame - one column per team, one row per date. Because teams have off-days on different dates, we then align everything to a common daily timeline and carry each team's total forward.

   wins = pd.concat({abbr: cumulative_wins(tid) for tid, abbr in AL_EAST.items()}, axis=1)
   wins.index = pd.to_datetime(wins.index)
   wins = wins.sort_index().ffill().fillna(0)

   The dict comprehension inside pd.concat({...}, axis=1) builds all five win series and glues them together side by side, using each abbreviation as the column name. Converting the index with pd.to_datetime makes it a real date axis we can resample. The two fills handle the gaps honestly: ffill() carries a team's win total forward across days it didn't play (its total simply hasn't changed), and fillna(0) sets the season's opening rows to zero before anyone has played.

4. Sample weekly and rank each week

   A line for all 162 games would be a tangle, so we down-sample to one snapshot per week, then convert win totals into standings positions. Ranking is what makes a bump chart a bump chart - we don't plot wins, we plot place.

   weekly = wins.resample("W").last().ffill()
   ranks = weekly.rank(axis=1, ascending=False, method="min")

   resample("W").last() groups the daily data into calendar weeks and keeps each team's final total for the week - the standings as they stood that Sunday. Then rank(axis=1, ...) is the key line: axis=1 ranks across the columns within each week, so it compares the five teams to each other rather than ranking a team against its own history. ascending=False makes the most wins rank 1 (first place), and method="min" means tied teams share the better rank instead of being split arbitrarily.

5. Check the finish line

   Before drawing, let's confirm the reconstruction matches reality by printing each team's final win total. If these numbers are right, every step before them was right too.

   final = wins.iloc[-1].sort_values(ascending=False).astype(int)
   print("Final 2023 AL East wins:")
   print(final.to_string())

   Final 2023 AL East win totals

   Final 2023 AL East wins:
   BAL    101
   TBR     99
   TOR     89
   NYY     82
   BOS     78

   These are the real final standings, which means our game-by-game accumulation is sound. The Orioles took the division with 101 wins, the Rays right on their heels at 99 - a 100-win team that finished second, the cruelty of a great division. Then a real gap to the Blue Jays at 89, the Yankees at a disappointing 82, and the Red Sox last at 78. wins.iloc[-1] grabs the final row of the cumulative table (each team's season-ending total), and .astype(int) cleans off the decimals the forward-fill introduced.

6. Draw the bump chart

   Now the payoff. We plot each team's rank over time as a line with markers, in its club color, and label the line at its right end so we don't need a separate legend. The one counter-intuitive move is inverting the y-axis - in a standings chart, first place belongs at the top, but rank 1 is the smallest number.

   fig, ax = plt.subplots(figsize=(8.8, 5))
   for team in ranks.columns:
       ax.plot(ranks.index, ranks[team], marker="o", markersize=3, linewidth=2.4,
               color=TEAM_COLORS.get(team), label=team)
       ax.text(ranks.index[-1], ranks[team].iloc[-1], "  " + team, va="center",
               fontsize=9, fontweight="bold", color=TEAM_COLORS.get(team))
   ax.invert_yaxis()
   ax.set_yticks([1, 2, 3, 4, 5])
   ax.set_ylabel("place in the AL East")
   ax.set_title("How the 2023 AL East standings shifted, week by week")
   sdt.save_fig(fig, "bump_chart", source="MLB Stats API")

   

   The single most important line is ax.invert_yaxis(): without it, the chart would be upside down, with the division leader scraping the bottom. Inverting flips it so rank 1 sits at the top where first place belongs, and the lines read like a standings table you can watch move. Labeling each line in place with ax.text at ranks.index[-1] - the last week - and leading the label with two spaces nudges the abbreviation just clear of the final marker, which is cleaner than a legend when lines cross as often as these do. We finish with sdt.save_fig, which stamps the chart with its source and the date it was retrieved before saving.

7. Read the season in the crossings

   A bump chart rewards a slow look. Trace a single line and you can see a team's whole arc - a steady climb, a midseason swoon, a final-week surge. The crossings are where the drama lives: every time two lines swap, a team passed a rival in the standings that week. Watch the Orioles' line work its way to the top and stay there, and the Rays' line shadow it just below after their blazing start. The Yankees' descent toward fourth is a season-long slide you can read at a glance. None of that is visible in the final table - it only shows the destination, while the bump chart shows the trip.

Troubleshooting