-
Notifications
You must be signed in to change notification settings - Fork 29.9k
/
index.d.ts
2669 lines (2501 loc) · 128 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Last module patch version validated against: 4.0.2
import { CountableTimeInterval, TimeInterval } from "d3-time";
// -------------------------------------------------------------------------------
// Shared Types and Interfaces
// -------------------------------------------------------------------------------
/**
* An Interpolator factory returns an interpolator function.
*
* The first generic corresponds to the data type of the interpolation boundaries.
* The second generic corresponds to the data type of the return type of the interpolator.
*/
export interface InterpolatorFactory<T, U> {
/**
* Construct a new interpolator function, based on the provided interpolation boundaries.
*
* @param a Start boundary of the interpolation interval.
* @param b End boundary of the interpolation interval.
*/
(a: T, b: T): (t: number) => U;
}
export type NumberValue = number | { valueOf(): number };
export type UnknownReturnType<Unknown, DefaultUnknown> = [Unknown] extends [never] ? DefaultUnknown : Unknown;
/**
* A helper interface for a continuous scale defined over a numeric domain.
*/
export interface ScaleContinuousNumeric<Range, Output, Unknown = never> {
/**
* Given a value from the domain, returns the corresponding value from the range, subject to interpolation, if any.
*
* If the given value is outside the domain, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the range.
*
* Note: The interpolation function applied by the scale may change the output type from the range type as part of the interpolation.
*
* @param value A numeric value from the domain.
*/
(value: NumberValue): Output | Unknown;
/**
* Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction,
* say to determine the data value corresponding to the position of the mouse.
*
* If the given value is outside the range, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the domain.
*
* IMPORTANT: This method is only supported if the range is numeric. If the range is not numeric, returns NaN.
*
* For a valid value y in the range, continuous(continuous.invert(y)) approximately equals y;
* similarly, for a valid value x in the domain, continuous.invert(continuous(x)) approximately equals x.
* The scale and its inverse may not be exact due to the limitations of floating point precision.
*
* @param value A numeric value from the range.
*/
invert(value: NumberValue): number;
/**
* Returns a copy of the scale’s current domain.
*/
domain(): number[];
/**
* Sets the scale’s domain to the specified array of numbers. The array must contain two or more elements.
* If the elements in the given array are not numbers, they will be coerced to numbers
*
* Although continuous scales typically have two values each in their domain and range, specifying more than two values produces a piecewise scale.
*
* Internally, a piecewise scale performs a binary search for the range interpolator corresponding to the given domain value.
* Thus, the domain must be in ascending or descending order. If the domain and range have different lengths N and M, only the first min(N,M) elements in each are observed.
*
* @param domain Array of numeric domain values.
*/
domain(domain: Iterable<NumberValue>): this;
/**
* Returns a copy of the scale’s current range.
*/
range(): Range[];
/**
* Sets the scale’s range to the specified array of values.
*
* The array must contain two or more elements. Unlike the domain, elements in the given array need not be numbers;
* any value that is supported by the underlying interpolator will work, though note that numeric ranges are required for invert.
*
* @param range Array of range values.
*/
range(range: Iterable<Range>): this;
/**
* Sets the scale’s range to the specified array of values while also setting the scale’s interpolator to interpolateRound.
*
* The rounding interpolator is sometimes useful for avoiding antialiasing artifacts,
* though also consider the shape-rendering “crispEdges” styles. Note that this interpolator can only be used with numeric ranges.
*
* The array must contain two or more elements. Unlike the domain, elements in the given array need not be numbers;
* any value that is supported by the underlying interpolator will work, though note that numeric ranges are required for invert.
*
* @param range Array of range values.
*/
rangeRound(range: Iterable<NumberValue>): this;
/**
* Returns whether or not the scale currently clamps values to within the range.
*/
clamp(): boolean;
/**
* Enables or disables clamping, respectively. If clamping is disabled and the scale is passed a value outside the domain,
* the scale may return a value outside the range through extrapolation.
*
* If clamping is enabled, the return value of the scale is always within the scale’s range. Clamping similarly applies to the "invert" method.
*
* @param clamp A flag to enable (true) or disable (false) clamping.
*/
clamp(clamp: boolean): this;
/**
* Returns approximately count representative values from the scale’s domain.
*
* If count is not specified, it defaults to 10.
*
* The returned tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10),
* and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.
* The specified count is only a hint; the scale may return more or fewer values depending on the domain. See also d3-array’s ticks.
*
* @param count Optional approximate number of ticks to be returned. If count is not specified, it defaults to 10.
*/
ticks(count?: number): number[];
/**
* Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values.
* The specified count should have the same value as the count that is used to generate the tick values.
*
* @param count Approximate number of ticks to be used when calculating precision for the number format function.
* @param specifier An optional valid format specifier string which allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.
* If specifier uses the format type "s", the scale will return a SI-prefix format based on the largest value in the domain.
* If the specifier already specifies a precision, this method is equivalent to locale.format.
*/
tickFormat(count?: number, specifier?: string): (d: NumberValue) => string;
/**
* Extends the domain so that it starts and ends on nice round values.
* This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value.
* An optional tick count argument allows greater control over the step size used to extend the bounds,
* guaranteeing that the returned ticks will exactly cover the domain.
* Nicing is useful if the domain is computed from data, say using extent, and may be irregular.
* For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0].
* If the domain has more than two values, nicing the domain only affects the first and last value.
*
* Nicing a scale only modifies the current domain; it does not automatically nice domains that are subsequently set using continuous.domain.
* You must re-nice the scale after setting the new domain, if desired.
*
* @param count An optional number of ticks expected to be used.
*/
nice(count?: number): this;
/**
* Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
*/
copy(): this;
}
/**
* Returns a number format function suitable for displaying a tick value,
* automatically computing the appropriate precision based on the fixed interval between tick values, as determined by d3.tickStep.
*
* @param start Start
* @param stop Stop
* @param count Approximate number of ticks to be used when calculating precision for the number format function.
* @param specifier An optional specifier allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.
* If specifier uses the format type s, the scale will return a SI-prefix format based on the larger absolute value of start and stop.
* If the specifier already specifies a precision, this method is equivalent to locale.format.
*/
export function tickFormat(start: number, stop: number, count: number, specifier?: string): (d: NumberValue) => string;
// -------------------------------------------------------------------------------
// Linear Scale Factory
// -------------------------------------------------------------------------------
/**
* A linear continuous scale defined over a numeric domain.
*
* Continuous scales map a continuous, quantitative input domain to a continuous output range.
* Each range value y can be expressed as a function of the domain value x: y = mx + b.
*
* If the range is also numeric, the mapping may be inverted.
*
* Note that the data types of the range and output of the scale must be compatible with the interpolator applied by the scale.
*
* The first generic corresponds to the data type of the range elements.
*
* The second generic corresponds to the data type of the output elements generated by the scale.
*
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*/
export interface ScaleLinear<Range, Output, Unknown = never> extends ScaleContinuousNumeric<Range, Output, Unknown> {
/**
* Returns the scale’s current interpolator factory, which defaults to interpolate.
*/
interpolate(): InterpolatorFactory<any, any>;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate(interpolate: InterpolatorFactory<Range, Output>): this;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* The generic "NewOutput" can be used to change the scale to have a different output element type corresponding to the new interpolation factory.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate<NewOutput>(interpolate: InterpolatorFactory<Range, NewOutput>): ScaleLinear<Range, NewOutput, Unknown>;
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScaleLinear<Range, Output, NewUnknown>;
}
/**
* Constructs a new continuous scale with the specified range, the default interpolator and clamping disabled.
* The domain defaults to [0, 1].
* If range is not specified, it defaults to [0, 1].
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleLinear<Range = number, Output = Range, Unknown = never>(
range?: Iterable<Range>,
): ScaleLinear<Range, Output, Unknown>;
/**
* Constructs a new continuous scale with the specified domain and range, the default interpolator and clamping disabled.
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param domain Array of numeric domain values.
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleLinear<Range, Output = Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScaleLinear<Range, Output, Unknown>;
// -------------------------------------------------------------------------------
// Power Scale Factories
// -------------------------------------------------------------------------------
/**
* A continuous power scale defined over a numeric domain.
*
* Continuous scales map a continuous, quantitative input domain to a continuous output range.
*
* Each range value y can be expressed as a function of the domain value x: y = mx^k + b, where k is the exponent value.
* Power scales also support negative domain values, in which case the input value and the resulting output value are multiplied by -1.
*
* If the range is also numeric, the mapping may be inverted.
*
* Note that the data types of the range and output of the scale must be compatible with the interpolator applied by the scale.
*
* The first generic corresponds to the data type of the range elements.
*
* The second generic corresponds to the data type of the output elements generated by the scale.
*
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*/
export interface ScalePower<Range, Output, Unknown = never> extends ScaleContinuousNumeric<Range, Output, Unknown> {
/**
* Returns the scale’s current interpolator factory, which defaults to interpolate.
*/
interpolate(): InterpolatorFactory<any, any>;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate(interpolate: InterpolatorFactory<Range, Output>): this;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* The generic "NewOutput" can be used to change the scale to have a different output element type corresponding to the new interpolation factory.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate<NewOutput>(interpolate: InterpolatorFactory<Range, NewOutput>): ScalePower<Range, NewOutput, Unknown>;
/**
* If exponent is not specified, returns the current exponent, which defaults to 1.
* (Note that this is effectively a linear scale until you set a different exponent.)
*/
exponent(): number;
/**
* Sets the current exponent to the given numeric value.
* (Note that this is effectively a linear scale until you set a different exponent.)
*/
exponent(exponent: number): this;
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScalePower<Range, Output, NewUnknown>;
}
/**
* Constructs a new continuous scale with the specified range, the exponent 1, the default interpolator and clamping disabled.
* The domain defaults to [0, 1].
* If range is not specified, it defaults to [0, 1].
* (Note that this is effectively a linear scale until you set a different exponent.)
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scalePow<Range = number, Output = Range, Unknown = never>(
range?: Iterable<Range>,
): ScalePower<Range, Output, Unknown>;
/**
* Constructs a new continuous scale with the specified domain and range, the exponent 1, the default interpolator and clamping disabled.
* (Note that this is effectively a linear scale until you set a different exponent.)
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param domain Array of numeric domain values.
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scalePow<Range, Output = Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScalePower<Range, Output, Unknown>;
/**
* Constructs a new continuous power scale with the specified range, the exponent 0.5, the default interpolator and clamping disabled.
* The domain defaults to [0, 1].
* If range is not specified, it defaults to [0, 1].
* This is a convenience method equivalent to d3.scalePow().exponent(0.5).
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleSqrt<Range = number, Output = Range, Unknown = never>(
range?: Iterable<Range>,
): ScalePower<Range, Output, Unknown>;
/**
* Constructs a new continuous power scale with the specified domain and range, the exponent 0.5, the default interpolator and clamping disabled.
* This is a convenience method equivalent to d3.scalePow().exponent(0.5).
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param domain Array of numeric domain values.
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleSqrt<Range, Output = Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScalePower<Range, Output, Unknown>;
// -------------------------------------------------------------------------------
// Logarithmic Scale Factory
// -------------------------------------------------------------------------------
/**
* A continuous logarithmic scale defined over a numeric domain.
*
* Continuous scales map a continuous, quantitative input domain to a continuous output range.
*
* The mapping to the range value y can be expressed as a function of the domain value x: y = m log(x) + b.
*
* As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero.
* A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values.
* (For a negative domain, input and output values are implicitly multiplied by -1.)
* The behavior of the scale is undefined if you pass a negative value to a log scale with a positive domain or vice versa.
*
* If the range is also numeric, the mapping may be inverted.
*
* Note that the data types of the range and output of the scale must be compatible with the interpolator applied by the scale.
*
* The first generic corresponds to the data type of the range elements.
*
* The second generic corresponds to the data type of the output elements generated by the scale.
*
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*/
export interface ScaleLogarithmic<Range, Output, Unknown = never>
extends ScaleContinuousNumeric<Range, Output, Unknown>
{
/**
* Returns a copy of the scale’s current domain.
*/
domain(): number[];
/**
* Sets the scale’s domain to the specified array of numbers. The array must contain two or more elements.
* If the elements in the given array are not numbers, they will be coerced to numbers
*
* As log(0) = -∞, a log scale domain must be strictly-positive or strictly-negative; the domain must not include or cross zero.
* A log scale with a positive domain has a well-defined behavior for positive values, and a log scale with a negative domain has a well-defined behavior for negative values.
* (For a negative domain, input and output values are implicitly multiplied by -1.)
* The behavior of the scale is undefined if you pass a negative value to a log scale with a positive domain or vice versa.
*
* Although continuous scales typically have two values each in their domain and range, specifying more than two values produces a piecewise scale.
*
* Internally, a piecewise scale performs a binary search for the range interpolator corresponding to the given domain value.
* Thus, the domain must be in ascending or descending order. If the domain and range have different lengths N and M, only the first min(N,M) elements in each are observed.
*
* @param domain Array of numeric domain values.
*/
domain(domain: Iterable<NumberValue>): this;
/**
* Returns the scale’s current interpolator factory, which defaults to interpolate.
*/
interpolate(): InterpolatorFactory<any, any>;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate(interpolate: InterpolatorFactory<Range, Output>): this;
/**
* Sets the scale’s range interpolator factory. This interpolator factory is used to create interpolators for each adjacent pair of values from the range;
* these interpolators then map a normalized domain parameter t in [0, 1] to the corresponding value in the range.
*
* Note: the default interpolator may reuse return values. For example, if the range values are objects, then the value interpolator always returns the same object, modifying it in-place.
* If the scale is used to set an attribute or style, this is typically acceptable (and desirable for performance);
* however, if you need to store the scale’s return value, you must specify your own interpolator or make a copy as appropriate.
*
* As part of the interpolation process the interpolated value from the range may be converted to a corresponding output value.
*
* The generic "NewOutput" can be used to change the scale to have a different output element type corresponding to the new interpolation factory.
*
* @param interpolate An interpolation factory. The generics for Range and Output of the scale must correspond to the interpolation factory applied to the scale.
*/
interpolate<NewOutput>(
interpolate: InterpolatorFactory<Range, NewOutput>,
): ScaleLogarithmic<Range, NewOutput, Unknown>;
/**
* Returns approximately count representative values from the scale’s domain.
*
* If count is not specified, it defaults to 10.
*
* If the base is an integer, the returned ticks are uniformly spaced within each integer power of base; otherwise, one tick per power of base is returned.
* The returned ticks are guaranteed to be within the extent of the domain. If the orders of magnitude in the domain is greater than count, then at most one tick per power is returned.
* Otherwise, the tick values are unfiltered, but note that you can use log.tickFormat to filter the display of tick labels.
*
* @param count Optional approximate number of ticks to be returned. If count is not specified, it defaults to 10.
*/
ticks(count?: number): number[];
/**
* Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values.
*
* The specified count typically has the same value as the count that is used to generate the tick values.
* If there are too many ticks, the formatter may return the empty string for some of the tick labels;
* however, note that the ticks are still shown.
* To disable filtering, specify a count of Infinity. When specifying a count, you may also provide a format specifier or format function.
* For example, to get a tick formatter that will display 20 ticks of a currency, say log.tickFormat(20, "$,f").
* If the specifier does not have a defined precision, the precision will be set automatically by the scale, returning the appropriate format.
* This provides a convenient way of specifying a format whose precision will be automatically set by the scale.
*
* @param count Approximate number of ticks to be used when calculating precision for the number format function.
* @param specifier An optional valid format specifier string which allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.
* For example, to get a tick formatter that will display 20 ticks of a currency, say log.tickFormat(20, "$,f").
* If the specifier does not have a defined precision, the precision will be set automatically by the scale, returning the appropriate format.
* This provides a convenient way of specifying a format whose precision will be automatically set by the scale.
*/
tickFormat(count?: number, specifier?: string): (d: NumberValue) => string;
/**
* Extends the domain to integer powers of base. For example, for a domain of [0.201479…, 0.996679…], and base 10, the nice domain is [0.1, 1].
* If the domain has more than two values, nicing the domain only affects the first and last value.
*
* Nicing a scale only modifies the current domain; it does not automatically nice domains that are subsequently set using continuous.domain.
* You must re-nice the scale after setting the new domain, if desired.
*/
nice(): this;
/**
* Returns the current base, which defaults to 10.
*/
base(): number;
/**
* Sets the base for this logarithmic scale to the specified value.
*/
base(base: number): this;
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScaleLogarithmic<Range, Output, NewUnknown>;
}
/**
* Constructs a new continuous scale with the specified range, the base 10, the default interpolator and clamping disabled.
* The domain defaults to [1, 10].
* If range is not specified, it defaults to [0, 1].
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleLog<Range = number, Output = Range, Unknown = never>(
range?: Iterable<Range>,
): ScaleLogarithmic<Range, Output, Unknown>;
/**
* Constructs a new continuous scale with the specified domain and range, the base 10, the default interpolator and clamping disabled.
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param domain Array of numeric domain values.
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleLog<Range, Output = Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScaleLogarithmic<Range, Output, Unknown>;
// -------------------------------------------------------------------------------
// Symlog Scale Factory
// -------------------------------------------------------------------------------
/**
* A bi-symmetric log transformation for wide-range data by Webber scale defined over a numeric domain.
*
* Continuous scales map a continuous, quantitative input domain to a continuous output range.
*
* See “A bi-symmetric log transformation for wide-range data” by Webber for more
*
* If the range is also numeric, the mapping may be inverted.
*
* Note that the data types of the range and output of the scale must be compatible with the interpolator applied by the scale.
*
* The first generic corresponds to the data type of the range elements.
*
* The second generic corresponds to the data type of the output elements generated by the scale.
*
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*/
export interface ScaleSymLog<Range, Output, Unknown = never> extends ScaleContinuousNumeric<Range, Output, Unknown> {
/**
* Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values.
*
* The specified count typically has the same value as the count that is used to generate the tick values.
* If there are too many ticks, the formatter may return the empty string for some of the tick labels;
* however, note that the ticks are still shown.
* To disable filtering, specify a count of Infinity. When specifying a count, you may also provide a format specifier or format function.
* For example, to get a tick formatter that will display 20 ticks of a currency, say log.tickFormat(20, "$,f").
* If the specifier does not have a defined precision, the precision will be set automatically by the scale, returning the appropriate format.
* This provides a convenient way of specifying a format whose precision will be automatically set by the scale.
*
* @param count Approximate number of ticks to be used when calculating precision for the number format function.
* @param specifier An optional valid format specifier string which allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.
* For example, to get a tick formatter that will display 20 ticks of a currency, say log.tickFormat(20, "$,f").
* If the specifier does not have a defined precision, the precision will be set automatically by the scale, returning the appropriate format.
* This provides a convenient way of specifying a format whose precision will be automatically set by the scale.
*/
tickFormat(count?: number, specifier?: string): (d: NumberValue) => string;
/**
* Returns the current constant, which defaults to 1.
*/
constant(): number;
/**
* Sets the symlog constant to the specified number and returns this scale;
* otherwise returns the current value of the symlog constant, which defaults to 1. See “A bi-symmetric log transformation for wide-range data” by Webber for more.
*/
constant(constant: number): this;
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScaleSymLog<Range, Output, NewUnknown>;
}
/**
* Constructs a new continuous scale with the specified range, the constant 1, the default interpolator and clamping disabled.
* The domain defaults to [0, 1].
* If range is not specified, it defaults to [0, 1].
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleSymlog<Range = number, Output = Range, Unknown = never>(
range?: Iterable<Range>,
): ScaleSymLog<Range, Output, Unknown>;
/**
* Constructs a new continuous scale with the specified domain and range, the constant 1, the default interpolator and clamping disabled.
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the output elements generated by the scale.
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*
* The range must be set in accordance with the range element type.
*
* The interpolator factory may be set using the interpolate(...) method of the scale.
*
* @param domain Array of numeric domain values.
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleSymlog<Range, Output = Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScaleSymLog<Range, Output, Unknown>;
// -------------------------------------------------------------------------------
// Identity Scale Factory
// -------------------------------------------------------------------------------
/**
* Identity scales are a special case of linear scales where the domain and range are identical; the scale and its invert method are thus the identity function.
* These scales are occasionally useful when working with pixel coordinates, say in conjunction with an axis.
*
* The generic corresponds to the data type of the unknown value.
*/
export interface ScaleIdentity<Unknown = never> {
/**
* Given a value from the domain, returns the corresponding value from the range, subject to interpolation, if any.
*
* If the given value is outside the domain, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the range.
*
* Note: The interpolation function applied by the scale may change the output type from the range type as part of the interpolation.
*
* @param value A numeric value from the domain.
*/
(value: NumberValue): number | Unknown;
/**
* Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction,
* say to determine the data value corresponding to the position of the mouse.
*
* If the given value is outside the range, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the domain.
*
* IMPORTANT: This method is only supported if the range is numeric. If the range is not numeric, returns NaN.
*
* For a valid value y in the range, continuous(continuous.invert(y)) approximately equals y;
* similarly, for a valid value x in the domain, continuous.invert(continuous(x)) approximately equals x.
* The scale and its inverse may not be exact due to the limitations of floating point precision.
*
* @param value A numeric value from the range.
*/
invert(value: NumberValue): number;
/**
* Returns a copy of the scale’s current domain.
*/
domain(): number[];
/**
* Sets the scale’s domain to the specified array of numbers. The array must contain two or more elements.
* If the elements in the given array are not numbers, they will be coerced to numbers
*
* Although continuous scales typically have two values each in their domain and range, specifying more than two values produces a piecewise scale.
*
* Internally, a piecewise scale performs a binary search for the range interpolator corresponding to the given domain value.
* Thus, the domain must be in ascending or descending order. If the domain and range have different lengths N and M, only the first min(N,M) elements in each are observed.
*
* @param domain Array of numeric domain values.
*/
domain(domain: Iterable<NumberValue>): this;
/**
* Returns a copy of the scale’s current range.
*/
range(): number[];
/**
* Sets the scale’s range to the specified array of values.
*
* The array must contain two or more elements. Unlike the domain, elements in the given array need not be numbers;
* any value that is supported by the underlying interpolator will work, though note that numeric ranges are required for invert.
*
* @param range Array of range values.
*/
range(range: Iterable<NumberValue>): this;
/**
* Returns approximately count representative values from the scale’s domain.
*
* If count is not specified, it defaults to 10.
*
* The returned tick values are uniformly spaced, have human-readable values (such as multiples of powers of 10),
* and are guaranteed to be within the extent of the domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data.
* The specified count is only a hint; the scale may return more or fewer values depending on the domain. See also d3-array’s ticks.
*
* @param count Optional approximate number of ticks to be returned. If count is not specified, it defaults to 10.
*/
ticks(count?: number): number[];
/**
* Returns a number format function suitable for displaying a tick value, automatically computing the appropriate precision based on the fixed interval between tick values.
* The specified count should have the same value as the count that is used to generate the tick values.
*
* @param count Approximate number of ticks to be used when calculating precision for the number format function.
* @param specifier An optional valid format specifier string which allows a custom format where the precision of the format is automatically set by the scale as appropriate for the tick interval.
* If specifier uses the format type "s", the scale will return a SI-prefix format based on the largest value in the domain.
* If the specifier already specifies a precision, this method is equivalent to locale.format.
*/
tickFormat(count?: number, specifier?: string): (d: NumberValue) => string;
/**
* Extends the domain so that it starts and ends on nice round values.
* This method typically modifies the scale’s domain, and may only extend the bounds to the nearest round value.
* An optional tick count argument allows greater control over the step size used to extend the bounds,
* guaranteeing that the returned ticks will exactly cover the domain.
* Nicing is useful if the domain is computed from data, say using extent, and may be irregular.
* For example, for a domain of [0.201479…, 0.996679…], a nice domain might be [0.2, 1.0].
* If the domain has more than two values, nicing the domain only affects the first and last value.
*
* Nicing a scale only modifies the current domain; it does not automatically nice domains that are subsequently set using continuous.domain.
* You must re-nice the scale after setting the new domain, if desired.
*
* @param count An optional number of ticks expected to be used.
*/
nice(count?: number): this;
/**
* Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
*/
copy(): this;
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScaleIdentity<NewUnknown>;
}
/**
* Constructs a new identity scale with the specified domain and range.
* If range is not specified, it defaults to [0, 1].
*
* The generic corresponds to the data type of the unknown value.
*
* @param range Array of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleIdentity<Unknown = never>(range?: Iterable<NumberValue>): ScaleIdentity<Unknown>;
// -------------------------------------------------------------------------------
// Radial Scale Factory
// -------------------------------------------------------------------------------
export interface ScaleRadial<Range, Output, Unknown = never> extends ScaleContinuousNumeric<Range, Output, Unknown> {
/**
* Returns the current unknown value, which defaults to undefined.
*/
unknown(): UnknownReturnType<Unknown, undefined>;
/**
* Sets the output value of the scale for undefined (or NaN) input values and returns this scale.
*
* @param value The output value of the scale for undefined (or NaN) input values.
*/
unknown<NewUnknown>(value: NewUnknown): ScaleRadial<Range, Output, NewUnknown>;
}
/**
* Constructs a new radial scale with the specified range.
* The domain defaults to [0, 1].
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the unknown value.
*
* The range must be set in accordance with the range element type.
*
* @param range Iterable of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleRadial<Range = number, Unknown = never>(
range?: Iterable<Range>,
): ScaleRadial<Range, Range, Unknown>;
/**
* Constructs a new radial scale with the specified domain and range.
*
* The first generic corresponds to the data type of the range elements.
* The second generic corresponds to the data type of the unknown value.
*
* The range must be set in accordance with the range element type.
*
* @param domain Iterable of numeric domain values.
* @param range Iterable of range values.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function scaleRadial<Range, Unknown = never>(
domain: Iterable<NumberValue>,
range: Iterable<Range>,
): ScaleRadial<Range, Range, Unknown>;
// -------------------------------------------------------------------------------
// Time Scale Factories
// -------------------------------------------------------------------------------
/**
* A linear scale defined over a temporal domain.
*
* Time scales implement ticks based on calendar intervals, taking the pain out of generating axes for temporal domains.
*
* If the range is numeric, the mapping may be inverted to return a date.
*
* Note that the data types of the range and output of the scale must be compatible with the interpolator applied by the scale.
*
* The first generic corresponds to the data type of the range elements.
*
* The second generic corresponds to the data type of the output elements generated by the scale.
*
* The third generic corresponds to the data type of the unknown value.
*
* If range element and output element type differ, the interpolator factory used with the scale must match this behavior and
* convert the interpolated range element to a corresponding output element.
*/
export interface ScaleTime<Range, Output, Unknown = never> {
/**
* Given a value from the domain, returns the corresponding value from the range, subject to interpolation, if any.
*
* If the given value is outside the domain, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the range.
*
* Note: The interpolation function applied by the scale may change the output type from the range type as part of the interpolation.
*
* @param value A temporal value from the domain. If the value is not a Date, it will be coerced to Date.
*/
(value: Date | NumberValue): Output | Unknown;
/**
* Given a value from the range, returns the corresponding value from the domain. Inversion is useful for interaction,
* say to determine the data value corresponding to the position of the mouse.
*
* If the given value is outside the range, and clamping is not enabled, the mapping may be extrapolated such that the returned value is outside the domain.