Skip to content

Commit d443349

Browse files
docs(chart): general data binding for numerical series; mixing series types
1 parent 66cf4dc commit d443349

File tree

3 files changed

+165
-3
lines changed

3 files changed

+165
-3
lines changed

components/chart/data-bind.md

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,29 @@ There are two key ways to bind data to the chart series and axes:
1919

2020
You can, of course, [mix these approaches](#mixed-data-source).
2121

22+
## Series Types
23+
24+
There are three main types of chart in terms of the data they require for their x-axis:
25+
26+
* **Categorical** - series like Area, Line, Column require a set of categories to match the data points values against. Those categories can be shared among different series, or unique. The categories are usually strings, but can also be [dates]({%slug components/chart/date-axis%}). While there are X and Y axes, the x-axis is not a progression of numerical values - spacing between all x-axis items is equal and they show the text of the category.
27+
* **Numerical** - series like Bubble, Scatter and Scatter Line represent two numerical values for the X and Y axes. They do not use categories on the x-axis and thus each data point is independent. This makes it easier to bind each series to a separate collection of data that can have different number of items in it, because plotting the data points is not dependent on string categories, but on numeric values that will be plotted and spaced according to their values.
28+
* **Axis-free** - series like Pie and Donut do not have a x-axis at all. They use categories to build a list of items for each series and show those categories in the legend, as opposed to the series name that is usually shown by the other chart types.
29+
30+
With this in mind, the information below is applicable for all chart types, but the finer points are mostly relevant to categorical charts.
31+
32+
## Mixing Series
33+
34+
You can use only series with the same general layout in a single chart. You cannot mix numerical with categorical x-axes in the same chart. For example:
35+
36+
* Line, Area and Column series can be used together.
37+
* Line, Area and Bar series can be used together. To rotate the layout of the chart according to the way Bar charts render, the bar series must be declared first. Otherwise, a column layout will be used.
38+
* Bar and Column charts have a different layout and the rendering will depend on the first declared series.
39+
* Scatter and ScatterLine series can be used together.
40+
* Bubble charts cannot be used with other chart types because they have a very distinct layout due to the Size dimension.
41+
* Pie and Donut charts will render only one series per chart and so only one can be used at a time.
42+
43+
44+
2245
## Independent Series Binding
2346

2447
In the simplest case, you provide two collections to the chart:
@@ -287,6 +310,145 @@ Standalone categories are ignored when there is category data binding to a model
287310
288311
![](images/standalone-categories-ignored-if-bound-from-series.png)
289312

313+
314+
## Numerical Charts
315+
316+
Numerical charts do not use categories and you do not need to consider how the x-axis is shared between the series and whether several data points will be in the same zone. You can provide a model for each series that contains the necessary information (x-value, y-value, and any other value that may be needed, such as size for bubble charts) and they will be plotted independently.
317+
318+
If one series has more data points than another, you will not get empty items on the x-axis, all data points are plotted according to general mathematical rules on the axes.
319+
320+
This means that it is often suitable to provide each series with its own collection of data, and these collections can often use the same model. You can still data bind the entire chart to a single collection, or use any of the approaches above.
321+
322+
>caption Series with a different number of items can be easily used in numerical charts
323+
324+
````CSHTML
325+
326+
@* Standalone collections of the same model type are used for the different series without consideration for matching categories *@
327+
328+
<TelerikChart>
329+
<ChartTitle Text="Unrecoverable Errors Per Minute vs. Signal Level"></ChartTitle>
330+
331+
<ChartSeriesItems>
332+
<ChartSeries Type="ChartSeriesType.Scatter"
333+
Data="@Series1Data"
334+
Name="APSK modulation"
335+
XField="@nameof(ModelData.Strength)"
336+
YField="@nameof(ModelData.Errors)">
337+
</ChartSeries>
338+
339+
<ChartSeries Type="ChartSeriesType.Scatter"
340+
Data="@Series2Data"
341+
Name="QAM modulation"
342+
XField="@nameof(ModelData.Strength)"
343+
YField="@nameof(ModelData.Errors)">
344+
</ChartSeries>
345+
</ChartSeriesItems>
346+
347+
<ChartXAxes>
348+
<ChartXAxis Max="-30" AxisCrossingValue="@(new object[] { -100 })">
349+
<ChartXAxisTitle Text="Signal Strength, dBm"></ChartXAxisTitle>
350+
</ChartXAxis>
351+
</ChartXAxes>
352+
353+
<ChartYAxes>
354+
<ChartYAxis>
355+
<ChartYAxisTitle Text="Error count"></ChartYAxisTitle>
356+
</ChartYAxis>
357+
</ChartYAxes>
358+
</TelerikChart>
359+
360+
@code {
361+
public class ModelData
362+
{
363+
public double Strength { get; set; }
364+
public double Errors { get; set; }
365+
}
366+
367+
public List<ModelData> Series1Data = new List<ModelData>()
368+
{
369+
new ModelData { Strength = -82, Errors = 15 },
370+
new ModelData { Strength = -79, Errors = 13 },
371+
new ModelData { Strength = -77, Errors = 10 },
372+
new ModelData { Strength = -74, Errors = 7 },
373+
new ModelData { Strength = -70, Errors = 3 },
374+
new ModelData { Strength = -65, Errors = 1 }
375+
};
376+
377+
public List<ModelData> Series2Data = new List<ModelData>()
378+
{
379+
new ModelData { Strength = -80, Errors = 25 },
380+
new ModelData { Strength = -76, Errors = 22 },
381+
new ModelData { Strength = -73, Errors = 17 },
382+
new ModelData { Strength = -70, Errors = 15 },
383+
new ModelData { Strength = -65, Errors = 12 },
384+
new ModelData { Strength = -61, Errors = 10 },
385+
new ModelData { Strength = -55, Errors = 7 },
386+
new ModelData { Strength = -50, Errors = 3 }
387+
};
388+
}
389+
````
390+
391+
>caption The same chart bound to a single model with fields for each series
392+
393+
````CSHTML
394+
@* You can also have a different number of series item if you bind the entire chart to the same model *@
395+
396+
<TelerikChart>
397+
<ChartTitle Text="Unrecoverable Errors Per Minute vs. Signal Level"></ChartTitle>
398+
399+
<ChartSeriesItems>
400+
<ChartSeries Type="ChartSeriesType.Scatter"
401+
Data="@AllChartData"
402+
Name="APSK modulation"
403+
XField="@nameof(ModelData.ApskStrength)"
404+
YField="@nameof(ModelData.ApskErrors)">
405+
</ChartSeries>
406+
407+
<ChartSeries Type="ChartSeriesType.Scatter"
408+
Data="@AllChartData"
409+
Name="QAM modulation"
410+
XField="@nameof(ModelData.QamStrength)"
411+
YField="@nameof(ModelData.QamErrors)">
412+
</ChartSeries>
413+
</ChartSeriesItems>
414+
415+
<ChartXAxes>
416+
<ChartXAxis Max="-30" AxisCrossingValue="@(new object[] { -100 })">
417+
<ChartXAxisTitle Text="Signal Strength, dBm"></ChartXAxisTitle>
418+
</ChartXAxis>
419+
</ChartXAxes>
420+
421+
<ChartYAxes>
422+
<ChartYAxis>
423+
<ChartYAxisTitle Text="Error count"></ChartYAxisTitle>
424+
</ChartYAxis>
425+
</ChartYAxes>
426+
</TelerikChart>
427+
428+
@code {
429+
public class ModelData
430+
{
431+
public double ApskStrength { get; set; }
432+
public double ApskErrors { get; set; }
433+
public double QamStrength { get; set; }
434+
public double QamErrors { get; set; }
435+
}
436+
437+
public List<ModelData> AllChartData = new List<ModelData>()
438+
{
439+
new ModelData { QamStrength = -80, QamErrors = 25, ApskStrength = -82, ApskErrors = 15 },
440+
new ModelData { QamStrength = -76, QamErrors = 22, ApskStrength = -79, ApskErrors = 13 },
441+
new ModelData { QamStrength = -73, QamErrors = 17, ApskStrength = -77, ApskErrors = 10 },
442+
new ModelData { QamStrength = -70, QamErrors = 15, ApskStrength = -74, ApskErrors = 7 },
443+
new ModelData { QamStrength = -65, QamErrors = 12, ApskStrength = -70, ApskErrors = 3 },
444+
new ModelData { QamStrength = -61, QamErrors = 10, ApskStrength = -65, ApskErrors = 1 },
445+
new ModelData { QamStrength = -55, QamErrors = 7 },
446+
new ModelData { QamStrength = -50, QamErrors = 3 }
447+
};
448+
}
449+
450+
````
451+
290452
## See Also
291453

292454
* [Live Demos: Chart](https://demos.telerik.com/blazor-ui/chart/index)

components/chart/types/bubble.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ To create a bubble chart:
2424

2525
1. add a `ChartSeries` to the `ChartSeriesItems` collection
2626
2. set its `Type` property to `ChartSeriesType.Bubble`
27-
3. provide a data collection to its `Data` property, which contains numerical data for the X and Y axes, and for the buble size
27+
3. provide a data collection to its `Data` property, which contains numerical data for the X and Y axes, and for the bubble size
2828

2929

3030
>caption A bubble chart that shows projected population change on a plot of life expectancy versus fertility rate
@@ -124,4 +124,4 @@ The size field should, generally, have positive values as it correlates to the p
124124

125125
## See Also
126126

127-
* [Live Demo: Area Chart](https://demos.telerik.com/blazor-ui/chart/area-chart)
127+
* [Live Demo: Bubble Chart](https://demos.telerik.com/blazor-ui/chart/bubble-chart)

components/chart/types/scatter.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,4 +107,4 @@ The `ColorField` can change the color of individual items. To use it, pass a val
107107

108108
## See Also
109109

110-
* [Live Demo: Area Chart](https://demos.telerik.com/blazor-ui/chart/area-chart)
110+
* [Live Demo: Scatter Chart](https://demos.telerik.com/blazor-ui/chart/scatter-chart)

0 commit comments

Comments
 (0)