Saving trial results

The file results.xml describes model results that should be saved in the SQL database. The values must be available in CSV files, which are generally the results of queries against the GCAM XML database, or they can be the results of arbitrary calculations.

The general idea is that the results are named, a file is identified, and the location in the file of the relevant values is identified using a combination of <Column> and <Constraint> elements.

Below is a detailed description of the XML elements used in results.xml, and finally, an example file.

XML elements

<ResultList>

This is the top-level element in the results.xml file. It must contain one or more <Result> elements and can contain any number of <comment> elements. The <ResultList> element takes no attributes.

<Result>

The <Result> element describes a single result to store in the SQL database. It may contains zero or one <File> elements, zero or one <Column> elements, and any number of <Constraint> or <comment> elements.

Results can be scalar values or time-series data. If no <Column> element is given, the result is assumed to be a time-series, and values for all year columns are stored in the “timeseries” table in the SQL database. Scalar results are stored in the “outvalue” table.

The <Result> element accepts the following attributes:

Attribute	Required	Default	Values
name	yes	(none)	text
type	yes	(none)	see below
desc	no	(none)	text

The result type must be either “diff” or “scenario”. The prior indicates a result that is the difference between a policy scenario and a baseline, whereas the latter is a result for a single baseline or scenario.

The optional desc attribute allows you to provide a description, which is stored in the database and can be displayed in graphical figures.

<File>

Indicates a CSV file from which to read numerical results.

Attribute	Required	Default	Values
name	yes	(none)	text

<Column>

The <Column> element indicates the column of the CSV file holding the data. If the column holds multiple rows of data, use a <Constraint> element to isolate the desired rows within that column.

Attribute	Required	Default	Values
name	yes	(none)	text

The name attribute identifies the column in the CSV file.

<Constraint>

Describes how to isolate data within a CSV file to save as a named result. This is roughly equivalent to a SQL “where” clause which specifies that a column must have a given relationship to a given value. The column attribute indicates which column to apply the constraint to; the value attribute provides a value to compare against; and the op attribute indicates how to perform the comparison.

Attribute	Required	Default	Values
column	yes	(none)	text
op	yes	(none)	see below
value	yes	(none)	text

The following values for op are recognized:

• ==, =, eq, equal : synonyms for equality, i.e., the value in the named column must be the same as value.
• <>, !=, neq, notEqual, not equal : synonyms for inequaltiy, i.e., the value in the named column must be different than value.
• startswith : the value in the named column must start with the given value.
• endswith : the value in the named column must end with the given value.
• contains : the value in the named column contain the string given in value. Note that contains accepts Python regular expressions, which means special regex characters must be “escaped” by preceding them with a “” character. See the documentation link above for further details.

Example

Following is an example of a results.xml file.

<?xml version="1.0" encoding="UTF-8"?>

<ResultList>
    <comment>
        <Result name="ci-rfs" type="diff"
                desc="Carbon intensity, RFS-style, g CO2e/MJ">
            <File name="carbon_intensity"/>
            <Column name="value"/>
            <Constraint column="method" op="equal" value="ci-rfs-style"/>
        </Result>
    </comment>

    <Result name="ci-luc" type="diff"
            desc="Carbon intensity, LUC-only, g CO2e/MJ">
        <File name="carbon_intensity"/>
        <Column name="value"/>
        <Constraint column="method" op="equal" value="ci-luc-only"/>
    </Result>

    <Result name="ci-all" type="diff"
            desc="Carbon intensity, All GHGs, g CO2e/MJ">
        <File name="carbon_intensity"/>
        <Column name="value"/>
        <Constraint column="method" op="equal" value="ci-all-ghgs"/>
    </Result>

    <Result name="delta-total-forcing" type="diff"
            desc="The change in total forcing between scenarios by timestep (W/m2)">
        <File name="Climate_forcing"/>
    </Result>

    <Result name="delta-total-forcing-2050" type="diff"
            desc="The change in total forcing in 2050 between scenarios (W/m2)">
        <File name="Climate_forcing"/>
        <Column name="2050"/>
    </Result>

    <Result name="fuelEJ" type="diff"
            desc="Change in use of the shocked fuel (EJ)">
        <File name="fuelEJ.csv"/>
        <Column name="value"/>
    </Result>

    <Result name="rebound" desc="Fuel rebound effect" type="diff">
        <File name="fuel_rebound.csv"/>
        <Column name="value"/>
    </Result>

    <Result name="liquidFuelPrice" type="scenario"
            desc="Refined liquids enduse price">
        <File name="Prices_by_sector.csv"/>
        <Constraint column="region" op="equal" value="USA"/>
        <Constraint column="sector" op="equal" value="refined liquids enduse"/>
    </Result>

    <Result name="deltaLiquidFuelPrice" type="diff"
            desc="Change in refined liquids enduse price">
        <File name="Prices_by_sector.csv"/>
        <Constraint column="region" op="equal" value="USA"/>
        <Constraint column="sector" op="equal" value="refined liquids enduse"/>
    </Result>

    <!-- scalar value for correlation plots -->
    <Result name="deltaLiquidFuelPrice-2050" type="diff"
            desc="The change in the price of refined liquids in 2050">
        <File name="Prices_by_sector.csv"/>
        <Column name="2050"/>
        <Constraint column="region" op="equal" value="USA"/>
        <Constraint column="sector" op="equal" value="refined liquids enduse"/>
    </Result>

</ResultList>