The rewriteSets.xml file defines named sets of rewrite statements that
can be added to queries defined in a separate :doc:`query-xml` file, or in
a <queries> element within a :doc:`project-xml` file.
The elements that comprise the rewriteSets.xml file are described below.
.. seealso:: Some elements of the ``rewriteSets.xml`` file can contain ``<CONDITIONAL>`` elements, as described below. See :doc:`conditional-xml` for further details.
This is the outermost element, which takes no attributes and contains one
or more <rewriteSet> elements. It may also contain <CONDITIONAL>
elements.
This element defines a set of rewrites, assigns the set a unique name, and
specifies the default 'level' to use if not overridden in the queries.xml
file when the rewrite set is referenced. If the append-values flag is
"true", rows are written out for all elements including those with zero results.
When the rewrite sets are inserted into a query file, level is set to "true"
if any of the rewrite sets specified append-values="true", otherwise the
value is set to "false".
If byAEZ="true", each rewrite is expanded to 18 elements with the same
'to' attribute, but with the 'from' attributes formed by appending 'AEZ'
and zero-padded, 2-digit integers from 1 to 18. In the example below, the
element
<rewriteSet name="landCover" level="LandLeaf" byAEZ="true"> <rewrite from="biomass" to="Biomass"/> ... </rewriteSet>
is expanded in the generated query file to:
<rewrite from="biomassAEZ01" to="Biomass"/> <rewrite from="biomassAEZ02" to="Biomass"/> <rewrite from="biomassAEZ03" to="Biomass"/> <rewrite from="biomassAEZ04" to="Biomass"/> <rewrite from="biomassAEZ05" to="Biomass"/> <rewrite from="biomassAEZ06" to="Biomass"/> <rewrite from="biomassAEZ07" to="Biomass"/> <rewrite from="biomassAEZ08" to="Biomass"/> <rewrite from="biomassAEZ09" to="Biomass"/> <rewrite from="biomassAEZ10" to="Biomass"/> <rewrite from="biomassAEZ11" to="Biomass"/> <rewrite from="biomassAEZ12" to="Biomass"/> <rewrite from="biomassAEZ13" to="Biomass"/> <rewrite from="biomassAEZ14" to="Biomass"/> <rewrite from="biomassAEZ15" to="Biomass"/> <rewrite from="biomassAEZ16" to="Biomass"/> <rewrite from="biomassAEZ17" to="Biomass"/> <rewrite from="biomassAEZ18" to="Biomass"/>
The <rewriteSet> element may contain <CONDITIONAL> elements.
The <rewrite> element defines a label rewrite. If the element
specifies byAEZ="true", the element is expanded as described
above. If all elements in a rewriteSet are to be expanded by AEZ,
it is more convenient to specify this once in the <rewriteSet>
element.
The resulting <rewrite> statements are inserted into the query
file and processed as usual by the GCAM batch query processor:
- If the "to" value is empty, any row with a matching value is dropped from the result set.
- If the "to" value specified a new name, the label is rewritten using the new name and grouped with other values having that name. This is used to aggregate values, e.g., from 32 regions to a smaller number. In the example below, the
resultSetnamedeightRegionsmaps the 32 standard GCAM regions into 8 regions.- If a value is not specified, or if the "from" and "to" values are the same, the row is processed normally.
| Attribute | Required | Default | Values |
|---|---|---|---|
| from | yes | (none) | text |
| to | yes | (none) | text |
| byAEZ | no | (none) | text |
This is an example of a file defining rewrite sets.
<rewriteSets> <rewriteSet name="eightRegions" level="region" append-values="true"> <rewrite from="USA" to="United States"/> <rewrite from="Brazil" to="Brazil"/> <rewrite from="Canada" to="Rest of World"/> <rewrite from="China" to="China"/> <rewrite from="Africa_Eastern" to="Africa"/> <rewrite from="Africa_Northern" to="Africa"/> <rewrite from="Africa_Southern" to="Africa"/> <rewrite from="Africa_Western" to="Africa"/> <rewrite from="Japan" to="Rest of Asia"/> <rewrite from="South Korea" to="Rest of Asia"/> <rewrite from="India" to="Rest of Asia"/> <rewrite from="Central America and Caribbean" to="Rest of South America"/> <rewrite from="Central Asia" to="Rest of Asia"/> <rewrite from="EU-12" to="Europe Union 27"/> <rewrite from="EU-15" to="Europe Union 27"/> <rewrite from="Europe_Eastern" to="Rest of World"/> <rewrite from="Europe_Non_EU" to="Rest of World"/> <rewrite from="European Free Trade Association" to="Rest of World"/> <rewrite from="Indonesia" to="Rest of Asia"/> <rewrite from="Mexico" to="Rest of South America"/> <rewrite from="Middle East" to="Rest of World"/> <rewrite from="Pakistan" to="Rest of Asia"/> <rewrite from="Russia" to="Rest of World"/> <rewrite from="South Africa" to="Africa"/> <rewrite from="South America_Northern" to="Rest of South America"/> <rewrite from="South America_Southern" to="Rest of South America"/> <rewrite from="South Asia" to="Rest of Asia"/> <rewrite from="Southeast Asia" to="Rest of Asia"/> <rewrite from="Taiwan" to="Rest of Asia"/> <rewrite from="Argentina" to="Rest of South America"/> <rewrite from="Colombia" to="Rest of South America"/> <rewrite from="Australia_NZ" to="Rest of Asia"/> </rewriteSet> <rewriteSet name="food" level="input"> <rewrite from="Corn" to="Grains"/> <rewrite from="FiberCrop" to="Other"/> <rewrite from="MiscCrop" to="Other"/> <rewrite from="OilCrop" to="Other"/> <rewrite from="OtherGrain" to="Grains"/> <rewrite from="PalmFruit" to="Other"/> <rewrite from="Rice" to="Grains"/> <rewrite from="Root_Tuber" to="Other"/> <rewrite from="SugarCrop" to="Other"/> <rewrite from="Wheat" to="Grains"/> <rewrite from="regional beef" to="Meat"/> <rewrite from="Dairy" to="Meat"/> <rewrite from="OtherMeat_Fish" to="Meat"/> <rewrite from="Pork" to="Meat"/> <rewrite from="Poultry" to="Meat"/> <rewrite from="SheepGoat" to="Meat"/> </rewriteSet> <!-- This rewriteSet specifies byAEZ="true", which causes each rewrite to be expanded to 18 elements with the same 'to' attribute, but with the 'from' attributes formed by appending 'AEZ' and zero-padded, 2-digit integers from 1 to 18, i.e., biomassAEZ01, biomassAEZ02, ..., biomassAEZ18. --> <rewriteSet name="landCover" level="LandLeaf" byAEZ="true"> <rewrite from="biomass" to="Biomass"/> <rewrite from="Corn" to="Cropland"/> <rewrite from="eucalyptus" to="Cropland"/> <rewrite from="FiberCrop" to="Cropland"/> <rewrite from="FodderGrass" to="Cropland"/> <rewrite from="FodderHerb" to="Cropland"/> <rewrite from="Forest" to="Forest (managed)"/> <rewrite from="Grassland" to="Grass"/> <rewrite from="Jatropha" to="Cropland"/> <rewrite from="MiscCrop" to="Cropland"/> <rewrite from="OilCrop" to="Cropland"/> <rewrite from="OtherArableLand" to="Cropland"/> <rewrite from="OtherGrain" to="Cropland"/> <rewrite from="PalmFruit" to="Cropland"/> <rewrite from="Pasture" to="Pasture (grazed)"/> <rewrite from="ProtectedGrassland" to="Other arable land"/> <rewrite from="ProtectedShrubland" to="Other arable land"/> <rewrite from="ProtectedUnmanagedForest" to="Forest (unmanaged)"/> <rewrite from="ProtectedUnmanagedPasture" to="Pasture (other)"/> <rewrite from="Rice" to="Cropland"/> <rewrite from="RockIceDesert" to="Other land"/> <rewrite from="Root_Tuber" to="Cropland"/> <rewrite from="Shrubland" to="Other arable land"/> <rewrite from="SugarCrop" to="Cropland"/> <rewrite from="Tundra" to="Other land"/> <rewrite from="UnmanagedForest" to="Forest (unmanaged)"/> <rewrite from="UnmanagedPasture" to="Pasture (other)"/> <rewrite from="UrbanLand" to="Other land"/> <rewrite from="Wheat" to="Cropland"/> <rewrite from="willow" to="Cropland"/> <rewrite from="SugarcaneEthanol" to="Cropland"/> </rewriteSet> </rewriteSets>