Highlighting date ranges in Matplotlib

Introduction

Highlighting date ranges helps you focus on important time periods in your charts. It makes trends or events easier to see.

You want to show a special event period on a timeline chart.

You need to emphasize weekends or holidays in a time series plot.

You want to compare data before and after a specific date range.

You want to mark a maintenance window or outage period in logs.

You want to visually separate different phases in a project timeline.

Syntax

Matplotlib

ax.axvspan(start_date, end_date, color='color', alpha=transparency)

start_date and end_date are dates or numbers marking the range.

color sets the highlight color, and alpha controls transparency (0 to 1).

Examples

Highlights the date range from January 1 to January 10, 2023, with a light yellow color.

Matplotlib

ax.axvspan('2023-01-01', '2023-01-10', color='yellow', alpha=0.3)

Highlights March 15 to March 20, 2023, in semi-transparent red using pandas timestamps.

Matplotlib

ax.axvspan(pd.Timestamp('2023-03-15'), pd.Timestamp('2023-03-20'), color='red', alpha=0.5)

Sample Program

This code plots values over 30 days and highlights January 10 to January 15 with a light green shade.

Matplotlib

import matplotlib.pyplot as plt
import pandas as pd

# Create dates and values
dates = pd.date_range('2023-01-01', periods=30)
values = range(30)

fig, ax = plt.subplots()
ax.plot(dates, values)

# Highlight a date range
ax.axvspan(pd.Timestamp('2023-01-10'), pd.Timestamp('2023-01-15'), color='green', alpha=0.3)

ax.set_title('Highlighting Date Range Example')
ax.set_xlabel('Date')
ax.set_ylabel('Value')
plt.show()

Important Notes

Use axvspan to highlight vertical ranges (dates on x-axis).

Adjust alpha to make the highlight more or less visible.

Make sure your dates are in a format matplotlib understands, like pandas Timestamps.

Summary

Use axvspan to highlight date ranges on time series plots.

Set color and transparency to make highlights clear but not distracting.

Highlighting helps focus attention on important periods in your data.

Practice

1. What does the plt.axvspan(start_date, end_date) function do in matplotlib?

easy

A. It draws a horizontal line at start_date.

B. It highlights a vertical span (date range) on the plot between start_date and end_date.

C. It creates a scatter plot of dates between start_date and end_date.

D. It sets the x-axis limits to start_date and end_date.

Solution

1. Step 1: Understand the function purpose

   plt.axvspan is used to highlight a vertical area on the plot, usually to mark a range on the x-axis.

2. Step 2: Match parameters to behavior

   The parameters start_date and end_date define the start and end of this vertical span on the x-axis, highlighting that date range.

3. Final Answer:

   It highlights a vertical span (date range) on the plot between start_date and end_date. -> Option B

4. Quick Check:

   Highlight date range = plt.axvspan(start_date, end_date) [OK]

Hint: Remember axvspan highlights vertical areas between two x-values [OK]

Common Mistakes:

• Confusing axvspan with line drawing functions
• Thinking it changes axis limits
• Assuming it plots points instead of highlighting

2. Which of the following is the correct syntax to highlight the date range from '2023-01-01' to '2023-01-10' with a semi-transparent red color in matplotlib?

easy

A. plt.axvspan(start='2023-01-01', end='2023-01-10', color='red', alpha=0.5)

B. plt.axvspan('2023-01-01', '2023-01-10', color='red', transparency=0.5)

C. plt.axvspan('2023-01-01', '2023-01-10', color='red', alpha=0.5)

D. plt.axvspan('2023-01-01', '2023-01-10', alpha=50, color='red')

Solution

1. Step 1: Check parameter names and order

   plt.axvspan takes start and end positions as first two arguments, then keyword arguments like color and alpha.

2. Step 2: Validate correct keyword for transparency

   alpha controls transparency and should be between 0 and 1. The value 0.5 means 50% transparent.

3. Final Answer:

   plt.axvspan('2023-01-01', '2023-01-10', color='red', alpha=0.5) -> Option C

4. Quick Check:

   Use alpha for transparency, not transparency keyword [OK]

Hint: Use alpha (0-1) for transparency, not transparency keyword [OK]

Common Mistakes:

• Using 'transparency' instead of 'alpha'
• Passing alpha as 50 instead of 0.5
• Using named parameters start= and end= which are invalid

3. Given the following code, what will be the color and transparency of the highlighted date range?

import matplotlib.pyplot as plt
import pandas as pd

dates = pd.date_range('2023-01-01', periods=5)
values = [10, 20, 15, 25, 30]
plt.plot(dates, values)
plt.axvspan(pd.Timestamp('2023-01-02'), pd.Timestamp('2023-01-04'), color='green', alpha=0.3)
plt.show()

medium

A. A green shaded area with 30% opacity between Jan 2 and Jan 4

B. A green shaded area with 70% opacity between Jan 2 and Jan 4

C. A fully opaque green shaded area between Jan 2 and Jan 4

D. No shaded area will appear because alpha is too low

Solution

1. Step 1: Understand alpha parameter meaning

   Alpha=0.3 means 30% opacity (or 70% transparent), so the color is faint but visible.

2. Step 2: Confirm color and date range

   The color is green, and the highlighted range is from Jan 2 to Jan 4 as specified.

3. Final Answer:

   A green shaded area with 30% opacity between Jan 2 and Jan 4 -> Option A

4. Quick Check:

   alpha=0.3 means 30% opacity, color='green' [OK]

Hint: Alpha 0.3 means 30% opacity, not 70% [OK]

Common Mistakes:

• Confusing alpha as transparency percentage
• Thinking alpha=0.3 means 70% opacity
• Assuming no highlight appears if alpha is low

4. Identify the error in the following code snippet that tries to highlight a date range:

import matplotlib.pyplot as plt
plt.axvspan('2023-01-01', '2023-01-05', color='blue', alpha=0.4)
plt.show()

medium

A. Dates are passed as strings; they should be converted to datetime objects.

B. The alpha value must be an integer, not a float.

C. The color parameter should be 'colour' instead of 'color'.

D. plt.show() is missing and must be added.

Solution

1. Step 1: Check parameter types for axvspan

   plt.axvspan expects numeric or datetime values for start and end. Passing strings directly causes errors.

2. Step 2: Correct usage for dates

   Convert strings to datetime objects using pd.Timestamp or datetime before passing.

3. Final Answer:

   Dates are passed as strings; they should be converted to datetime objects. -> Option A

4. Quick Check:

   axvspan needs datetime, not string dates [OK]

Hint: Convert date strings to datetime objects before axvspan [OK]

Common Mistakes:

• Passing date strings directly without conversion
• Misusing alpha as integer
• Wrong color parameter spelling

5. You have a time series plot of daily sales data from '2023-01-01' to '2023-01-31'. You want to highlight weekends (Saturdays and Sundays) with a light gray transparent background. Which approach correctly applies this using matplotlib?

hard

A. Use plt.fill_between with weekend dates and color='gray', alpha=0.2.

B. Use plt.axvspan once with start='2023-01-01' and end='2023-01-31' and color='gray', alpha=0.2.

C. Plot vertical lines on weekends using plt.axvline with color='gray' and alpha=0.2.

D. Loop through dates, check if weekday is Saturday or Sunday, then use plt.axvspan for each weekend with color='gray' and alpha=0.2.

Solution

1. Step 1: Identify weekend dates in the range

   Loop through each date, check if it is Saturday (weekday=5) or Sunday (weekday=6).

2. Step 2: Highlight each weekend separately

   Use plt.axvspan for each weekend day or range with desired color and transparency.

3. Step 3: Understand why other options fail

   Use plt.axvspan once with start='2023-01-01' and end='2023-01-31' and color='gray', alpha=0.2. highlights entire month, not weekends. Plot vertical lines on weekends using plt.axvline with color='gray' and alpha=0.2. draws lines, not spans. Use plt.fill_between with weekend dates and color='gray', alpha=0.2. is for y-axis fills, not x-axis spans.

4. Final Answer:

   Loop through dates, check if weekday is Saturday or Sunday, then use plt.axvspan for each weekend with color='gray' and alpha=0.2. -> Option D

5. Quick Check:

   Highlight weekends individually with axvspan [OK]

Hint: Highlight each weekend separately with axvspan in a loop [OK]

Common Mistakes:

• Highlighting entire date range instead of weekends
• Using axvline instead of axvspan for spans
• Trying to fill y-axis area instead of x-axis date range