Automatize documentation of output KPI in RTD by smartie2076 · Pull Request #869 · rl-institut/multi-vector-simulator

smartie2076 · 2021-04-23T06:38:32Z

Adresses #873

Changes proposed in this pull request:
❌ Create table (MVS_output_list.csv) with following column headings: :Definition:,valid_interval,:Type:,:Unit:,label,ref,categories (economic, technical, environemental? --> technical),see_also -> already implemented with file MVS_kpi_list.csv

Explain the categories shown in the RTD, like here a211ccf
Add each parameter in the RTD using .inc and so on. inc created with 3b63e37, applied with a211ccf
[?] Create a table-view of the parameters, like here, e5c4e79
Fill new file MVS_kpis_list.csv with content, use MVS_output_parameters_tooltips.xlsx to start with
Add a file MVS_kpi_categories.csv, relating to the :categories: in MVS_kpis_list.csv: 42707f0
Create bulleted list of outputs of each category, comp. here, 1d2f9ce. Done with: e2414b3, 2cd4c08
Check MVS_kpis_list.csv for completeness
Implement the references from one KPI to other related KPI
Decapitalize any first letters of constants in constants_json_strings.py and remove all spaces

The following steps were realized, as well (if applies):

Use in-line comments to explain your code
Write docstrings to your code (example docstring)
❌ For new functionalities: Explain in readthedocs
❌ Write test(s) for your new patch of code (pytests, assertion debug messages)
Update the CHANGELOG.md
Apply black (black . --exclude docs/)
Check if benchmark tests pass locally (EXECUTE_TESTS_ON=master pytest)

smartie2076 · 2021-04-23T06:39:53Z

Goal for output parameter documentation, as mentioned in #853:

Output KPI (how we calculate them)
   Short description loaded automatically form .inc files generated form a MVS_outputs.csv
   	Columns :Definition:,valid_interval,:Type:,:Unit:,label,ref,categories (economic, technical, environemental? --> technical),see_also (collection of links)
   Not in a csv file for the complete and formal mathematical definition

smartie2076 · 2021-04-23T06:46:25Z

PR #842 shows an outline of how this worked for the input parameters.

smartie2076 · 2021-04-23T06:57:37Z

@Bachibouzouk already prepared the processing of the output parameters:

generate_kpi_description in conf.py -> creates .inc files in model/outputs
fill MVS_kpis_list.csv with info
Add .. include:: outputs/<Datei Name>.inc at the appropriate location

smartie2076 · 2021-04-23T14:34:32Z

I personally do not think that creating a table view of the parameters is necessary.

Bachibouzouk · 2021-04-26T10:09:27Z

@smartie2076 - Several internal references are not using the correct label names, this should be fixed

smartie2076 · 2021-04-26T11:38:29Z

There are a couple of references calling label pdf-report-commands that do not work:

D:\PycharmProjects\mvs_eland\docs\model\simulation_outputs.rst:352: WARNING: undefined label: pdf-report-commands (if the link has no caption the label must precede a section he
ader)
D:\PycharmProjects\mvs_eland\docs\model\simulation_outputs.rst:361: WARNING: undefined label: pdf-report-commands (if the link has no caption the label must precede a section he
ader)

They are called here twice (:ref:'report section <pdf-report-commands>'). It seems that when converting the README.rst to readme.inc (here) the label that is defined here is not used?

I did not change anything here, though, so I do not think this is the issue.

smartie2076 · 2021-04-26T12:39:12Z

I am making sure that we can not have capitalization and space typos anymore

smartie2076 · 2021-04-28T08:55:49Z

@ciaradunks @Bachibouzouk I am sorry about the many commits - I actualy wanted to push the refactoring into a seperate branch and PR, but mistakenly pushed to this branch.

Personally, I dont know anymore what :type: is supposed to help me with. Currently, all are numeric. I might be able to also add the figures and dispatch flows in there, and then those would be timeseries/png/the report. Is that what was intended?

Bachibouzouk · 2021-04-28T12:47:25Z

Personally, I dont know anymore what :type: is supposed to help me with

I would distinguish between numeric and array of numeric
If the outputs you provide are all numeric (no arrays) we can remove the column :type: :)

smartie2076 · 2021-04-28T13:01:03Z

Personally, I dont know anymore what :type: is supposed to help me with

I would distinguish between numeric and array of numeric
If the outputs you provide are all numeric (no arrays) we can remove the column :type: :)

I now used it in #874, and now there are also the type time series and file types

CHANGELOG.md

docs/MVS_kpis_list.csv

docs/conf.py

docs/model/simulation_outputs.rst

smartie2076 · 2021-05-03T15:02:32Z

Thank you for the thorough review @ciaradunks !

- Adapt `conf.generate_parameter_description` for output KPI - Create `conf.generate_kpi_description()`

- Add `MVS_kpi_categories.csv` - Create list using `MVS_kpi_categories.csv` and `MVS_kpis_list.csv` with `conf.generate_kpi_categories()`

- Add some labels - Add introductory text - Minor restructuring

- Add section explaining how KPI will be defined - Add section of suffixes of KPI, add label in `assumptions.rst` - Add `.. include::` for each KPI that needs to be officially defined - Restructure, so that Economic - Technical - Environmental - Figures - Autoreport

-> "total_non_renewable_energy_use" And fix

-> "total_non-renewable_energy_use" And fix

And fix

…ation" -> "renewable_share_of_local_generation" And fix

And fix

…ent" -> "specific_emissions_per_electricity_equivalent" And fix

…vider" -> "total_consumption_from_energy_provider"

And fix

…osts_of_electricity_equivalent" And fix

And fix

…_sector_coupling"

Co-authored-by: ciaradunks <[email protected]>

Bachibouzouk

I made some of the change I proposed on #878

docs/conf.py

docs/model/constraints.rst

Bachibouzouk · 2021-05-04T06:04:42Z

docs/model/eland_requirements.rst

-* :ref:`Levelized cost of energy (LCOE) <lcoe>` of the energy system, in electricity equivalent
-* :ref:`Levelized cost of an energy carrier <lcoe>` in electricity equivalent (LCOEleq) for each energy carrier in the energy system
-* :ref:`Levelized cost of asset dispatch <lcoe_asset>`, calculated from the annuity of an asset and their throughput
+* :ref:`NPC <costs_total>` and annuity of the whole energy system


Are you sure you want to replace net present cost by cost_total. If yes, why call this variable NPC then? I find it confusing. LCOE is explicitly named before being abbreviated below but NPC not

Yes, the name in the .csv for costs_total is also NPC (https://multi-vector-simulator.readthedocs.io/en/latest/model/simulation_outputs.html#net-present-costs-npc-costs-total) we could also use Net present costs here, though.

At some point we should actually change costs_total into NPC directly in the code, so that it is also displayed correctly in the report. Multiple ways to do this (either translate for the report/outputs only, or translate when adding the keys to the dict_values)

src/multi_vector_simulator/utils/data_parser.py

docs/model/simulation_outputs.rst

smartie2076 self-assigned this Apr 23, 2021

smartie2076 added the documentation Improvements or additions to documentation label Apr 23, 2021

smartie2076 force-pushed the rtd/output_parameters branch 2 times, most recently from f7bd13d to 490c590 Compare April 28, 2021 08:52

smartie2076 marked this pull request as ready for review April 28, 2021 08:55

smartie2076 requested a review from ciaradunks April 28, 2021 09:02

smartie2076 changed the title ~~Proper documentation of output parameters in RTD~~ Automatize documentation of output KPI in RTD Apr 28, 2021

smartie2076 mentioned this pull request Apr 28, 2021

Outputs of MVS need to be documented #873

Open

4 tasks

ciaradunks approved these changes May 3, 2021

View reviewed changes

docs/model/simulation_outputs.rst Outdated Show resolved Hide resolved

docs/model/simulation_outputs.rst Outdated Show resolved Hide resolved

docs/model/simulation_outputs.rst Outdated Show resolved Hide resolved

docs/model/simulation_outputs.rst Outdated Show resolved Hide resolved

smartie2076 added 9 commits May 3, 2021 17:12

Update MVS_kpis_list.csv

70e9426

Compile MVS_kpis_list.csv into .inc files

75c76b6

- Adapt `conf.generate_parameter_description` for output KPI - Create `conf.generate_kpi_description()`

Create list of outputs

9654cc5

- Add `MVS_kpi_categories.csv` - Create list using `MVS_kpi_categories.csv` and `MVS_kpis_list.csv` with `conf.generate_kpi_categories()`

Minor changes: Black, Comments

d2c15d1

Add introduction to simulation_outputs.rst

b1661e8

- Add some labels - Add introductory text - Minor restructuring

Add bulleted list of KPI per category

439d7b4

Fix references calling labels

5e75209

Use global constant in data_parser.py

8e3bb6c

smartie2076 and others added 25 commits May 3, 2021 17:12

TOTAL_NON_RENEWABLE_ENERGY_USE = "Total non-renewable energy use"

85288d1

-> "total_non_renewable_energy_use" And fix

TOTAL_NON_RENEWABLE_ENERGY_USE = "Total non-renewable energy use"

b86c71f

-> "total_non-renewable_energy_use" And fix

RENEWABLE_FACTOR = "Renewable factor" -> "renewable_factor"

6e74347

And fix

RENEWABLE_SHARE_OF_LOCAL_GENERATION = "Renewable share of local gener…

14339f7

…ation" -> "renewable_share_of_local_generation" And fix

TOTAL_EMISSIONS = "Total emissions" -> "total_emissions"

8d7ec04

And fix

SPECIFIC_EMISSIONS_ELEQ = "Specific emissions per electricity equival…

755c292

…ent" -> "specific_emissions_per_electricity_equivalent" And fix

TOTAL_CONSUMPTION_FROM_PROVIDERS = "Total_consumption_from_energy_pro…

12bbb28

…vider" -> "total_consumption_from_energy_provider"

ATTRIBUTED_COSTS = "Attributed costs" -> "attributed_costs"

18a3dbe

And fix

LCOeleq = "Levelized costs of electricity equivalent" -> "levelized_c…

6eb57a8

…osts_of_electricity_equivalent" And fix

TOTAL_DEMAND = "Total_demand" -> "total_demand"

e780b1f

And fix

TOTAL_EXCESS = "Total_excess" -> "total_excess"

1e05658

And fix

TOTAL_FEEDIN = "Total_feedin" -> "total_feedin"

f3cbd1d

And fix

DEGREE_OF_AUTONOMY = "Degree of autonomy" -> "degree_of_autonomy"

be98bc5

And fix

DEGREE_OF_SECTOR_COUPLING = "Degree of sector coupling" -> "degree_of…

c9a33f9

…_sector_coupling"

Apply replacing spaces and capitalization of KPI

39b2ccd

Sort alphabetically by ref name

18a3b50

Add and fix Degree of net zero energy (NZE)

9d6ef07

Add and fix total_consumption_from_energy_provider / Energy import

99c7cf8

Fix references to outdated labels

77b34f9

Implemented reference to connected indicators

51b7d1e

Fix spelling mistake

079682a

Formatting with black

69e4bbd

Changelog.md

ca0cf68

Apply suggestions from code review

326d0a0

Co-authored-by: ciaradunks <[email protected]>

Code review

d94f610

smartie2076 force-pushed the rtd/output_parameters branch from b20978f to d94f610 Compare May 3, 2021 15:13

smartie2076 merged commit 5c0d561 into dev May 3, 2021

smartie2076 deleted the rtd/output_parameters branch May 3, 2021 15:18

Bachibouzouk reviewed May 4, 2021

View reviewed changes

smartie2076 mentioned this pull request May 31, 2021

Release/v1.0.0 #898

Merged

Conversation

smartie2076 commented Apr 23, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smartie2076 commented Apr 23, 2021

Uh oh!

smartie2076 commented Apr 23, 2021

Uh oh!

smartie2076 commented Apr 23, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smartie2076 commented Apr 23, 2021

Uh oh!

Bachibouzouk commented Apr 26, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smartie2076 commented Apr 26, 2021

Uh oh!

smartie2076 commented Apr 26, 2021

Uh oh!

smartie2076 commented Apr 28, 2021

Uh oh!

Bachibouzouk commented Apr 28, 2021

Uh oh!

smartie2076 commented Apr 28, 2021

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

smartie2076 commented May 3, 2021

Uh oh!

Bachibouzouk left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Bachibouzouk May 4, 2021

Choose a reason for hiding this comment

Uh oh!

smartie2076 May 4, 2021

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

smartie2076 commented Apr 23, 2021 •

edited

Loading

smartie2076 commented Apr 23, 2021 •

edited

Loading

Bachibouzouk commented Apr 26, 2021 •

edited

Loading

Bachibouzouk left a comment •

edited

Loading