G-Cubed charts

Overview

The gcubed Python package includes two applications that assist with visualizing projections generated using G-Cubed models. They can be used with levels projections and with deviations between projections.

To use the applications, you first need to run a G-Cubed experiment and saving a set of projections (in levels or deviations) as a CSV file. Throughout this documentation, that projections data file will be referred to with the name projections_data.csv. However, you can name the file as you wish, so long as it has a .csv extension.

They requires Python and the gcubed package to be installed.

They are started from the terminal prompt and will display the graphics application in a new tab in your default web browser.

The two applications differ slightly in their functionality.

The first application, G-Cubed Chart, supports exploration of the projections for a single variable. It provides extensive search functionality to find the right variable to chart. It requires you to search for and select the variable of interest from the projections data file that you have uploaded in your web browser.

If you have a specific set of charts that you would like to view repeatedy, you can use the second application, G-Cubed Chart-Pack, that can plot multiple charts, each of which can contain multiple series. G-Cubed Chart-Pack` requires you to upload both the projections data file and the file containing the definition of the chart-pack that interests you.

Setup

If you have set up the G-Cubed environment, you should be ready to use G-Cubed Charts.

Start G-Cubed graphics applications

For the G-Cubed Chart application, run the following command at the terminal prompt:

python -m gcubed.graphics

For the G-Cubed Chart-Pack application, run the following command at the terminal prompt:

python -m gcubed.graphics.charts

For the streamlined G-Cubed Chart-Pack application, run the following command at the terminal prompt:

python -m gcubed.graphics.hypercube

All of these commands will open a new tab in your default web browser. The applications will work in your web browser even when there is no Internet connection.

The G-Cubed Chart application

First upload the projections data file to the G-Cubed Chart application. This will then populate the variable search system, enabling you to find and select the variable to display in the chart.

Once the projections data file has been uploaded, the File status will show the name of the file and you can now start choosing variables.

In Variable selection section, you can type any text substring that you want to use to search for the variable of interest. It will be matched against the variable name, its description, its units, the type of variable it is, and the region it is associated with. The text search is case-insensitive.

For example, if you are interested in inflation related variables, you can type ‘inf’. Then the dropdown menu will show those variables of your interest.

Another way to conveniently choose variables is to use the Limit search... checkboxes. Click any of the checkboxes and new dropdown menus will appear. Use them to restrict the set variables that can match your variable search.

In Graphing options section, you can set the year range that you are interested in for your chosen variable. You can type in the start year and end year at your discretion, or you can use the default year (2018-2050) or full year range provided in the projections data file by clicking one of the buttons.

Some helpful tips

Hover your mouse over the graph and some useful icons will show up in the top-right corner. The camera-shaped icon can be used to save the chart as a PNG image file.

The G-Cubed Chart-Pack application

First upload the chart-pack file to the G-Cubed Chart-Pack application.

Next upload the projections data file to the G-Cubed Chart application. This will then populate the variable search system.

Once both files have been uploaded file has been uploaded, the charts will display.

There will be one chart for each chart defined in the chart-pack file.

In each chart, there will be one series plotted for each series associated with the chart in the chart-pack file.

The G-Cubed Hypercube application

The hypercube application is only available in G-Cubed Python version 2.0.0.3 and later.

The Hypercube application is a fancy version of the chart-pack application. It is fully backward compatible with the chart pack files used with the chart-pack application but it does require projections CSV files that have been accessed using the gcubed.projections.charting_projections property as opposed to the gcubed.projections.annotated_publishable_projections property of a projections object.

The projections CSV files used with the Hypercube application must have an additional column documenting the details of each variable that has been projected so that the title and legend for each chart can be automatically generated from the variable specified for each series in the chart.

The benefit of the hypercube application over the chart-pack application is that you do not need to specify colors or labels for the series and you do not need to specify a label for the chart. All of that information is deduced from the information about each variable in the chart. That information is based upon the documentation in the model SYM files.

Otherwise, usage of the hypercube application is identical to usage of the chart-pack application.

Eventually the chart-pack application will be deprecated and the hypercube application will replace it.

G-Cubed Chart-Pack file format

An example chart-pack file is available.

The G-Cubed Chart-Pack file must be a CSV file. The file must have exactly 6 columns.

Each row in the file describes one of the following object types:

  • pack - The chart pack itself. A chart pack file must only have one row that describes the pack.
  • chart - A chart. A chart pack file must have at least one row that describes a chart.
  • series - A series in a chart. Each chart in a chart pack file must have at least one row that describes a series.

The file must have a header row. The header row must contain the following columns:

  1. type - one of pack, chart, or series, depending on the type of chart-pack object being described by the row.
  2. attributes - The attributes of the object.
  3. variable - The full name of the variable (capitalisation matters). This is only used in series rows.
  4. label - The text string label describing the object, used for pack and chart titles and series legends.

The attributes column contains zero or more name-value pairs, separated by the | character. The following attributes are supported:

  • color - The color to be used for the line showing a series. Valid values for the color attribute are any value HTML color strings. e.g.:
    • blue
    • red
    • #ff0000
    • #f00
    • rgb(255,0,0)
    • rgba(255,0,0,0.5)
  • start_year=YYYY the first year to show in the horizontal axis of the chart. e.g. start_year=2018.

  • end_year=YYYY the last year to show in the horizontal axis of the chart. e.g. end_year=2050.

To specify a chart from 2020 to 2030, the attributes cell for the chart would contain start_year=2020|end_year=2030.

Additional attributes to provide more control over chart formatting may be supported in the future.

Ordering of rows in a G-Cubed Chart-Pack file

The chart pack is created in the order of the rows in the chart pack definition file. Thus, the pack row must be the first row in the file.

This pack row is then followed by a chart row.

The chart row is followed by its series rows.

If there is another chart in the pack, the row for that chart comes next and it is followed by its series rows.

This continues until all charts in the pack have been defined.

Charts are shown in the order that they are documented in the chart-pack file.

To reorder charts in the pack, reorder the rows in the chart pack definition file.