Skip to content

Getting Started

Jump to bottom
Rajendra Adhikari edited this page Dec 20, 2023 · 8 revisions

Setup AWS credentials

If you haven't already, please setup your AWS credentials before proceeding.

Get started

To get started, import the BuildStockQuery class and initialize a run object. If you are trying to connect to a ComStock run or to a published dataset in OEDI, see the notes below.

from buildstock_query import BuildStockQuery
my_run = BuildStockQuery(workgroup='rescore',
                         db_name='euss-final',
                         table_name='euss_res_final_2018_550k_20220901')

The workgroup, db_name and table_name can be found from the Athena console as shown in the highlight below.

image

If skip_reports is not set to True, the run object initialization will print a upgrade report and verify the integrity of the simulation result.

Here is an example upgrade report for the table above:

         fail  unapplicable  success     Sum  Applied %  no-chng  bad-chng  \
upgrade                                                                      
0        1084             0   548916  550000        0.0        0         0   
1           1         17092   531823  548916       96.9     6097       949   
2           2         12117   536797  548916       97.8     6527       879   
...
         ok-chng  true-bad-chng  true-ok-chng  null     any  no-chng %  \
upgrade                                                                  
0              0              0             0     0       0        0.0   
1         524777            277        525480     0  531823        1.1   
2         529391            354        529940     0  536797        1.2   
...

         bad-chng %  ok-chng %  true-ok-chng %  true-bad-chng %  
upgrade                                                          
0               0.0        0.0             0.0              0.0  
1               0.2       98.7            98.8              0.1  
2               0.2       98.6            98.7              0.1  
...

Annual and timeseries tables are verified to have the same number of buildings.
All buildings are verified to have the same number of (35040) timeseries rows.

The report is generated using get_success_report function. The various columns have the following meaning:

fail: Number of buildings for which the simulation failed.
unapplicable: Number of buildings to which the upgrade didn't apply.
success: The number of buildings for which the upgrade applied and simulation completed successfully. No simulation is run for unapplicable buildings.
sum: Sum of the first three columns.
applied %: Success / Sum * 100 %.
no-chng: Number of successful simulation that didn't have any change in values for any enduses.
bad-chng: Number of successful simulation that had bad changes. It's considered a bad change if none of the fuel has any reduction in energy consumption, and at least one fuel has an increase in energy consumption.
ok-chng: Count of successful simulation that are neither no-chng nor bad-chng.
true-bad-chng: Count of only those bad changes in which neither of the umnet cooling/heating hours decreased. In other words, the increase in energy consumption in one of the fuel type (often electricity - for electrification upgrades) didn't result in improvement of cooling/heating umnet hours. Only works when unmet hours are available. 
true-ok-chng: Adjustment of ok-chng after using true-bad-chng instead of bad-chng
null: Included for testing/integrity-checking purpose. It refers to number of buildings that are are neither no-chng, not bad-chng nor ok-chng. It should always be zero.
any: Sum of the no-chng + bad-chng + ok-chng. Refers to any change (including no-change).
x-chng: The percentage form of the change calculated by using success count as the base.

In addition, the initialization function also checks the integrity of timeseries and baseline table. Namely,

  1. Whether the annual and timeseries table have the same number of buildings or not. In all healthy runs, they should, but sometimes, when things don't get properly uploaded, or BuildStockBatch crashes/encounter error when writing timeseries/annual result files, they could be different. This check helps catch such issues early.

  2. Whether all buildings in timeseries have same number of rows and what the number of rows is. Healthy runs are supposed to have this to be the case, and should have 8760 (or 8784 for leap year) rows for hourly simulation, or 35040 (or 35136 for leap year) for 15-min resolution simulation. This check helps catch issues with timeseries data.

Note about connecting to ComStock result

In order to hookup BuildStockQuery with ComStock result, you will need to pass an extra buildstock_type argument to the constructor.

my_run = BuildStockQuery(workgroup=...,
                         db_name=...,
                         table_name=...,
                         buildstock_type='comstock'
                        )

Note about connecting to published dataset

By default, BuildStockQuery expects the Athena database/tables structure to be of the format that BuildStockBatch uploads. However, published ResStock dataset and ComStock dataset that are hosted in OEDI use structures that are different. In order to connect with such dataset, (after you have created / have access to Athena tables created from those dataset - link to video on how to do that), you can pass an extra db_schema argument to the constructor.

my_run = BuildStockQuery(workgroup=...,
                         db_name=...,
                         table_name=...,
                         buildstock_type='resstock',
                         db_schema='resstock_oedi',
                        )

Here is the set of buildstock_type and db_schema that are available and their relationship.

Buildstock Type Default DB Schema Alternative DB Schemas
resstock resstock_default resstock_oedi
comstock comstock_default comstock_oedi

Clone this wiki locally