ContinuousHistogram.cs

// AForge Math Library
// AForge.NET framework
// http://www.aforgenet.com/framework/
//
// Copyright © AForge.NET, 2007-2011
// contacts@aforgenet.com
//

namespace AForge.Math
{
    using System;

    /// <summary>
    /// Histogram for continuous random values.
    /// </summary>
    /// 
    /// <remarks><para>The class wraps histogram for continuous stochastic function, which is represented
    /// by integer array and range of the function. Values of the integer array are treated
    /// as total amount of hits on the corresponding subranges, which are calculated by splitting the
    /// specified range into required amount of consequent ranges.</para>
    /// 
    /// <para>For example, if the integer array is equal to { 1, 2, 4, 8, 16 } and the range is set
    /// to [0, 1], then the histogram consists of next subranges:
    /// <list type="bullet">
    /// <item>[0.0, 0.2] - 1 hit;</item>
    /// <item>[0.2, 0.4] - 2 hits;</item>
    /// <item>[0.4, 0.6] - 4 hits;</item>
    /// <item>[0.6, 0.8] - 8 hits;</item>
    /// <item>[0.8, 1.0] - 16 hits.</item>
    /// </list>
    /// </para>
    /// 
    /// <para>Sample usage:</para>
    /// <code>
    /// // create histogram
    /// ContinuousHistogram histogram = new ContinuousHistogram(
    ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
    /// // get mean and standard deviation values
    /// Console.WriteLine( "mean = " + histogram.Mean + ", std.dev = " + histogram.StdDev );
    /// </code>
    /// </remarks>
    /// 
    [Serializable]
    public class ContinuousHistogram
    {
        private int[] values;
        private Range range;

        private float mean;
        private float stdDev;
        private float median;
        private float min;
        private float max;
        private int   total;

        /// <summary>
        /// Values of the histogram.
        /// </summary>
        /// 
        public int[] Values
        {
            get { return values; }
        }

        /// <summary>
        /// Range of random values.
        /// </summary>
        /// 
        public Range Range
        {
            get { return range; }
        }

        /// <summary>
        /// Mean value.
        /// </summary>
        /// 
        /// <remarks><para>The property allows to retrieve mean value of the histogram.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get mean value (= 0.505 )
        /// Console.WriteLine( "mean = " + histogram.Mean.ToString( "F3" ) );
        /// </code>
        /// </remarks>
        /// 
        public float Mean
        {
            get { return mean; }
        }

        /// <summary>
        /// Standard deviation.
        /// </summary>
        /// 
        /// <remarks><para>The property allows to retrieve standard deviation value of the histogram.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get std.dev. value (= 0.215)
        /// Console.WriteLine( "std.dev. = " + histogram.StdDev.ToString( "F3" ) );
        /// </code>
        /// </remarks>
        /// 
        public float StdDev
        {
            get { return stdDev; }
        }

        /// <summary>
        /// Median value.
        /// </summary>
        /// 
        /// <remarks><para>The property allows to retrieve median value of the histogram.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get median value (= 0.500)
        /// Console.WriteLine( "median = " + histogram.Median.ToString( "F3" ) );
        /// </code>
        /// </remarks>
        /// 
        public float Median
        {
            get { return median; }
        }

        /// <summary>
        /// Minimum value.
        /// </summary>
        /// 
        /// <remarks><para>The property allows to retrieve minimum value of the histogram with non zero
        /// hits count.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get min value (= 0.250)
        /// Console.WriteLine( "min = " + histogram.Min.ToString( "F3" ) );
        /// </code>
        /// </remarks>
        public float Min
        {
            get { return min; }
        }

        /// <summary>
        /// Maximum value.
        /// </summary>
        /// 
        /// <remarks><para>The property allows to retrieve maximum value of the histogram with non zero
        /// hits count.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get max value (= 0.875)
        /// Console.WriteLine( "max = " + histogram.Max.ToString( "F3" ) );
        /// </code>
        /// </remarks>
        /// 
        public float Max
        {
            get { return max; }
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="ContinuousHistogram"/> class.
        /// </summary>
        /// 
        /// <param name="values">Values of the histogram.</param>
        /// <param name="range">Range of random values.</param>
        /// 
        /// <remarks>Values of the integer array are treated as total amount of hits on the
        /// corresponding subranges, which are calculated by splitting the specified range into
        /// required amount of consequent ranges (see <see cref="ContinuousHistogram"/> class
        /// description for more information).
        /// </remarks>
        /// 
        public ContinuousHistogram( int[] values, Range range )
        {
            this.values = values;
            this.range  = range;

            Update( );
        }

        /// <summary>
        /// Get range around median containing specified percentage of values.
        /// </summary>
        /// 
        /// <param name="percent">Values percentage around median.</param>
        /// 
        /// <returns>Returns the range which containes specifies percentage of values.</returns>
        /// 
        /// <remarks><para>The method calculates range of stochastic variable, which summary probability
        /// comprises the specified percentage of histogram's hits.</para>
        /// 
        /// <para>Sample usage:</para>
        /// <code>
        /// // create histogram
        /// ContinuousHistogram histogram = new ContinuousHistogram(
        ///     new int[] { 0, 0, 8, 4, 2, 4, 7, 1, 0 }, new Range( 0.0f, 1.0f ) );
        /// // get 50% range
        /// Range range = histogram.GetRange( 0.5f );
        /// // show the range ([0.25, 0.75])
        /// Console.WriteLine( "50% range = [" + range.Min + ", " + range.Max + "]" );
        /// </code>
        /// </remarks>
        /// 
        public Range GetRange( float percent )
        {
            int min, max, hits;
            int h = (int) ( total * ( percent + ( 1 - percent ) / 2 ) );
            int n = values.Length;
            int nM1 = n - 1;

            // skip left portion
            for ( min = 0, hits = total; min < n; min++ )
            {
                hits -= values[min];
                if ( hits < h )
                    break;
            }
            // skip right portion
            for ( max = nM1, hits = total; max >= 0; max-- )
            {
                hits -= values[max];
                if ( hits < h )
                    break;
            }
            // return range between left and right boundaries
            return new Range(
                ( (float) min / nM1 ) * range.Length + range.Min,
                ( (float) max / nM1 ) * range.Length + range.Min );
        }

        /// <summary>
        /// Update statistical value of the histogram.
        /// </summary>
        /// 
        /// <remarks>The method recalculates statistical values of the histogram, like mean,
        /// standard deviation, etc. The method should be called only in the case if histogram
        /// values were retrieved through <see cref="Values"/> property and updated after that.
        /// </remarks>
        /// 
        public void Update( )
        {
            int hits;
            int i, n = values.Length;
            int nM1 = n - 1;

            float rangeLength = range.Length;
            float rangeMin = range.Min;

            max    = 0;
            min    = n;
            mean   = 0;
            stdDev = 0;
            total  = 0;

            double sum = 0;

            // calculate mean, min, max
            for ( i = 0; i < n; i++ )
            {
                hits = values[i];

                if ( hits != 0 )
                {
                    // max
                    if ( i > max )
                        max = i;
                    // min
                    if ( i < min )
                        min = i;
                }

                // accumulate total value
                total += hits;
                // accumulate mean value
                sum += ( ( (double) i / nM1 ) * rangeLength + rangeMin ) * hits;
            }

            if ( total != 0 )
            {
                mean = (float) ( sum / total );
            }

            min = ( min / nM1 ) * rangeLength + rangeMin;
            max = ( max / nM1 ) * rangeLength + rangeMin;

            // calculate stadard deviation
            sum = 0;
            double diff;

            for ( i = 0; i < n; i++ )
            {
                hits = values[i];
                diff = ( ( (double) i / nM1 ) * rangeLength + rangeMin ) - mean;
                sum += diff * diff * hits;
            }

            if ( total != 0 )
            {
                stdDev = (float) Math.Sqrt( sum / total );
            }

            // calculate median
            int m, halfTotal = total / 2;

            for ( m = 0, hits = 0; m < n; m++ )
            {
                hits += values[m];
                if ( hits >= halfTotal )
                    break;
            }
            median = ( (float) m / nM1 ) * rangeLength + rangeMin;
        }
    }
}