Data
Given the complexity and computational intensity of ResStock, the best pathway for professionals and researchers to use ResStock successfully is use pre-created results, rather than running ResStock themselves. This section provides information about accessing ResStock results and links to published datasets.
Published Datasets
These datasets explore the annual and timeseries energy consumption of the U.S. residential building stock at the end-use level. Access the webinar recording, webinar slides, and the technical documentation for each dataset as they are available:
- 2024.2 webinar recording, webinar slides, and the technical documentation
- 2024.1 technical documentation
- 2022.1 webinar recording, webinar slides, and the technical documentation
- 2021.1 webinar recording, and the technical documentation
ResStock dataset releases are summarized in the following table with links for accessing the aggregate results. Scroll to the right for information on all of the datasets.
| 2024.2 | 2024.2 | 2024.1 | 2022.1 | 2022.1 | 2022.1 | 2021.1 | 2021.1 | |
| Weather Year | AMY 2018 | TMY3 | TMY3 | AMY 2018 | AMY 2012 | TMY3 | AMY 2018 | TMY3 |
| OEDI Name | 2024/ resstock_amy2018_release_2 | 2024/ resstock_tmy3_release_2 | 2024/ resstock_dataset_2024.1/resstock_tmy3 | 2022/ resstock_amy2018_release_1 | 2022/ resstock_amy2012_release_1 | 2022/ resstock_tmy3_release_1 | 2021/ resstock_2018_release_1 | 2021/ resstock_tmy3_release_1 |
| Data Viewer Links | n/a | n/a | n/a | by state | by state | by state | by_state, by_puma_northeast, by_puma_midwest, by_puma_south, by_puma_west | by_state, by_puma_northeast, by_puma_midwest, by_puma_south, by_puma_west |
| Data Table with Characteristics | metadata | metadata | metadata | metadata | metadata | metadata | metadata | metadata |
| OpenEI Data Lake | data dictionary | data dictionary | data dictionary | data dictionary | data dictionary | data dictionary | data dictionary | data dictionary |
| Publication Date | March 2024 | March 2024 | February 2024 | September 2022 | September 2022 | October 2022 | October 2021 | October 2021 |
| Release # | 2024.2 | 2024.2 | 2024.1 | 2022.1 | 2022.1 | 2022.1 | 2021.1 | 2021.1 |
| Building Stock Represented | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 | Residential housing stock circa 2018 |
| Upgrade Measures | 15 | 15 | 260 | 10 | 10 | 10 | 0 | 0 |
| Samples Simulated | 550,000 | 550,000 | 2,200,000 | 550,000 | 550,000 | 550,000 | 550,000 | 550,000 |
| Timeseries or Annual Data | Timeseries and annual | Timeseries and annual | Annual | Timeseries and annual | Timeseries and annual | Timeseries and annual | Timeseries and annual | Timeseries and annual |
| Representative Number of Dwellings for Each Modeled Dwelling Unit | 252.3016 | 252.3016 | 63.0753 | 242.1310 | 242.1310 | 242.1310 | 242.1310 | 242.1310 |
| Energy output available | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| Carbon Emissions output available | Yes | Yes | Yes | Yes | Yes | Yes | No | No |
| Utility Bills output available | Yes | Yes | Yes | No | No | No | No | No |
| Indoor Air Temperature output available | Yes | Yes | No | Yes | Yes | No | No | No |
Data Access Platforms, Structure, and Content
ResStock data releases are collections of datasets include energy use across technology (e.g., air-conditioning, refrigerators, lighting, etc.) and fuel type that represents the United States housing stock. Data include either 550,000 or 2,200,000 models that if scaled up, cover all residential energy use in the U.S. housing sector. Data releases also include “what-if” scenarios of technology adoption. The output of each energy model is one year of energy consumption either summed for the whole year or at 15-minute intervals. Dealing with the raw output data from a national ResStock dataset requires skills for dealing with large files and large number of files, that might make interpretation inaccessible for many users. To support many use cases, aggregate load profiles (i.e. timeseries energy use added together from multiple models) for the following geographic resolutions are published for ResStock releases:
- 17 ASHRAE/International Energy Conservation Code (IECC) climate zones
- 8 U.S. Department of Energy Building America Climate zones
- 2,300 + U.S. Census Public Microdata Areas
- 3,100+ U.S. Counties
- 48 States (continental U.S. only)
Data Access Platforms
The following table summarizes the various ways to access and use ResStock data. Scroll right to see all of the options.
| Metdata | Individual Load Profiles | Aggregate Load Profiles | Data Viewer | Dashboards | Full Database | |
| Data Format | .csv and parquet files | .csv and parquet files | .csv and parquet files | Interactive dashboard with .csv exports | Interactive dashboards with image, .xlsx, .csv, .pdf , .pptx, and tableau workbook exports | Amazon S3 bucket |
| Time Scale | Annual | 15-minute intervals | 15-minute intervals | Customizable | Annual | Annual or 15-minute intervals |
| Grouped By | Individual Building ID | Individual Building ID | ASHRAE IECC Climate Zone 2004, Building America Climate Zone, ISO RTO region, State | Customizable | Customizable | Customizable |
| Fields By | Building Input Characteristics | - | Building type | - | Building Input Characteristics | Building Input Characteristics |
| Fields By | Energy Consumption | Energy Consumption | Energy Consumption | Energy Consumption | Energy Consumption | Energy Consumption |
| Fields By | Energy Savings | Energy Savings | Energy Savings | Energy Savings | Energy Savings | Energy Savings |
| Fields By | Emissions | Emissions | Emissions | Emissions | Emissions | Emissions |
| Fields By | Calculated Fields | Calculated Fields | Calculated Fields | - | Calculated Fields | Calculated Fields |
| Accessed Via | Open Energy Data Initiative (OEDI) | Open Energy Data Initiative (OEDI) | Open Energy Data Initiative (OEDI) | ResStock.nrel.gov | public.tableau.com/app/profiles/nrel.buildingstock/vizzes | Scripting Languages |
The dataset has been formatted in multiple ways to meet the needs of different users and use cases.
- Metadata: File of individual modeled dwelling unit housing and demographic characteristics together with annual energy and emission results. This is often called the “metadata” file.
- Load Profiles: Timeseries energy and emissions results (individual building or pre-aggregated by geography) in downloadable spreadsheets.
- Data Viewer: A web-based interactive data viewer with customizable time scales and aggregations.
- Dashboards: In-depth web-based interactive data viewer with customizable aggregations for exploring annual results and sometimes supplemental metrics (e.g., upgrade costs).
- Full Database: Full raw model results. Big data skills required.
Aggregate ResStock datasets can be accessed via the Open Energy Initiative (OpenEI) Data Lake, the ResStock Data Viewer, and the ResStock dashboards. Each data release can have multiple datasets for different weather years. Within the weather years, all dataset releases include 2018 and a “TMY3” weather year – which is a “typical meteorological year”. These weather files attempt to avoid capturing any year’s unusual weather pattern by compiling the most representative historic weather for a location. TMY3 timeseries energy data should not be used for larger geographies, i.e., one or more counties. In compiling the typical / representative weather TMY3 weather files pull historic weather from different years (e.g., January 2005, February 2002, March 1995, etc.). A key issue is that adjacent counties might pull their historic weather from different months, so regional weather patterns will not be aligned in aggregate timeseries results. Aggregate annual energy results can be used together since it will smooth out weather differences.
Please note, that there are separate public datasets available for residential and commercial building stocks. If you are interested in commercial buildings, please check out our sibling tool ComStock.
OEDI Data Lake
OpenEI is an energy information portal and is developed and maintained by the National Renewable Energy Laboratory (NREL) with funding and support from the U.S. Department of Energy and a network of international partners & sponsors. The OpenEI data lake contains comprehensive aggregate data for ResStock releases. This includes metadata and timeseries energy consumption results (baseline and upgrades, if applicable), individual building energy models, weather files, geographic information, and data dictionaries.
The ResStock release directory structure of the data lake is summarized in the table below.
ResStock Data Viewer
The ResStock Data Viewer exists to quickly filter, slice, combine, visualize, and download results in custom ways. This platform is available at resstock.nrel.gov/datasets, and the Data Viewer link for each dataset is listed when available. Multiple geographic views of the datasets on the data viewer have been created: by state, by Census region, and by PUMA.
ResStock Dashboards
ResStock dashboards exist to give a more comprehensive overview of results in different ways, from housing characteristics, specific housing upgrade scenarios, or even focusing in on a specific topic like heat pumps. This platform is available at public.tableau.com/app/profile/nrel.buildingstock/vizzes. Multiple geographic views of the datasets on the dashboards have been created: by state, by Building America Climate Zone, and by AHSRAE / IECC Climate Zone.
OEDI Directory Structure and Contents
| Name | Contents |
| building_energy_models | Building energy models, in OpenStudio format, that were run to create the dataset. |
| geographic_information | Information on various geographies used in the dataset provided for convenience. Includes map files showing the shapes of the geographies (states, PUMAs) used for partitioning and lookup table mapping between census tracts and various other geographies. |
| metadata | Building characteristics (age, area, HVAC system type, etc.) for each of the building energy models run to create the timeseries and annual data. Descriptions of the characteristics are included in the data_dictionary.tsv and enumeration_dictionary.tsv. |
| metadata_and_annual_results | Building characteristics (age, area, HVAC system type, etc.) for each of the building energy models run and annual results for the data. |
| timeseries_aggregates | Aggregate end-use load profiles by building type and geography that can be opened and analyzed in Excel, Python, or other common data analysis tools. Aggregated at different geographies. |
| timeseries_individual_buildings | The raw timeseries data for each building energy model. This is a large number of individual files! |
| weather | Key weather data used as an input to run the building energy models to create the dataset. |
| data_dictionary.tsv | Describes the column names found in the metadata and timeseries data files. |
| enumeration_dictionary.tsv | Expands the definitions of the enumerations used in the metadata files. |
| upgrades_lookup.json | Measure package number matched with measure package name for quick reference. |
| Measure Package Index.csv | Description of measure package name with brief details on what the measure package includes. |
Dataset Naming Convention
ResStock releases on OEDI and the Data Viewer use a variation of the following naming convention.
Example 1: <dataset type>_dataset_<year of publication>.<release number>_<weather data>
Example 1: resstock_dataset_2024.1_resstock_tmy3
Example 2: <dataset type>_<weather data>_release_<release number>
Example 2: resstock_amy2018_release_2
- dataset type
- resstock = residential building stock
- comstock = commercial building stock
- weather data
- amy2018 = actual meteorological year 2018 (2018 weather data from NOAA ISD, NSRDB, and MesoWest)
- tmy3 = typical meteorological year from 1991-2005 (see this publication for details )
- year of publication
- 2024 = dataset was published in 2024
- 2022 = dataset was published in 2022
- etc.
- release
- release_1 = first release of the dataset during the year of publication
- release_2 = second release of the dataset during the year of publication
- etc.
Field Naming Convention
Below is a description of the field naming convention. The general topics are below, but this may not be a comprehensive list depending on the dataset, and not all fields may be represented depending on the file type.
At the highest level there is – “in.” for inputs, “out.” For outputs, and then a handful of other columns that provide simulation information.
For the “out.” prefix there is a second level that includes – fuel type, emissions, model parameter and statistic fields, and site energy. The “in.” prefix does not have a second level.
The third level of “out.” includes the end uses.
Finally, units are denoted by a “.” with the unit following.
| First Level | ||
| Prefix or name | Description | Example |
| bldg_id | unique id of the building model | 673 |
| upgrade | unique id number of the upgrade | 1.01 |
| Upgrade_name | name of the upgrade | ENERGY STAR heat pump with electric back up |
| weight | how many dwelling units this building model represents in real life | 63.075 |
| applicability | indication if the upgrade was applied to that building model | TRUE |
| in. | inputs of building characteristics and geospatial codes | in.sqft |
| out. | modeled outputs | out.electricity.plug_loads. energy_consumption.kwh |
| models_used | Number of building models used for the simulation | 477 |
| units_represented | number of real life dwelling units represented by the number of models used | 120347.88 |
| Second Level | ||
| Prefix or name | Description | Example |
| out.params | value of characteristics of the upgraded dwelling that can be potentially used as cost multiplier | out.params.size_water_heater_gal |
| out.[fuel type] | fuel type - electricity, natural gas, propane, etc. | out.electricity.net.energy_consumption.kwh |
| out.site_energy | total of all end uses, site energy | out.site_energy.total.energy_consumption.kwh |
| out.load | energy delivered by the technology | out.load.hot_water.energy_delivered.kbtu |
| out.emissions | total emissions | out.emissions.electricity.lrmer_low_re_cost_2030_boxavg_co2e_kg |
| out.emissions_reduction | reduction of total emissions | out.emissions_reduction.natural_gas. lrmer_high_re_cost_2030_boxavg.co2e_kg |
| out.energy_burden | energy burden of the dwelling unit | out.energy_burden.percentage |
| out.energy_burden_reduction | reduction of energy burden of the dwelling unit | out.energy_burden.percentage_points |
| out.bills | energy bill of the dwelling unit and currency | out.bills.fuel_oil.usd |
| out.unmet_hours | number of hours the HVAC system could not meet load | out.unmet_hours.cooling.hour |
| upgrade.hvac_[system efficiency] | HVAC system efficiency | upgrade.hvac_cooling_efficiency |
| upgrade.[hvac system has offset] | if the HVAC system has an offset and if true what is the offset | OF |
| Additional levels | ||
| Prefix or name | Description | Example |
| out.[fuel type].[end use] | end uses_heating, cooling, water heating, etc. | out.electricity.range_oven.energy_consumption.kWh |
| out.emissions.[fuel type].[emissions scenario] | emissions by fuel type and emissions scenario | out.emissions.propane.lrmer_low_re_cost_2030_boxavg.co2e_kg |
| out.bills.[fuel type].usd.savings | energy bill savings based on fuel type | out.bills.electricity.usd.savings |
| Units | ||
| …foo | ”.” denotes the start of the unit name | .co2e_kg |