Data dictionary + automated RTD generation

[joseph-robertson]

Pull Request Description

Closes #1043.

Introduce:

• [x] resources/data/dictionary/inputs.csv
  • This is a file created by hand
  • It contains every output that is prefixed with build_existing_model
  • Columns: Name, Description
• [x] resources/data/dictionary/outputs.csv
  • This is a file created by hand
  • Columns: Index, Row Index, Sums To, Annual Name, Annual Units, Timeseries ResStock Name, Timeseries BuildStockBatch Name, Timeseries Units, Notes
• [x] New tests in test/test_bsb_analysis.rb:
  • test_<project>_inputs: check characteristics columns against the dictionary
  • test_<project>_annual_outputs: check annual columns against the dictionary, and check Sums To column
  • test_timeseries_resstock_outputs: check ResStock timeseries columns against the dictionary, and check Sums To column
  • test_timeseries_buildstockbatch_outputs: check BuildStockBatch timeseries columns against the dictionary, and check Sums To column
• [x] docs/read_the_docs/source/workflow_outputs/csv_tables.rb
  • creates individual csv tables, organized by category, that RTD renders
• [x] docs/read_the_docs/source/workflow_inputs/create_characteristics_rst.rb
  • creates Housing Characteristics section of RTD; subsections are each Parameter referenced from Available Outputs

Checklist:

• [x] Timeseries names reported by bsb vs those in results_timeseries.csv; could we include the bsb-processed timeseries names (e.g., "Timeseries BuildStockBatch Name") in addition to the raw datapoint timeseries names (e.g., "Timeseries ResStock Name")? Yes.
  • parquet/timeseries/upgrade=0/groupX.parquet (use pandas for reading these files)
• [x] Create a second build_existing_model. table with the argument rows (i.e., the blank Options rows).
• [x] Explicitly mention in the docs that you need to look at the raw data dictionary to understand how outputs relate to each other (i.e., "Row Index" and "Sums To" columns).
• [x] In Upgrade Costs, specify that number of options go from 1..25 (near "represents any of the defined option numbers.").
• [x] Update Housing Characteristics section based on the image below (this may be some kind of source_report.csv to .rst exercise); requires that source_report.csv is updated to contain columns of interest; create a placeholder "Description" column until it can be populated.
• [x] Are RTD docs actually being automatically generated? They are for the docs artifact, but what about committing updated characteristics.rst and csv_tables/*.csv back to the repository? Should probably move the "Build documentation" step back to the "update-results" job so we can commit changes to the docs folder.
• [x] Talk with Noel about whether we want, e.g., <ScenarioName> instead of actual emissions scenario. Update: yes, we should use <scenario_name> (and <type>) in the data dictionary file, for both emissions and utility bills.

Checklist

Not all may apply:

• [x] Tests (and test files) have been updated
• [x] Documentation has been updated
• [x] Changelog has been updated
• [x] openstudio tasks.rb update_measures has been run
• [x] No unexpected regression test changes on CI (checked comparison artifacts)

[nmerket]

Just looking at this file, this is awesome. We'll have to change some things in our downstream processing, but it'll be so much easier now. Thank you.

[joseph-robertson]

After meeting:

• [x] Describe "Sums To" in documentation
• [x] Change emissions/bills to use <place_holders>
• [x] Provide more links between ResStock docs and bsb docs

[joseph-robertson]

@rajeee Where, on the bsb hpxml wfg docs page, do you suppose we should link to the resstock docs?

[joseph-robertson]

@rajeee Where, on the bsb hpxml wfg docs page, do you suppose we should link to the resstock docs?

@rajeee and I talked a bit about this. The references should be within the applicable sections of the wfg docs page. We should get this PR merged before making the wfg docs updates, as I need the exact urls.