# ECM Definition Reference¶

In some parts of the definition of an ECM, specific values must be entered for the ECM to be valid and successfully included in an analysis. In particular, the installed cost and energy efficiency units used must match exactly with the expected units for a given building sector, end use, and technology type. These units are defined by the EIA Annual Energy Outlook data used to define the baseline technology cost, efficiency, and lifetime.

## Applicable baseline market options¶

For each of the keys in the applicable baseline market definition, only specific entries are expected and allowable. This section outlines those acceptable entries for each of the keys.

For some keys, there are shorthand summary values that can be used when all or a large group of more specific values for that key apply. For example, if all of the climate zones should be included in the applicable baseline market, the value “all” can be specified instead of typing out each climate zone name in a list. These shorthand values are provided after the semi-colon in the lists below. Additional notes might also be provided to further clarify the different summary values available for a given key. More information regarding the use of these shorthand values is in the Baseline market shorthand values section.

, , , , ; all

### Building type¶

Residential: single family home, multi family home, mobile home; all residential

Commercial: assembly, education, food sales, food service, health care, lodging, large office, small office, mercantile/service, warehouse, other; all commercial

Note

“all” can be used instead of specifying both “all residential” and “all commercial” if all residential and commercial building types apply.

### Structure type¶

new, existing; all

### Fuel type¶

Residential: electricity, natural gas, distillate, other fuel; all

Commercial: electricity, natural gas, distillate; all

### End use¶

The end use names appear verbatim in the first column of the tables for residential and commercial buildings.

Note

While “all” is available for specifying all of the end uses in residential and/or commercial buildings (depending on the building types selected), its use should be limited to ECMs where a single technology can credibly affect all energy use in the building. Using the “all” option for end uses also significantly increases computational expense, and that expense will scale exponentially if uncertainty is present on any of the ECMs in the analysis.

Residential

End Use Fuel Type
electricity natural gas distillate other fuel
heating X X X X
secondary heating X X X X
cooling X X
water heating X X X X
cooking X X   X
drying X X   X
lighting X
refrigeration X
ceiling fan * X
fans and pumps * X
computers * X
TVs * X
other ** X X X X
all X X X X

* These end uses and all associated technologies may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for associated technologies.

** For the “other” end use, all associated technologies aside from “dishwasher,” “clothes washing,” and “freezers” may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for associated technologies.

Commercial

End Use Fuel Type
electricity natural gas distillate
heating X X X
cooling X X
ventilation X
water heating X X X
lighting X
refrigeration X
cooking X X
PCs * X
non-PC office equipment * X
MELs * X
all X X X

* These end uses and all associated technologies may currently only be specified for the add-on measure type due to the lack of available baseline cost, performance, and lifetime data for the associated technologies.

### Technology¶

Technology names appear verbatim. For residential building types, the lighting technology names are in the body of the table, categorized by illumination technology (e.g., incandescent, fluorescent) and application or fixture type. For commercial building types, the lighting technology names are categorized generally by bulb type or application. In both cases, these categories are provided for convenience and are not used anywhere in an ECM definition.

Tip

If the technology name for a given end use and fuel type is indicated as null, the ECM definition should have the unquoted text “null” written into the technology field.

Note

“all” is available as an option to specify all of the technology names that apply to all of the building types, fuel types, and end uses specified for the applicable baseline market. In addition, “all” can be made specific to a particular end use by specifying “all” followed by the end use name – “all heating” or “all water heating,” for example. This shorthand will capture all of the technologies in the named end use that apply to the building types and fuel types included in the applicable baseline market. For example, if the building type is “single family homes” and the fuel type is specified as [“electricity”, “natural gas”] then “all heating” will include all of the heating technologies for residential buildings that use electricity or natural gas.

Residential – Supply

• heating

• electricity: , , resistance heat
• natural gas: , boiler (NG), furnace (NG)
• distillate: boiler (distillate), furnace (distillate)
• other fuel: resistance, furnace (kerosene), stove (wood), furnace (LPG)
• secondary heating

• electricity: secondary heater
• natural gas: secondary heater
• distillate: secondary heater
• other fuel: secondary heater (wood), secondary heater (coal), secondary heater (kerosene), secondary heater (LPG)
• cooling

• electricity: room AC, , , central AC
• natural gas:
• water heating

• electricity: electric WH, solar WH
• natural gas: null
• distillate: null
• other fuel: null
• cooking

• all fuel types: null
• drying

• all fuel types: null
• lighting

Fixture Type Bulb Type
incandescent/halogen fluorescent LED
general service general service (incandescent) general service (CFL) general service (LED)
reflector reflector (incandescent)
reflector (halogen)
reflector (CFL) reflector (LED)
linear fixture   linear fluorescent (T-8)
linear fluorescent (T-12)
linear fluorescent (LED)
exterior external (incandescent)
external (high pressure sodium)
external (CFL) external (LED)
• refrigeration: null

• ceiling fan: null

• fans and pumps: null

• computers: desktop PC, laptop PC, network equipment, monitors

• TVs: home theater and audio, set top box, video game consoles, DVD, TV

• other

• electricity: dishwasher, clothes washing, freezers, rechargeables, coffee maker, dehumidifier, electric other, microwave, pool heaters and pumps, security system, portable electric spas, wine coolers
• natural gas: other appliances
• distillate: other appliances
• other fuel: other appliances

Residential – Demand

roof, wall, infiltration, ground, windows solar, windows conduction, equipment gain, people gain

Commercial – Supply

• heating

• electricity: , , ,
• natural gas: , , gas_boiler, gas_furnace
• distillate: oil_boiler, oil_furnace
• cooling

• electricity: rooftop_AC, scroll_chiller, res_type_central_AC, reciprocating_chiller, , centrifugal_chiller, , wall-window_room_AC, screw_chiller
• natural gas: , gas_chiller, ,
• ventilation: ,

• water heating

• electricity: Solar water heater, HP water heater, elec_booster_water_heater, elec_water_heater
• natural gas: gas_water_heater, gas_instantaneous_WH, gas_booster_WH
• distillate: oil_water_heater
• lighting

• general service: 100W A19 Incandescent, 100W Equivalent A19 Halogen, 100W Equivalent CFL Bare Spiral, 100W Equivalent LED A Lamp,
• PAR-38: Halogen Infrared Reflector (HIR) PAR38, Halogen PAR38, LED PAR38
• linear fluorescent: T5 F28, T8 F28, T8 F32, T8 F59, T8 F96
• low/high bay: T5 4xF54 HO High Bay, Mercury Vapor, Metal Halide, Sodium Vapor
• other: LED Integrated Luminaire
• refrigeration: Commercial Beverage Merchandisers, Commercial Compressor Rack Systems, Commercial Condensers, Commercial Ice Machines, Commercial Reach-In Freezers, Commercial Reach-In Refrigerators, Commercial Refrigerated Vending Machines, Commercial Supermarket Display Cases, Commercial Walk-In Freezers, Commercial Walk-In Refrigerators

• cooking

• electricity: Range, Electric, 4 burner, oven, 11-inch gr;
• natural gas: Range, Gas, 4 burner, oven, 11-inch griddle;
• PCs

• non-PC office equipment

• MELs: elevators, escalators, coffee brewers, kitchen ventilation, laundry, lab fridges and freezers, fume hoods, medical imaging, large video boards, shredders, private branch exchanges, voice-over-IP telecom, IT equipment, office UPS, data center UPS, security systems, distribution transformers, non-road electric vehicles

Commercial – Demand

roof, wall, ground, floor, infiltration, ventilation, windows conduction, windows solar, lighting gain, equipment gain, people gain, other heat gain

## Energy efficiency units¶

Residential – Equipment (Supply)

• Heating

• Boilers and furnaces (AFUE)
• All other equipment types (COP)
• Secondary heating

• Electricity (COP)
• All other fuel types (AFUE)
• Cooling (COP)

• Water heating (EF)

• Refrigeration (kWh/yr)

• Cooking

• Electricity (kWh/yr)
• Natural gas (TEff)
• LPG (TEff)
• Drying (EF)

• Lighting (lm/W)

• Other

• Clothes washing (kWh/cycle)
• Dishwasher (EF)
• Freezers (kWh/yr)
• All other equipment types (relative savings (constant) with add-on measure type designation)

Commercial – Equipment (Supply)

• Heating (BTU out/BTU in)
• Cooling (BTU out/BTU in)
• Water heating (BTU out/BTU in)
• Ventilation (cfm-hr/BTU in)
• Cooking (BTU out/BTU in)
• Lighting (lm/W)
• Refrigeration (BTU out/BTU in)

Residential and Commercial – Sensors and Controls (Supply)

• All sensors and controls ECMs (relative savings (constant) or relative savings (dynamic))

Residential and Commercial – Envelope Components (Demand)

• Windows conduction (R value)
• Windows solar (SHGC)
• Wall, roof, and ground (R value)
• Infiltration
• Residential (ACH)
• Commercial (CFM/ft^2 @ 0.3 in. w.c.)

## Installed cost units¶

Residential – Equipment (Supply)

• All equipment except sensors and controls ($/unit) Commercial – Equipment (Supply) • Ventilation ($/1000 CFM)
• Lighting ($/1000 lm) • Cooking ($/ft^2 floor)
• Heating, cooling, water heating, and refrigeration ($/kBtu/h service, e.g.,$/kBtu/h heating)

Residential and Commercial – Sensors and Controls (Supply)

• Sensor networks ($/node) • Occupant-centered controls ($/occupant)
• All other controls ECMs ($/ft^2 floor) Residential and Commercial – Envelope Components (Demand) • Windows ($/ft^2 glazing)
• Walls ($/ft^2 wall) • Roof ($/ft^2 roof)
• Floor/ground ($/ft^2 footprint) ## ECM JSON schema¶ This section outlines the elements of a JSON file that defines an energy conservation measure (ECM) – a technology included for analysis with Scout. More details about ECMs can be found in the Analysis Approach and Tutorial 1 sections. Each sub-section corresponds to a single key in the JSON. The details provided for each key include the parent and child fields, valid data types, a brief description of the field, and one or more illustrative examples. Parent keys are above and child keys are below the current key in the hierarchy of a JSON file. {"parent key": { "current key": { "child key": "value"}}}  The data type “none” indicates that null is a valid value for that key. The parent “root” indicates that it is at the top of the hierarchy, that is, there are no parents for that key. ### name¶ • Parents: root • Children: none • Type: string A descriptive name of the technology defined in the ECM. If possible, the name length should be kept to under 55 characters including spaces. The name should not be shared with any other ECM. {... "name": "Residential Natural Gas HPWH", ...}  ### climate_zone¶ • Parents: root • Children: none • Type: string, list Either a single climate zone or list of climate zones to which the ECM applies. The climate zone strings must come from the list of valid entries in the ECM Definition Reference. {... "climate_zone": ["AIA_CZ2", "AIA_CZ3"], ...}  ### bldg_type¶ • Parents: root • Children: none • Type: string, list A single building type or a list of residential and/or commercial building types in which the ECM could be installed. The building types specified must be from the list of valid entries in the ECM Definition Reference. {... "bldg_type": "all residential", ...}  ### structure_type¶ • Parents: root • Children: none • Type: string, list The structure type indicates whether the technology described by the ECM is suitable for application in new construction, completed/existing buildings, or both. Valid structure types are new, existing, or all, respectively. {... "structure_type": "new", ...}  Tip If the ECM technology can be applied to both new construction and existing buildings but with differing energy efficiency, installed costs, and/or service life, those differing values should be specified explicitly in the energy_efficiency, installed_cost, and/or product_lifetime fields. This specification method is explained in the Detailed input specification section. ### fuel_type¶ • Parents: root • Children: none • Type: string, list The fuel type(s) should correspond to the energy source(s) used by the technology described in the ECM, and can be specified as a string for a single fuel type or as a list to include multiple fuel types. The fuel type(s) should be drawn from the list of valid fuel types. {... "fuel_type": "electricity", ...}  Tip If the ECM describes a technology that does not use energy directly but affects the energy use of the building, i.e., windows and building envelope, the fuel type should be specified as all. Tip If fuel switching is included in the ECM definition, then the fuel types listed should include all fuel types corresponding to equipment or technologies that can be supplanted by the technology described in the ECM. Further information about using the fuel_switch_to field is in the Multiple fuel types section. ### end_use¶ • Parents: root • Children: none • Type: string, list The end use corresponds to the type of building function that is served by the technology described in the ECM. The end use can be specified as a single string or, if multiple end uses apply, as a list. The valid end uses depend on the building type(s) and fuel type(s) specified, as indicated in the end use tables in the ECM Definition Reference. {... "end_use": ["heating", "cooling"], ...}  Tip If the ECM is describing a technology that affects the heating and cooling load of a building, such as insulation, windows, or an air barrier, the end uses should be given as ["heating", "cooling"]. ### technology¶ • Parents: root • Children: none • Type: string, list The technology field lists the specific technologies or device types that can be replaced by the technology described by the ECM. A complete listing of valid technology names is provided in the ECM Definition Reference. {... "technology": ["HP water heater", "elec_water_heater", "electric WH"], ...}  ### market_entry_year¶ • Parents: root • Children: none • Type: int, none The market entry year specifies the year that the ECM entered or is expected to enter the market. The year should be given as an integer in the format YYYY. null is also an acceptable value for the market entry year, and is interpreted to mean that the ECM is available in the first year simulated in Scout. {... "market_entry_year": 2019, ...}  ### market_entry_year_source¶ The market entry year source indicates the reference from which the market entry year for the ECM was derived. If the market entry year is null, the source can also be given as null without the dict (see market_exit_year_source). {... "market_entry_year_source": { "notes": "", "source_data": [{ "title": "High Efficiency Troffer Performance Specification, Version 5.0", "author": "", "organization": "U.S. Department of Energy", "year": 2015, "pages": null, "URL": "https://betterbuildingssolutioncenter.energy.gov/sites/default/files/attachments/High%20Efficiency%20Troffer%20Performance%20Specification.pdf"}]}, ...}  ### market_exit_year¶ • Parents: root • Children: none • Type: int, none The market exit year indicates the final year that the technology described in the ECM is available for purchase. The year should be formatted as YYYY. null is also an acceptable market exit year value, and is interpreted as the technology remaining available through the final year simulated in Scout. {... "market_exit_year": null, ...}  ### market_exit_year_source¶ The market exit year source indicates the original source for the exit year specified for the ECM. The field is formatted identically to the market_entry_year_source field. If the market exit year is null, the source can also be given as null without the dict. {... "market_exit_year_source": null, ...}  ### energy_efficiency¶ The energy efficiency value(s) define the energy performance of the technology being described by the ECM. The numeric values should be given such that they correspond to the required units given in the energy_efficiency_units field. {... "energy_efficiency": 2.8, ...}  If it is appropriate for the technology described by the ECM, the energy efficiency can be specified more precisely using one or more of the optional child fields. The values should then be reported in a dict where the keys correspond to the applicable child fields. If multiple levels of specificity are desired, the hierarchy of the nested keys must use the following order: climate_zone, bldg_type, end_use and structure_type. Additional information regarding this specification method can be found in the Detailed input specification section. {... "energy_efficiency": { "AIA_CZ1": { "heating": 1.05, "cooling": 1.3, "water heating": 1.25}, "AIA_CZ2": { "heating": 1.15, "cooling": 1.26, "water heating": 1.31}, "AIA_CZ3": { "heating": 1.3, "cooling": 1.21, "water heating": 1.4}, "AIA_CZ4": { "heating": 1.4, "cooling": 1.16, "water heating": 1.57}, "AIA_CZ5": { "heating": 1.4, "cooling": 1.07, "water heating": 1.7}}, ...}  ### energy_efficiency_units¶ This field specifies the units of the reported energy efficiency values for the ECM. The correct energy efficiency units depend on the building type, end use, and in some cases, equipment type of the technology described by the ECM. The units can be determined using the list of energy efficiency units in the ECM Definition Reference. {... "energy_efficiency_units": "COP", ...}  In cases where the energy efficiency is specified with one or more of the optional keys, if the units are the same for all values, the units can still be reported with a single string. If the units are different for some of the keys used, a dict with a structure parallel to the energy efficiency data should be used to report the units. (Energy efficiency units are not a function of climate zone and do not have to be specified with a climate zone breakdown even if the efficiency varies by climate zone.) {... "energy_efficiency_units": { "heating": { "all residential": "COP", "small office": "BTU out/BTU in"}, "cooling": { "all residential": "COP", "small office": "BTU out/BTU in"}}, ...}  Energy efficiency can also be specified with relative units, as described in the Relative energy efficiency units section, or with probability distributions on some or all values, detailed in the Probability distributions section. ### energy_efficiency_source¶ This key is used to specify the source of the ECM’s energy efficiency (i.e., energy performance) values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field. {... "energy_efficiency_source": { "notes": "Minimum Luminaire Efficiency value reported in section 1.4, sub-section II.a.2.a.", "source_data": [{ "title": "High Efficiency Troffer Performance Specification, Version 5.0", "author": "", "organization": "U.S. Department of Energy", "year": 2015, "pages": 5, "URL": "https://betterbuildingssolutioncenter.energy.gov/sites/default/files/attachments/High%20Efficiency%20Troffer%20Performance%20Specification.pdf"}]}, ...}  ### installed_cost¶ The installed cost field represents the typical total cost of the technology and installation of the technology into a building. Costs should be specified such that they are consistent with the required units for the type of technology described by the ECM. {... "installed cost": 14, ...}  Since installation costs can vary by building type (implicitly by building square footage) and whether the technology is being installed as part of new construction or as a replacement of existing equipment or renovation of an existing building, the costs can be specified in a dict using the indicated optional child fields. The keys should match exactly with the allowable values for each of those fields. {... "installed_cost": { "all residential": 8, "all commercial": 10}, ...}  The installed costs can be specified with detail beyond what is shown using the additional optional child field types, as illustrated for the energy_efficiency field. The order of the hierarchy is: bldg_type, structure_type. Further information about detailed structures for specifying the installed cost is in the Detailed input specification section. ### cost_units¶ • Parents: root • Children: (optional) matching installed_cost • Type: string, dict Cost units correspond to the installed cost given for the ECM. The cost units should match the required units based the type of technology described by the ECM. {... "cost_units": "$/1000 lm",
}


If there is only a single cost value, a single units value should be given; if the installed cost is specified by one or more of the optional keys and the various installed costs have different units, the cost units should be specified with the same dict structure as the costs. (Cost units are not a function of climate zone and do not have to be specified with a climate zone breakdown even if the costs vary by climate zone.)

{...
"cost_units": {
"all residential": "$/unit", "all commercial": "$/1000 lm"},
...}


### installed_cost_source¶

This key is used to specify the source of the ECM’s installed cost values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field.

{...
"installed_cost_source": {
"notes": "Table 6.3, average of values reported in Total Installed Cost column for the Gas Storage water heater equipment type.",
"source_data": [{
"title": "Energy Savings Potential and RD&D Opportunities for Commercial Building Appliances (2015 Update)",
"author": "Navigant Consulting; William Goetzler, Matt Guernsey, Kevin Foley, Jim Young, Greg Chung",
"organization": "U.S. Department of Energy",
"year": 2016,
"pages": 80,
"URL": "http://energy.gov/sites/prod/files/2016/06/f32/DOE-BTO%20Comml%20Appl%20Report%20-%20Full%20Report_0.pdf"}]},
...}


• Parents: root
• Children: (optional) values from bldg_type
• Type: int, dict

The product lifetime is the expected usable life of the technology described by the ECM in years. The lifetime value should be an integer greater than 0.

{...
...}


The product lifetime can be specified by building type, if appropriate for the ECM. The building types are the keys in the lifetime dict and should match the types listed in the bldg_type field. Additional information regarding this specification method can be found in the Detailed input specification section.

{...
"single family home": 10,
"small office": 7,
"mercantile/service": 6},
...}


• Parents: root
• Children: none
• Type: string

The product lifetime units are years. This field is included largely to ensure that the correct units were used when specifying the product lifetime.

{...
...}


This key is used to specify the source of the ECM’s product lifetime values. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source and the values in the ECM definition should be supplied in the notes field.

{...
"notes": "Table C-2, Lamp Life column, average of A-Type, Track Lighting, and Downlights Incandescent Omni rows; converted to years assuming an average use of 8 hours/day.",
"source_data": [{
"title": "Energy Savings Forecast for Solid-State Lighting in General Illumination Applications",
"author": "Navigant Consulting; Julie Penning, Kelsey Stober, Victor Taylor, Mary Yamada",
"organization": "U.S. Department of Energy",
"year": 2016,
"pages": 65,
"URL": "http://energy.gov/sites/prod/files/2016/09/f33/energysavingsforecast16_2.pdf"}]},
...}


### time_sensitive_valuation¶

The time sensitive valuation value(s) define the time sensitive efficiency impacts of the technology being described by the ECM. One or more time sensitive ECM features may be described, including conventional, shave, fill, shift, and/or shape. Each feature is indicated as a dict key as follows.

{...
"time_sensitive_valuation": {
"conventional": {...}},
...}


If an ECM has multiple time sensitive features, they may be specified as follows.

{...
"time_sensitive_valuation": {
"conventional": {...},
...,
"shape": {...}},
...}


Optionally, a user may define an end use break down of time sensitive features by setting the end use as the first level in the dict key hierarchy, followed by the time sensitive feature type key.

{...
"time_sensitive_valuation": {
"heating": {
"conventional": {...},
...,
"shape": {...}},
"cooling": {
"conventional": {...},
...,
"shape": {...}}},
...}


Note that if an end use breakout is used, keys for all the ECM’s applicable end uses must be included - e.g., if the ECM applies to both heating and cooling, both the heating and cooling keys must be reflected in the time sensitive valuation dict.

### time_sensitive_valuation_source¶

This key is used to specify the source of the ECM’s time sensitive valuation data. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source(s) and the values in the ECM definition should be supplied in the notes field.

{...
"time_sensitive_valuation_source": {
"notes": "Study provides estimate of commercial load curtailment magnitude.",
"source_data": [{
"title": "Characterization of demand response in the commercial, industrial, and residential sectors in the United States",
"author": "Sila Kiliccote, Daniel Olsen, Michael D. Sohn, Mary Ann Piette",
"organization": "Lawrence Berkeley National Laboratory",
"year": 2015,
"pages": 17,
"URL": "https://onlinelibrary.wiley.com/doi/abs/10.1002/wene.176"}]},
...}


### measure_type¶

• Parents: root
• Children: none
• Type: string

This field is used to specify whether the technology described by the ECM could be substituted for a component already installed in buildings, such as an electric cold-climate heat pump being substituted for an electric furnace and central AC system, or enhance the efficiency of an existing component, such as a window film applied to an existing window or an HVAC controls system that improves the efficiency of existing HVAC equipment. The measure type is then either "full service" or "add-on", respectively. Supplementary information and illustrative examples of the use of this field are available in the Add-on type ECMs section.

{...
"measure_type": "full service",
...}


### fuel_switch_to¶

• Parents: root
• Children: none
• Type: string, list

If the ECM is intended to replace comparable building components that use one of multiple fuel types, such as both electric and natural gas water heaters, this field should identify the fuel type of the technology described by the ECM. The fuel type should match exactly with one of the fuel types listed in the ECM Definition Reference. If the value of fuel_type is a single fuel type that matches the technology described by the ECM, this field can be given as null. Additional information regarding the use of this field is available in the Multiple fuel types section.

{...
"fuel_switch_to": "natural gas",
...}


### market_scaling_fractions¶

The market scaling fraction is used to further reduce the energy use of the applicable baseline market [1] specified for an ECM whose technology corresponds to only a fraction of that market. The market scaling fraction value should be between 0 and 1, representing the desired fraction of the baseline market. If the ECM does not need a market scaling fraction, the field should be given the value null.

{...
"market_scaling_fractions": 0.18,
...}


Market scaling fractions can be separately specified using the optional child fields if relevant to the technology described by the ECM, if the fields are part of the applicable baseline market, and if appropriate source information is provided.

{...
"market_scaling_fractions": {
"new": 1,
"existing": 0.43},
...}


Further information regarding the use of market scaling fractions is in the Market scaling fractions section.

### market_scaling_fractions_source¶

The market scaling fractions source identifies the sources that were used to determine the market scaling fraction, including the exact method for deriving the fraction. If the market_scaling_fractions field is null, the source should also be specified as null.

{...
"market_scaling_fractions_source": {
"title": "Energy Savings Forecast for Solid-State Lighting in General Illumination Applications",
"author": "Navigant Consulting; Julie Penning, Kelsey Stober, Victor Taylor, Mary Yamada",
"organization": "U.S. Department of Energy",
"year": 2016,
"pages": 23,
"URL": "http://energy.gov/sites/prod/files/2016/09/f33/energysavingsforecast16_2.pdf"},
"fraction_derivation": "In Figure 4.4, sum of 2015 data for LED - Connected Lighting, LED - Controls, and Conventional Lighting - Controls."},
...}


Multiple scaling fraction values can share the same source so long as the calculation procedure for all of the values is provided in the fraction_derivation field, however, no more than one source is allowed for each scaling fraction value. If scaling fractions correspond to different sources, the source information can be given in a nested dict with the same top level structure as the scaling fractions themselves. If the market scaling fraction is set to 1 for one of the keys in the nested structure, the source information can be given as a string explaining any assumptions.

{...
"market_scaling_fractions_source": {
"new": "Assumes that all new commercial buildings are constructed with BAS",
"existing": {
"title": "CBECS 2012 - Table B1. Summary table: total and means of floorspace, number of workers, and hours of operation, 2012",
"author": "U.S. Energy Information Administration (EIA)",
"organization": "U.S. Energy Information Administration (EIA)",
"year": "2012",
"URL": "http://www.eia.gov/consumption/commercial/data/2012/bc/cfm/b1.cfm",
"fraction_derivation": "37051 ft^2 floor of commercial buildings with BAS / 87093 ft^2 floor total commercial buildings"}},
...}


### retro_rate¶

• Parents: root
• Children: none
• Type: float, none

This field assigns an ECM-specific retrofit rate to use in stock-and-flow calculations. The retrofit rate value should be specified as a fraction between 0 and 1. For example, 0.1 corresponds to 10% of the existing technology stock being retrofitted annually.

{...
"retro_rate": 0.1,
...}


### retro_rate_source¶

This field is used to specify the source of the ECM’s retrofit rate data. The source_data field description explains how to specify multiple sources. Any details regarding the relationship between the values in the source and the values in the ECM definition should be supplied in the notes field.

{...
"retro_rate_source": {
"notes": "Increased commercial building retrofit rate to represent the potential impacts of the DEEP database in accelerating energy savings from commercial retrofits.",
"source_data": [{
"title": "Accelerating the energy retrofit of commercial buildings using a database of energy efficiency performance",
"author": "Sang Hoon Lee, Tianzhen Hong, Mary Ann Piette, Geof Sawaya, Yixing Chen, Sarah C. Taylor-Lange",
"organization": "Lawrence Berkeley National Laboratory",
"year": 2015,
"pages": 10,
"URL": "https://eta.lbl.gov/sites/all/files/publications/tianzhen_hong_-_accelerating_the_energy_retrofit_of_commercial_buildings_using_a_database_of_energy_efficiency_performance.pdf"}]},
...}


### _description¶

• Parents: root
• Children: none
• Type: string

A one to two sentence description of the ECM. If the ECM is prospective, i.e., describing a technology still being researched, the description should include URLs or other identifying information for additional references that contain further details about the technology.

{...
"_description": "LED troffers for commercial modular dropped ceiling grids that are a replacement for the entire troffer luminaire for linear fluorescent bulbs, not a retrofit kit or linear LED bulbs that slot into existing troffers.",
...}


### _notes¶

• Parents: root
• Children: none
• Type: string

A text field that can be used for explanatory notes regarding the technologies that can be replaced by the ECM, any notable assumptions made in the specification of the ECM, or any other relevant information about the ECM that is not captured by any other field.

{...
"_notes": "Energy efficiency is specified for the luminaire, not the base lamp.",
...}


A dict containing basic information about the user that originally created the ECM.

{...
"name": "Maureen Baruch Kilda",
"organization": "U.S. Department of Energy",
"email": "maureen.b.kilda@hq.doe.gov",
"timestamp": "2016-01-28 21:17:35 UTC"}
...}


### _updated_by¶

A dict containing basic information that identifies the user that last updated the ECM, identical in structure to the dict in the _added_by field. null if the ECM has never been modified.

{...
"_updated_by": null
...}


### conventional¶

This field restricts the application of a conventional efficiency impact to a certain period within the day, defined by start and stop parameters.

{...
"start": 12,
"stop": 20
...}


### shave¶

This field sets a rule that no loads are greater than a certain percentage of peak daily load, as defined by peak_fraction (between 0 and 1). Optionally, users may restrict this rule to a certain period within the day, defined by start and stop parameters.

{...
"peak_fraction": 0.8,
"start": 12,
"stop": 20
...}


### fill¶

This field sets a rule no loads are less than a certain percentage of peak daily load, as defined by peak_fraction (between 0 and 1). Optionally, users may restrict this rule to a certain period within the day, defined by start and stop parameters.

{...
"peak_fraction": 0.4,
"start": 12,
"stop": 20
...}


### shift¶

This field shifts loads earlier by the number of hours specified using the offset_hrs_earlier parameter. Optionally, a user may restrict this rule to a certain period within the day, defined by start and stop parameters. In this case, total load reductions during the specified period will be evenly redistributed across the same period of time shifted earlier by the number of hours specified in offset_hrs_earlier. If no time restrictions are provided, the feature will shift the entire baseline energy load shape earlier by the number of hours specified in offset_hrs_earlier.

{...
"offset_hrs_earlier": 12,
"start": 12,
"stop": 20
...}


### shape¶

This field allows users to either define a custom load shape or load savings shape for an ECM using the custom_load or custom_savings parameters, or to flatten a baseline load shape by a certain percentage using the flatten_fraction parameter (using a value between 0 and 1). Optionally, users may restrict the latter rule to a certain period within the day, defined by start and stop parameters.

{...
"custom": [...]
...}

{...
"flatten_fraction": 0.5,
"start": 12,
"stop": 20
...}


### start¶

This field indicates the hour of the day (from 1 to 24) that applicaiton of a time sensitive ECM feature begins.

{...
"start": 12
...}


### stop¶

This field indicates the hour of the day (from 1 to 24) that application of a time sensitive ECM feature ends.

{...
"stop": 20
...}


### peak_fraction¶

• Parents: shave, fill
• Children: None,
• Type: float

This field indicates the fraction of daily peak load (between 0 and 1) that hourly loads must remain either above or below (depending on whether a peak shaving or valley filling time sensitive feature is indicated).

{...
"peak_fraction": 0.8
...}


### offset_hrs_earlier¶

• Parents: shift
• Children: None,
• Type: int

This field indicates the number of hours earlier to shift baseline loads or load reductions.

{...
"offset_hrs_earlier": 12
...}


### flatten_fraction¶

• Parents: shape
• Children: None,
• Type: float

This field indicates the fraction to use (between 0 and 1) in scaling down the difference between hourly baseline energy loads and the average daily baseline energy load.

{...
"flatten_fraction": 0.5
...}


• Parents: shape
• Children: None,
• Type: list

This field provides a list of 24 fractions (between 0 and 1) that are used to rescale a baseline energy load shape to conform with a user-specified load shape. The fractions, which are specified for each hour of the day, represent each hourly load’s percentage of maximum daily load under the custom load shape.

{...
"custom": [0.79, 0.70, 0.61, 0.56, 0.52, 0.52, 0.54, 0.58, 0.63, 0.67, 0.69, 0.71,
0.71, 0.71, 0.76, 0.76, 0.80, 0.85, 0.90, 0.95, 0.99, 1, 0.96, 0.88]
...}


### custom_savings¶

• Parents: shape
• Children: None,
• Type: list

This field provides a list of 24 fractions that are used to rescale a baseline energy load shape to conform with a user-specified load savings shape. The fractions, which are specified for each hour of the day, represent the percentage of baseline load saved under the custom load savings shape.

{...
"custom": [0.5, 0.5, 0.5, 0.5, 0.5, 0.6, 1, 1.3, 1.4, 1.5, 1.6, 1.8,
1.9, 2, 1, 0.5, 0.75, 0.75, 0.75, 0.75, 0.5, 0.5, 0.5, 0.5]
...}


### notes¶

The notes field should include the exact location of the specific information used from the source(s) identified. The location information should include the table or figure number, and if the value is drawn from tabular data, the applicable row and column heading(s). The notes should also outline any calculations performed to convert from the values found in the source(s) to the value used in the ECM definition, including unit conversions and methods for combining multiple values (e.g., averaging, market share-weighted averaging). Any other assumptions regarding the derivation of the related value in the ECM definition should also be included.

{...
"notes": "Value drawn from Table 1 for the Ventless or Vented Electric, Standard product type. For clothes drying, the expected units of EF (Energy Factor) are equivalent to lbs/kWh.",
...}


### fraction_derivation¶

For the market scaling fractions, this field should provide a description of how the values were calculated. The description should have enough detail for another user to be able to easily repeat the calculations.

{...
"fraction_derivation": "Sum of 2015 data for LED - Connected Lighting, LED - Controls, and Conventional Lighting - Controls.",
...}


### source_data¶

A list that encloses one or more dicts, where each dict corresponds to a single source and includes all of the child fields listed.

{...
"source_data": [{
"title": "ENERGY STAR Program Requirements: Product Specification for Clothes Dryers",
"author": null,
"organization": "U.S. Environmental Protection Agency",
"year": 2014,
"pages": "2-3",
"URL": "https://www.energystar.gov/sites/default/files/specs//ENERGY%20STAR%20Final%20Version%201%200%20Clothes%20Dryers%20Program%20Requirements.pdf"}],
...}


### title¶

The title of the source document.

{...
"title": "ENERGY STAR Program Requirements: Product Specification for Clothes Dryers",
...}


### author¶

The names of the author(s) of the publication, if any are identified. If no authors are listed, null or an empty string are acceptable values for this field if no authors are identified by name in the source.

{...
"author": null,
...}


### organization¶

The journal publication, organization, or other entity that released the source article, report, specification, test result, or other reference.

{...
"organization": "U.S. Environmental Protection Agency",
...}


### year¶

The year that the source was published or last updated.

{...
"year": 2014,
...}


### pages¶

The page number(s) of the information in the source document, if applicable. If the source is not divided into pages, this entry can have the value null. If the relevant information can be found on a single page, the page number should be given as an integer. If the information is divided across several pages or a range of pages, the page numbers should be given as a string.

{...
"pages": "24, 26-29, 37",
...}


### URL¶

The URL where the source can be found on the internet. The URL should point directly to the original source file, if possible.

{...
"URL": "https://www.energystar.gov/sites/default/files/specs//ENERGY%20STAR%20Final%20Version%201%200%20Clothes%20Dryers%20Program%20Requirements.pdf",
...}


### name¶

The name of the author of the initial definition or latest changes to the ECM.

{...
...}


### organization¶

The organization or employer with which the named author is affiliated.

{...
"organization": "U.S. Department of Energy",
....}


### email¶

The email address of the named author.

{...
"email": "james.clipper@ee.doe.gov",
...}


### timestamp¶

The date and time at which the relevant changes were completed. The entry should be formatted as YYYY-MM-DD HH:MM:SS, with the time reported in 24-hour Universal Coordinated Time (UTC) if possible.

{...
"timestamp": "2014-03-27 14:36:18 UTC",
...}


Footnotes

 [1] The applicable baseline market is comprised of the climate_zone, bldg_type, structure_type, fuel_type, end_use, and technology fields.