Basics of Defining a Chart in XML

<?xml version='1.0' encoding='utf-8' ?>
<visualizations>
  <chart>
    <x_axis/>
    <y_axis/>
    <legend/>
    <series_list >
      <series /> 
         . . .
      <series /> 
    </series_list>
    <filters>
      <filter/>
         . . .
      <filter/>
    </filters>  
  </chart>
</visualizations>

Below is an example of a simple single-series chart and the XML required to create it

<?xml version='1.0' encoding='utf-8' ?>

<visualizations owner='' access='public' force_recalc='1'>

  <chart title='Basin Average Annual Precipitation'
            type='line' bkgr_color='#ffffff'
            input_dir='/Envision/StudyAreas/BigWood/Outputs'
            data_dir ='/Explorer/Topic/Explorer/Charts/Data' >

    <x_axis label='Year'
               src='Ref/Run0/ModelOutput_Ref_Run0.csv'
               col='Year' format='' min_val='auto' max_val='auto'
               type='day'
               start_year='1980'/>

    <y_axis label='Inches'
               src ='auto' 
               format='g' 
               min_val='auto' 
               max_val='auto'  
               type=''/>

    <legend item_width='120' float='1' />

    <series_list >

      <series label='Historic'
                 src='Ref_Historic/Run0/Basin_Climate_Ref_Historic_Run0.csv'
                 col='Basin Mean Daily Precip (mm)' 
                 x_src='Ref_Historic/Run0/Basin_Climate_Ref_Historic_Run0.csv' 
                 x_col='0' 
                 color='black' 
                 width='2' 
                 line_style='solid' 
                 marker='none' 
                 transform='xrange(1,10950);periodmean(365);yscale(14.37)' 
                 /> 

    </series_list>
    
    <filters>
      <filter id='filter' type='textbox' text='' />
    </filters>
  
  </chart>
</visualizations>

Attributes for Chart XML are described next.

Chart XML Elements

Chart XML files are XML-compliant text files consisting of a single <visualizations">tag with the following attributes

Within the visualizations, <chart> tag define individual charts to be displayed. Attributes of the chart tag are given below. In addition to these attributes, child tags define various aspects of the chart.

Chart Types

The table below provides a list of available chart types.

Defining the X-Axis

The X-Axis of a chart is defined within the <x_axis> child tag within the parent <chart> tag. Attributes of the <x_axis> tag are:

Defining the Y-Axis

The Y-Axis of a chart is defined within the <y_axis> child tag within the parent <chart> tag. Attributes of the <y_axis> tag are:

Defining the Chart Legend

The Chart Legend is defined within the <legend> child tag within the parent <chart> tag. Attributes of the <legend> tag are:

Defining the Chart Series

A Chart Series is a set of data that define a single line (or area) on a chart. Charts can have zero or more series. Each series is defined within the chart's <series_list> tag. Within the <series_list> tag, child <series> tags define individual series. The <series_list> tag has a single, optional attribute, 'autogen'. Setting 'autogen' to 1 will generate a series for every column on the input data source (CSV file) defined for the Y-Axis - this is a good shortcut for rapidly viewing, via a chart, the contents of the CSV file. When defining series manually, use the <series> tag, one for each series. Attributes of the <series> tag are:

Transforms

Transforms modify the datasets they operate on. Transforms are applied using a pipeline model; multiple transforms operate on a dataset in series. The first listed transform is applied first; the results of that tranform are passed down the pipeline, where the second transform is applied. This process repeats until all transforms have been processed. Note that transforms may change the shape (i.e. number of rows and/or columns) of the dataset; this may have consequences for subsequent transforms in the pipeline. For those transforms that modify the shape of the data, check the "Notes" section below - any shape changes associated with a tranform are noted there.

The table below list transforms available for data manipulation for charting. Multiple tranforms may be specified in a pipeline by separating individual transforms with a ';' (semicolon).

Including Charts in an Explorer Page

Including charts in an Explorer page requires adding markup text to the page to include an aspx ChartControl for each chart you want on the page. The ChartControl includes a "Src" attribute that specifies where to find the XML describing the chart. Additionally, each ChartControl must have a unique ID attribute.

This markup text generally takes one of two forms: One presenting the chart with a caption, one without. Examples of both are provided below. In both cases, the real work is done in the <viz:ChartControl> tag.

In both cases, we need to register the ChartControl at the top of the aspx page (after the "Page" directive, before any content sections) as follows:

<%@ Register TagPrefix="viz" Namespace="EnvChart" Assembly="EnvChart" %>

Including a Chart Without a Caption

<viz:ChartControl ID='ch1' Height="560" Src="BasinAvgPrecip.xml" runat="server" ></viz:ChartControl>

Including a Chart and Caption - for this example, we add a caption using a table.

<div>
   <table style="height:560px;width:100%;">
      <tr class="caption" style="width:100%;">
         <td><span style="font-weight:bold;">Average Precipitation by Climate Model</span></td>
      </tr>
      <tr class="chart">
         <td class="chart" style="width:100%;">
            <viz:ChartControl ID='ch1' Height="560" Src="BasinAvgPrecip.xml" runat="server"></viz:ChartControl>
         </td>
      </tr>
   </table>
</div>