What’s new in buildstockbatch 0.20?
About this Document
This document describes changes between buildstockbatch version 0.19 and buildstockbatch version 0.20
This guide introduces what’s new in buildstockbatch version 0.20 and also documents changes which affect users migrating their analyses from 0.19.
Please carefully review the section on schema changes as the minimum schema version has been updated to the new version, 0.3, and there are non-backwards-compatible changes in the schema update.
Schema Version Update
The input schema has been updated to version 0.3. Project configuration files
will need to be upgraded to use the new format. The
schema_version key now
needs to be a string, so put some quotes around the version number.
There are no more
keys. This information is defined in the new
The sampler now has its own section in the configuration file. In it, you
specify which kind of sampler to use and the arguments to pass to it. These
arguments used to be scattered all around the project configuration file and it
caused some confusion when arguments would only apply to some kinds of samplers.
They are now consolidated under the
sampler key and each sampler type
specifies its own options. Complete documentation of the available samplers and
their arguments is at Samplers.
Here are a few examples for common scenarios:
Residential Quota Sampling
schema_version: 0.2 stock_type: residential baseline: sampling_algorithm: quota n_datapoints: 350000
schema_version: '0.3' sampler: type: residential_quota args: n_datapoints: 350000
Residential Quota with Downselecting
Downselecting is no longer a separate config item, it is implemented in a different sampler type. See Residential Quota Downselect Sampler.
schema_version: 0.2 stock_type: residential baseline: sampling_algorithm: quota n_datapoints: 350000 downselect: logic: - Geometry Building Type RECS|Single-Family Detached - Vacancy Status|Occupied resample: false
schema_version: '0.3' sampler: type: residential_quota_downselect args: n_datapoints: 350000 logic: - Geometry Building Type RECS|Single-Family Detached - Vacancy Status|Occupied resample: false
baseline.precomputed_sample key has been removed and the precomputed
sampling is its own sampler type. Downselecting is no longer permitted with a
precomputed sample. If you want to downselect, please modify your buildstock.csv
file to only include the buildings you want in your sample. See
schema_version: 0.2 stock_type: residential baseline: precomputed_sample: path/to/buildstock.csv n_datapoints: 350000
schema_version: '0.3' sampler: type: precomputed args: sample_file: path/to/buildstock.csv # n_datapoints determined from csv file
Workflow Generator Specification
The workflow generator has changed as well. Many inputs to the workflow were
previously at the top level in the project configuration file. This was again
confusing because different config entries only applied to certain workflow
generators. In previous versions, the appropriate workflow generator was
inferred based on the
stock_type key. Now it is explicitly defined and the
arguments to be passed to it are defined under the
See Workflow Generators.
schema_version: 0.2 stock_type: residential timeseries_csv_export: reporting_frequency: Hourly include_enduse_subcategories: true
schema_version: '0.3' workflow_generator: type: residential_hpxml args: timeseries_csv_export: reporting_frequency: Hourly include_enduse_subcategories: true
Reporting Measures in Workflows
reporting_measures configuration key that now resides under
allows measure arguments to be passed to reporting measures.
schema_version: 0.2 stock_type: residential reporting_measures: - ReportingMeasure1 - ReportingMeasure2
schema_version: '0.3' workflow_generator: type: residential_default args: reporting_measures: - measure_dir_name: ReportingMeasure1 arguments: arg1: value - measure_dir_name: ReportingMeasure2
Commercial Workflow Generator Hard-Coded Measures
The commercial workflow generator has changed to remove most of the hard-coded reporting measures, allowing them to be added to the config file as-needed. This should avoid the need to create custom BuildStockBatch environments for each project that needs to add/remove/modify reporting measures.
Old hard-coded reporting measures:
OpenStudio Results (measure_dir_name:
la_100_qaqc(if include_qaqc = true in config)
simulation_settings_check(if include_qaqc = true in config)
New hard-coded reporting measures:
SimulationOutputReport(reports annual totals in results.csv)
TimeseriesCSVExport(generates timeseries results at Timestep frequency)
Two other hard-coded model measures were removed from the workflow. These will be added to the workflow via the options-lookup.tsv in ComStock instead.
Removed hard-coded model measures:
AWS EMR Configuration Name Changes
In an effort to use more appropriate language, in the AWS Configuration, we
renamed the following keys under
Keep Individual Timeseries
For some applications it is helpful to keep the timeseries parquet files for each simulation. Normally, they are aggregated into fewer, larger files. There was a key introduced in v0.19.1 that enabled this. We moved it to a new home place in the config file.
schema_version: 0.2 eagle: postprocessing: keep_intermediate_files: true # default false if omitted
schema_version: '0.3' postprocessing: keep_individual_timeseries: true # default false if omitted