feat: add heatmap plot

[danielolsen]

Purpose

Add this plot, which has been used fairly extensively in the Macro Grid report, to the codebase.

What the code is doing

The code is mostly just passing appropriate parameters to other functions, and orchestrating the creation of a plot figure.

Usage Example/Visuals

Default behavior, using summed curtailment for an Ambitious scenario:

from powersimdata.scenario.scenario import Scenario
from postreise.analyze.generation.curtailment import calculate_curtailment_time_series
from postreise.plot.plot_heatmap import plot_heatmap
import matplotlib.pyplot as plt

scenario = Scenario(1270)
summed_curtailment = calculate_curtailment_time_series(scenario).sum(axis=1)
plot_heatmap(summed_curtailment)
plt.show()

If we flip the colorbar colors:

plot_heatmap(summed_curtailment, cmap="PiYG_r"); plt.show()

..and then we want to plot in GW, rather than MW:

plot_heatmap(summed_curtailment, cmap="PiYG_r", scale=1e-3, cbar_label="GW")

...and then we want to explicitly set the range to 250 GW, with updated labels to match:

plot_heatmap(
    summed_curtailment,
    cmap="PiYG_r",
    scale=1e-3,
    cbar_label="GW",
    vmin=0,
    vmax=250,
    cbar_tick_labels=['0', '50', '100', '150', '200', '≥250'],
)

...and then we want to translate from UTC to CST:

plot_heatmap(
    summed_curtailment,
    cmap="PiYG_r",
    scale=1e-3,
    cbar_label="GW",
    vmin=0,
    vmax=250,
    cbar_tick_labels=['0', '50', '100', '150', '200', '≥250'],
    time_zone="ETC/GMT+6",
    time_zone_label="(CST)"
)

...and then we also want to add a contour for the saturated area:

plot_heatmap(
    summed_curtailment,
    cmap="PiYG_r",
    scale=1e-3,
    cbar_label="GW",
    vmin=0,
    vmax=250,
    cbar_tick_labels=['0', '50', '100', '150', '200', '≥250'],
    time_zone="ETC/GMT+6",
    time_zone_label="(CST)",
    contour_levels=[250],
)

etc.

Time estimate

15 minutes.

[BainanXia]

• Should we add a demo notebook for this plot?
• Maybe we should add a default unit in the cbar_label="MW"?
• Maybe we should add the capability to allow the user to change color scheme?
• With vmax being set, what if cbar_tick_labels is not specified, will it be generated automatically with the last tick being >=vmax?
• Maybe we should add some input validation checks such as the series should have timestamps as index?

[rouille]

• Maybe we should add some input validation checks such as the series should have timestamps as index?

There is a _check_time_series function!

[danielolsen]

* Should we add a demo notebook for this plot?

* Maybe we should add a default unit in the `cbar_label="MW"`?

* Maybe we should add the capability to allow the user to change color scheme?

* With `vmax` being set, what if `cbar_tick_labels` is not specified, will it be generated automatically with the last tick being `>=vmax`?

* Maybe we should add some input validation checks such as the series should have timestamps as index?

1. I think the docstring is documentation enough, but I can add a demo script if you want.
2. This plot can be used for things other than power, e.g. LMP.
3. That's available via the cmap parameter
4. No
5. I will add this.

[BainanXia]

* Should we add a demo notebook for this plot?

* Maybe we should add a default unit in the `cbar_label="MW"`?

* Maybe we should add the capability to allow the user to change color scheme?

* With `vmax` being set, what if `cbar_tick_labels` is not specified, will it be generated automatically with the last tick being `>=vmax`?

* Maybe we should add some input validation checks such as the series should have timestamps as index?

1. I think the docstring is documentation enough, but I can add a demo script if you want.
2. This plot can be used for things other than power, e.g. LMP.
3. That's available via the cmap parameter
4. No
5. I will add this.

1. By convention, we are going to have a demo notebook for each plot function in PostREISE which gives a straight impression of what kind of plot a function generates without reading through the docstrings.
2. I see. That's cool.
3. Ah, right.
4. Is there a way to overwrite the default behavior?
5. Thanks.

[danielolsen]

1. By convention, we are going to have a demo notebook for each plot function in PostREISE which gives a straight impression of what kind of plot a function generates without reading through the docstrings.

2. I see. That's cool.

3. Ah, right.

4. Is there a way to overwrite the default behavior?

5. Thanks.

1. Okay
4. We could maybe add some checks so that if you set vmax and/or vmin, there's a check as to whether there are any values that get clipped, and if so then we find some way to get the default ticks and labels and edit them... but for now I think the value of that effort is rather low since the user has the option to do it themselves as needed. If later we end up using this function a bunch them we can tack that function on later.

[BainanXia]

This is good to go. Thanks!

[rouille]

Should we move the plt.show() inside the function?

[danielolsen]

Should we move the plt.show() inside the function?

I think this is a larger conversation about what we want our plot functions to ultimately do: return a plot, or display a plot. I think right now we have a mixture, but it would be nice to standardize.

[rouille]

One more