Series

• Oct 12, 2020
• 13 minutes to read

A series is a group of data points that have the same argument and value types. The series type determines the number of values that are required to define a point; it also specifies point appearance. Series can also have additional series elements that help analyze data and provide extra information; series also allow you to filter data before displaying it in a chart.

The following image displays the Area, Line and Side-by-Side Bar series in a 2D XY Diagram:

This document consists of the following sections:

• How to: Create a Series
• How to: Populate a Series with Data
• MVVM Binding
• Series Types
• Series Elements
• Colorize Series

How to: Create Series

Use one of the approaches below to add series to a chart.

Manually Create a Series

The following example shows how to add an empty series to a chart:

XAML

<dxc:ChartControl x:Name="chart">
    <dxc:XYDiagram2D>
        <dxc:PointSeries2D DisplayName="New Series"/>
    </dxc:XYDiagram2D>
</dxc:ChartControl>

The table below lists classes and properties used by the markup above:

Diagram.Series	The diagram series’ collection. The context property: you can declare series directly after a diagram’s declaration in XAML.
Series	The base class for all individual series in the chart.

Create a Series From a Data Source

The following code generates series from a data source:

XAML

<dxc:ChartControl DataSource="{Binding AnnualSales}">
    <dxc:ChartControl.DataContext>
        <local:AnnualSalesViewModel>
    </dxc:ChartControl.DataContext>
    <dxc:ChartControl.Diagram>
        <dxc:XYDiagram2D SeriesDataMember="Year">
            <dxc:XYDiagram2D.SeriesTemplate>
                <dxc:BarSideBySideSeries2D ArgumentDataMember="Region"
                                           ValueDataMember="Value"/>
            </dxc:XYDiagram2D.SeriesTemplate>
        </dxc:XYDiagram2D>
    </dxc:ChartControl.Diagram>
</dxc:ChartControl>

C#

public class AnnualSalesViewModel {
    public IReadOnlyList<AnnualSalesItem> AnnualSales { get; }

    public AnnualSalesViewModel() {
        AnnualSales = new List<AnnualSalesItem>() {
            new AnnualSalesItem(2015, "Asia", 4.23D),
            new AnnualSalesItem(2015, "North America", 3.485D),
            new AnnualSalesItem(2015, "Europe", 3.088D),
            new AnnualSalesItem(2015, "Australia", 1.78D),
            new AnnualSalesItem(2015, "South America", 1.602D),
            new AnnualSalesItem(2016, "Asia", 4.768D),
            new AnnualSalesItem(2016, "North America", 3.747D),
            new AnnualSalesItem(2016, "Europe", 3.357D),
            new AnnualSalesItem(2016, "Australia", 1.957D),
            new AnnualSalesItem(2016, "South America", 1.823D),
            new AnnualSalesItem(2017, "Asia", 5.289D),
            new AnnualSalesItem(2017, "North America", 4.182D),
            new AnnualSalesItem(2017, "Europe", 3.725D),
            new AnnualSalesItem(2017, "Australia", 2.272D),
            new AnnualSalesItem(2017, "South America", 2.117D)
        };
    }
}

public class AnnualSalesItem {
    public int Year { get; }
    public String Region { get; }
    public decimal Value { get; }

    public AnnualSalesItem(int year, string region, decimal value) {
        this.Year = year;
        this.Region = region;
        this.Value = value;
    }
}

VB.NET

Public Class AnnualSalesViewModel
    Public ReadOnly Property AnnualSales As IReadOnlyList(Of AnnualSalesItem)

    Public Sub New()
        AnnualSales = New List(Of AnnualSalesItem) From {
            New AnnualSalesItem(2015, "Asia", 4.23D),
            New AnnualSalesItem(2015, "North America", 3.485D),
            New AnnualSalesItem(2015, "Europe", 3.088D),
            New AnnualSalesItem(2015, "Australia", 1.78D),
            New AnnualSalesItem(2015, "South America", 1.602D),
            New AnnualSalesItem(2016, "Asia", 4.768D),
            New AnnualSalesItem(2016, "North America", 3.747D),
            New AnnualSalesItem(2016, "Europe", 3.357D),
            New AnnualSalesItem(2016, "Australia", 1.957D),
            New AnnualSalesItem(2016, "South America", 1.823D),
            New AnnualSalesItem(2017, "Asia", 5.289D),
            New AnnualSalesItem(2017, "North America", 4.182D),
            New AnnualSalesItem(2017, "Europe", 3.725D),
            New AnnualSalesItem(2017, "Australia", 2.272D),
            New AnnualSalesItem(2017, "South America", 2.117D)
        }
    End Sub
End Class

Public Class AnnualSalesItem
    Public ReadOnly Property Year As Integer
    Public ReadOnly Property Region As String
    Public ReadOnly Property Value As Decimal

    Public Sub New(Year As Integer, Region As String, Value As Decimal)
        Me.Year = Year
        Me.Region = Region
        Me.Value = Value
    End Sub
End Class

The markup above uses the following classes and properties:

Member	Description
ChartControl.DataSource	Gets or sets the chart control’s data source.
Diagram.SeriesTemplate	Specifies the series template settings.
Diagram.SeriesDataMember	Gets or sets the name of the data field whose values are used to automatically generate and populate series.

The Chart control performs the following to generate series from a data source:

1. Groups data source items by an item field the SeriesDataMember property specifies.
2. Creates the same number of series as formed groups, and equals the number of the series data member unique values.
3. Assigns a unique group for each series: Series.DisplayName set to the string representation of the SeriesDataMember value, and the series uses group items to automatically populate series with points.

How to: Populate a Series with Data

The series displays data you provide. This section describes methods you can use to populate series with data:

Manually Add Points to a Series

The following markup adds a Line series with five manually added series points:

XAML

<dxc:ChartControl>
    <dxc:ChartControl.DataContext>
        <local:AnnualSalesViewModel>
    </dxc:ChartControl.DataContext>
    <dxc:XYDiagram2D>
        <dxc:LineSeries2D DisplayName="2017">
            <dxc:SeriesPoint Argument="Asia" Value="5.289"/>
            <dxc:SeriesPoint Argument="North America" Value="4.182"/>
            <dxc:SeriesPoint Argument="Europe" Value="3.725"/>
            <dxc:SeriesPoint Argument="Australia" Value="2.272"/>
            <dxc:SeriesPoint Argument="South America" Value="2.117"/>
        </dxc:LineSeries2D>
    </dxc:XYDiagram2D>
</dxc:ChartControl>

The markup above uses the following classes and properties:

Member	Description
Series.Points	The series’s collection of points.
SeriesPoint	An individual point.

Note that several series require more than one Value per point to display data. These series provide attached properties to specify additional values:

Series	Attached Property
Bubble	BubbleSeries2D.Weight
Stock Candle Stick	FinancialSeries2D.OpenValue FinancialSeries2D.HighValue FinancialSeries2D.LowValue FinancialSeries2D.CloseValue Note that the point’s value should not be specified for the financial series.
Side-by-Side Range Bar Overlapped Range Bar	RangeBarSeries2D.Value2
Range Area	RangeAreaSeries2D.Value2
Range Polar Area	PolarRangeAreaSeries2D.Value2
Range Radar Area	RadarRangeAreaSeries2D.Value2

Populate a series with data from a data source

The following code populates a new series with points from the item collection that the chart’s data context object provides:

XAML

<dxc:ChartControl>
    <dxc:ChartControl.DataContext>
        <local:SalesViewModel>
    <dxc:ChartControl.DataContext>
    <dxc:ChartControl.Diagram>
        <dxc:XYDiagram2D>
            <dxc:XYDiagram2D.Series>
                <dxc:BarSideBySideSeries2D DisplayName="2017"
                                           DataSource="{Binding SalesIn2017}"
                                           ArgumentDataMember="Region"
                                           ValueDataMember="Value"/>
                </dxc:XYDiagram2D.Series>
            </dxc:XYDiagram2D>
        </dxc:ChartControl.Diagram>
</dxc:ChartControl>

C#

public class SalesViewModel {
    public IReadOnlyList<SalesItem> SalesIn2017 { get; }

    public SalesViewModel() {
        SalesIn2017 = new List<SalesItem>() {
            new SalesItem("Asia", 5.289D),
            new SalesItem("North America", 4.182D),
            new SalesItem("Europe", 3.725D),
            new SalesItem("Australia", 2.272D),
            new SalesItem("South America", 2.117D)
        }
    }
}

public class SalesItem {
    public string Region { get; }
    public decimal Value { get; }

    public SalesItem(string region, decimal value) {
        this.Region = region
        this.Value = value
    }
}

VB.NET

Public Class SalesViewModel
    Public ReadOnly Property SalesIn2017 As IReadOnlyList(Of SalesItem)

    Public Sub New()
        SalesIn2017 = New List(Of SalesItem) From {
            New SalesItem("Asia", 5.289D),
            New SalesItem("North America", 4.182D),
            New SalesItem("Europe", 3.725D),
            New SalesItem("Australia", 2.272D),
            New SalesItem("South America", 2.117D)
        }
    End Sub
End Class

Public Class SalesItem
    Public ReadOnly Property Region As String
    Public ReadOnly Property Value As Decimal

    Public Sub New(Region As String, Value As Decimal)
        Me.Region = Region
        Me.Value = Value
    End Sub
End Class

This code utilizes the following classes and properties:

Member	Description
Series.DataSource	Specifies the series’s data source.
Series.ArgumentDataMember	Gets or sets the name of the data field which contains arguments for generated series points.
Series.ValueDataMember	Gets or sets the name of the data field which contains values for generated series points.

To populate series with points from a data source, the chart control generates a series point for each data item. Then, series points use the argument data member’s values as Argument values and the value data member’s values as Value values.

Note that several series require more than one ValueDataMember specified to display data. The following table lists series that have specific ValueDataMember parameters:

Series	Parameters
Bubble	Series.ValueDataMember BubbleSeries2D.WeightDataMember
Stock Candle Stick	FinancialSeries2D.OpenValueDataMember FinancialSeries2D.HighValueDataMember FinancialSeries2D.LowValueDataMember FinancialSeries2D.CloseValueDataMember
Side-by-Side Range Bar Overlapped Range Bar	Series.ValueDataMember RangeBarSeries2D.Value2DataMember
Range Area	Series.ValueDataMember RangeAreaSeries2D.Value2DataMember
Range Polar Area Range Radar Area	Series.ValueDataMember CircularRangeAreaSeries2D.Value2DataMember

Important

The Series.Points property returns series points that represent data source values on a chart. The first time you access this property, the series generates series points when the chart/series is bound to data. It is recommended that you avoid using this property, because series point generation requires additional time to convert internal data objects to series points, which in turn can lead to control freezes.

Refer to the Lesson 3 - Bind Chart Series to Data topic for a step-by-step guide that explains how to create a chart, and bind it to a data source.

MVVM Binding

Use the Diagram.SeriesItemsSource property to bind a chart to a collection of series view models when your application uses the MVVM (Model-View-ViewModel) architecture. The Diagram.SeriesItemTemplate and Diagram.SeriesItemTemplateSelector properties specify how the chart converts view model objects to series.

The following code uses the MVVM architecture to populate the Chart Control with series:

View Example

MainWindow.xaml

<dxc:ChartControl>
    <dxc:ChartControl.Legends>
        <dxc:Legend HorizontalPosition="Left" VerticalPosition="Top" Orientation="Horizontal"/>
    </dxc:ChartControl.Legends>
    <dxc:XYDiagram2D SeriesItemsSource="{Binding GdpSeries}">
        <dxc:XYDiagram2D.SeriesItemTemplate>
            <DataTemplate>
                <dxc:LineSeries2D DisplayName="{Binding CountryName}"
                                  DataSource="{Binding Values}"
                                  ArgumentDataMember="Year"
                                  ValueDataMember="Value"/>
            </DataTemplate>
        </dxc:XYDiagram2D.SeriesItemTemplate>
    </dxc:XYDiagram2D>
</dxc:ChartControl>

ChartViewModel.cs

public class ChartViewModel {
    public IEnumerable<GdpSeries> GdpSeries { get; private set; }

    public ChartViewModel() {
        GdpSeries = new Collection<GdpSeries> {
            new GdpSeries {
                CountryName = "USA",
                Values = new Collection<Gdp> {
                    new Gdp { Year = 2015, Value = 18.037},
                    new Gdp { Year = 2014, Value = 17.393},
                    new Gdp { Year = 2013, Value = 16.692},
                    new Gdp { Year = 2012, Value = 16.155},
                    new Gdp { Year = 2011, Value = 15.518},
                    new Gdp { Year = 2010, Value = 14.964},
                    new Gdp { Year = 2009, Value = 14.419},
                    new Gdp { Year = 2008, Value = 14.719}
                }
            },
            new GdpSeries {
                CountryName = "China",
                Values = new Collection<Gdp> {
                    new Gdp { Year = 2015, Value = 11.065},
                    new Gdp { Year = 2014, Value = 10.482},
                    new Gdp { Year = 2013, Value = 9.607},
                    new Gdp { Year = 2012, Value = 8.561},
                    new Gdp { Year = 2011, Value = 7.573},
                    new Gdp { Year = 2010, Value = 6.101},
                    new Gdp { Year = 2009, Value = 5.11},
                    new Gdp { Year = 2008, Value = 4.598}
                }
            },
            new GdpSeries {
                CountryName = "Japan",
                Values = new Collection<Gdp> {
                    new Gdp { Year = 2015, Value = 4.383},
                    new Gdp { Year = 2014, Value = 4.849},
                    new Gdp { Year = 2013, Value = 5.156},
                    new Gdp { Year = 2012, Value = 6.203},
                    new Gdp { Year = 2011, Value = 6.157},
                    new Gdp { Year = 2010, Value = 5.7},
                    new Gdp { Year = 2009, Value = 5.231},
                    new Gdp { Year = 2008, Value = 5.038}
                }
            }
        };
    }
}

ChartViewModel.vb

Public Class ChartViewModel
    Private privateGdpSeries As IEnumerable(Of GdpSeries)
    Public Property GdpSeries() As IEnumerable(Of GdpSeries)
        Get
            Return privateGdpSeries
        End Get
        Private Set(ByVal value As IEnumerable(Of GdpSeries))
            privateGdpSeries = value
        End Set
    End Property

    Public Sub New()
        GdpSeries = New Collection(Of GdpSeries) From { _
            New GdpSeries With { _
                .CountryName = "USA", .Values = New Collection(Of Gdp) From { _
                    New Gdp With {.Year = 2015, .Value = 18.037}, _
                    New Gdp With {.Year = 2014, .Value = 17.393}, _
                    New Gdp With {.Year = 2013, .Value = 16.692}, _
                    New Gdp With {.Year = 2012, .Value = 16.155}, _
                    New Gdp With {.Year = 2011, .Value = 15.518}, _
                    New Gdp With {.Year = 2010, .Value = 14.964}, _
                    New Gdp With {.Year = 2009, .Value = 14.419}, _
                    New Gdp With {.Year = 2008, .Value = 14.719} _
                } _
            }, _
            New GdpSeries With { _
                .CountryName = "China", .Values = New Collection(Of Gdp) From { _
                    New Gdp With {.Year = 2015, .Value = 11.065}, _
                    New Gdp With {.Year = 2014, .Value = 10.482}, _
                    New Gdp With {.Year = 2013, .Value = 9.607}, _
                    New Gdp With {.Year = 2012, .Value = 8.561}, _
                    New Gdp With {.Year = 2011, .Value = 7.573}, _
                    New Gdp With {.Year = 2010, .Value = 6.101}, _
                    New Gdp With {.Year = 2009, .Value = 5.11}, _
                    New Gdp With {.Year = 2008, .Value = 4.598} _
                } _
            }, _
            New GdpSeries With { _
                .CountryName = "Japan", .Values = New Collection(Of Gdp) From { _
                    New Gdp With {.Year = 2015, .Value = 4.383}, _
                    New Gdp With {.Year = 2014, .Value = 4.849}, _
                    New Gdp With {.Year = 2013, .Value = 5.156}, _
                    New Gdp With {.Year = 2012, .Value = 6.203}, _
                    New Gdp With {.Year = 2011, .Value = 6.157}, _
                    New Gdp With {.Year = 2010, .Value = 5.7}, _
                    New Gdp With {.Year = 2009, .Value = 5.231}, _
                    New Gdp With {.Year = 2008, .Value = 5.038} _
                } _
            } _
        }
    End Sub
End Class

GdpSeries.cs

public class GdpSeries {
    public String CountryName { get; set; }
    public IEnumerable<Gdp> Values { get; set; }
}

public class Gdp {
    public int Year { get; set; }
    public double Value { get; set; }
}

GdpSeries.vb

Public Class GdpSeries
    Public Property CountryName() As String
    Public Property Values() As IEnumerable(Of Gdp)
End Class

Public Class Gdp
    Public Property Year() As Integer
    Public Property Value() As Double
End Class

The code above utilizes the properties below:

Member	Description
Diagram.SeriesItemsSource	Gets or sets the collection of objects used to generate series.
Diagram.SeriesItemTemplate	Gets or sets the DataTemplate that specifies how to convert a model object to a series.
Diagram.SeriesItemTemplateSelector	Gets or sets the custom logic for selecting a data template that converts a model object to a series.

Series Types

The Chart Control provides 2D and 3D series. The following sections list all available series:

• 2D Series Types
• 3D Series Types

Note that series of each type have unique specifics and settings. The control can only simultaneously display different types of series if they are compatible.

Series Elements

Element	Image
Series point labels You can show points with labels to provide extra information, such as point arguments or values.
Total labels Total labels display summary values of several Bar Stacked or Pie series’ points.
Indicators Indicators help you to analyze and process series data visually.
Series titles A series title provides additional information on a series.

Colorize Series

The XYSeries.Brush property allows you to specify series color. The Area Series and Funnel Series provide the Border properties that contain the Brush property. This property specifies the series’ border brush:

The following markup demonstrates how to specify a custom color for a series:

Xaml

<dxc:ChartControl Padding="0">
    <dxc:ChartControl.DataContext>
        <local:MainViewModel/>
    </dxc:ChartControl.DataContext>
    <dxc:ChartControl.Diagram>
        <dxc:XYDiagram2D>
            <dxc:XYDiagram2D.Series>
                <dxc:SplineAreaSeries2D DataSource="{Binding History}"
                                        ArgumentDataMember="Date"
                                        ValueDataMember="Balance"
                                        Brush="#43a047">
                    <dxc:SplineAreaSeries2D.Border>
                        <dxc:SeriesBorder Brush="#88000000"/>
                    </dxc:SplineAreaSeries2D.Border>
                </dxc:SplineAreaSeries2D>
            </dxc:XYDiagram2D.Series>
        </dxc:XYDiagram2D>
    </dxc:ChartControl.Diagram>
</dxc:ChartControl>

C# View & ViewModel

class HistoryItem {
    public DateTime Date { get; set; }
    public double Balance { get; set; }
}

class MainViewModel {
    public IReadOnlyList<HistoryItem> History { get; }

    public MainViewModel() {
        DateTime initDate = DateTime.Now;
        History = new List<HistoryItem> {
            new HistoryItem { Date = initDate, Balance = 277 },
            new HistoryItem { Date = initDate.AddYears(-1), Balance = 328.5 },
            new HistoryItem { Date = initDate.AddYears(-2), Balance = 297 },
            new HistoryItem { Date = initDate.AddYears(-3), Balance = 255.3 },
            new HistoryItem { Date = initDate.AddYears(-4), Balance = 173.5 },
            new HistoryItem { Date = initDate.AddYears(-5), Balance = 131.8 },
        };
    }
}

VB View & ViewModel

Class HistoryItem
    Public Property Date As DateTime
    Public Property Balance As Double
End Class

class MainViewModel {
    Public Property History As IReadOnlyList(Of HistoryItem)

    Public Sub New()
        Dim initDate As DateTime = DateTime.Now
        History = New List(Of HistoryItem) From {
            New HistoryItem { .Date = initDate, .Balance = 277 },
            New HistoryItem { .Date = initDate.AddYears(-1), .Balance = 328.5 },
            New HistoryItem { .Date = initDate.AddYears(-2), .Balance = 297 },
            New HistoryItem { .Date = initDate.AddYears(-3), .Balance = 255.3 },
            New HistoryItem { .Date = initDate.AddYears(-4), .Balance = 173.5 },
            New HistoryItem { .Date = initDate.AddYears(-5), .Balance = 131.8 },
        }
    End Sub
End Class

The classes and properties below configure series’ colors:

Symbol	Description
XYSeries.Brush	Gets or sets the color of the XY-series.
AreaSeries2D.Border AreaStackedSeries2D.Border CircularAreaSeries2D.Border	Provides access to a series border’s settings.
SeriesBorder	Contains settings the specify the appearance of a series border.

Important

The Chart Control can use only SolidColorBrush objects to draw series.

Note

The pie/donut series and funnel series do not provide series color and you should utilize series points’ brushes

Tip

Use the ChartControl.BoundDataChanged event to specify colors of series generated via the Series Template.