Overview
Data is filtered on a series-by-series basis, and when it is filtered, its data points are either removed from the series' Points collection (which is the default behavior), or marked as being empty. The points that get filtered depends on the filtering criteria specified. When you are working with your data, keep in mind that a filtering operation can modify the original series' data, and also that you can use an output series to store modified series data.
 Note |
|---|
| When filtering multiple series, you must make certain that all of those series are aligned, otherwise an exception will be thrown. |
For more information, see the topic on Aligning Series.
| Note |
|---|
| The term "constant" is used in this article to refer to an integer value. |
Filtering Data
Several properties and methods of the DataManipulator class are used for filtering, these include:
- FilterSetEmptyPoints property. This property determines if filtering, as a result of a Filter or FilterTopN method call, will remove data points from the collection (its default behavior), or mark them as empty points. For more information, see the topic on Empty Points.
- FilterMatchedPoints property. If this property is True (its default value), then all points that match its filtering criteria will get filtered. If it is set to False, points that do not match the filtering criteria will get filtered. This property does not apply to the FilterTopN method.
- Filter method. This property filters a series' data points using a date or time range, or a comparison of a data point value to a number value, or some custom user-defined criteria.
- FilterTopN method. This property filters a series' data points, and removes, or sets as empty, all points except for those with either the largest or smallest values in the series. This property does not apply to FilterMatchedPoints method.
The Filter, and FilterTopN methods take these parameters:
- Filtering criteria. One or more arguments that define the filtering criteria.
- Input series. Defines the input data for the filtering operation. Can be specified as a Series object, or as a string with comma-separated series names.
- Output series. Defines the series to be used to store the resulting data following a filtering operation. The output series parameter is optional, and as as such can be left blank. However, you should note that, if you choose not to specify an output series, then the result of the filtering operation will be stored in the input series, overriding the original series' data. For this parameter you can specify a Series object, or a string with comma-separated series names.
If you specify a Series object as an output series, and that series has not been created and added to the SeriesCollection, then when the function call is made an exception will be thrown. However, if the series has not been created and added to the series collection, but it has been specified as a string expression, then it will automatically be created at run-time, and have default series properties (e.g. column chart type, etc.) assigned to it. In addition to this, the ChartArea property of this series will get set to "Default". If a chart area with the name "Default" already exists in the ChartAreasCollection, then it will be used to draw the chart. If there is no chart area name "Default", then the first ChartArea object in the collection will be used to display the series.
Filtering Using Date or Time Ranges
This criteria can be used when the X values of the data points are dates (set by a Series' XValueType property), and is accomplished using the Filter method. Series data is split into ranges where the defined elements of the range are filtered. To define a date range use two parameters:
- dateRange of type DateRangeType. Defines the type of the range used, and can be DayOfWeek, DayOfMonth, Month, etc.
- rangeElements of type string. This defines which elements inside the range are filtered. This parameter lets you specify multiple elements by using a comma, or dash separated list (e.g. "1-10, 20, 25").
Note
A week always starts with Sunday and ends with Saturday.
Filtering All Points Except for the Largest or Smallest Points
Filters all points from a series except for a specified number of points with the largest or smallest point values. This filtering criteria is used with FilterTopN method, and the following parameters can be used to define the criteria:
- pointCount of type Int32. Number of largest or smallest points to retain.
- usingValues of type string (optional). Defines the point values to be used in the comparison ("X", "Y", "Y2", "Y3", ...). The default value is the first Y value ("Y").
- getTopValues of type boolean (optional). If set to True the resulting series will contain points with the largest values, otherwise the points with the smallest values will be retained. The default value is True.
Filtering by Comparing Point Values to a Constant
Filters data points by comparing one of their values with a constant, this is done using the Filter method. The following parameters are used:
- compareMethod of type CompareMethod. The comparison operation to be used when comparing the point values with the constant (e.g. less than, etc.).
- compareValue of type double. The constant value to be used in the comparison.
- usingValues of type string (optional). Defines the point value to be used in the comparison ("X", "Y", "Y2", "Y3", ...). The default is the first Y value.
Filtering With User-Defined Criteria
When the filtering criteria is complex and cannot be defined using the methods described above then a user-defined criteria can be specified using the IDataPointFilter interface. This interface exposes the FilterDataPoint method, which determines the data points to be removed. The following are the parameters of the FilterDataPoint method and its return value:
- point of type DataPoint . The point object to be filtered.
- series of type Series. The series that the point belongs to.
- pointIndex of type Int32. The data point's index in the data point collection of the Series object.
- Return true if the point should be filtered, otherwise return false.
Filtering Multiple Series
The filtering methods of the DataManipulator class allow you to simultaneously filteri multiple aligned series by specifying a comma-separated list of series names. All points in each series will be filtered using the values from the first series. In other words, data points with the same indexes will be removed from all series depending on whether or not a point in the first series is filtered.
Some Points to Note
- Remember to align multiple series when filtering, otherwise an exception will be thrown. For more information on aligning Series, see the topic on Aligning Series.
- You can filter two series independently by calling the Filter method twice while using one input series.
- If you use an output series, then the number of output series must be the same as the number of input series, otherwise an exception will be thrown.
- All series in the chart's Series collection may be filtered with one method call if a "*" is specified as an input string.