Visit Gigasoft's Web Site
ProEssentials v8 Help

Chapter 6: Date/Time Handling

 

The Graph and Scientific Graph have different methods of getting dates along the x axis.

 

We will first discuss the easiest date-time, the Scientific Graph Object and next the Graph Object.

Scientific Graph with Dates along X Axis

The Scientific Graph has a mechanism for handling date/time formatted data. It uses XData or XDataII to store serially formatted data. Using correctly formatted data and setting the DateTimeMode property to reflect that format will cause the normal numerical x axis to be replaced with a linear date/time calendar axis. This date/time scale is dynamic and will adjust in structure based upon the date/time range currently shown. This allows the end-user to zoom and always have an appropriate x axis scale to match the range of time graphed.

 

The date format is constructed from integer and decimal portions. The integer portion is the number of days from 12/31/1899. The decimal portion is the fraction of day.

 

If your date/time data is not in a compatible format, ProEssentials includes the function PEcreateserialdate to create the proper format.

 

Above we mentioned both XData and XDataII. The property you will use depends on the type of date/time data you are graphing.

 

If your data includes Date and Time:

Use XDataII for double precision storage and set UsingXDataII equal to TRUE.

 

If your data includes only Dates:

Use XData for single precision storage.

 

The following example code show how to use DateTimeMode.

 

Pesgo1.PeData.Subsets = 1;
Pesgo1.PeData.Points = 4;
Pesgo1.PeData.Xii[0, 0] = DateTime.Now.ToOADate();
Pesgo1.PeData.Xii[0, 1] = DateTime.Now.ToOADate()+20;
Pesgo1.PeData.Xii[0, 2] = DateTime.Now.ToOADate()+40;
Pesgo1.PeData.Xii[0, 3] = DateTime.Now.ToOADate()+60; // creates 60 day range
Pesgo1.PeData.UsingXDataii = true;
Pesgo1.PeData.DateTimeMode = true;
Pesgo1.PePlot.Method = SGraphPlottingMethod.PointsPlusLine;
Pesgo1.PeGrid.Configure.AutoMinMaxPadding = 10;
Pesgo1.PeFunction.ReinitializeResetImage();

 

The above example code produces the following graph.

 

The Scientific Graph shows all time within its range (continuous time). All 24 hours and all days of the week will show between the start date/time on the left and the ending date/time on the right. If your data is discontinuous, (from 8am to 5pm Monday through Friday), the Graph Object's date/time mechanism may be a better choice.

 

Note that the use of DateTimeMode is not compatible with ManualXAxisTicknLine. If you need a specific looking date/time scale, you will have to manually produce this scale as described in Chapter 6 Creating Custom Scales. When we hear of developers wanting a custom date time scale for the Pesgo, it's mostly related to a time spans of hours, seconds, milliseconds. In such a case, it may be best to not enable DateTimeMode, use XData that describes an offset or run-time type value, and then optionally use the feature as in example 132 to produce a custom scale.

 

Within the demo and example projects, see example 106 and 135.

 

Graph Objects with Dates along X Axis

With the Graph Object, you have two choices.

  1. Simply assign PointLabels for each data-point.

  2. Use the DateTimeMode feature.

1. Assigning PointLabels

Point labels are text-strings, so assigning a date is accomplished by passing a string formatted as desired. For example, "2/26/14" or "Feb 26, 14" could be passed as a point label. These point labels are placed below the x axis and also below the corresponding data-point. If your graph has many data-points, you may want to control the frequency and first point label location. In this case, refer to Chapter 6 Graph Object's X Axis for more information.

2. Using DateTimeMode

Using DateTimeMode with the Graph Object is a specialized mechanism to plot date/times along the x axis. This feature can handle discontinuous time data (for example, time values from 8am to 5pm Monday through Friday) however, the data needs to be quantified. This mode will automatically and dynamically construct a linear date/time calendar along the x axis. As the user zooms, this scale will change in structure to best accommodate the range of time.

 

There are several related properties which need to be used to implement this feature:

 

DeltaX

DeltasPerDay

StartTime

AutoXData

XData, XDataII, UsingXDataII

 

You can quickly see there's more going-on than just setting PointLabels, or just the Pesgo's XData.

 

The first thing you need to decide is if you are working with intra-day, daily, weekly, or monthly data. Lets start with intra-day, this is the most involved but is also the most common.

 

For Intra-Day Data

DeltaX needs to be set to the number of minutes between each data point. Common values will be 1, 2, 5, but any value will work. 1 meaning 1 minute, 2 meaning 2 minutes, and so on. Thus you can see what we mean by quantified. Each data point represents the value at a quantity of time.

 

DeltasPerDay needs to be set to the number of data points in a day. Each day will have to have the same number of data points. If your DeltasPerDay is set to 300, then you need 300 pieces of YData for each day. No more. No less. If you don't have a valid data value for a particular time segment, assign a NullDataValue to this location.

StartTime represents a Date/Time value of the first data point in the chart. This is a serially formatted double precision floating point value similar to the format that VB and Delphi use to represent Date/Times. If not using VB or Delphi, you can use the function PEcreateserialdate to create a date/time value in the proper format.

 

AutoXData is optional but recommended. If you don't manually assign XData, this feature will automatically generate XData during the object's initialization. If dealing with Intra-Day data, be sure to set UsingXDataII to TRUE. Either set AutoXData to 0 (PEAXD_ALLDAYS) for ProEssentials to generate XData which includes all days of the week; or set AutoXData to 1 (PEAXD_NOSATORSUN) for ProEssentials to generate XData which skips Saturdays and Sundays.  AutoXData simplifies your implementation as you don't set XData, however, you must set YData to match what the chart is expecting to find, simply the DeltasPerDay amount of values per day.

 

XData/XDataII can be set manually. ProEssentials will look to see if XData or XDataII exists. If it does, it will not use AutoXData to automatically generate XData. If your data skips days such as Monday and Tuesday, then you will have to manually construct XData. Look at the example code below for an example of creating XData manually.

 

UsingXDataII should be set to TRUE for Intra-Day data and left FALSE for daily, weekly, or monthly data.

 

Following is an example of using DateTimeMode and AutoXData.

 

Pego1.PeData.Subsets = 1;
Pego1.PeData.Points = 3000;
Pego1.PeData.DeltaX = 2;
Pego1.PeData.DeltasPerDay = 210;
Pego1.PeData.StartTime = DateTime.Now.ToOADate();
Pego1.PeData.UsingXDataii = true;
Pego1.PeData.AutoXData = AutoXData.IncludeSatSun;
Pego1.PeData.DateTimeMode = true;
for (int p = 0; p < 3000; p++)
    Pego1.PeData.Y[0, p] = 5.0F + (float) Math.Sin(p * 0.024F);

 

The above code produces the following image. Note that it's not important that the last day has DeltasPerDay data points, just the starting day and all days between the first and last day.

 

Now lets repeat the example but this time generate XDataII manually. Study this example if you will be constructing your own XData manually. This above code produces the same image as above.

 

Pego1.PeData.Subsets = 1;
Pego1.PeData.Points = 3000;
Pego1.PeData.DeltaX = 2;
Pego1.PeData.DeltasPerDay = 210;
Pego1.PeData.StartTime = DateTime.Now.ToOADate() + 0.333333333333333F; // Today 8:00am
Pego1.PeData.UsingXDataii = true;
Pego1.PeData.DateTimeMode = true;
double d = DateTime.Now.ToOADate();
int i = 0;
for (int p = 0; p < 3000; p++)
{
    Pego1.PeData.Y[0, p] = 5.0F + (float) Math.Sin(p * 0.024F);
    Pego1.PeData.Xii[0, p] = d + 0.333333333333333F + (((i * 2.0F) / 60.0F) / 24.0F);
    // 2 represents data every two minutes, same as DeltaX
    // 60 represents 60 minutes in an hour
    // 24 represents 24 hours in a day
    i = i + 1; // increment data per day counter
    if (i >= 210) // 210 is DeltasPerDay as above
    {
        i = 0; // reset data per day counter
        d = d + 1; // increment day
    }
}

 

 

For Daily, Weekly, Monthly Data

These types of charts are easier than the Intra-Day chart.

 

Set DeltaX as follows...

 

DeltaX

Type of Data

- 1 (negative 1)

Daily

- 2

Weekly

- 3

Monthly

 

DeltasPerDay is ignored.

 

UsingXDataII can be left the default state FALSE. Double precision is not needed for Daily, Weekly, or Monthly data.

 

StartTime, AutoXData, XData are used as above.

 

For Daily Data, make sure you have one data point for each day. If there is a day with no data, assign the NullDataValue to this data point. You do not have to have a full year's worth of data points for the last year shown, only the first year and every year between the first and last. If a leap year exists in your data, you need to account for this in your data and have an extra data point as necessary.

 

For Weekly Data, make sure you have 52 weekly data points per year. You do not have to have 52 data points in the last year shown.

 

For Monthly Data, make sure you have 12 monthly data points per year. You do not have to have 12 data points in the last year shown.

 

Below is an example of a Daily Data Chart.

 

Pego1.PeData.Subsets = 1;
Pego1.PeData.Points = 300;
Pego1.PeData.DeltaX = -1; // daily data, 300 days, almost 1 year of data
Pego1.PeData.StartTime = DateTime.Now.ToOADate();
Pego1.PeData.AutoXData = AutoXData.IncludeSatSun;
Pego1.PeData.DateTimeMode = true;
for (int p = 0; p < 300; p++)
    Pego1.PeData.Y[0, p] = 5.0F + (float)

The resulting image is shown below.

 

As with the Scientific Graph Object, note that the use of DateTimeMode is not compatible with ManualXAxisTicknLine. If you need a specific looking date/time scale, you will have to manually produce this scale as described in to Chapter 6 Creating Custom Scales.

 

Within the demo and example projects, see examples 016, and 030.