Data is often grouped according to the time period in which they were registered. It is therefore necessary to
provide a mechanism to group time data into categories. The range of the data is divided into a number of intervals,
where each interval becomes a category in a time scale. This type of time scale is implemented by the DateTimeScale class. This class inherits from CategoricalScale, but provides some additional functionality.
Constructing Time Scales
The DateTimeScale class has four constructors. They come in two pairs, each pair offering one
way of defining the intervals that make up the scale.
The first constructor takes one argument: a DateTime array that contains the boundaries of the
intervals. The values in this array must be in ascending order, or an ArgumentException will be
thrown.
| C# |  Copy |
|---|
DateTime start = new DateTime(2005, 11, 15);
DateTime[] bounds = new DateTime[] {start, start.AddDays(10),
start.AddDays(20), start.AddDays(30), start.AddDays(40)};
DateTimeScale scale1 = new DateTimeScale(bounds);
|
| Visual Basic | Copy |
|---|
Dim start As DateTime = New DateTime(2005, 11, 15)
Dim bounds As DateTime() = New DateTime() {start, start.AddDays(10), _
start.AddDays(20), start.AddDays(30), start.AddDays(40)}
Dim scale1 As DateTimeScale = New DateTimeScale(bounds)
|
The second constructor also has a DateTime array as its first argument, but has one additional
argument: a SpecialBins value that specifies which special intervals to include in the scale.
The possible values are as follows:
Values of the SpecialBins enumeration
| Name | TH |
|---|
| None | No special intervals are included. |
| BelowMinimum | There is a special interval for values below the scale's minimum value. |
| AboveMaximum | There is a special interval for values above the scale's maximum value. |
| OutOfRange | There is a special interval for values that are outside the scale's range. |
| Missing | There is a special interval for missing values. |
If BelowMinimum is included, an interval with lower bound DateTime.MinValue is inserted
before all other intervals. If AboveMaximum is included, an interval with upper bound
DateTime.MaxValue is added at the end. The following creates a scale with intervals of one month for the
period November 15, 2005 to March 15, 2006:
| C# | Copy |
|---|
DateTime start = new DateTime(2005, 11, 15);
DateTime[] bounds = new DateTime[] {start, start.AddDays(10),
start.AddDays(20), start.AddDays(30), start.AddDays(40)};
DateTimeScale scale2 = new DateTimeScale(bounds, SpecialBins.BelowMinimum);
|
| Visual Basic | Copy |
|---|
Dim start As DateTime = New DateTime(2005, 11, 15)
Dim bounds As DateTime() = New DateTime() {start, start.AddDays(10), _
start.AddDays(20), start.AddDays(30), start.AddDays(40)}
Dim scale2 As DateTimeScale = New DateTimeScale(bounds, SpecialBins.BelowMinimum)
|
The third constructor takes three arguments. The first two are the lower bound of the first interval, and the
upper bound of the last interval. The third argument is a DateTimeUnit value that specifies the size of
the intervals. The possible values are:
Values of the DateTimeUnit enumeration
| Member Name | Description |
|---|
| The time unit is unknown. |
| The time unit is one hour |
| The time unit is one day. |
| The time unit is one week. |
| The time unit is one month. |
| The time unit is one quarter. |
| The time unit is one year. |
The boundaries of the intervals are set on whole time units. For example, if the lower bound is on the 15th of
march, and the time unit is DateTimeUnit.Month, then the first interval will span the period
March 15 - March 31.
The fourth constructor has one additional argument: a SpecialBins value that indicates which special values should be tabulated in
addition to those within the specified interval.
The code below creates a scale with five intervals for values between 50 and 100:
| C# | Copy |
|---|
DateTime fromDate = new DateTime(2005, 11, 15);
DateTime toDate = new DateTime(2006, 3, 15);
DateTimeScale scale3 = new DateTimeScale(fromDate, toDate, DateTimeUnit.Month);
|
| Visual Basic | Copy |
|---|
Dim fromDate As DateTime = New DateTime(2005, 11, 15)
Dim toDate As DateTime = New DateTime(2006, 3, 15)
Dim scale3 As DateTimeScale = New DateTimeScale(fromDate, toDate, DateTimeUnit.Month)
|
The above scale is made up of 5 intervals. The first and last intervals cover only a part of a month. The three
middle intervals each cover a full month.
Properties and Methods
The Count property returns the number of intervals in
the scale. The IsOrdered property indicates whether
the scale is ordered or unordered. It always returns true.
The GetBounds()()() method returns a
DateTime array containing the boundaries of the intervals. If the BelowMinimum or
AboveMaximum intervals were included, the return value includes these intervals as well.
The GetLowerBound(Int32) and GetUpperBound(Int32) methods take one argument and return the lower
and upper bound of the interval with the specified index.
| C# | Copy |
|---|
Console.WriteLine(scale3.GetLowerBound(2));
Console.WriteLine(scale3.GetUpperBound(2));
|
| Visual Basic | Copy |
|---|
Console.WriteLine(scale3.GetLowerBound(2)) ' Prints '1/1/2006'
Console.WriteLine(scale3.GetUpperBound(2)) ' Prints '2/1/2006'
|
The GetCaption method returns the text label of
the level at the specified level index. The GetCaptions()()() method returns a string array containing the
captions for each level.
The GetEnumerator()()() method returns an
IEnumerator object that can be used to iterate through the levels of the scale.
Mapping Values to Intervals
Time scales convert dates and times to intervals. The Map()()() method provides this functionality.
This method is overloaded. The first overload takes any object as its only argument. This object is converted to a
number using the Convert.ToDateTime method. If this conversion succeeds, the index of the interval
containing the number is returned. If the number is outside the scale, -1 is returned.
The second overload takes an array of objects and returns an integer array of the indexes corresponding to those
objects. Each of these methods takes an optional IFormatProvider argument that is used to convert the
object value to a number.
The DateTimeScale class also provides type-safe overloads. One maps a number to the index of the
interval. The second takes an array and returns an array of indexes.
The example below uses the scale defined earlier. Each line prints the same value ('2'):
| C# | Copy |
|---|
Console.WriteLine(scale3.Map(new DateTime(2006, 1, 6)));
Console.WriteLine(scale3.Map("1/6/2006"));
IFormatProvider provider = System.Globalization.CultureInfo.CreateSpecificCulture("NL-BE").DateTimeFormat
Console.WriteLine(scale3.Map("6/1/2006", provider));
|
| Visual Basic | Copy |
|---|
Console.WriteLine(scale3.Map(New DateTime(2006, 1, 6)))
Console.WriteLine(scale3.Map("1/6/2006"))
Dim provider As IFormatProvider = _
System.Globalization.CultureInfo.CreateSpecificCulture("NL-BE").DateTimeFormat
Console.WriteLine(scale3.Map("6/1/2006", provider));
|
In the last line, the value is provided in a format that uses a month-day-year format. The right
DateTimeFormat is required to make the result correct.