Migrate BETTER API from V1 to V2 #3881

perryr16 · 2023-02-28T20:20:06Z

Any background context you want to provide?

The API service that the SEED platform uses to generate BETTER analysis has undergone a version change from V1 to V2. The V1 endpoints have been overwritten by the V2 endpoints breaking the existing functionality. It's worth noting that this is BETTER API V2, however, all endpoints still point to the api/v1/ URL.

V2 makes changes to how Portfolio Analyses are processed (a Portfolio is a collection of Buildings). In V1 a portfolio analysis was initiated and a building_analysis was created for each building in the portfolio. In V2 instead of creating building_analyses, a portfolio analysis will generate a portfolio_building_analysis for each building in the portfolio.

What's this PR do?

This PR migrates the BETTER pipeline functionality to the BETTER V2 endpoints.

new pathways to retrieve and store portfolio_building_analyses
updates to variable naming
Add a new Org Settings page button to verify the current token.

How should this be manually tested?

To test the BETTER token verification button

Go to organization settings > API Key > there is now a button to "Verify Token"
The button text and color will change to indicate a valid or invalid token.
You must save changes to reverify the token

To test the BETTER analyses

You must first have inventory that meets the better requirements. This includes meter data, property type, city, state, and gross floor area. Note that the property type "Office" is reliable.
select one property and run a better analysis > ensure a successful run and the property now displays the analysis results
select multiple properties and run a better analysis with "Run Portfolio Analysis" unchecked. Ensure a successful run and the selected properties show the analysis results
select multiple properties and run a better analysis with "Run Portfolio Analysis" checked. Ensure a successful run and the selected properties show the analysis results

What are the relevant tickets?

#3874

Screenshots (if appropriate)

Known issues

BETTER V2 introduces an enable_pvwatts analysis configuration key. This key has been hardcoded to false. Integrating this key will require further design.

Of the 3 active BETTER servers, production and staging are functional, while development is missing endpoints.

Within the /buildingsync.py file of SEED, there are a number of property_types that are defined as accepted BETTER (and bsync) properties, however several of them will cause a BETTER analysis to fail.

passing types: Office, Hotel, K-12 School, Multifamily Housing
failing types: Hospital (General Medical & Surgical), Bank Branch, Courthouse, Data Center, Distribution Center, Financial Office, Non-Refrigerated Warehouse, Refrigerated Warehouse, Retail Store, Senior Care Community, Supermarket/Grocery Store, Other

…to incorporate pvwatts

…ER v2

…e on an analysis_property_view

…o portfolio building analyses (BETTER v2)

…Analysis object

perryr16 · 2023-02-28T22:11:50Z

config/settings/docker_dev.py

+# BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better.lbl.gov')
+BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better-lbnl-staging.herokuapp.com')
+# BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better-lbnl-development.herokuapp.com')


At the writing of this, production and staging servers are functional and the development server is missing endpoints

Line 47 doesn't seem necessary here.

perryr16 · 2023-02-28T22:14:45Z

seed/analysis_pipelines/better/helpers.py



-def _store_better_portfolio_analysis_results(better_analysis_id, better_building_analyses, context):


better_analysis_id can be found in better_building_analyses

perryr16 · 2023-02-28T22:19:45Z

seed/analysis_pipelines/better/pipeline.py

+        _store_better_building_analysis_results(
+            better_building_analyses,
+            context,
+        )


_store_better_building_analysis_results should only be run if better_portfolio_id is None

anchapin

Everything from this PR works as intended. Good job!

anchapin · 2023-03-06T21:58:20Z

config/settings/docker_dev.py

+# BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better.lbl.gov')
+BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better-lbnl-staging.herokuapp.com')
+# BETTER_HOST = os.environ.get('BETTER_HOST', 'https://better-lbnl-development.herokuapp.com')


Line 47 doesn't seem necessary here.

perryr16 · 2023-03-08T21:30:13Z

Below are the results from various Analysis configuration tests. Note that it's important that the analysis "Run" doesn't fail if BETTER returns an error for one building in an analysis. This allows results for other buildings in the analysis to be processed.

SINGLE BUILIDNGS

1 Valid Property Type ("Hotel")
Analysis completes with data
1 Invalid Property Type ("Bank Branch")
The analysis "completes", however, the building has the following under "latest message"
- Building Analysis generation status returned "FAILED": Internal error. Could not generate building analytics. No benchmark data is defined for country US and space type BANK_BRANCH
1 building without a Property Type
The analysis fails with the following "latest message"
- Error preparing BETTER input: BETTER analysis requires the property's type must be one of the following: Office, Hotel, K-12 School, Hospital (General Medical & Surgical), Bank Branch, Courthouse, Data Center, Distribution Center, Financial Office, Mul..
1 building with unsupported Property Type ("Unsupported Type")
The analysis fails with the following "latest message"
- Error preparing BETTER input: BETTER analysis requires the property's type must be one of the following: Office, Hotel, K-12 School, Hospital (General Medical & Surgical), Bank Branch, Courthouse, Data Center, Distribution Center, Financial Office, Mul...

MULTIPLE BUILDINGS - NON PORTFOLIO

2 Valid Property Type ("Hotel"). Non-Portfolio
Analysis completes and each building has valid and unique analysis data
2 Invalid Property Type ("Bank Branch"). Non-Portfolio
The Analysis completes with the following errors on each building
- Building Analysis generation status returned "FAILED": Internal error. Could not generate building analytics. No benchmark data is defined for country US and space type BANK_BRANCH
1 Valid and 1 Invalid building. Non-Portfolio
The analysis completes, the valid property has analysis data while the unsuported type returns
- BETTER analysis could not be fetched: Status Code: 404 Not found.
- Building Analysis generation status returned "FAILED": Internal error. Could not generate building analytics. No benchmark data is defined for country US and space type BANK_BRANCH

PORTFOLIOS

2 Valid Property Type ("Hotel"). Portfolio. Default Benchmark Data Type
The analysis completes with valid data
2 Valid Property Type ("Hotel"). Portfolio. Generate Benchmark Data Type
The analysis completes with valid data
2 Invalid Property Type ("Bank Branch"). Portfolio. Default Benchmark Data Type
The analysis completes with the following errors on each property
- BETTER analysis could not be fetched: Status Code: 404 Not found.
- Building Analysis generation status returned "FAILED": Internal error. Could not generate building analytics. No benchmark data is defined for country US and space type BANK_BRANCH
2 Invalid Property Type ("Bank Branch"). Portfolio. Generate Benchmark Data Type
The analysis completes with valid data. This is expected, the BETTER documentation states that if all buildings in a portfolio are of the same type, but no default benchmark data, it can be run if the "GENERATE" option is selected as the Benchmark Data Type
1 Valid and 1 Invalid Property Type ("Hotel", "Bank Branch"). Portfolio. Default or Generate Benchmark Data Type
The Analysis fails because portfolios must be of the same property type. The Portfolio Analysis's latest message is
- Failed to generate BETTER portfolio analysis: All buildings in portfolio analytics must be of same space type (found space types: HOTEL,BANK_BRANCH)
1 Valid and 1 Unsupported Property Type ("Office", "Unsupported Type"). Portfolio. Default or Generate Benchmark Data
The analysis completes but the unsupported property types have been excluded from the portfolio as no BETTER building was created. The results are present for those with valid property types.
The failing building has the following error message
- Error preparing BETTER input: BETTER analysis requires the property's type must be one of the following: Office, Hotel, K-12 School, Hospital (General Medical & Surgical), Bank Branch, Courthouse, Data Center, Distribution Center, Financial Office, Mul...

perryr16 · 2023-03-09T21:32:25Z

Added the ability to display warning messages for portfolio analysis if it is created with less than 30 buildings.

RDmitchell · 2023-03-09T21:41:26Z

@perryr16 -- looks great ! Thx

kflemin

🎉

nllong

worked as expected! The change of single vs portfolio of buildings is strange, but c'est la vie.

Good work!

…date_range' to match other analyses functionality

# Conflicts: # seed/static/seed/partials/analyses.html # seed/static/seed/partials/analysis_details.html # seed/static/seed/partials/inventory_detail_analyses_modal.html

Minor cleanup

axelstudios · 2023-03-22T12:44:07Z

I fixed a some minor issues, primarily that the BETTER_TOKEN_TEXT wasn't using translate correctly so the URL appeared in the hyperlink but not printed at the end.

Issues that remain to be fixed

There are tons of docstring errors in the BETTER code, where params and return values don't accurately reflect the inputs/outputs

perryr16 added 16 commits February 24, 2023 09:06

update variable name, key names, and error handling for None types

e33953e

update json path to v2 naming

5e80dc8

v2 variable naming, and disable pvwatts. Will need a larger refactor …

46521a0

…to incorporate pvwatts

v2 variable naming

79a5b25

better host options, develop is not up to date with staging

52f741b

create new endpoint to check validity of better api token

8bdf378

button to check validity of better api token

ebacfc3

new function to get a portfolio_building_analysis. Introduced in BETT…

b3b549d

…ER v2

generate a new function to store BETTER v2 portfolio_building_analyss…

f022139

…e on an analysis_property_view

separate paths for saving portfolio and building analyses

8f6884a

precommit

e6cabdd

introduce new PortfolioBuildingAnalysis class to track data related t…

a41a849

…o portfolio building analyses (BETTER v2)

remove redundant arguments that can be found on the PortfolioBuilding…

195b13b

…Analysis object

precommit

78f5078

add better server addresses for future devs

b93796d

precommit

d2fcbdc

perryr16 added the Maintenance Tag as maintenance if the issue relates to general cleanup, maintenance, etc. Do not delete label. label Feb 28, 2023

Merge branch 'develop' into 3874-BETTER-v2-migration

63b4ac2

perryr16 commented Feb 28, 2023

View reviewed changes

logging

57e5f89

perryr16 marked this pull request as ready for review March 1, 2023 16:47

perryr16 requested review from nllong, anchapin and axelstudios March 1, 2023 16:47

perryr16 added 4 commits March 3, 2023 14:54

error catch on failed generation for a builing analysis

2d032f2

precommit

9822a37

catch 500 error responses on invalid building type

df9061f

display more desciptive error message

517292f

anchapin approved these changes Mar 6, 2023

View reviewed changes

perryr16 added 5 commits March 8, 2023 10:00

revert changes

6b6f2c8

combine property type errors

c903401

update erorr responses

6b4a089

allow custom error messages to be logged to analysismessage

69a9f31

allow word wrap for long message strings

c7615e7

perryr16 added 4 commits March 9, 2023 14:20

return a third variable 'warnings'

1be55be

function to check warnings

25949f7

update documentation

dedde96

precommit

a86ea2e

kflemin self-requested a review March 10, 2023 05:42

kflemin approved these changes Mar 10, 2023

View reviewed changes

nllong approved these changes Mar 14, 2023

View reviewed changes

perryr16 and others added 4 commits March 21, 2023 12:49

Merge branch 'develop' into 3874-BETTER-v2-migration

2a592d1

analysis configuration select_meters value update. 'select' becomes '…

ba4f59b

…date_range' to match other analyses functionality

Merge branch 'develop' into 3874-BETTER-v2-migration

5e91702

# Conflicts: # seed/static/seed/partials/analyses.html # seed/static/seed/partials/analysis_details.html # seed/static/seed/partials/inventory_detail_analyses_modal.html

Fixed better_host_url in org settings

d96b71a

Minor cleanup

axelstudios approved these changes Mar 22, 2023

View reviewed changes

axelstudios merged commit e07f088 into develop Mar 22, 2023

axelstudios deleted the 3874-BETTER-v2-migration branch March 22, 2023 12:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Migrate BETTER API from V1 to V2 #3881

Migrate BETTER API from V1 to V2 #3881

perryr16 commented Feb 28, 2023 •

edited

perryr16 Feb 28, 2023

anchapin Mar 6, 2023

perryr16 Feb 28, 2023

perryr16 Feb 28, 2023 •

edited by anchapin

anchapin left a comment

anchapin Mar 6, 2023

perryr16 commented Mar 8, 2023

perryr16 commented Mar 9, 2023

RDmitchell commented Mar 9, 2023

kflemin left a comment

nllong left a comment

axelstudios commented Mar 22, 2023



		def _store_better_portfolio_analysis_results(better_analysis_id, better_building_analyses, context):

Migrate BETTER API from V1 to V2 #3881

Migrate BETTER API from V1 to V2 #3881

Conversation

perryr16 commented Feb 28, 2023 • edited

Any background context you want to provide?

What's this PR do?

How should this be manually tested?

What are the relevant tickets?

Screenshots (if appropriate)

Known issues

perryr16 Feb 28, 2023

Choose a reason for hiding this comment

anchapin Mar 6, 2023

Choose a reason for hiding this comment

perryr16 Feb 28, 2023

Choose a reason for hiding this comment

perryr16 Feb 28, 2023 • edited by anchapin

Choose a reason for hiding this comment

anchapin left a comment

Choose a reason for hiding this comment

anchapin Mar 6, 2023

Choose a reason for hiding this comment

perryr16 commented Mar 8, 2023

SINGLE BUILIDNGS

MULTIPLE BUILDINGS - NON PORTFOLIO

PORTFOLIOS

perryr16 commented Mar 9, 2023

RDmitchell commented Mar 9, 2023

kflemin left a comment

Choose a reason for hiding this comment

nllong left a comment

Choose a reason for hiding this comment

axelstudios commented Mar 22, 2023

Issues that remain to be fixed

perryr16 commented Feb 28, 2023 •

edited

perryr16 Feb 28, 2023 •

edited by anchapin