GatherBy
Details
- GatherBy[{e1,e2,e3,…},f] evaluates f[ei] for each i to determine how to gather the ei.
- GatherBy[list,…] gives results that follow the ordering of elements in list.
- Within each sublist generated by GatherBy[list,…], elements appear in the same order as in list; the complete sublists are ordered so that their first elements appear in the same order as in list.
- GatherBy[list,Identity] is equivalent to Gather[list]. »
- GatherBy effectively produces an equivalence partition.
- GatherBy[list,{f1,f2}] is equivalent to Map[GatherBy[#,f2]&,GatherBy[list,f1]]. »
- GatherBy[f][list] is equivalent to GatherBy[list,f]. »
Examples
open all close allBasic Examples (2)
Scope (4)
GatherBy[Range[10], Mod[#, 3]&]Gather by the first component, and within that group, gather by the last component:
Tuples[{{a, b}, {1, 2}, {x, y}}]GatherBy[%, {First, Last}]Use Framed to display grouping:
Map[Framed, %, {1, 2}]Define a GatherBy operator:
op = GatherBy[Last];Use the operator to gather integer data, putting each group on a separate row of a column:
ints = RandomInteger[4, {10, 3}];
op[ints]//ColumnUse the operator to gather string data:
words = RandomChoice[RandomWord[5], {10, 2}];
op[words]//ColumnCreate a list of associations:
data = Table[AssociationThread[CharacterRange["a", "c"] -> RandomInteger[5, 3]], {10}]Gather by the value of the key "a":
Framed /@ GatherBy[data, #a&]Gather by the values of the keys "a" and "b", using the operator form of GatherBy:
Map[Framed, GatherBy[{#a&, #b&}][data], {1, 2}]Applications (4)
Sort and then gather strings by their first letters:
words = RandomChoice[WordData[], {1000}];f = StringTake[#, {1}]&;GatherBy[SortBy[words, f], f]//ShortFlatten@Table[DateString[{y, m}, {"Month", "/", "YearShort"}], {y, RandomChoice[Range[2000, 2010], 5]}, {m, RandomChoice[Range[12], 3]}]GatherBy[%, DateList[{#, {"Month", "/", "YearShort"}}][[1]]&]data = Transpose[{RandomReal[5, 10], RandomChoice[{a, b, c}, 10], RandomReal[10, 10]}]Group elements based on the value of the second element:
gathered = GatherBy[data, #[[2]]&]Count the number of data points in each group:
Map[{#[[1, 2]], Length[#[[All, -1]]]}&, gathered]Compute the means of the third element by group:
Map[{#[[1, 2]], Mean[#[[All, -1]]]}&, gathered]Group machine numbers by equivalence class based on rounding off the last tol bits:
tol = 7;
f[x_] := Module[{re = Round[RealExponent[x, 2]], e}, e = (53 - tol - re);
m = 2 ^ e;
N[Round[x m] / m]];Generate an unordered sample of distinct machine numbers close to 1:
ϵ = $MachineEpsilon;
r = RandomSample[Table[1 + k ϵ, {k, 100}]]g = GatherBy[r, f]See how the factors
in
were grouped:
Round[(g - 1) / ϵ]Here are the equivalence representatives
and the values
such that
:
Table[{InputForm[r = f[x]], (r - 1) / ϵ}, {x, g[[All, 1]]}]Properties & Relations (4)
GatherBy[list,Identity] is equivalent to Gather[list]:
list = RandomInteger[10, 10];
GatherBy[list, Identity] === Gather[list]GatherBy[list,f] is equivalent to Gather[list,(f[#1]===f[#2])&]:
m = RandomInteger[1, {10, 5}];
GatherBy[m, Norm] == Gather[m, (Norm[#1] === Norm[#2])&]Display the groups along with the norm of each group:
Grid[Map[{MatrixForm[#], Norm[First[#]]}&, GatherBy[m, Norm] ]]GatherBy[list,{f1,f2}] is equivalent to Map[GatherBy[#,f2]&,GatherBy[list,f1]]:
list = Range[-4, 4];
GatherBy[list, {Positive, EvenQ}] === Map[GatherBy[#, EvenQ]&, GatherBy[list, Positive]]GatherBy[f][list] is equivalent to GatherBy[list,f]:
list = Range[-4, 4];
GatherBy[EvenQ][list] === GatherBy[list, EvenQ]See Also
Gather GroupBy SplitBy SortBy Split Sort Select Cases
Function Repository: GatherByIndex GroupByList DuplicatesBy TallyBy
Related Guides
Text
Wolfram Research (2008), GatherBy, Wolfram Language function, https://reference.wolfram.com/language/ref/GatherBy.html (updated 2026).
CMS
Wolfram Language. 2008. "GatherBy." Wolfram Language & System Documentation Center. Wolfram Research. Last Modified 2026. https://reference.wolfram.com/language/ref/GatherBy.html.
APA
Wolfram Language. (2008). GatherBy. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/GatherBy.html
BibTeX
@misc{reference.wolfram_2026_gatherby, author="Wolfram Research", title="{GatherBy}", year="2026", howpublished="\url{https://reference.wolfram.com/language/ref/GatherBy.html}", note=[Accessed: 12-June-2026]}
BibLaTeX
@online{reference.wolfram_2026_gatherby, organization={Wolfram Research}, title={GatherBy}, year={2026}, url={https://reference.wolfram.com/language/ref/GatherBy.html}, note=[Accessed: 12-June-2026]}