Histograms#

class sage.plot.histogram.Histogram(datalist, options)[source]#

Bases: GraphicPrimitive

Graphics primitive that represents a histogram. This takes quite a few options as well.

EXAMPLES:

sage: from sage.plot.histogram import Histogram
sage: g = Histogram([1,3,2,0], {}); g
Histogram defined by a data list of size 4
sage: type(g)
<class 'sage.plot.histogram.Histogram'>
sage: opts = { 'bins':20, 'label':'mydata'}
sage: g = Histogram([random() for _ in range(500)], opts); g
Histogram defined by a data list of size 500

>>> from sage.all import *
>>> from sage.plot.histogram import Histogram
>>> g = Histogram([Integer(1),Integer(3),Integer(2),Integer(0)], {}); g
Histogram defined by a data list of size 4
>>> type(g)
<class 'sage.plot.histogram.Histogram'>
>>> opts = { 'bins':Integer(20), 'label':'mydata'}
>>> g = Histogram([random() for _ in range(Integer(500))], opts); g
Histogram defined by a data list of size 500

We can accept multiple sets of the same length:

sage: g = Histogram([[1,3,2,0], [4,4,3,3]], {}); g
Histogram defined by 2 data lists

>>> from sage.all import *
>>> g = Histogram([[Integer(1),Integer(3),Integer(2),Integer(0)], [Integer(4),Integer(4),Integer(3),Integer(3)]], {}); g
Histogram defined by 2 data lists
get_minmax_data()[source]#

Get minimum and maximum horizontal and vertical ranges for the Histogram object.

EXAMPLES:

sage: H = histogram([10,3,5], density=True); h = H[0]
sage: h.get_minmax_data()  # rel tol 1e-15
{'xmax': 10.0, 'xmin': 3.0, 'ymax': 0.4761904761904765, 'ymin': 0}
sage: G = histogram([random() for _ in range(500)]); g = G[0]
sage: g.get_minmax_data() # random output
{'xmax': 0.99729312925213209, 'xmin': 0.00013024562219410285, 'ymax': 61, 'ymin': 0}
sage: Y = histogram([random()*10 for _ in range(500)], range=[2,8]); y = Y[0]
sage: ymm = y.get_minmax_data(); ymm['xmax'], ymm['xmin']
(8.0, 2.0)
sage: Z = histogram([[1,3,2,0], [4,4,3,3]]); z = Z[0]
sage: z.get_minmax_data()
{'xmax': 4.0, 'xmin': 0, 'ymax': 2, 'ymin': 0}

>>> from sage.all import *
>>> H = histogram([Integer(10),Integer(3),Integer(5)], density=True); h = H[Integer(0)]
>>> h.get_minmax_data()  # rel tol 1e-15
{'xmax': 10.0, 'xmin': 3.0, 'ymax': 0.4761904761904765, 'ymin': 0}
>>> G = histogram([random() for _ in range(Integer(500))]); g = G[Integer(0)]
>>> g.get_minmax_data() # random output
{'xmax': 0.99729312925213209, 'xmin': 0.00013024562219410285, 'ymax': 61, 'ymin': 0}
>>> Y = histogram([random()*Integer(10) for _ in range(Integer(500))], range=[Integer(2),Integer(8)]); y = Y[Integer(0)]
>>> ymm = y.get_minmax_data(); ymm['xmax'], ymm['xmin']
(8.0, 2.0)
>>> Z = histogram([[Integer(1),Integer(3),Integer(2),Integer(0)], [Integer(4),Integer(4),Integer(3),Integer(3)]]); z = Z[Integer(0)]
>>> z.get_minmax_data()
{'xmax': 4.0, 'xmin': 0, 'ymax': 2, 'ymin': 0}
sage.plot.histogram.histogram(datalist, aspect_ratio='automatic', align='mid', weights=None, range=None, bins=10, edgecolor='black', **options)[source]#

Computes and draws the histogram for list(s) of numerical data. See examples for the many options; even more customization is available using matplotlib directly.

INPUT:

  • datalist – A list, or a list of lists, of numerical data

  • align – (default: “mid”) How the bars align inside of each bin. Acceptable values are “left”, “right” or “mid”

  • alpha – (float in [0,1], default: 1) The transparency of the plot

  • bins – The number of sections in which to divide the range. Also can be a sequence of points within the range that create the partition

  • color – The color of the face of the bars or list of colors if multiple data sets are given

  • cumulative – (default: False) If True, then a histogram is computed in which each bin gives the counts in that bin plus all bins for smaller values. Negative values give a reversed direction of accumulation

  • edgecolor – The color of the border of each bar

  • fill – (default: True) Whether to fill the bars

  • hatch – (default: None) symbol to fill the bars with; one of “/”, “", “|”, “-”, “+”, “x”, “o”, “O”, “.”, “*”, “” (or None)

  • hue – The color of the bars given as a hue. See hue for more information on the hue

  • label – A string label for each data list given

  • linewidth – (float) width of the lines defining the bars

  • linestyle – (default: ‘solid’) Style of the line. One of ‘solid’ or ‘-’, ‘dashed’ or ‘–’, ‘dotted’ or ‘:’, ‘dashdot’ or ‘-.’

  • density – (default: False) If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1.

  • range – A list [min, max] which define the range of the histogram. Values outside of this range are treated as outliers and omitted from counts

  • rwidth – (float in [0,1], default: 1) The relative width of the bars as a fraction of the bin width

  • stacked – (default: False) If True, multiple data are stacked on top of each other

  • weights – (list) A sequence of weights the same length as the data list. If supplied, then each value contributes its associated weight to the bin count

  • zorder – (integer) the layer level at which to draw the histogram

Note

The weights option works only with a single list. List of lists representing multiple data are not supported.

EXAMPLES:

A very basic histogram for four data points:

sage: histogram([1, 2, 3, 4], bins=2)
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram([Integer(1), Integer(2), Integer(3), Integer(4)], bins=Integer(2))
Graphics object consisting of 1 graphics primitive
../../_images/histogram-1.svg

We can see how the histogram compares to various distributions. Note the use of the density keyword to guarantee the plot looks like the probability density function:

sage: nv = normalvariate
sage: H = histogram([nv(0, 1) for _ in range(1000)], bins=20, density=True, range=[-5, 5])
sage: P = plot(1/sqrt(2*pi)*e^(-x^2/2), (x, -5, 5), color='red', linestyle='--')            # needs sage.symbolic
sage: H + P                                                                     # needs sage.symbolic
Graphics object consisting of 2 graphics primitives

>>> from sage.all import *
>>> nv = normalvariate
>>> H = histogram([nv(Integer(0), Integer(1)) for _ in range(Integer(1000))], bins=Integer(20), density=True, range=[-Integer(5), Integer(5)])
>>> P = plot(Integer(1)/sqrt(Integer(2)*pi)*e**(-x**Integer(2)/Integer(2)), (x, -Integer(5), Integer(5)), color='red', linestyle='--')            # needs sage.symbolic
>>> H + P                                                                     # needs sage.symbolic
Graphics object consisting of 2 graphics primitives
../../_images/histogram-2.svg

There are many options one can use with histograms. Some of these control the presentation of the data, even if it is boring:

sage: histogram(list(range(100)), color=(1,0,0), label='mydata', rwidth=.5, align="right")
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram(list(range(Integer(100))), color=(Integer(1),Integer(0),Integer(0)), label='mydata', rwidth=RealNumber('.5'), align="right")
Graphics object consisting of 1 graphics primitive
../../_images/histogram-3.svg

This includes many usual matplotlib styling options:

sage: T = RealDistribution('lognormal', [0, 1])
sage: histogram( [T.get_random_element() for _ in range(100)], alpha=0.3, edgecolor='red', fill=False, linestyle='dashed', hatch='O', linewidth=5)
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> T = RealDistribution('lognormal', [Integer(0), Integer(1)])
>>> histogram( [T.get_random_element() for _ in range(Integer(100))], alpha=RealNumber('0.3'), edgecolor='red', fill=False, linestyle='dashed', hatch='O', linewidth=Integer(5))
Graphics object consisting of 1 graphics primitive
../../_images/histogram-4.svg
sage: histogram( [T.get_random_element() for _ in range(100)],linestyle='-.')
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram( [T.get_random_element() for _ in range(Integer(100))],linestyle='-.')
Graphics object consisting of 1 graphics primitive
../../_images/histogram-5.svg

We can do several data sets at once if desired:

sage: histogram([srange(0, 1, .1)*10, [nv(0, 1) for _ in range(100)]], color=['red', 'green'], bins=5)
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram([srange(Integer(0), Integer(1), RealNumber('.1'))*Integer(10), [nv(Integer(0), Integer(1)) for _ in range(Integer(100))]], color=['red', 'green'], bins=Integer(5))
Graphics object consisting of 1 graphics primitive
../../_images/histogram-6.svg

We have the option of stacking the data sets too:

sage: histogram([[1, 1, 1, 1, 2, 2, 2, 3, 3, 3], [4, 4, 4, 4, 3, 3, 3, 2, 2, 2] ], stacked=True, color=['blue', 'red'])
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram([[Integer(1), Integer(1), Integer(1), Integer(1), Integer(2), Integer(2), Integer(2), Integer(3), Integer(3), Integer(3)], [Integer(4), Integer(4), Integer(4), Integer(4), Integer(3), Integer(3), Integer(3), Integer(2), Integer(2), Integer(2)] ], stacked=True, color=['blue', 'red'])
Graphics object consisting of 1 graphics primitive
../../_images/histogram-7.svg

It is possible to use weights with the histogram as well:

sage: histogram(list(range(10)), bins=3, weights=[1, 2, 3, 4, 5, 5, 4, 3, 2, 1])
Graphics object consisting of 1 graphics primitive

>>> from sage.all import *
>>> histogram(list(range(Integer(10))), bins=Integer(3), weights=[Integer(1), Integer(2), Integer(3), Integer(4), Integer(5), Integer(5), Integer(4), Integer(3), Integer(2), Integer(1)])
Graphics object consisting of 1 graphics primitive
../../_images/histogram-8.svg