Histograms in C# QuickStart Sample

Illustrates how to create histograms using the Histogram class in the Numerics.NET.DataAnalysis namespace in C#.

This sample is also available in: Visual Basic, F#, IronPython.

Overview

This QuickStart sample demonstrates how to create and work with histograms using the Histogram class in Numerics.NET.

The sample shows several different ways to create histograms:

  • Creating histograms with evenly spaced bins by specifying bounds and bin count
  • Creating histograms with explicitly specified bin boundaries
  • Creating histograms using Index objects to define bins
  • Creating histograms for categorical data

It demonstrates key histogram operations including:

  • Adding data to histograms using the Tabulate method
  • Incrementing individual bins
  • Accessing bin information like bounds and counts
  • Finding which bin contains a specific value
  • Iterating through bins and their values
  • Working with both numerical and categorical data

The sample uses a practical example of analyzing test scores to illustrate these concepts. It shows how to create different binning strategies and how to work with the resulting histogram data structures.

The code

using System;

using Numerics.NET.DataAnalysis;
using Numerics.NET;
using Index = Numerics.NET.DataAnalysis.Index;

// Illustrates the use of the Histogram class.

// The license is verified at runtime. We're using
// a 30 day trial key here. For more information, see
//     https://numerics.net/trial-key
Numerics.NET.License.Verify("your-trial-key-here");

// Histograms are used to summarize the distribution of data.
// This QuickStart sample creates a histogram from data
// in a variety of ways.

// We use the test scores of students on a hypothetical national test.
// First we create a NumericalVariable that holds the test scores.
var group1Results = Vector.Create(
    62, 77, 61, 94, 75, 82, 86, 83, 64, 84,
    68, 82, 72, 71, 85, 66, 61, 79, 81, 73);

// We can create a histogram with evenly spaced bins
// by specifying the lower bound, the upper bound,
// and the number of bins:
var histogram1 = Histogram.CreateEmpty(50, 100, 5);

// We can also provide the bounds explicitly:
int[] bounds = new int[] {50, 62, 74, 88, 100};
var histogram2 = Histogram.CreateEmpty(bounds);

// Or we can first create an Index object
var index = Index.CreateBins(bounds);
var histogram3 = Histogram.CreateEmpty(index);

// To tally the results, we simply call the Tabulate method.
// The data can be supplied as a vector:
histogram1.Tabulate(group1Results);
// or simply as any enumerable, including an array:
histogram2.Tabulate(group1Results.ToArray());

// You can add multiple data sets to the same histogram:
histogram2.Tabulate(new int[] {74, 68, 89});
// Or you can add individual data points using the Increment method.
// This will increment the count of the bin that contains
// the specified value:
histogram2.Increment(83);
histogram2.Increment(78);

// Histograms are just vectors, so the SetToZero method
// clears all the data:
histogram2.SetToZero();

// The Bins property returns an index of bins:
var bins = histogram1.Bins;
// The Length property returns the total number of bins:
Console.WriteLine($"# bins: {bins.Length}");
// For binned histograms, the bins are of type Interval<T>:
Interval<int> bin = bins[2];
// Interval structures have a lower bound, an upper bound:
Console.WriteLine($"Bin 2 has lower bound {bin.LowerBound}.");
Console.WriteLine($"Bin 2 has upper bound {bin.UpperBound}.");
// You can get the value at a specific bin using the Get method:
Console.WriteLine($"Bin 2 has value {histogram1.Get(bin)}.");

// The histogram's FindBin method returns the Histogram bin
// that contains a specified value:
bin = histogram1.FindBin(83);
Console.WriteLine($"83 is in bin {bin}");

// You can use the BinsAndValues property to iterate through all the bins
// in a for-each loop:
foreach(var pair in histogram1.BinsAndValues)
    Console.WriteLine("Bin {0}: {1}", pair.Key, pair.Value);

// You can also create histograms for categorical data:
var success = Vector.CreateCategorical(
    new bool[] { true, false, true, true, false });
var histogram4 = success.CreateHistogram();
// Bins for categorical histograms are just the categories:
var successes = histogram4.Get(true);
Console.WriteLine(successes);

Console.Write("Press any key to exit.");
Console.ReadLine();