From 6437a9f7268b2aa854608d5c85366515594db7cc Mon Sep 17 00:00:00 2001 From: Rajendra Adhikari Date: Mon, 18 Dec 2023 11:12:09 -0600 Subject: [PATCH 1/3] Update README.md --- README.md | 100 +++--------------------------------------------------- 1 file changed, 5 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index d83b8c4..a80f869 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,10 @@ # BuildStockQuery (NREL SWR-23-58) - - - - - - - - - -A library to run AWS Athena queries to get various data from a BuildStock run. +BuildStockQuery is a python library designed to simplify and streamline the process of querying massive, terabyte-scale datasets generated by ResStock™ and ComStock™. ResStock (SWR-19-15) is a U.S. DOE-supported, NREL-built, national residential building energy stock model that enables a new approach to large-scale residential energy analysis across the U.S. by combining large public and private data sources, statistical sampling, detailed sub-hourly building simulations, and high-performance computing. + +BuildStockQuery offers an intuitive Object-Oriented Programming (OOP) interface to the ResStock output dataset allowing users to easily perform common queries and receive results in familiar pandas DataFrame format, abstracting away the need for complex SQL query. By initializing a query object with the pertinent Athena database and table names, users can easily query for various kinds of insights, for example, timeseries electricity for an end use for a given state grouped by building types. -# Installation Instruction +Dcumentation and walkthrough: https://github.com/NREL/buildstock-query/wiki -## Install as a library to your existing project -1. Make sure you have read access to the repo (which you should already have if you are reading this in github.com) -2. On your activated python / conda environment (Currently requries python >= 3.10), run the following command: - -`pip install git+https://github.com/NREL/buildstock-query` - -If you want to install a particular branch (for example you want to test a branch under development), you can do - -`pip install git+https://github.com/NREL/buildstock-query@branch_name` - -## Development installation -If you want to contribute back to the repo, and maybe fix bugs / add functions as you work with buildstock_query, you can do this. -1. Clone the repo to your computer: - -`git clone https://github.com/NREL/buildstock-query` - -2. Checkout a new branch so you can modify/fix things - -`git checkout -b bill_query` - -3. Activate your project environment (your project env has to have python >= 3.10) - -`conda activate your_existing_project_env` - -4. Do dev install of the buildstock_query in editable mode to your env - -`pip install -e .[dev]` - - - -## Usage example -The main class is called BuildStockQuery. -An object of BuildStockQuery needs to be created to perform various queries. In addition to supporting various -query member functions, the BuildStockQuery object contains 4 member objects that can be used to perform certain -class of queries and analysis. These 4 member objects can be accessed as follows:: - -``` -from buildstock_query import BuildStockQuery - -bsq = BuildStockQuery(...) `BuildStockQuery` object -bsq.agg `buildstock_query.aggregate_query.BuildStockAggregate` -bsq.report `buildstock_query.report_query.BuildStockReport` -bsq.savings `buildstock_query.savings_query.BuildStockSavings` -bsq.utility `buildstock_query.utility_query.BuildStockUtility` -``` - -``` -# Some basic query can be done directly using the BuildStockQuery object. For example: -from buildstock_query import BuildStockQuery -bsq = BuildStockQuery(...) -bsq.get_results_csv() -bsq.get_upgrades_csv() - -# Other more specific queries can be done using specific query class objects. For example: -bsq.agg.aggregate_annual(...) -bsq.agg.aggregate_timeseries(...) -... -bsq.report.get_success_report(...) -bsq.report.get_successful_simulation_count(...) -... -bsq.savings.savings_shape(...) -... -bsq.utility.aggregate_annual_by_eiaid(...) -``` - -In addition, the library also exposes `buildstock_query.tools.upgrades_analyzer.UpgradesAnalyzer`. It can be used to -perform quality check for the apply logic in buildstock configuration file. -``` -from buildstock_query import UpgradesAnalyzer -ua = UpgradesAnalyzer(yaml_file='my_buildstock_configuration.yml', 'my_buildstock.csv') -options_report = ua.get_report() -options_report.drop(columns=['applicable_buildings']).to_csv('options_report.csv') -ua.save_detailed_report('detailed_report.csv') -``` - -`buildstock_query.tools.upgrades_analyzer.UpgradesAnalyzer` is also exposed as an script and can be directly used -from the command line by simply calling it (from the env buildstock_query is installed in): -``` ->>>upgrades_analyzer -Welcome to upgrades analyzer -... -``` - -There is also another experimental tool called `buildstock_query.tools.upgrades_visualizer` available from command line. -This tool is only available when doing a 'full' install. The tool starts a localhost poltly dash dashboard that can be -used for analytic visualization of annual results for different upgrades. -``` ->>>upgrades_visualizer -Welcome to upgrades visualizer -... - -``` -More usage examples are available in jupyter notebooks at: https://github.com/NREL/buildstock-query/tree/main/example_usage +Usage examples: https://github.com/NREL/buildstock-query/tree/main/example_usage From e7f240079ae59f2e9ede4da00cddf86b64244bf1 Mon Sep 17 00:00:00 2001 From: Rajendra Adhikari Date: Mon, 18 Dec 2023 11:25:07 -0600 Subject: [PATCH 2/3] Fix polars mean calc --- buildstock_query/tools/upgrades_visualizer/figure.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/buildstock_query/tools/upgrades_visualizer/figure.py b/buildstock_query/tools/upgrades_visualizer/figure.py index face9c8..b0f9f2d 100644 --- a/buildstock_query/tools/upgrades_visualizer/figure.py +++ b/buildstock_query/tools/upgrades_visualizer/figure.py @@ -75,7 +75,7 @@ def _get_plot(self, df, params: PlotParams): for second_name, second_df in second_plots: name = ','.join(second_name) if second_name else str(grp0) count = len(second_df) - mean = pl.mean(second_df['value']) + mean = second_df['value'].mean() if counter >= 500: yvals.append(0.1) xvals.append("Too many groups") @@ -90,7 +90,7 @@ def _get_plot(self, df, params: PlotParams): elif params.value_type == ValueTypes.count: val = second_df['building_id'].n_unique() else: - val = pl.mean(second_df['value']) + val = second_df['value'].mean() val = float(val) yvals.append(val) xvals.append(name) From 13144cd74f91eb79c6d45c05e23fe928fff464dc Mon Sep 17 00:00:00 2001 From: Rajendra Adhikari Date: Mon, 18 Dec 2023 11:29:14 -0600 Subject: [PATCH 3/3] Update README.md Typo fix. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a80f869..a7e5434 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ BuildStockQuery is a python library designed to simplify and streamline the proc BuildStockQuery offers an intuitive Object-Oriented Programming (OOP) interface to the ResStock output dataset allowing users to easily perform common queries and receive results in familiar pandas DataFrame format, abstracting away the need for complex SQL query. By initializing a query object with the pertinent Athena database and table names, users can easily query for various kinds of insights, for example, timeseries electricity for an end use for a given state grouped by building types. -Dcumentation and walkthrough: https://github.com/NREL/buildstock-query/wiki +Documentation and walkthrough: https://github.com/NREL/buildstock-query/wiki Usage examples: https://github.com/NREL/buildstock-query/tree/main/example_usage