README, tutorial and code improvement

[rouille]

Pull Request doc

Purpose

• Rewrite README
• Write tutorial presenting the analysis modules
• Write a chunck of the tutorial on the plotting modules

What the code is doing

Refactor 3 map related modules - postreise.plot.plot_carbon_map, postreise.plot.plot_interconnection and postreise.plot.plot_lmp_map - to:

• Use bokeh and matplotlib builtin functionalities (color bar, data normalization, etc.)
• Use existing postreise.plot.plot_states module
• Expand list of optional parameters
• Check validity of parameters passed to the function.

In other modules:

• Improve docstrings
• make sure that optional parameters are optional in the postreise.plot.plot_powerflow_snapshot module
• make the postreise.plot.plot_carbon_bar more flexible, it can now takes n scenarios
• add tooltip label name as argument in plot_states function located in the postreise.plot.plot_states module
• fix deprecation warnings (MatplotlibDeprecationWarning: The 's' parameter of annotate() has been renamed 'text' since Matplotlib 3.3 #259)
• rename variables

Testing

Copy/Paste the code snippets in the docs.

Where to look

The postreise.plot.plot_carbon_map, postreise.plot.plot_interconnection, postreise.plot.plot_lmp_map and postreise.plot.plot_carbon_bar modules. For the tutorial I would recommend to generate the docs (see below)

Usage Example/Visuals

Two options:

• Checkout this branch along with the ben/postreise branch in the docs repository and run tox there. Click on PostREISE in the side bar and navigate the tutorial. The code snippets can be used to generate the plots that are rendered on this page
• Run the postreise/plot/demo/plot_tutorial notebook that has been used to generate the plots in the tutorial (I will delete the notebook before merging)

Time estimate

1h

Note

I did not update the notebooks. Do we want to keep the notebooks once all the plots are in the docs? In fact, someone looking at the notebooks on GitHub won't be able to visualize the maps.

[danlivengood]

Hi all!

Daniel asked me to add some comments here as I’ve been using Ben’s PostREISE branch while creating our Training Session 3 slides.

First and foremost, Ben, Thank You! I have found this tutorial quite helpful and the plotting functions easy-to-use.

Along the way, I’ve found at least one code block that didn’t work for me. If this (or any other) is operator error, my apologies.

• The code snippet for “calculate the hourly congestion surplus” returns
  NameError: name 'congestion' is not defined

[danlivengood]

We also discussed that it might be smart to not use the Python keyword 'map' as the function return names in the Plotting Scenario Data blocks

• get a power flow snapshot
• show carbon emission by generator type using circles overlay on a map
• map locational marginal price
• map transmission lines color coded by interconnection
• compare carbon emission by generator type for two scenarios on a map

[danlivengood]

In the figure code block
plot stacked generation and carbon emission for 1-to-n scenarios side-by-side
the Scenario calls are 'xxx', which I assume are intended to be 2497 and 3101

[rouille]

We also discussed that it might be smart to not use the Python keyword 'map' as the function return names in the Plotting Scenario Data blocks

• get a power flow snapshot

• show carbon emission by generator type using circles overlay on a map

• map locational marginal price

• map transmission lines color coded by interconnection

• compare carbon emission by generator type for two scenarios on a map

This has been fixed. Unfortunately, I forgot to update the docs in Dropbox @danlivengood before taking off

[rouille]

In the figure code block

plot stacked generation and carbon emission for 1-to-n scenarios side-by-side

the Scenario calls are 'xxx', which I assume are intended to be 2497 and 3101

This has been fixed too.

[danlivengood]

In the block "calculate total emissions by generator type and bus," I believe

emission_by_resources_and_bus = summarize_emissions_by_bus(emission)

should be

emission_by_resources_and_bus = summarize_emissions_by_bus(emission, grid)

[danlivengood]

In the blocks
calculate hourly curtailment by generator type(s)
and
calculate scenario-long average curtailment fraction for a set of generator type(s)

I'm getting a "ValueError: invalid renewable resource(s): ", which I believe is coming from the inclusion of hydro. It runs properly when I change it to solar and wind.

[danlivengood]

In the heatmap figure 'plot any time-series values using a heatmap where each column is one color-coded day', there is a mismatch between the output of the calculate function which is curtailment, but then summed_curtailment is used in the plot_heatmap call

I'm assuming those should be the same (it runs correctly when they align)

---

NameError Traceback (most recent call last)
in
11
12 plot_heatmap(
---> 13 summed_curtailment,
14 cmap="PiYG_r",
15 scale=1e-3,

NameError: name 'summed_curtailment' is not defined

[danlivengood]

In the emissions chart 'compare total carbon emissions by generator type for 1-to-n scenarios through bar charts'
I believe name should be labels

[danlivengood]

In 2 code blocks, the output is either empty or 0. They are correct, but for a 'new' user, it might cause a question of wondering whether the block ran correctly.

get total storage nameplate capacity in an area
Currently
Scenario 2497, state "CA", output = 0.
I'd suggest
Scenario 3823, state "AR", output = 500

get the hourly capacity factor of each generator fueled by resource(s) in an area
Currently
Scenario 3101, interconnect "Texas", output = empty table
I'd suggest
Scenario 1270, interconnect "Texas", output = non-empty table

[danlivengood]

In calculate individual generator costs at given powers,
the function
calc_costs
has been updated to be
calculate_costs

#269

Recommend changing the block to be

from powersimdata import Scenario
from postreise.analyze.generation.emissions import calculate_costs

scenario = Scenario(403)
costs = calculate_costs(scenario)

[danielolsen]

I've gone through all the code, and left a couple small comments where things could be shined up a bit more, but I think this is a big improvement and ready to go in whenever you think it is.

[BainanXia]

Do we want to follow the convention: always return the axes of the plot and provide option to not show the plot immediately after the function call? Same comment for all the plot functions being refactored here.

[rouille]

The plotting functions that are in the tutorial and that don't have the axes returned and the show_plot parameters are:

• plot_bar_generation_vs_capacity
• plot_bar_shortfall
• map_carbon_emission_generator and map_carbon_emission_difference
• plot_curtailment_time_series
• plot_n_scenarios
• plot_generation_time_series_stack
• plot_heatmap
• map_interconnections
• map_lmp
• plot_pie_generation_vs_capacity
• plot_powerflow_snapshot

Should I go ahead and refactor them?

[BainanXia]

Great work! I think this is good to go at this point with two open problems to solve in future PRs
a) refactor plots following the convention: returning an axes object and giving the option for now showing it
b) deal with notebooks
based on our offline discussions with @rouille and @danielolsen