Skip to content

Latest commit

 

History

History
121 lines (82 loc) · 4.78 KB

tutorial3.rst

File metadata and controls

121 lines (82 loc) · 4.78 KB

Tutorial, Part 3

Here, in Part 3, we will customize the project to:

  • modify chart appearance,
  • add another query and plot the results, and
  • aggregate regions to simplify plot appearance.

3.0 The chart sub-command

The :ref:`chart <chart>` sub-command plots data provided in CSV files. A typical workflow is to run queries on GCAM results to produce CSV files, compute differences and then use chart to plot any or all of this. If you compute custom results, you can store in CSV files as well, and use chart on those.

The :ref:`chart <chart>` sub-command offers numerous options to control the appearance of figures. Take a moment to review this using the link above.

We need to refer to the project file for the tutorial, so we'll present it again here:

.. literalinclude:: ../../pygcam/etc/examples/project.xml
   :language: xml
   :linenos:

Notice the following:

  • Line 50 defines <step name="plotDiff" runFor="policy">, which calls the internal @chart sub-command.

  • The @chart command references 4 variables in curly braces: {diffPlotArgs}, {diffPlots}, {baseline}, and {scenario}.

  • {diffPlotArgs} and {diffPlots} are defined later in the project file (at lines 72 and 75, respectively) while {baseline} and {scenario} are defined internally by the :ref:`run <run>` command.

  • The variable diffPlotArgs provides some options for the chart command that are common to our charts. Consolidating them here allows us to control aesthetics more easily. The following options used are:

    -D {diffsDir} --outputDir figures --years {years} --label --ygrid --zeroLine
    

Where:

  • -D {diffsDir} indicates the directory in which files are found. The value {diffsDir} is filled in at run-time, since it differs for each scenario.
  • --outputDir figures indicates that plots should be written in the directory figures, relative to the directory specified with -D.
  • --years {years} says to plot results for this range of years. The value for {years} is defined at line 12. This is defined in a variable to allow the range to be changed consistently for all plots by changing either the start or end years, defined at lines 10 and 11, which in turn form the value for years
  • --label requests that a label be rendered down the right side of the figure with the name of the file.
  • ygrid requests that light grey horizontal lines at major Y-axis values.
  • --zeroLine requests a line drawn at zero on all figures

Lines 75-81, starting with <tmpFile varName="diffPlots"> defines a temporary file whose contents are composed from the enclosed <text> elements, and whose name is stored in the project variable named diffPlots. (Temporary files are deleted before :doc:`gcamtool` exits.) The chart sub-command can be passed the name of a file containing options defining a plot to create, one plot per line. The options on each line of this file are combined with those at the command-line level (in this case via {diffPlotArgs}. This is complicated, but it reduces a lot of redundancy.

CSV files generated by queries include the name of the query (with spaces replaced by hyphens) followed by a hyphen and the scenario name. CSV files generated by the :ref:`diff <diff>` sub-command have a similar convention, but the name includes both the scenario and baseline names, separated by a hyphen. Thus, the results from the difference file created by running the query titled "Land Use Change Emission" on both the baseline and policy and subtracting, is called:

Land_Use_Change_Emission-{scenario}-{reference}.csv

3.1 Modify plot appearance

We will now modify the plot slightly. Let's:

  • make the label black, rather than light grey
  • add a box around the plot
  • remove the grid lines
  • remove the zero line

We do this by changing the definition of plotDiffArgs to this:

<var name="diffPlotArgs" eval="1">-D {diffsDir} --outputDir figures --years {years} --label --labelColor=black --box</var>

To regenerate the figure for the tax-10 scenario, run this command:

$ gt run -S tax-10 -s plotDiff

The Land Use Change Emissions plot now looks like this:


images/tutorial/Land_Use_Change_Emission-tax-10-base-by-region-mod1.*

Let's also change the number of columns in the legend by changing -n 4 on line 76 to -n 3, so the legend isn't quite so wide. Run the plotDiff step again, as above. We now see:


images/tutorial/Land_Use_Change_Emission-tax-10-base-by-region-mod2.*

In :doc:`tutorial4`, we will modify our queries to aggregate into a smaller number of regions.