doc/refactor: improve documentation and usability of investment costs

[danielolsen]

Pull Request doc

Purpose

• Update docstrings to reflect latest code details (which already include inflation calculations).

What the code is doing

• In investment_costs.py: Most of the changes are docstrings, adding info that the costs are automatically brought to today using the inflation calculations. The other changes are that when we don't sum all costs together, we now return a single Series containing the cost data, rather than a data frame (the current practice for gen costs and ac costs) with many columns, one of which is "Cost" (AC line calculations) or "CAPEX_total" (plant calculations). This should be more intuitive for the user, who shouldn't have to wade through many unrelated columns when they are really just interested in cost. The indices are still preserved, in case they want to do grouping using more info in the Grid's plant or branch data frames. We also update the docstrings for these changed return types.
• In test_investment_costs.py: We update the test case according to the new return types.
• In upgrade.py: for the cost-prioritization for congested branch upgrades, we update the code based on the new return type for AC branches.

Testing

Existing tests still pass. The refactor of the cost-prioritized upgrades for congested mesh branches has been tested manually, since it is tough to create an automated test due to the instantiation of a base Grid within this algorithm:

from powersimdata import Scenario
ref_scenario = Scenario(3101)
new_scenario = Scenario()
new_scenario.set_grid(interconnect="Western")
new_scenario.change_table.scale_congested_mesh_branches(ref_scenario, upgrade_n=5, method="cost")

(completes successfully)

As far as I can tell, this is the only use of the changed code in this repo that is not already covered by unit tests.

Time estimate

5-10 minutes.

[ahurli]

If we're calculating inflation to "today", do we want to update this to 2021? Or better yet, get the current year?

from datetime import datetime
datetime.today().year

[danielolsen]

The first parameter of calculate_inflation is the start_year, and if the end_year is not specified then we automatically use the latest year for which we have data in powersimdata.design.investment.const.inflation_rate_pct.

[ahurli]

Same as above regarding the hardcoded "today" year in _calculate_single_line_cost.