ACC Carbon Tool

Emitter groups

Emitter groups are the foundations of the ACC carbon tool. An emitter group represents a collection of carbon sources that you can analyse. It could represent the emissions from the whole world, or from a particular construction project.

The ACC Carbon tool includes several predefined emitter groups, and also allows you to add your own — either individually, or as part of a emitter suite.

Introduction

An emitter group consists of a set of carbon sources which emit carbon (or other greenhouse gases) into the atmosphere each year. Absorption from the atmosphere is represented as a negative emission.

The ACC Carbon Tool includes several predefined emitter groups available to all users which you cannot overwrite, delete, or change. You can also add your own emitter groups, which will be available only to you.

You can see the definition of any emitter group by selecting it on the Emitter groups page.

Core information

Each emitter group has a unique name, an optional description, an optional start year, and a collection of sources.

Occurrences

Occurrences occur probabilistically. All occurrences for a source use the same occurrence distribution, but the distribution parameters are different for each occurrence.

The emissions for each occurrence depend on the year in which the occurrence takes place. For example, consider a source with a uniform occurrence distribution, with three occurrences as follows: min 15 and max 20, min 30 and max 35, min 45 and max 50. This source will have emissions in three years: the first will be between the 15th and 20th year of the simulation, the second between the 30th and 35th, and the third between the 45th and 50th years. The amount emitted in each of those years will be probabilistic, using the source's distribution and the distribution parameters for that year.

Start year

Some emitter groups specify a start year: the calendar year in which the first emissions occur. This is used in conjunction with the calendar year in which the simulation starts to determine which emissions are simulated in each year of the simulation.

If an emitter group does not specify a start year, the first year of emissions in the emitter group are used for the first year of the simulation, regardless of the calendar year in which the simulation starts.

Source

Each source in an emitter group has information about its emissions in each year, expressed in probabilistic terms. The emissions from a particular source have the same type of distribution in each year, but may have different parameters. By selecting a source on the Emitter groups page, you can see which probability distribution it uses and the parameters used in each year.

If no parameters are present for a particular year, the simulation will use the parameters for the last year for which they are present.

A source may be designated as an emit source, meaning that its emissions can never be negative (it can never absorb carbon from the atmosphere), or a sink, meaning that its emissions can never be positive (it always absorbs rather than emits), or neither, in which case its emissions may be either positive or negative.

Some sources are active only in selected years — these years are called occurrences.

A small chart on the Emitter groups page indicates the shape of the emissions from the selected source, and when its occurrences (if any) might occur. Note that these charts are indicative only — they do not show an accurate representation of the occurrence distributions.

Examples

The predefined ACC-distributions emitter group includes at least one source that uses each distribution. Some sources use occurrences, and some include negative emissions (they absorb carbon from the atmosphere).

Download the file that defines this emitter group.

Introduction

An emitter suite is a set of linked emitter groups. All the groups in the suite have names beginning with the same prefix: there is a predefined suite with the prefix pds1 (standing for predefined suite number 1).

An emitter suite is often used to represent a set of options for a project. The pds1 suite represents a set of options for a city centre site: either constructing a new building (with five different design options) or retrofitting the existing building. The emissions for each option come from a number of sources — for a building, these might include the construction process, the use of the building during its lifetime, and various maintenance processes (such as replacing windows or cladding). Crucially, all the options have the same set sources (obviously with different emissions levels and distributions).

Defining an emitter suite produces an emitter group for each option (whose names begin with the suite prefix plus opt, for 'option') and an overall emitter group that has one source for each option (whose name begins with the suite prefix plus coll, for 'collection'). All these emitter groups can be used when specifying scenarios in the usual way. It is often useful to perform a component analysis on a single option emitter group or a pair of option emitter groups, and a collection analysis on the collection emitter group.

Option emitter groups

Each option emitter group in the suite has the same set of sources. The distributions for each source can vary between options, though the specification is not as flexible as it is when defining an individual emitter group.

Groups or suites?

Should you define emitter groups individually, or as part of an emitter suite? There are advantages and disadvantages to both approaches.

Defining individual emitter groups gives you much more flexibility. There is no limitation on the sources that compose the group, and each source may have varying emission levels. However, it can be fiddly to construct the specification files for many emitter groups at one time, and to ensure consistency between groups.

Defining a suite of emitter groups provides consistency between groups, including between the option emitter groups and the collection emitter group, and it may be simpler to construct a single specification file for the emitter suite. However, there is less flexibility in how sources are defined, and the collection group inevitably provides a somewhat simplified view. The results for the individual options may well not be consistent between a component analysis of the option emitter group and a collection analysis of the collection emitter group.

Collection emitter group

The collection emitter group is defined automatically from the definitions of the options in the emitter suite. It contains one source for each option. The definition of each source is inevitably a simplified representation of the underlying option — for example, each source has the same distribution shape in each year, which will not be the same as the total results for the underlying option emitter group.

Adding

Add a new emitter group or suite by uploading a csv file containing its specification, using the file format described below. You can do this from the Emitter groups page.

Any emitter groups that you add will be available only to you. They will be available for up to two weeks after your most recent visit to the site from your current browser. You are advised to keep track of your csv files so that you can upload them again as necessary.

Changing

Once an emitter group has been uploaded, either individually or as part of a suite, you cannot edit it directly. However, you can upload a new file that overwrites an existing emitter group or suite. Make sure you check the Overwrite existing emitter group(s)? box

You cannot overwrite an individual emitter group that is part of a suite. To change a group that is in a suite, you have to upload a new file to overwrite the whole suite.

Deleting

You can delete one of your emitter groups or suites by uploading a special deletion file, making sure you have checked the Overwrite existing emitter group(s)? box. A deletion file contains just two rows:

  • The first row must have the same format as a normal group or suite specification file, containing either the name of the group to be deleted or the prefix of the suite to be deleted.
  • The second row contains just one field: the word delete.

You cannot delete an individual emitter group that is part of a suite. To delete a group that is in a suite, you have to upload a new file to delete or overwrite the whole suite.

Csv files

Emitter groups are specified in csv (comma separated variable) files. Csv files are plain text files, and can be created from spreadsheet apps such as Excel or text editors such as Notepad++. They consist of a number of rows of data, each row composed of a series of fields separated by commas. Each field can contain either a number or some text. Each field may be surrounded by quotation marks, but does not have to be. However, quotation marks must be used if the field is intended to contain a comma.

Download an example of a csv file specifying an emitter group.

Comments

Comments can be included in the file in three ways:

  • All rows beginning with a # are ignored
  • All fields after the first twelve on each row are ignored
  • All rows after the row with end in the first field are ignored

File structure

An emitter group file consists of

  • The emitter group row: giving the name and description of the emitter group.
  • An optional start year: specifying the calendar year in which the emissions in the emitter group start. If this row is not present, the emissions will start in the first year of the simulation.
  • Any number of source blocks: specifying each emissions source in the emitter group.
  • An optional end row: all rows after this row are ignored.

Emitter group row

The emitter group row must be the first row in the file. It must contain three fields:

  • Field 1 must be the word emitter_group.
  • Field 2 contains the name of the emitter group. The name is truncated to the first 25 characters.
  • Field 3 contains a description of the emitter group. The description is truncated to the first 150 characters. You can include commas in the description by enclosing it in quotation marks.

Start year row

The optional start year row must come before the source blocks. It must contain two fields:

  • Field 1 must be the word start_year.
  • Field 2 contains the calendar year.

If this row is not present, the emissions for this emitter group will start in the first year of the simulation.

Source block

A source block consists of:

  • A source row: the first row in the block, giving the name of the source.
  • A distribution row: describing the probability distribution used to model the emissions from this source
  • A year data block: specifying the emissions in each year
  • An occurrence distribution row: describing the probability distribution used to model when the emissions occur (this row is optional)
  • An occurrence data block: specifying the probability distribution of emissions occurring (this row is optional)

End row

The first field in the end row must be the word end. All rows in the file after the end row are ignored. This row is optional.

Source row

Each source block starts with a source row, which must contain two or three fields:

  • Field 1 must be the word source
  • Field 2 must be the name of the source. The name is truncated to the first 25 characters. Source names must be unique within an emitter group.
  • Field 3 is optional. If it is present it must be either the word emit (meaning that this source always emits carbon into the atmosphere, and never absorbs it) or the word sing (this source always absorbs carbon from the atmosphere, and never emits it). If this field it not present the source may either emit or absorb carbon.

Distribution row

A distribution row is the second row in a source block and must contain at least two fields:

  • Field 1 must be the word distribution
  • Field 2 must be the name of the distribution. The valid options are described on the distributions help page. If this row is not present, the distribution name is assumed to be none.

The remaining fields, if any, are the distribution parameters. Distribution parameters are required only for some distributions. See the distributions help page for details.

Year data block

The year data block is the heart of the source block. It contains the year by year emissions information for the source. It consists of a variable number of rows.

The first row contains a single field, which must contain the word year_data.

Each of the following rows contains the emissions information for one or more years. There must be at least one row (ie, information for at least one year). When the information is used in a simulation, the information for the final year will be used for any year after that. If you want a source to have emissions for only a limited period, the final row must therefore contain zeros for every parameter.

The basic information required for each year depends on the distribution as described on the distributions help page

Each data row in the year data block can take one of four forms:

  • A row specifies the emissions for a single year. The row contains a single set of items as described on the distributions help page.

    For example, a row for a source with a normal distribution should contain two fields, the first giving the mean emissions for the year and the second giving the standard deviation.

  • A row specifies the emissions for a number of years. The row contains a single set of items as described on the distributions help page, followed by a field containing the character x and a final field containing the number of years to which the information applies.

    For example, a row for a source with a uniform distribution will contain four fields. The same minimum and maximum values will repeat for the number of years specified by field 4.

  • A row specifies how the emissions information should be interpolated over a number of years. The row contains a set of items as described on the distributions help page, followed by a field containing the word to, then another set of items, then a field containing the word over, and finally a field containing the number of years over which the interpolation should take place.

    For example, a row for a normal distribution will contain 6 fields. In this case, the mean and standard deviation will each be interpolated linearly over the specified number of years.

  • A row specifies how the emissions information will trend starting from the specified values. The row contains a set of items as described on the distributions help page, followed by a field containing the word then, then another set of fields with values between -1 and +1.

    For example, a row for a source with a normal distribution will contain 5 fields. In this case, the mean and standard deviation will each trend at the corresponding rate specified in the second set of fields.

Occurrence distribution row

An occurrence distribution row is required in a source block only if the source emissions occur intermittently. The occurrence distribution and occurrence data allow stochastic modelling of the years in which intermittent emissions will occur. The format of the occurrence distribution row is the same as the format of the distribution row except that field 1 must contain the word occurrence_dist.

Occurrence data block

An occurrence data block is required in a source block only if the source emissions occur intermittently. The occurrence distribution and occurrence data allow stochastic modelling of the years in which intermittent emissions will occur. The format of the occurrence data block is the same as the format of the year data block except that the first row must consist of a single field containing the word occurrence_data, and only first form of data row, specifying the information for a single occurrence, is permitted.

Each row of the occurrence data block specifies the distribution of an occurrence of the emission. For example, if the occurrence distribution is uniform, the occurrence is equally likely to occur in any year between the minimum and maximum.

Csv files

Emitter suites are specified in csv (comma separated variable) files. Csv files are plain text files, and can be created from spreadsheet apps such as Excel or text editors such as Notepad++. They consist of a number of rows of data, each row composed of a series of fields separated by commas. Each field can contain either a number or some text. Each field may be surrounded by quotation marks, but does not have to be. However, quotation marks must be used if the field is intended to contain a comma.

Download an example of a csv file specifying an emitter suite.

File structure

An emitter suite file consists of

  • The emitter suite row: giving the name, prefix, and description of the emitter group.
  • The options block: giving the names and descriptions of the options.
  • The sources block which defines the sources in the options emitter groups
  • Distribution, distribution range, distribution shape and amounts blocks, which between them specify the emissions data for the sources in the options emitter groups. These blocks are known as the source emissions blocks.
  • The collection block, which specifies the emissions data for sources in the collection emitter group.
  • An optional end row: all rows after this row are ignored.

Options block

The options block consists of:

  • The block start row has a single field, containing the word options.
  • There is one content row for each option, containing two fields: the option name and the option description. The option name is truncated to 25 characters, and the description is truncated to 150 characters. Option names must be unique within the suite.
  • The block end row consists of the single field end_options.

Sources block

The sources block consists of:

  • The first field in the block start row contains the word sources. The remaining fields contain the names of the sources in the option emitter groups. The source names must be unique, and are truncated to 25 characters.
  • There are up to six source content rows, each consisting of a key in the first field and then one field for each source. The source content rows are described below.
  • The block end row consists of the single field end_sources.

Collection block

The collection block specifies the distributions for the sources in the collection emitter group. It consists of

  • The first field in the block start row contains the word collection_params. The remaining fields contain the names of the options defined in the options block. They may appear in any order. Each option defines a source in the collection emitter group.

  • There must be three content rows, which may appear in any order. They should start with the following keywords: distribution, distribution_range, and distribution_shape. They specify the distribution information for the sources in the collection emitter group, as described below.

    The amount for each source in the collection emitter group is calculated from the total of the amounts specified for each source in the corresponding option emitter group, taking into account the start_year, interval, and stop_year.

  • The block end row consists of the single field end_collection_params.

Comments

Comments can be included in the file in two ways:

  • All rows beginning with a # are ignored
  • All rows after the row with end in the first field are ignored

End row

The first field in the end row must be the word end. All rows in the file after the end row are ignored. This row is optional.

Blocks

The emitter suite file contains a number of blocks. Each block has three types of row:

  • Each block begins with a block start row consisting of a field giving the block type followed by a number of fields specifying what information the content rows contain.
  • A set of content rows containing information specifying a source or option.
  • Each block ends with a block end row consisting of a single field: end_{block type} using the block type was specified in the block start row.

Emitter suite row

The emitter suite row must be the first row in the file. It must contain four fields:

  • Field 1 must be the word suite.
  • Field 2 contains the name of the emitter suite. The name is truncated to the first 25 characters.
  • Field 3 contains the prefix that all emitter group names in the suite will start with. The prefix is truncated to the first 5 characters.
  • Field 4 contains a description of the emitter suite. The description is truncated to the first 150 characters. You can include commas in the description by enclosing it in quotation marks. You may wish to include a note of the units used for the emissions in your emitter suite in the description, but you do not have to do so.

Source emissions blocks

There are four source emissions blocks: the distribution distribution_range, distribution_shape, and amounts blocks. These blocks may appear in any order, but must be after the options and sources blocks. They all have the same format:

  • The start block row contains the block keyword followed by a list of source names. All names in the list must have appeared in the start block row. They can appear in any order, and some may be omitted.

  • Each contents row starts with the name of one of the options defined in the options block. This is followed by one field for each of the source names listed in the start block row. The content of this field depends on the block:

    Block Field
    distribution The probability distribution to use for the emissions for the corresponding source in the option specified at the start of the row. Valid options are none, normal, uniform, and triangle.
    distribution_range The range parameter to use for the distribution, as described below. It is interpreted as a factor to be applied to the amount, and is typically a number between 0 and 1.
    distribution_shape The shape parameter to use for the distribution, as described below.
    amounts The amount parameter to use for the distribution, as described below.
  • The block end row consists of the single field end_distribution, end_distribution_range, end_distribution_shape, or end_amounts.

Source content row

The source block contains up to six content rows. Each row consists of a keyword in the first field followed by one field for each source listed in the start block row:

Keyword Content
start_year The year of the projection in which the emissions from each source start. Emissions are zero for all previous years. The first year of the projection is year 0. This row must be present.
interval The interval at which the emissions from each source occur. An interval of 1 means they occur every year. An interval of 5 means there are four years in which they don't occur between every year in which they do. This row must be present.
stop_year The year of the projection in which the emissions from each source stop. Emissions are zero for all subsequent years. The first year of the projection is year 0. This row must be present.
occ_distribution The probability distribution to be used for intermittent occurrences of emissions. It is ignored if the interval for source is less than 10 years. This row is optional. See the distributions help page for more information.
occ_range The range parameter to be used for the occurrence distribution, as described below. This row is optional, but must be present if any occurrence distribution is not none. It is interpreted as a number of years, and must be an integer.
occ_shape The shape parameter to be used for the occurrence distribution, as described below. This row is optional.

Distribution amounts, ranges, and shapes

The distributions used in emitter suites are specified using three parameters: an amount, range, and shape.

The amount is usually the mean of the distribution.

The range describes the spread of the distribution. It is input as either a factor to be applied to the amount (for source distributions — the calculated range is the product of the input value and the amount) or a number of years (for occurrence distributions).

The shape is a parameter used for some asymmetric distributions, whose interpretation depends on the distribution in question.

They are converted into the usual parameters for the relevant distribution as follows:

Distribution Amount Range Shape Notes
none The (deterministic) level of emissions in each year is the amount.
uniform The amount is the mean of the distribution. The minimum is the amount minus the calculated range, and the maximum is the amount plus the calculated range.
normal The mean of the distribution is the amount and the standard deviation is the calculated range.
triangle The mode of the distribution is the amount. The minimum is the amount minus the calculated range, and the maximum is the amount plus the product of the calculated range and the shape. If the shape is not specified it defaults to 1 (giving a symmetric distribution).