gradelib.plot#

Functions for plotting.

gradelib.plot.grade_distribution(gradebook: Gradebook, x_min: float = 0.6, x_max: float = 1, bin_width: float = 0.025)#

Visualize the grade distribution with respect to a scale.

This will plot an interactive histogram of the grade distribution, with each individual grade marked as a dot. Furthermore, if a grading scale is provided, the letter grade thresholds are marked on the histogram as vertical lines, and the frequency of each letter grade is shown.

Parameters:

  • gradebook (Gradebook)

  • x_min (float) – The smallest extent of the axis containing scores. Default: 0.6

  • x_max (float) – The greatest extent of the axis containing scores. Default: 1.02

  • bin_width – How wide each bin should be. Default: 0.025.

gradelib.plot.grade_shift_animation_2d(scores: Tuple[Tuple[Sequence[float], Sequence[float]], Tuple[Sequence[float], Sequence[float]]], filepath: str | Path | None = None, title: str | tuple[str, str] | None = None, xlabel: str | tuple[str, str] | None = None, ylabel: str | tuple[str, str] | None = None, color: str = '#007aff', alpha: float = 0.5, setup_figure: Callable | None = None) → FuncAnimation#

Visualize the shift in scores as an animated scatter plot.

This is especially useful for visualizing the effect of a grading policy, such as a curve or allowing multiple attempts on two assignments. For example, suppose a course allows students to retake Midterm 01 and Midterm 02 to improve their scores. The animation created by this function will start by plotting a scatter plot of Midterm 01 vs. Midterm 02 scores for all students. As the animation progresses, the scores will shift to show the new scores after the retake, demonstrating the “shift” of the scores due to the grading policy. The animation then “rewinds” to show the original scores, allowing for an infinite loop of the before-and-after effect.

Parameters:

  • scores (Tuple[Tuple[Sequence[float], Sequence[float]], Tuple[Sequence[float], Sequence[float]]]) – A tuple containing two tuples, each with two sequences of floats. The first tuple contains the before and after scores for all students on Assignment A, and the second tuple contains the before and after scores for all students on Assignment B.

  • filepath (Optional[Union[str, pathlib.Path]]) – The path to save the animation to. If None, the animation will not be saved.

  • title (Optional[Union[str, tuple[str, str]]]) – The title of the plot. If a tuple is provided, the first element will be displayed at the start of the animation and the second element at the end. If a string is provided, it will be used for both the start and end of the animation. If nothing is provided, no title will be displayed.

  • xlabel (Optional[Union[str, tuple[str, str]]]) – The label for the x-axis. If a tuple is provided, the first element will be displayed at the start of the animation and the second element at the end. If a string is provided, it will be used for both the start and end of the animation. If nothing is provided, no label will be displayed.

  • ylabel (Optional[Union[str, tuple[str, str]]]) – The label for the y-axis. If a tuple is provided, the first element will be displayed at the start of the animation and the second element at the end. If a string is provided, it will be used for both the start and end of the animation. If nothing is provided, no label will be displayed.

  • color (str) – The color of the points in the scatter plot. Default: “#007aff”.

  • alpha (float) – The transparency of the points in the scatter plot. Default: 0.5.

  • setup_figure (Optional[Callable]) – A callable that sets up the figure and axes for the plot. Should return matplotlib Figure and Axes objects. If None, a default setup function will be used.

Returns:

The animation object. If filepath is provided, the animation will also be saved to the specified path.

Return type:

matplotlib.animation.FuncAnimation