31:[] 2e:{"title":"d3.group, d3.rollup, d3.index","cells":[{"id":0,"value":"# d3.group, d3.rollup, d3.index\n\nAs its name suggests, [d3.group](https://d3js.org/d3-array/group) groups values by key. It returns a [map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) from *key* to the corresponding array of *values* from the input. For example, say you have a table of highly-paid athletes:","pinned":false,"hidden":false,"mode":"md"},{"id":5,"value":"athletes = [\n {name: \"Floyd Mayweather\", sport: \"Boxing\", nation: \"United States\", earnings: 285},\n {name: \"Lionel Messi\", sport: \"Soccer\", nation: \"Argentina\", earnings: 111},\n {name: \"Cristiano Ronaldo\", sport: \"Soccer\", nation: \"Portugal\", earnings: 108},\n {name: \"Conor McGregor\", sport: \"MMA\", nation: \"Ireland\", earnings: 99},\n {name: \"Neymar\", sport: \"Soccer\", nation: \"Brazil\", earnings: 90},\n {name: \"LeBron James\", sport: \"Basketball\", nation: \"United States\", earnings: 85.5},\n {name: \"Roger Federer\", sport: \"Tennis\", nation: \"Switzerland\", earnings: 77.2},\n {name: \"Stephen Curry\", sport: \"Basketball\", nation: \"United States\", earnings: 76.9},\n {name: \"Matt Ryan\", sport: \"Football\", nation: \"United States\", earnings: 67.3},\n {name: \"Matthew Stafford\", sport: \"Football\", nation: \"United States\", earnings: 59.5}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":9,"value":"To group the athletes by sport:","pinned":false,"hidden":false,"mode":"md"},{"id":11,"value":"athletesBySport = d3.group(athletes, d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":410,"value":"Now you can query the map for a particular group:","pinned":false,"hidden":false,"mode":"md"},{"id":396,"value":"athletesBySport.get(\"Basketball\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":409,"value":"You can iterate over the groups, say to construct a table:","pinned":false,"hidden":false,"mode":"md"},{"id":408,"value":"\n \n \n \n ${Array.from(athletesBySport, ([key, values]) => html`\n \n \n \n `)}\n

Sport	Athletes
${key}	${values.map(d => d.name).join(\", \")}

","pinned":true,"hidden":false,"mode":"html"},{"id":15,"value":"Each group’s values are in the same relative order as the input. Thus, since the table above was in order of descending earnings, so too are each group.","pinned":false,"hidden":false,"mode":"md"},{"id":362,"value":"athletesBySport.get(\"Soccer\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":361,"value":"If you specify more than one key, a nested map is returned.","pinned":false,"hidden":false,"mode":"md"},{"id":227,"value":"athletesByNationSport = d3.group(athletes, d => d.nation, d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":254,"value":"To pull a specific group out of the nested map, chain calls to [*map*.get](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/get).","pinned":false,"hidden":false,"mode":"md"},{"id":65,"value":"athletesByNationSport.get(\"United States\").get(\"Boxing\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":243,"value":"Keys can be computed dynamically; they needn’t be simple properties. For example, here we group by the first letter of each name.","pinned":false,"hidden":false,"mode":"md"},{"id":262,"value":"d3.group(athletes, d => d.name[0])","pinned":true,"hidden":false,"mode":"ojs"},{"id":21,"value":"If you’d prefer a nested array instead of a map, say for use with [*selection*.data](https://d3js.org/d3-selection/joining#selection_data) or [*array*.filter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/filter), use [d3.groups](https://d3js.org/d3-array/group#groups) (plural).","pinned":false,"hidden":false,"mode":"md"},{"id":23,"value":"d3.groups(athletes, d => d.name)","pinned":true,"hidden":false,"mode":"ojs"},{"id":201,"value":"d3.groups(athletes, d => d.name, d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":568,"value":"If you’d prefer a flat array instead of a map, consider [d3.flatGroup](./d3-flatgroup).","pinned":false,"hidden":false,"mode":"md"},{"id":193,"value":"## Key equality\n\nAs of [release 2.10](https://github.com/d3/d3-array/releases/tag/v2.10.0), d3.group constructs an [InternMap](/@mbostock/internmap) which determines key equality using [*object*.valueOf](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf) and the [*SameValueZero* algorithm](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Equality_comparisons_and_sameness#Same-value-zero_equality). Thus, unlike a normal Map, you can use dates as keys. For instance, consider this table of transactions:","pinned":false,"hidden":false,"mode":"md"},{"id":191,"value":"transactions = [\n {name: \"Jim\", amount: 3400, date: new Date(\"2015-11-12\")},\n {name: \"Carl\", amount: 12011, date: new Date(\"2015-11-12\")},\n {name: \"Carl\", amount: 2391, date: new Date(\"2015-11-12\")},\n {name: \"Stacy\", amount: 3405, date: new Date(\"2015-10-09\")},\n {name: \"Stacy\", amount: 1201, date: new Date(\"2016-01-04\")}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":289,"value":"If you group the transactions by date, each date is interned using its corresponding primitive value (milliseconds since UNIX epoch), and thus transactions occurring on the same date are grouped together as expected.","pinned":false,"hidden":false,"mode":"md"},{"id":208,"value":"d3.group(transactions, d => d.date) // 👍 Dates can be equal!","pinned":true,"hidden":false,"mode":"ojs"},{"id":119,"value":"## Rollups\n\n[d3.rollup](https://d3js.org/d3-array/group#rollup) lets you “reduce” each group by computing a corresponding summary value, such as a sum or count. The result is a map from key to reduced value.\n\nIts signature is similar to d3.group’s signature, with an added *reducer* function as the second argument: rollup(*data*, **_reducer_**, *key1*, *key2*…). For each group, the reducer receives the group as an array, and returns the reduced value. (In fact, d3.group is just a special case of d3.rollup where the aggregate function is the identity function.)\n\nFor example, to count athletes by sport:","pinned":false,"hidden":false,"mode":"md"},{"id":122,"value":"d3.rollup(athletes, v => v.length, d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":344,"value":"Or, to compute the total earnings per sport for these athletes with [d3.sum](https://d3js.org/d3-array/summarize#sum):","pinned":false,"hidden":false,"mode":"md"},{"id":347,"value":"d3.rollup(athletes, v => d3.sum(v, d => d.earnings), d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":378,"value":"In conjunction with [d3.least](/@d3/d3-least), d3.rollup can be used to compute the biggest (or smallest) group according to the reduced value.","pinned":false,"hidden":false,"mode":"md"},{"id":385,"value":"d3.least(d3.rollup(athletes, v => d3.sum(v, d => d.earnings), d => d.sport), ([, sum]) => -sum)","pinned":true,"hidden":false,"mode":"ojs"},{"id":389,"value":"You can similarly get the biggest or smallest group using d3.group together with d3.least.","pinned":false,"hidden":false,"mode":"md"},{"id":373,"value":"d3.least(d3.group(athletes, d => d.sport), ([, v]) => -d3.sum(v, d => d.earnings))","pinned":true,"hidden":false,"mode":"ojs"},{"id":123,"value":"As with d3.group, if you specify more than one key, a nested map is returned.","pinned":false,"hidden":false,"mode":"md"},{"id":165,"value":"d3.rollup(athletes, v => v.length, d => d.nation, d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":166,"value":"The *reducer* is only applied to the leaf groups: above, counting the athletes for a particular nation and sport. The reducer is not applied to the parent groups, or to the values as a whole. (For nested calculations, consider [d3.hierarchy](https://d3js.org/d3-hierarchy).)\n\nAnd as with d3.groups, use d3.rollups to get a nested array instead of a nested map, and [d3.flatRollup](./d3-flatgroup) for a flat array.","pinned":false,"hidden":false,"mode":"md"},{"id":129,"value":"d3.rollups(athletes, v => d3.sum(v, d => d.earnings), d => d.sport)","pinned":true,"hidden":false,"mode":"ojs"},{"id":155,"value":"d3.rollups is particularly useful to create [hierarchies](https://observablehq.com/collection/@d3/d3-hierarchy) from flat datasets, as for example in this [circle-packing diagram of H-1B Employers](https://observablehq.com/@mbostock/2019-h-1b-employers).","pinned":false,"hidden":false,"mode":"md"},{"id":441,"value":"## Indexes\n\n[d3.index](https://d3js.org/d3-array/group#index) creates a Map from key to unique value. Given several keys, it returns a nested Map.","pinned":false,"hidden":false,"mode":"md"},{"id":448,"value":"index = d3.index(athletes, d => d.name)","pinned":true,"hidden":false,"mode":"ojs"},{"id":455,"value":"It is particularly useful to join two datasets. For a (toy) example, suppose we have a selection of interesting athletes’ facts:","pinned":false,"hidden":false,"mode":"md"},{"id":458,"value":"facts = [\n {about: \"Neymar\", fact: \"Neymar is Neymar da Silva Santos Júnior\"},\n {about: \"Roger Federer\", fact: \"Federer has won 20 Grand Slam men's singles titles\"},\n {about: \"Megan Rapinoe\", fact: \"Rapinoe was named The Best FIFA Women's Player in 2019\"}\n]","pinned":true,"hidden":false,"mode":"ojs"},{"id":461,"value":"With the index, we can join the two datasets:","pinned":false,"hidden":false,"mode":"md"},{"id":464,"value":"facts.map(({about: name, fact}) => ({fact, name, ...index.get(name)}))","pinned":true,"hidden":false,"mode":"ojs"},{"id":469,"value":"The previous join was made by looping through all the facts; for each fact, we looked up the athlete’s data in the index. We might, alternatively, want to loop through all the athletes’ data and look up in the facts index. (Note how we can use the [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining) notation `?.` to return undefined when no fact is found.)","pinned":false,"hidden":false,"mode":"md"},{"id":472,"value":"{\n const index = d3.index(facts, d => d.about);\n return athletes.map(({name, ...values}) => ({name, fact: index.get(name)?.fact}))\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":488,"value":"{\n const index = d3.index(facts, d => d.about);\n return athletes.map(({name, ...values}) => ({name, fact: index.get(name)?.fact, ...values}))\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":442,"value":"d3.index will throw an error if several elements share the same key:","pinned":false,"hidden":false,"mode":"md"},{"id":446,"value":"d3.index(athletes, d => d.nation)","pinned":true,"hidden":false,"mode":"ojs"},{"id":507,"value":"As with d3.group and d3.rollup, we can use several keys and look up the values by chaining “queries”:","pinned":false,"hidden":false,"mode":"md"},{"id":509,"value":"nn = d3.index(athletes, d => d.nation, d => d.sport, d => d.name)","pinned":true,"hidden":false,"mode":"ojs"},{"id":521,"value":"nn.get(\"United States\")?.get(\"Basketball\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":513,"value":"nn.get(\"United States\")?.get(\"Basketball\")?.get(\"LeBron James\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":526,"value":"nn.get(\"United States\")?.get(\"Soccer\")?.get(\"Rapinoe\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":494,"value":"[d3.indexes](https://d3js.org/d3-array/group#indexes) returns the index as a nested array:","pinned":false,"hidden":false,"mode":"md"},{"id":503,"value":"d3.indexes(athletes, d => d.nation, d => d.name)","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}