diff --git a/CHANGELOG.md b/CHANGELOG.md index 8f814ef707..97f88725f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,9 @@ Features - Add flexibility to specify location of the radiant barrier ([#1188](https://github.com/NREL/resstock/pull/1188)) - Add ability to describe detailed performance data for variable-speed air-source HVAC systems ([#1188](https://github.com/NREL/resstock/pull/1188), [#1200](https://github.com/NREL/resstock/pull/1200)) - Include additional 2022 Cambium 25-year LRMER emissions data ([#1194](https://github.com/NREL/resstock/pull/1194)) +<<<<<<< HEAD +- Add Census dwelling unit count by state table in resstock/resources/ folder ([#1193](https://github.com/NREL/resstock/pull/1193)) +======= - Add optional switch to BuildExistingModel (defaulted to false) for modeling whole SFA/MF buildings ([#1200](https://github.com/NREL/resstock/pull/1200)) - Update hot water usage multipliers based on field data rather than engineering judgement ([#1210](https://github.com/NREL/resstock/pull/1210)) - Allow definition of multiple unavailable periods (i.e., vacancy, power outage) ([#1209](https://github.com/NREL/resstock/pull/1209)) @@ -12,6 +15,7 @@ Features - Refrigerator energy use is now affected by its ambient temperature using hourly constant and temperature coefficients from ANSI/RESNET/ICC 301-2022 Addendum C ([#1209](https://github.com/NREL/resstock/pull/1209)) - Add Metropolitan and Micropolitan Statistical Area tsv, County Metro Status tsv, and State Metro Median Income tsv ([#1212](https://github.com/NREL/resstock/pull/1212)) +>>>>>>> origin/develop Fixes - Remove old HPWH options from options_lookup ([#1190](https://github.com/NREL/resstock/pull/1190)) diff --git a/docs/read_the_docs/source/workflow_inputs/CensusTableB25001-dwelling_unit_counts.csv b/docs/read_the_docs/source/workflow_inputs/CensusTableB25001-dwelling_unit_counts.csv new file mode 100644 index 0000000000..2fbf4df4e4 --- /dev/null +++ b/docs/read_the_docs/source/workflow_inputs/CensusTableB25001-dwelling_unit_counts.csv @@ -0,0 +1,57 @@ +Total,2018 ACS 5-yrs,2019 ACS 5-yrs,2020 ACS 5-yrs,2021 ACS 5-yrs,2022 ACS 5-yrs +Contiguous US (DC incl.),135529853,136569411,137567810,138765649,140056552 +Contiguous US (DC incl.) + AK,135845239,136886312,137886180,139090083,140382740 +50 States (DC incl.),136384292,137428986,138432751,139647020,140943613 +50 States (DC incl.) + Puerto Rico,137947451,138989822,139992727,141200811,142506742 +Alabama,2244462,2255026,2270398,2278526,2296920 +Alaska,315386,316901,318370,324434,326188 +Arizona,2970935,3003286,3040595,3056890,3097768 +Arkansas,1362040,1370281,1379778,1361880,1371709 +California,14084824,14175976,14210945,14328539,14424442 +Colorado,2352202,2386475,2361372,2454873,2500095 +Connecticut,1512305,1516629,1521199,1527039,1531332 +Delaware,428251,433195,438438,445104,451556 +District of Columbia,311545,315176,319192,344306,350372 +Florida,9348689,9448159,9562324,9764897,9915957 +Georgia,4241003,4283477,4329675,4375039,4426780 +Hawaii,539053,542674,546571,556937,560873 +Idaho,711731,723594,737411,742145,758877 +Illinois,5347268,5360315,5373385,5412995,5427357 +Indiana,2870670,2886548,2903720,2911562,2931710 +Iowa,1386722,1397087,1407819,1407100,1417064 +Kansas,1266378,1273297,1280376,1272290,1278548 +Kentucky,1974406,1983949,1994554,1988420,1999202 +Louisiana,2045554,2059918,2074664,2066323,2080371 +Maine,739077,742788,746793,737782,741803 +Maryland,2437740,2448422,2459650,2516341,2531075 +Massachusetts,2882739,2897259,2913009,2979634,2999314 +Michigan,4580939,4596198,4611913,4566504,4580447 +Minnesota,2420473,2438203,2458030,2470483,2493956 +Mississippi,1316108,1322808,1330867,1317375,1324992 +Missouri,2775635,2790397,2804664,2782081,2795030 +Montana,505685,510180,514956,512553,517430 +Nebraska,830749,837476,844248,840802,848023 +Nevada,1235096,1250893,1268533,1269846,1288357 +New Hampshire,630955,634726,638611,636480,640335 +New Jersey,3605401,3616614,3628732,3738342,3756340 +New Mexico,932818,937920,943568,937397,943149 +New York,8287087,8322722,8362971,8449178,8494452 +North Carolina,4573066,4627089,4687122,4673933,4739881 +North Dakota,367684,373063,376597,370111,372376 +Ohio,5188270,5202304,5217090,5232733,5251209 +Oklahoma,1723230,1731632,1740972,1741721,1751802 +Oregon,1750539,1768901,1788855,1798864,1818599 +Pennsylvania,5673599,5693314,5713345,5728788,5753908 +Rhode Island,467412,468335,469289,481168,483053 +South Carolina,2256951,2286826,2319112,2325248,2362253 +South Dakota,387637,392215,396817,391857,396623 +Tennessee,2930530,2963486,2996127,3011124,3050850 +Texas,10769900,10937026,11112975,11433880,11654971 +Utah,1066131,1087112,1110369,1133558,1162654 +Vermont,333013,334999,337214,333519,335138 +Virginia,3491091,3514032,3537788,3596100,3625285 +Washington,3064381,3106528,3150194,3170695,3216243 +West Virginia,890715,892182,893615,859437,859142 +Wisconsin,2681232,2694527,2709444,2718369,2734511 +Wyoming,274985,276846,278495,271818,273291 +Puerto Rico,1563159,1560836,1559976,1553791,1563129 \ No newline at end of file diff --git a/docs/read_the_docs/source/workflow_inputs/characteristics.rst b/docs/read_the_docs/source/workflow_inputs/characteristics.rst index adf58a2c40..ff31ee03a4 100644 --- a/docs/read_the_docs/source/workflow_inputs/characteristics.rst +++ b/docs/read_the_docs/source/workflow_inputs/characteristics.rst @@ -1,6 +1,6 @@ .. _housing_characteristics: -Housing Characteristics +Housing Characteristics Distributions ======================= Each parameter sampled by the national project is listed alphabetically as its own subsection below. diff --git a/docs/read_the_docs/source/workflow_inputs/dwelling_unit_counts.rst b/docs/read_the_docs/source/workflow_inputs/dwelling_unit_counts.rst new file mode 100644 index 0000000000..0110604be0 --- /dev/null +++ b/docs/read_the_docs/source/workflow_inputs/dwelling_unit_counts.rst @@ -0,0 +1,24 @@ +.. _dwelling-unit-counts: + +Dwelling unit counts of the U.S. residential building stock +=========================================================== +ResStock uses data from the U.S. Census American Community Survery (ACS) to specify the number of dwelling units in the U.S. +These estimates include both occupied and vacant dwellings. +The data comes from the ACS `Table B25001 `_. + +These data can be used in project files +(like the `national_baseline.yml `_) +to specify the ``n_buildings_represented`` variable. + +.. note:: + + If you want to use state level unit counts, the proper downselect logic must be used in the ``sampler`` block of the project file. + +.. literalinclude:: .gemrc + +.. _dwelling_unit_count_table: + +.. csv-table:: Dwelling unit counts from ACS Table B25001. + :file: CensusTableB25001-dwelling_unit_counts.csv + :widths: 30, 15, 15, 15, 15, 15 + :header-rows: 1 diff --git a/docs/read_the_docs/source/workflow_inputs/index.rst b/docs/read_the_docs/source/workflow_inputs/index.rst index 37bb6fcec7..612032b680 100644 --- a/docs/read_the_docs/source/workflow_inputs/index.rst +++ b/docs/read_the_docs/source/workflow_inputs/index.rst @@ -9,6 +9,5 @@ Contents in :ref:`housing_characteristics` are populated based on the national p .. toctree:: :maxdepth: 2 - characteristics - modifying_probability_distributions - writing_housing_characteristics + dwelling_unit_counts + characteristics \ No newline at end of file diff --git a/docs/read_the_docs/source/workflow_inputs/modifying_probability_distributions.rst b/docs/read_the_docs/source/workflow_inputs/modifying_probability_distributions.rst deleted file mode 100644 index c98a695aed..0000000000 --- a/docs/read_the_docs/source/workflow_inputs/modifying_probability_distributions.rst +++ /dev/null @@ -1,66 +0,0 @@ -Modifying Probability Distributions -=================================== - -This section provides a description of the housing characteristics and their dependencies and options. - -A particular building within the building stock has a set of characteristics (e.g., level of wall insulation, type of lighting, vintage, and a variety of different schedules). Each housing characteristic corresponds to a tab-separated value (tsv) file with the extension `.tsv`. These housing characteristics files are found in the ``/housing_characteristics`` directory. A housing characteristic defines the probability mass function (PMF) of that characteristic in the building stock. - -:math:`Pr(X=A_i) = P(A_i) > 0 \hspace{5mm} and \hspace{5mm} \sum_{A_i\in S_A} P(A_i) = 1 \hspace{5mm} for \hspace{5mm} i=1:n` - -When sampling a discrete random variable :math:`X` to create a representative building, :math:`X` takes a particular **Option** :math:`A_i`. All possible options are collected in the set :math:`S_A=\{A_0,A_1,...,A_n\}` and is size :math:`n`. Since these are probabilities, the entries :math:`P(A_i)` must be greater than 0 and the probability of all possible options must sum to 1. - -For example, a set of options for a building's vintage (when the building was built) may be the following: - -:math:`S_A = {<1950, 1950s, 1960s, 1970s, 1980s, 1990s, 2000s}.` - -Then the probability mass function may look like the following: - -+------------------+-------+-------+-------+-------+-------+-------+-------+ -| :math:`A_i` | <1950 | 1950s | 1960s | 1970s | 1980s | 1990s | 2000s | -+==================+=======+=======+=======+=======+=======+=======+=======+ -| :math:`P(X=A_i)` | 0.020 | 0.060 | 0.090 | 0.230 | 0.370 | 0.130 | 0.090 | -+------------------+-------+-------+-------+-------+-------+-------+-------+ - -Where the probability of a building having a given vintage in this example is - -- 2% built before 1950, -- 6% in the 1950s, -- 9% in the 1960s, -- 23% in the 1970s, -- 37% in the 1980s, -- 13% in the 1900s, and -- 9% in the 2000s. - -However, housing characteristics can have a **Dependency**, :math:`B_i`, to another housing characteristic. All possible values of the dependency are collected in the set :math:`S_B = {B_0,B_1,...B_m}` which is size :math:`m`. If the **Option** of interest :math:`A_j` and the **Dependency** :math:`B_i` is known to have occurred when sampling :math:`X` in the creation of a representative building, then conditional probability of :math:`A_j` given :math:`B_i` is usually written :math:`P(A_j|B_i)=P_{B_i}(A_j)`. - -Using the example from before, the PMF of the vintage depends on location of the particular building stock (which is represented by EPW weather files). In this example the vintage housing characteristic is examined. The first three lines in the ``/housing_characteristics/Vintage.tsv`` are shown in the table below. - -+-----------------------+-------------------------------------------------+-------+-------+-------+-------+-------+-------+-------+ -| | Location EPW (:math:`S_B`) | <1950 | 1950s | 1960s | 1970s | 1980s | 1990s | 2000s | -+-----------------------+-------------------------------------------------+-------+-------+-------+-------+-------+-------+-------+ -| :math:`P(B_0|A_j)` | USA_FL_Key.West.Intl.AP.722010_TMY3.epw | 0.02 | 0.06 | 0.09 | 0.23 | 0.37 | 0.13 | 0.09 | -+-----------------------+-------------------------------------------------+-------+-------+-------+-------+-------+-------+-------+ -| :math:`P(B_1|A_j)` | USA_FL_Miami.Intl.AP.722020_TMY3.epw | 0.05 | 0.13 | 0.13 | 0.18 | 0.17 | 0.18 | 0.16 | -+-----------------------+-------------------------------------------------+-------+-------+-------+-------+-------+-------+-------+ - -The vintage is dependent on the EPW location. The vintage discrete PMF that uses the Key West International Airport weather file, :math:`B_0`, is defined by the following distribution: - -- 2% built before 1950, -- 6% in the 1950s, -- 9% in the 1960s, -- 23% in the 1970s, -- 37% in the 1980s, -- 13% in the 1900s, and -- 9% in the 2000s. - -While the vintage PMF that uses the Miami International Airport weather file, :math:`B_1` is defined by the following distribution: - -- 5% built before 1950, -- 13% in the 1950s, -- 9% in the 1960s, -- 13% in the 1970s, -- 18% in the 1980s, -- 17% in the 1900s, and -- 18% in the 2000s. - -The **Options** can correspond to a Measure in OpenStudio or can be used as a **Dependency** for other housing characteristics. For the list of available options for a given housing characteristic, see the ``resources/options_lookup.tsv`` file. In this file the "Parameter Name" corresponds to the housing characteristic, the "Option Name" corresponds to an available option for the housing characteristic, the "Measure Dir" corresponds to the OpenStudio Measure being used, and the following columns correspond to different arguments needed by the OpenStudio Measure. Each option used in the housing characteristics tsv files must be in this ``resources/options_lookup.tsv``. These options can be modified by the user to model their particular building stock. diff --git a/docs/read_the_docs/source/workflow_inputs/writing_housing_characteristics.rst b/docs/read_the_docs/source/workflow_inputs/writing_housing_characteristics.rst deleted file mode 100644 index 8d5927dbca..0000000000 --- a/docs/read_the_docs/source/workflow_inputs/writing_housing_characteristics.rst +++ /dev/null @@ -1,10 +0,0 @@ -Writing Housing Characteristics -=============================== - -This section provides a description of the standard format for the housing characteristics. In order to stop recommitting entire files and to keep differences easy to read during the review process, a standard format for writing housing characteristics has been created. All housing characteristics shall follow these format guidelines: - -Guidelines ----------- - -1. All lines have the line ending characters '\\r\\n' (i.e., "crlf" or "carriage return, line feed"). -2. Comment lines in the housing characteristics file, indicated by the "#" symbol, can be added. \ No newline at end of file