Skip to content

Commit c6a97d3

Browse files
mbostockmbostock
committed
document group and bin
1 parent adae136 commit c6a97d3

3 files changed

Lines changed: 442 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2287,7 +2287,7 @@ Most aggregation methods require binding the output channel to an input channel;
22872287
Plot.groupX({y: "sum"}, {x: "species", y: "body_mass_g"})
22882288
```
22892289
2290-
You can control whether a channel is computed before or after grouping. If a channel is declared only in *options* (and it is not a special group-eligible channel such as *x*, *y*, *z*, *fill*, or stroke), it will be computed after grouping and be passed the grouped data: each datum is the array of input data corresponding to the current group.
2290+
You can control whether a channel is computed before or after grouping. If a channel is declared only in *options* (and it is not a special group-eligible channel such as *x*, *y*, *z*, *fill*, or *stroke*), it will be computed after grouping and be passed the grouped data: each datum is the array of input data corresponding to the current group.
22912291
22922292
```js
22932293
Plot.groupX({y: "count"}, {x: "species", title: group => group.map(d => d.body_mass_g).join("\n")})

‎src/transforms/bin.d.ts‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,40 @@ export type ThresholdsFunction = (values: any[], min: any, max: any) => any[];
1010
export type Thresholds = ThresholdsName | ThresholdsFunction | RangeInterval;
1111

1212
export interface BinOptions {
13+
/**
14+
* Whether the distribution is cumulative (use -1 for the [complementary
15+
* cumulative](https://en.wikipedia.org/wiki/Cumulative_distribution_function#Complementary_cumulative_distribution_function_.28tail_distribution.29))
16+
*/
1317
cumulative?: boolean | number;
18+
/**
19+
* The domain, or a function that receives the values and returns the
20+
* domain. Values outside the domain will be omitted.
21+
*/
1422
domain?: ((values: any[]) => [min: any, max: any]) | [min: any, max: any];
23+
/**
24+
* The **thresholds** value may be specified as:
25+
*
26+
* * *auto* (default) - Scott’s rule, capped at 200
27+
* * *freedman-diaconis* - the [Freedman–Diaconis
28+
* rule](https://en.wikipedia.org/wiki/Freedman–Diaconis_rule)
29+
* * *scott* - [Scott’s normal reference
30+
* rule](https://en.wikipedia.org/wiki/Histogram#Scott.27s_normal_reference_rule)
31+
* * *sturges* - [Sturges’
32+
* formula](https://en.wikipedia.org/wiki/Histogram#Sturges.27_formula)
33+
* * a count (hint) representing the desired number of bins
34+
* * an array of *n* threshold values for *n* - 1 bins
35+
* * an interval or time interval (see also **interval**)
36+
* * a function that returns an array, count, or time interval
37+
*/
1538
thresholds?: Thresholds;
39+
/**
40+
* An alternative way of specifying the bins thresholds. It may be either an
41+
* interval (object with a floor method), a time interval such as *day*, or a
42+
* number. If a number *n*, threshold values are consecutive multiples of *n*
43+
* that span the domain. When the thresholds are specified as an interval, and
44+
* the default **domain** is used, the domain will automatically be extended
45+
* to start and end to align with the interval.
46+
*/
1647
interval?: RangeInterval;
1748
}
1849

@@ -35,17 +66,198 @@ export interface BinReducerImplementation {
3566
}
3667

3768
export interface BinOutputOptions extends BinOptions {
69+
/**
70+
* The data reducer; defaults to the array of values that belong to the bin in
71+
* input order.
72+
*/
3873
data?: BinReducer | null;
74+
/**
75+
* The filter reducer, defaults to a check on empty bins. Use null to return
76+
* all bins, for example to impute sum=0 for a line chart.
77+
*/
3978
filter?: BinReducer | null;
79+
/**
80+
* The order in which the bins are generated, specified as an aggregation
81+
* method (defaults to ascending).
82+
*/
4083
sort?: BinReducer | null;
84+
/**
85+
* Reverse the order in which the bins are generated.
86+
*/
4187
reverse?: boolean;
4288
}
4389

4490
/** How to reduce binned channel values. */
4591
export type BinOutputs = ChannelReducers<BinReducer> & BinOutputOptions;
4692

93+
/**
94+
* Aggregates continuous data—quantitative or temporal values such as
95+
* temperatures or times—into discrete bins and then computes summary statistics
96+
* for each bin such as a count or sum. The binX transform is often used in
97+
* conjunction with the rectY mark, to make histograms.
98+
*
99+
* ```
100+
* Plot.rectY(penguins, Plot.binX({y: "count"}, {x: "culmen_length_mm"}))
101+
* ```
102+
*
103+
* The following aggregation methods are supported:
104+
*
105+
* * *first* - the first value, in input order
106+
* * *last* - the last value, in input order
107+
* * *count* - the number of elements (frequency)
108+
* * *distinct* - the number of distinct values
109+
* * *sum* - the sum of values
110+
* * *proportion* - the sum proportional to the overall total (weighted
111+
* frequency)
112+
* * *proportion-facet* - the sum proportional to the facet total
113+
* * *min* - the minimum value
114+
* * *min-index* - the zero-based index of the minimum value
115+
* * *max* - the maximum value
116+
* * *max-index* - the zero-based index of the maximum value
117+
* * *mean* - the mean value (average)
118+
* * *median* - the median value
119+
* * *mode* - the value with the most occurrences
120+
* * *pXX* - the percentile value, where XX is a number in [00,99]
121+
* * *deviation* - the standard deviation
122+
* * *variance* - the variance per [Welford’s
123+
* algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm)
124+
* * *x* - the middle of the bin’s *x* extent (when binning on *x*)
125+
* * *x1* - the lower bound of the bin’s *x* extent (when binning on *x*)
126+
* * *x2* - the upper bound of the bin’s *x* extent (when binning on *x*)
127+
* * *y* - the middle of the bin’s *y* extent (when binning on *y*)
128+
* * *y1* - the lower bound of the bin’s *y* extent (when binning on *y*)
129+
* * *y2* - the upper bound of the bin’s *y* extent (when binning on *y*)
130+
* * a function to be passed the array of values for each bin and the extent of
131+
* the bin
132+
* * an object with a *reduce* method, and optionally a *scope*
133+
*
134+
* Most aggregation methods require binding the output channel to an input
135+
* channel; for example, if you want the **y** output channel to be a *sum* (not
136+
* merely a count), there should be a corresponding **y** input channel
137+
* specifying which values to sum. If there is not, *sum* will be equivalent to
138+
* *count*.
139+
*
140+
* To control how *x* is divided into bins, the following options are supported:
141+
*
142+
* * **thresholds** - the threshold values; see below
143+
* * **interval** - an alternative method of specifying thresholds
144+
* * **domain** - values outside the domain will be omitted
145+
* * **cumulative** - if positive, each bin will contain all lesser bins
146+
*/
47147
export function binX<T>(outputs?: BinOutputs, options?: T & BinOptions): Transformed<T>;
48148

149+
/**
150+
* Aggregates continuous data—quantitative or temporal values such as
151+
* temperatures or times—into discrete bins and then computes summary statistics
152+
* for each bin such as a count or sum. The binY transform is often used in
153+
* conjunction with the rectX mark, to make vertical histograms.
154+
*
155+
* ```
156+
* Plot.rectX(penguins, Plot.binY({x: "count"}, {y: "culmen_length_mm"}))
157+
* ```
158+
*
159+
* The following aggregation methods are supported:
160+
*
161+
* * *first* - the first value, in input order
162+
* * *last* - the last value, in input order
163+
* * *count* - the number of elements (frequency)
164+
* * *distinct* - the number of distinct values
165+
* * *sum* - the sum of values
166+
* * *proportion* - the sum proportional to the overall total (weighted
167+
* frequency)
168+
* * *proportion-facet* - the sum proportional to the facet total
169+
* * *min* - the minimum value
170+
* * *min-index* - the zero-based index of the minimum value
171+
* * *max* - the maximum value
172+
* * *max-index* - the zero-based index of the maximum value
173+
* * *mean* - the mean value (average)
174+
* * *median* - the median value
175+
* * *mode* - the value with the most occurrences
176+
* * *pXX* - the percentile value, where XX is a number in [00,99]
177+
* * *deviation* - the standard deviation
178+
* * *variance* - the variance per [Welford’s
179+
* algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm)
180+
* * *x* - the middle of the bin’s *x* extent (when binning on *x*)
181+
* * *x1* - the lower bound of the bin’s *x* extent (when binning on *x*)
182+
* * *x2* - the upper bound of the bin’s *x* extent (when binning on *x*)
183+
* * *y* - the middle of the bin’s *y* extent (when binning on *y*)
184+
* * *y1* - the lower bound of the bin’s *y* extent (when binning on *y*)
185+
* * *y2* - the upper bound of the bin’s *y* extent (when binning on *y*)
186+
* * a function to be passed the array of values for each bin and the extent of
187+
* the bin
188+
* * an object with a *reduce* method, and optionally a *scope*
189+
*
190+
* Most aggregation methods require binding the output channel to an input
191+
* channel; for example, if you want the **y** output channel to be a *sum* (not
192+
* merely a count), there should be a corresponding **y** input channel
193+
* specifying which values to sum. If there is not, *sum* will be equivalent to
194+
* *count*.
195+
*
196+
* To control how *y* is divided into bins, the following options are supported:
197+
*
198+
* * **thresholds** - the threshold values; see below
199+
* * **interval** - an alternative method of specifying thresholds
200+
* * **domain** - values outside the domain will be omitted
201+
* * **cumulative** - if positive, each bin will contain all lesser bins
202+
*/
49203
export function binY<T>(outputs?: BinOutputs, options?: T & BinOptions): Transformed<T>;
50204

205+
/**
206+
* Aggregates continuous data—quantitative or temporal values such as
207+
* temperatures or times—into discrete *x* and *y* bins and then computes
208+
* summary statistics for each bin such as a count or sum. The bin transform is
209+
* often used in conjunction with the rect mark, to make heatmaps.
210+
*
211+
* ```
212+
* Plot.rect(penguins, Plot.bin({fill: "count"}, {x: "culmen_depth_mm", y: "culmen_length_mm"}))
213+
* ```
214+
*
215+
* The following aggregation methods are supported:
216+
*
217+
* * *first* - the first value, in input order
218+
* * *last* - the last value, in input order
219+
* * *count* - the number of elements (frequency)
220+
* * *distinct* - the number of distinct values
221+
* * *sum* - the sum of values
222+
* * *proportion* - the sum proportional to the overall total (weighted
223+
* frequency)
224+
* * *proportion-facet* - the sum proportional to the facet total
225+
* * *min* - the minimum value
226+
* * *min-index* - the zero-based index of the minimum value
227+
* * *max* - the maximum value
228+
* * *max-index* - the zero-based index of the maximum value
229+
* * *mean* - the mean value (average)
230+
* * *median* - the median value
231+
* * *mode* - the value with the most occurrences
232+
* * *pXX* - the percentile value, where XX is a number in [00,99]
233+
* * *deviation* - the standard deviation
234+
* * *variance* - the variance per [Welford’s
235+
* algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm)
236+
* * *x* - the middle of the bin’s *x* extent (when binning on *x*)
237+
* * *x1* - the lower bound of the bin’s *x* extent (when binning on *x*)
238+
* * *x2* - the upper bound of the bin’s *x* extent (when binning on *x*)
239+
* * *y* - the middle of the bin’s *y* extent (when binning on *y*)
240+
* * *y1* - the lower bound of the bin’s *y* extent (when binning on *y*)
241+
* * *y2* - the upper bound of the bin’s *y* extent (when binning on *y*)
242+
* * a function to be passed the array of values for each bin and the extent of
243+
* the bin
244+
* * an object with a *reduce* method, and optionally a *scope*
245+
*
246+
* Most aggregation methods require binding the output channel to an input
247+
* channel; for example, if you want the **fill** output channel to be a *sum*
248+
* (not merely a count), there should be a corresponding **fill** input channel
249+
* specifying which values to sum. If there is not, *sum* will be equivalent to
250+
* *count*.
251+
*
252+
* To control how *x* and *y* are divided into bins, the following options are supported:
253+
*
254+
* * **thresholds** - the threshold values; see below
255+
* * **interval** - an alternative method of specifying thresholds
256+
* * **domain** - values outside the domain will be omitted
257+
* * **cumulative** - if positive, each bin will contain all lesser bins
258+
*
259+
* To pass separate binning options for *x* and *y*, the **x** and **y** input
260+
* channels can be specified as an object with the options above and a **value**
261+
* option to specify the input channel values. (🌶 NOT TYPED.)
262+
*/
51263
export function bin<T>(outputs?: BinOutputs, options?: T & BinOptions): Transformed<T>;

0 commit comments

Comments
 (0)