WOLFRAM

Wolfram Language & System Documentation Center

BinLists[data]

gives lists of the elements of data whose values lie in successive integer bins.

BinLists[data,binspec]

gives lists of the elements of data whose values lie in successive bins specified by binspec.

BinLists[datainds,…]

gives the lists of the labels inds specified by the binning of data.

Details
Details and Options Details and Options
Examples  
Basic Examples  
Scope  
Basic Uses  
Data with Quantities  
Data with Labels  
Applications  
Properties & Relations  
Possible Issues  
See Also
Related Guides
History
Cite this Page

BinLists

BinLists[data]

gives lists of the elements of data whose values lie in successive integer bins.

BinLists[data,binspec]

gives lists of the elements of data whose values lie in successive bins specified by binspec.

BinLists[datainds,…]

gives the lists of the labels inds specified by the binning of data.

Details

  • BinLists drops elements whose values do not correspond to real numbers.
  • The following bin-width specifications binspec can be given:
  • dxbins of width dx »
    {xmin,xmax,dx}bins of width dx from xmin to xmax »
    {{b1,b2,…}}the intervals [b1,b2), [b2,b3), … »
    xbins,ybins,…bin specifications for multivariate data understood as {{x1,y1,…},{x2,y2, …},…} »
  • BinLists[data,dx] takes the bin boundaries to be integer multiples of dx, with the first bin starting at Ceiling[Min[data]-dx,dx] and the last bin ending at Floor[Max[data]+dx,dx].
  • BinLists[data] is equivalent to BinLists[data,1].
  • In BinLists[data,{xmin,xmax,dx}], elements are placed in bin i when their values satisfy .
  • BinLists[data,{xmin,xmax}] is equivalent to BinLists[data,{xmin,xmax,1}].
  • In BinLists[data,{{b1,b2,…}}], elements are put in bin i when their values satisfy .
  • In the form BinLists[data,{{b1,b2,…}}], the bi at each end can be -Infinity and +Infinity.
  • If the bi do not form an increasing sequence, they are automatically sorted by BinLists.
  • If data consists of length-n sublists, then n bin specifications must be given, and BinLists[data,…] yields an array of lists of depth n.
  • Within each bin, elements appear in the same order as in the original data.
  • The data can have the following forms and interpretations:
  • {x1,x2,…}list of real numbers or quantities »
    {{x1,y1,…},{x2,y2,…},…}list of vectors of the same dimension »
    SparseArrayan array equivalent to Normal[data] »
    QuantityArrayarray of column-compatible quantities »
    TimeSeries, TemporalData,…vector or array of values (the time stamps ignored) »
  • Labels inds for the input elements xi can be given in the following formats: »
  • {x1,x2,…}use the xi themselves (no labels by default)
    {x1,x2,…}Automaticuse integer labels
    {x1,x2,…}{v1,v2,…}a rule between all the elements and all the labels
    {x1v1,x2v2,…}a list of rules between the element xi and its label vi

Examples

open all close all

Basic Examples  (3)

List elements in bins of a specified width:

Wolfram Language code: BinLists[{1, 3, 2, 1, 4, 5, 6, 2}, 2]

Make lists of elements in bins of width 1 from 0 to 10:

Wolfram Language code: BinLists[{1, 3, 2, 1, 4, 5, 6, 2}, {0, 10, 1}]

List elements in a sequence of ranges:

Wolfram Language code: BinLists[{1, 3, 2, 1, 4, 5, 6, 2}, {{-Infinity, 2, 5, 7, Infinity}}]

Scope  (12)

Basic Uses  (8)

List squares mod 3 and 5 in two-dimensional unit bins:

Wolfram Language code: data = Table[Mod[i ^ 2, {3, 5}], {i, 20}]; Dimensions[data]
Wolfram Language code: BinLists[data, 1, 1]

List random pairs in bins of width 0.25 in both dimensions:

Wolfram Language code: data = RandomReal[{-1, 1}, {10, 2}]; Dimensions[data]
Wolfram Language code: BinLists[data, {-1, 1, .25}, {-1, 1, .25}]

List multidimensional data in ranges:

Wolfram Language code: data = RandomReal[{-1, 1}, {10, 2}];
Wolfram Language code: BinLists[data, {{-2, .3, 2}}, {{-1, -.4, .2, 1}}]

Bin data in any dimension:

Wolfram Language code: BinLists[RandomReal[{-1, 1}, {10, 4}]]

Bin data, ignoring values that are not real:

Wolfram Language code: BinLists[{1.5, 3, a, 2.5, 1, I}, 2]

Bin data of any precision:

Wolfram Language code: BinLists[{1.5, 3, N[3, 20], 2.5, 1, E}, 2]

SparseArray data can be used just like dense arrays:

Wolfram Language code: data = SparseArray[{{1, 1} -> 5, {3, 2} -> 4}, {30, 2}]
Wolfram Language code: BinLists[data]
Wolfram Language code: sp = SparseArray[{{i_, i_} :> i, {i_, j_} /; j == i + 1 :> i - 1}, {10, 3}, 3]
Wolfram Language code: BinLists[sp]

Bin data from a time series:

Wolfram Language code: ts = TemporalData[TimeSeries, {{{-0.8514215942160073, 0.498847153572056, -0.5117595526567502, -0.1541269987967291, 0.21199829846035145, 0.7834143496676975, -0.16460155429334833, 0.8166857502105551, -0.662728145444706, -0.9440223497598601, 0.34 ... 0.12583411201016714}}, {TemporalData`DateSpecification[{2014, 2, 2, 0, 0, 0.}, {2014, 2, 14, 0, 0, 0.}, {1, "Day"}]}, 1, {"Continuous", 1}, {"Discrete", 1}, 1, {ResamplingMethod -> {"Interpolation", InterpolationOrder -> 1}}}, True, 10.1];
Wolfram Language code: BinLists[ts]

The time stamps are ignored:

Wolfram Language code: BinLists[ts["Values"]]
Wolfram Language code: % == %%

Data with Quantities  (3)

Bin quantity data:

Wolfram Language code: data = {Quantity[-1.541, "Grams"], Quantity[-0.849, "Grams"], Quantity[-0.477, "Grams"], Quantity[-0.133, "Grams"], Quantity[-0.11, "Grams"], Quantity[-0.054, "Grams"], Quantity[0.226, "Grams"], Quantity[0.259, "Grams"], Quantity[1.4, "Grams"], Quantity[1.661, "Grams"]};

Automatic bins:

Wolfram Language code: BinLists[data]

Specify bin width:

Wolfram Language code: BinLists[data, Quantity[.5, "Grams"]]

Bins of fixed width, minimum and maximum:

Wolfram Language code: BinLists[data, {Quantity[-1, "Grams"], Quantity[1, "Grams"], Quantity[.1, "Grams"]}]

Specify bin intervals:

Wolfram Language code: BinLists[data, {{Quantity[-2, "Grams"], Quantity[0, "Grams"], Quantity[2, "Grams"]}}]

Bin mixed-type data:

Wolfram Language code: mat = RandomReal[10, {3, 3}]; mat[[All, 1]] *= Quantity["Meters"]; mat[[All, 3]] *= Quantity["Seconds"];

The units are compatible for each dimension:

Wolfram Language code: mat//MatrixForm

Specify bin width for each dimension:

Wolfram Language code: BinLists[mat, Quantity[2, "Meters"], 3, Quantity[1, "Seconds"]]

QuantityArray can be used just like arrays:

Wolfram Language code: data = QuantityArray[RandomReal[1, 6], "Pounds"]

Automatic bins:

Wolfram Language code: BinLists[data]

Specify bin width in compatible units:

Wolfram Language code: BinLists[data, Quantity[.2, "Kilograms"]]

Data with Labels  (1)

Bin data with output as an array of labels:

Wolfram Language code: BinLists[{1.5, 3, 2.5, 1, E, 7} -> {"a", "b", "c", "d", "e", "f"}, 2]
Wolfram Language code: BinLists[{1.5 -> "a", 3 -> "b", 2.5 -> "c", 1 -> "d", E -> "e", 7 -> "f"}, 2]

Bin data with default integer labels:

Wolfram Language code: BinLists[{1.5, 3, 2.5, 1, E, 7} -> Automatic, 2]

Applications  (1)

Visualize two-dimensional data in bins:

Wolfram Language code: Flatten[BinLists[RandomReal[10, {10 ^ 4, 2}], 2, 2], 1]//ListPlot

Properties & Relations  (1)

The length of BinLists is equivalent to the results from BinCounts:

Wolfram Language code: data = RandomReal[{-5, 5}, 1000];
Wolfram Language code: Map[Length, BinLists[data]]
Wolfram Language code: BinCounts[data]
Wolfram Language code: %% == %

For a list of vectors:

Wolfram Language code: data2 = RandomReal[{-5, 5}, {1000, 2}];
Wolfram Language code: Map[Length, BinLists[data2], {2}] == BinCounts[data2]

Possible Issues  (4)

Binning intervals are closed on the left:

Wolfram Language code: BinLists[{1, 2, 3, 4, 5}]
Wolfram Language code: BinLists[{1 - $MachineEpsilon, 2, 3, 4, 5}]

For data involving quantities, the bin specification must be given in compatible units:

Wolfram Language code: data = Quantity[RandomReal[1, 20], "Meters"];
Wolfram Language code: BinLists[data, .2]
Wolfram Language code: BinLists[data, Quantity[20, "Centimeters"]]

Matrix data must have unit-compatible columns:

Wolfram Language code: mat = {{Quantity[1.03, "Meters"], Quantity[1.65, "Meters"], Quantity[1.49, "Meters"]}, {4.013, 3.40, 2.5}, {Quantity[3.9, "Seconds"], Quantity[1.88, "Seconds"], Quantity[3.52, "Seconds"]}};
Wolfram Language code: BinLists[mat]
Wolfram Language code: BinLists[Transpose@mat]

The bins obtained using the specification {min,max,dx} may not include all data points:

Wolfram Language code: data = Range[1, 50];
Wolfram Language code: res1 = BinLists[data, {Min[data], Max[data], 10}]
Wolfram Language code: {Length[data], Total[Length /@ res1]}

Specify the min and max so all data points are included in the bin covering:

Wolfram Language code: dx = 10; min = 1; max = min + dx * Ceiling[Length[data] / dx];
Wolfram Language code: res2 = BinLists[data, {min, max, dx}]
Wolfram Language code: Total[Length /@ res2]

Alternatively, use the width-only bin specification dx:

Wolfram Language code: res3 = BinLists[data, 10]
Wolfram Language code: Total[Length /@ res3]
Wolfram Research (2007), BinLists, Wolfram Language function, https://reference.wolfram.com/language/ref/BinLists.html (updated 2024).

Text

Wolfram Research (2007), BinLists, Wolfram Language function, https://reference.wolfram.com/language/ref/BinLists.html (updated 2024).

CMS

Wolfram Language. 2007. "BinLists." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2024. https://reference.wolfram.com/language/ref/BinLists.html.

APA

Wolfram Language. (2007). BinLists. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/BinLists.html

BibTeX

@misc{reference.wolfram_2026_binlists, author="Wolfram Research", title="{BinLists}", year="2024", howpublished="\url{https://reference.wolfram.com/language/ref/BinLists.html}", note=[Accessed: 12-June-2026]}

BibLaTeX

@online{reference.wolfram_2026_binlists, organization={Wolfram Research}, title={BinLists}, year={2024}, url={https://reference.wolfram.com/language/ref/BinLists.html}, note=[Accessed: 12-June-2026]}