Home Energy Analysis Tool
Provide an app that helps residential energy coaches or advocates, and some homeowners, estimate a home's heating requirements (heat load) and assess whether proposed heat pumps have sufficient heating capacity for the home.
https://github.com/codeforboston/home-energy-analysis-tool
Category: Consumption
Sub Category: Buildings and Heating
Keywords from Contributors
code-for-america code-for-boston
Last synced: about 15 hours ago
JSON representation
Repository metadata
Calculator app improving state of art in heat pump sizing with Heat Smart Alliance coaches
- Host: GitHub
- URL: https://github.com/codeforboston/home-energy-analysis-tool
- Owner: codeforboston
- License: mit
- Created: 2023-05-10T11:38:27.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-12-22T20:32:05.000Z (16 days ago)
- Last Synced: 2025-12-23T13:20:50.000Z (16 days ago)
- Language: TypeScript
- Homepage: http://heat.heatsmartalliance.org
- Size: 76.6 MB
- Stars: 19
- Watchers: 9
- Forks: 43
- Open Issues: 79
- Releases: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
README.md
Goal: Provide an app that helps residential energy coaches or advocates, and some homeowners, estimate a home's heating requirements (heat load) and assess whether proposed heat pumps have sufficient heating capacity for the home. The app will use information about the home including it's location, usual thermostat settings, and historical energy usage, provided by the resident, to calculate the heating requirements in BTUs/hr. Key outputs will include two graphs, one showing the heating requirement vs. outdoor temperature and another comparing the home with other homes based on floor area. In the future, this app may be extended to provide more information, such an estimate of electricity use by a heat pump, cost of heating with a heat pump vs. fossil fuel and other such features.
Users: Heatsmart Alliance coaches, energy coaches with other affiliations, and users of the CfB sibling project.
Original method: An Excel spreadsheet with formulas that perform the calculations. Inputs to the existing spreadsheet include historic energy usage, typical thermostat settings, and temperature data from a weather station close to the home. More info on this existing spreadsheet and a link to request a download are available from the HeatSmart Alliance at this link.
Teams
UI/UX and/or Design
This team will work with the other teams to match the interface and necessary research together. Original figma is available here (https://www.figma.com/design/qaxsZ6TW7gjQdUGjuPypZ5/heat-tool-design---new-one-?node-id=2080-12489&p=f)
JavaScript
This team will plan and build the user interface. React and Remix in Epic Stack. Uses Pyodide to run python code on frontend.
It will also get information from the weather station API that the rules engine can use for its calculations. In the future, it may work on permissions and persistence of household dataREADME.md.
Rules Engine
Rules engine provides reading, validation and calculations for heat data that are read from the 2 gas companies National Grid and Eversource. https://docs.google.com/document/d/1-CAsHL1WhCPQW8iXA_XXgSUWHZsCKiTsPHOVz9eV0AE/edit?tab=t.0
Definitions:
Balance point: Outdoor temperature beyond which no heating is required.
Inclusion code: winter=1|spring=0|summer=-1|fall=0( determines the months to be used for heat load calculations)
Thermostat set point: the temp in F at which the home is normally set.
setback_temperature: temp in F at which the home is set during off hours.
setback_hours_per_day: average # of hours per day the home is at setback temp.
design_set_point: a standard internal temperature / thermostat it can be read for a county from helpers.py.
set point - different from the preferred set point of an individual homeowner.
avg_indoor_temp: average indoor temperature on a given day
`((24 - setback_hours_per_day) * thermostat_set_point + setback_hours_per_day * setback_temperature) / 24`
design_temp: an outside temperature that represents one of the coldest days of the year for the given location of a home.
ua: the heat transfer coefficient
hdd: heating degree days on a given day for a given home `(Balance Point-avg_indoor_temp)`.
dhw: heat used for non heating purposes.
maximun heat load: `(design_set_point - design_temp) * ua`
Documentation:
- design_temp [README.md](/design_temp/README.md)
Calculations:
The data files for each home is used to calculate the heat load for the home irrespective of the fuel type used. The data is normalized to be fuel type agnostic and the intermediate bill that is generated converts temperature data and billing period inputs into internal classes used for heat loss calculations.
Validations:
1.Validate the csv for the heating company National Gird/Eversource
Tests:
Tests for Engine:
- Generating intermediate bill
- Generating Normalized bill
- Calculate Non heating usage
Tests for Parser:
- Identify gas company
- Error of neither of the 2 Nation Grid/ Eversource
Auth
Role based Authorization, used from epic stack. For further documentation refer to
https://github.com/epicweb-dev/epic-stack/blob/main/docs/permissions.md?plain=1
Persistence
The epic stack has the default schemas in prisma.schema. The models specific to the project are placed after the default models in the same file. Migrations are run during the heat-stack setup. Updates to the model will create new migrations as necessary.
Deploy
The epic stack uses Fly.io for default deployment. This application works with it out of the box. The documentation is here https://github.com/epicweb-dev/epic-stack/blob/main/docs/deployment.md
Installation
To install the front end, see this README.md
To install the rules engine, see this README.md
Documentation
Further reading can be done here (https://drive.google.com/drive/folders/1z8dBfvQD78AAt7VI2z3J3YVubFNDpq-O)
Owner metadata
- Name: Code for Boston
- Login: codeforboston
- Email: hello@codeforboston.org
- Kind: organization
- Description: Improving civic life and social good in Greater Boston.
- Website: https://www.codeforboston.org
- Location: Boston, MA
- Twitter: codeforboston
- Company:
- Icon url: https://avatars.githubusercontent.com/u/2533182?v=4
- Repositories: 119
- Last ynced at: 2024-04-15T11:18:18.984Z
- Profile URL: https://github.com/codeforboston
GitHub Events
Total
- Create event: 134
- Issues event: 238
- Watch event: 6
- Delete event: 140
- Member event: 3
- Issue comment event: 212
- Push event: 424
- Pull request review comment event: 57
- Pull request review event: 77
- Pull request event: 264
- Fork event: 9
Last Year
- Create event: 129
- Issues event: 223
- Watch event: 6
- Delete event: 138
- Member event: 3
- Issue comment event: 200
- Push event: 406
- Pull request review event: 71
- Pull request review comment event: 52
- Pull request event: 251
- Fork event: 8
Committers metadata
Last synced: 4 days ago
Total Commits: 315
Total Committers: 38
Avg Commits per committer: 8.289
Development Distribution Score (DDS): 0.832
Commits in past year: 133
Committers in past year: 16
Avg Commits per committer in past year: 8.313
Development Distribution Score (DDS) in past year: 0.692
| Name | Commits | |
|---|---|---|
| Thad Kerosky | c****t@t****t | 53 |
| Alan Pinkert | a****t@g****m | 53 |
| AdamFinkle | 7****e | 45 |
| Ethan-Strominger | 3****r | 34 |
| mciethan | e****x@g****m | 24 |
| Jonathan Kwan | j****1 | 13 |
| Harry Zhu | h****6@g****m | 11 |
| Jeff Korenstein | 6****n | 10 |
| William Van Steen | w****n | 8 |
| Erika Nesse | e****e@g****m | 7 |
| eriksynn | 1****n | 6 |
| K Fuquay | k****y@g****m | 4 |
| plocket | 5****t | 4 |
| interianow | 2****w | 4 |
| ZaimaGull | Z****l@G****m | 4 |
| Nate | 1****r | 4 |
| Derek McIntire | 7****e | 3 |
| nikulabs | n****s@g****m | 2 |
| Debajyoti Debnath | d****h@p****u | 2 |
| dwindleduck | 1****k | 2 |
| Vlad Korolev | v****d@v****g | 2 |
| stemgene | 3****e | 2 |
| Devin Altobello | 1****o | 2 |
| pravindransolutions | 1****s | 2 |
| thatoldplatitude | 9****e | 1 |
| spghtti | 2****i | 1 |
| binamkayastha | b****a | 1 |
| TBardini | t****5@g****m | 1 |
| Steve Breit | 6****t | 1 |
| Matthew Zagaja | m****a | 1 |
| and 8 more... | ||
Committer domains:
- northeastern.edu: 1
- jacobparis.com: 1
- v-lad.org: 1
- purdue.edu: 1
- thadk.net: 1
Issue and Pull Request metadata
Last synced: 11 days ago
Total issues: 252
Total pull requests: 477
Average time to close issues: 3 months
Average time to close pull requests: 13 days
Total issue authors: 24
Total pull request authors: 42
Average comments per issue: 0.86
Average comments per pull request: 0.58
Merged pull request: 326
Bot issues: 0
Bot pull requests: 0
Past year issues: 136
Past year pull requests: 237
Past year average time to close issues: 19 days
Past year average time to close pull requests: 3 days
Past year issue authors: 10
Past year pull request authors: 16
Past year average comments per issue: 0.49
Past year average comments per pull request: 0.35
Past year merged pull request: 155
Past year bot issues: 0
Past year bot pull requests: 0
Top Issue Authors
- ethanstrominger (55)
- AdamFinkle (53)
- thadk (35)
- jkwan2011 (24)
- alanisaac (15)
- plocket (12)
- baipai (9)
- stevebreit (8)
- debajyotid2 (8)
- pravindransolutions (5)
- eriksynn (4)
- interianow (4)
- derekvmcintire (3)
- mciethan (3)
- jkoren (3)
Top Pull Request Authors
- thadk (97)
- AdamFinkle (96)
- ethanstrominger (78)
- alanisaac (52)
- jkoren (18)
- eriksynn (14)
- thatoldplatitude (12)
- interianow (10)
- derekvmcintire (10)
- kfuquay (8)
- vladistan (8)
- stemgene (8)
- plocket (5)
- axiomizer (4)
- Tcoding12 (4)
Top Issue Labels
- rules-engine (62)
- user-experience (40)
- good first issue (20)
- heat-app-js (18)
- question (15)
- could have (9)
- must have (7)
- technical (7)
- breakout (6)
- documentation (6)
- enhancement (5)
- heat-app (4)
- sub-issue (4)
- build (3)
- security (3)
- close? (2)
- should have (2)
- on hold (1)
- bug (1)
Top Pull Request Labels
- heat-app-js (7)
- on hold (2)
- do not merge (2)
- rules-engine (1)
Score: 8.222553638396958