-
Notifications
You must be signed in to change notification settings - Fork 47
Quantitative Scales
Wiki ▸ API Reference ▸ Scales ▸ Quantitative Scales
Scales are functions that map from an input domain to an output range. Quantitative scales have a continuous domain, such as the set of real numbers, or dates. There are also ordinal scales, which have a discrete domain, such as a set of names or categories. Scales are an optional feature in D3; you don't have to use them, if you prefer to do the math yourself. However, using scales can greatly simplify the code needed to map a dimension of data to a visual representation.
A scale object, such as that returned by d3.scale.linear, is both an object and a function. That is: you can call the scale like any other function, and the scale has additional methods that change its behavior. Like other classes in D3, scales follow the method chaining pattern where setter methods return the scale itself, allowing multiple setters to be invoked in a concise statement.
리니어 스케일은 가장 일반적인 스케일이다. 연속적인 입력 범위(domain)을 연속적인 출력 범위(range)로 매핑하기에 좋은 선택이다. 이 매핑은 선형 매핑이다. 출력 범위값 y는 입력 범위 값 x에 관한 선형 함수 y = mx + b로 표시할 수 있다. 입력 범위(domain)는 일반적으로 시각화하기를 원하는 데이터의 차원(demension)이다. 예를 들면 표본 인구에서 학생들 키같은 거다. 출력 범위(range)는 일반적으로 원하는 시각화 출력값의 차원이다. 예를 들면 바(histogram) 차트 안의 막대 높이 같은거다.
# d3.scale.linear()
입력 범위가 [0,1]이고 출력 범위가 [0,1]인 리니어 스케일을 새로 생성한다. 이처럼 막 생성한 리니어 스케일은 1:1이다. 즉 linear(0.5)는 0.5를 반환한다.
# linear(x)
Given a value x in the input domain, returns the corresponding value in the output range.
# linear.invert(y)
Returns the value in the input domain x for the corresponding value in the output range y. This represents the inverse mapping from range to domain. For a valid value y in the output range, linear(linear.invert(y)) equals y; similarly, for a valid value x in the input domain, linear.invert(linear(x)) equals x. Equivalently, you can construct the invert operator by building a new scale while swapping the domain and range. The invert operator is particularly useful for interaction, say to determine the value in the input domain that corresponds to the pixel location under the mouse.
Note: the invert operator is only supported if the output range is numeric! D3 allows the output range to be any type; under the hood, d3.interpolate or a custom interpolator of your choice is used to map the normalized parameter t to a value in the output range. Thus, the output range may be colors, strings, or even arbitrary objects. As there is no facility to "uninterpolate" arbitrary types, the invert operator is currently supported only on numeric ranges.
# linear.domain([numbers])
numbers를 인자로 넘기면 지정한 숫자 배열로 스케일의 입력 범위를 지정한다. 배열에는 두개 이상의 숫자가 있어야 한다. 인자로 넘긴 배열의 원소가 숫자가 아니면, 숫자로 변경한다. 이 변경은 스케일이 호출될 때 비슷하게 일어난다. 그러므로 선형 스케일를 타입 인코딩을 위해 사용할 수 있다. 마치 javascript date objects가 숫자로 변경할 수 있는 것 처럼 말이다. 하지만 날짜 변화는 d3.time.scale를 사용하는게 더 편하다. (여러분은 valueOf를 이용한 숫자형 객체를 구현할 수 있다. ) numbers 인자로 넘기지 않으면 현재 입력 범위를 반환한다.
Although linear scales typically have just two numeric values in their domain, you can specify more than two values for a polylinear scale. In this case, there must be an equivalent number of values in the output range. A polylinear scale represents multiple piecewise linear scales that divide a continuous domain and range. This is particularly useful for defining diverging quantitative scales. For example, to interpolate between white and red for negative values, and white and green for positive values, say:
var color = d3.scale.linear()
.domain([-1, 0, 1])
.range(["red", "white", "green"]);The resulting value of color(-.5) is "#ff8080", and the value of color(.5) is "#80c080". Internally, polylinear scales perform a binary search for the output interpolator corresponding to the given domain value. By repeating values in both the domain and range, you can also force a chunk of the input domain to map to a constant in the output range.
# linear.range([values])
If values is specified, sets the scale's output range to the specified array of values. The array must contain two or more values, to match the cardinality of the input domain. The elements in the given array need not be numbers; any value that is supported by the underlying interpolator will work. However, numeric ranges are required for the invert operator. If values is not specified, returns the scale's current output range.
# linear.rangeRound(values)
Sets the scale's output range to the specified array of values, while also setting the scale's interpolator to d3.interpolateRound. This is a convenience routine for when the values output by the scale should be exact integers, such as to avoid antialiasing artifacts. It is also possible to round the output values manually after the scale is applied.
# linear.interpolate([factory])
If factory is specified, sets the scale's output interpolator using the specified factory. The interpolator factory defaults to d3.interpolate, and is used to map the normalized domain parameter t in [0,1] to the corresponding value in the output range. The interpolator factory will be used to construct interpolators for each adjacent pair of values from the output range. If factory is not specified, returns the scale's interpolator factory.
# linear.clamp([boolean])
If boolean is specified, enables or disables clamping accordingly. By default, clamping is disabled, such that if a value outside the input domain is passed to the scale, the scale may return a value outside the output range through linear extrapolation. For example, with the default domain and range of [0,1], an input value of 2 will return an output value of 2. If clamping is enabled, the normalized domain parameter t is clamped to the range [0,1], such that the return value of the scale is always within the scale's output range. If boolean is not specified, returns whether or not the scale currently clamps values to within the output range.
# linear.nice()
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. The precision of the round value is dependent on the extent of the domain dx according to the following formula: exp(round(log(dx)) - 1). Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.20147987687960267, 0.996679553296417], the nice domain is [0.2, 1]. If the domain has more than two values, nicing the domain only affects the first and last value.
# linear.ticks(count)
Returns approximately count representative values from the scale's input domain. 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 input 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 input domain.
# linear.tickFormat(count)
Returns a number format function suitable for displaying a tick value. The specified count should have the same value as the count that is used to generate the tick values. You don't have to use the scale's built-in tick format, but it automatically computes the appropriate precision based on the fixed interval between tick values.
# linear.copy()
Returns an exact copy of this linear scale. Changes to this scale will not affect the returned scale, and vice versa.
Identity scales are a special case of linear scales where the domain and range are identical; the scale and its invert method are both the identity function. These scales are occasionally useful when working with pixel coordinates, say in conjunction with the axis and brush components.
# d3.scale.identity()
Constructs a new identity scale with the default domain [0, 1] and the default range [0, 1]. An identity scale is always equivalent to the identity function.
# identity(x)
# identity.invert(x)
Returns the given value x.
# identity.domain([numbers])
# identity.range([numbers])
If numbers is specified, sets the scale's input domain and output range to the specified array of numbers. The array must contain two or more numbers. If the elements in the given array are not numbers, they will be coerced to numbers; this coercion happens similarly when the scale is called. If numbers is not specified, returns the scale's current input domain (or equivalently, output range).
# identity.ticks(count)
Returns approximately count representative values from the scale's input domain (or equivalently, output range). 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 input 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 input domain.
# identity.tickFormat(count)
Returns a number format function suitable for displaying a tick value. The specified count should have the same value as the count that is used to generate the tick values. You don't have to use the scale's built-in tick format, but it automatically computes the appropriate precision based on the fixed interval between tick values.
# identity.copy()
Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
Power scales are similar to linear scales, except there's an exponential transform that is applied to the input domain value before the output range value is computed. The mapping to the output range value y can be expressed as a function of the input domain value x: y = mx^k + b, where k is the exponent value. Power scales also support negative values, in which case the input value is multiplied by -1, and the resulting output value is also multiplied by -1.
# d3.scale.sqrt()
Constructs a new power scale with the default domain [0,1], the default range [0,1], and the exponent .5. This method is shorthand for:
d3.scale.pow().exponent(.5)The returned scale is a function that takes a single argument x representing a value in the input domain; the return value is the corresponding value in the output range. Thus, the returned scale is equivalent to the sqrt function for numbers; for example sqrt(0.25) returns 0.5.
# d3.scale.pow()
Constructs a new power scale with the default domain [0,1], the default range [0,1], and the default exponent 1. Thus, the default power scale is equivalent to the identity function for numbers; for example pow(0.5) returns 0.5.
# pow(x)
Given a value x in the input domain, returns the corresponding value in the output range.
# pow.invert(y)
Returns the value in the input domain x for the corresponding value in the output range y. This represents the inverse mapping from range to domain. For a valid value y in the output range, pow(pow.invert(y)) equals y; similarly, for a valid value x in the input domain, pow.invert(pow(x)) equals x. Equivalently, you can construct the invert operator by building a new scale while swapping the domain and range. The invert operator is particularly useful for interaction, say to determine the value in the input domain that corresponds to the pixel location under the mouse.
Note: the invert operator is only supported if the output range is numeric! D3 allows the output range to be any type; under the hood, d3.interpolate or a custom interpolator of your choice is used to map the normalized parameter t to a value in the output range. Thus, the output range may be colors, strings, or even arbitrary objects. As there is no facility to "uninterpolate" arbitrary types, the invert operator is currently supported only on numeric ranges.
# pow.domain([numbers])
If numbers is specified, sets the scale's input domain to the specified array of numbers. The array must contain two or more numbers. If the elements in the given array are not numbers, they will be coerced to numbers; this coercion happens similarly when the scale is called. Thus, a power scale can be used to encode any type that can be converted to numbers. If numbers is not specified, returns the scale's current input domain.
As with linear scales (see linear.domain), power scales can also accept more than two values for the domain and range, thus resulting in polypower scale.
# pow.range([values])
If values is specified, sets the scale's output range to the specified array of values. The array must contain two or more values, to match the cardinality of the input domain. The elements in the given array need not be numbers; any value that is supported by the underlying interpolator will work. However, numeric ranges are required for the invert operator. If values is not specified, returns the scale's current output range.
# pow.rangeRound(values)
Sets the scale's output range to the specified array of values, while also setting the scale's interpolator to d3.interpolateRound. This is a convenience routine for when the values output by the scale should be exact integers, such as to avoid antialiasing artifacts. It is also possible to round the output values manually after the scale is applied.
# pow.exponent([k])
If k is specified, sets the current exponent to the given numeric value. If k is not specified, returns the current exponent. The default value is 1.
# pow.interpolate([interpolator])
If factory is specified, sets the scale's output interpolator using the specified factory. The interpolator factory defaults to d3.interpolate, and is used to map the normalized domain parameter t in [0,1] to the corresponding value in the output range. The interpolator factory will be used to construct interpolators for each adjacent pair of values from the output range. If factory is not specified, returns the scale's interpolator factory.
# pow.clamp([boolean])
If boolean is specified, enables or disables clamping accordingly. By default, clamping is disabled, such that if a value outside the input domain is passed to the scale, the scale may return a value outside the output range through linear extrapolation. For example, with the default domain and range of [0,1], an input value of 2 will return an output value of 2. If clamping is enabled, the normalized domain parameter t is clamped to the range [0,1], such that the return value of the scale is always within the scale's output range. If boolean is not specified, returns whether or not the scale currently clamps values to within the output range.
# pow.nice()
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. The precision of the round value is dependent on the extent of the domain dx according to the following formula: exp(round(log(dx)) - 1). Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.20147987687960267, 0.996679553296417], the nice domain is [0.2, 1]. If the domain has more than two values, nicing the domain only affects the first and last value.
# pow.ticks([count])
Returns approximately count representative values from the scale's input domain. 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 input 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 input domain.
# pow.tickFormat([count])
Returns a number format function suitable for displaying a tick value. The specified count should have the same value as the count that is used to generate the tick values. You don't have to use the scale's built-in tick format, but it automatically computes the appropriate precision based on the fixed interval between tick values.
# pow.copy()
Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
Log scales are similar to linear scales, except there's a logarithmic transform that is applied to the input domain value before the output range value is computed. The mapping to the output range value y can be expressed as a function of the input domain value x: y = m log(x) + b. Log scales also support negative values, in which case the input value is multiplied by -1, and the resulting output value is also multiplied by -1. However, note that the domain of a log scale should never contain zero, as log(0) is negative infinity.
# d3.scale.log()
Constructs a new log scale with the default domain [1,10], the default range [0,1], and the base 10.
# log(x)
Given a value x in the input domain, returns the corresponding value in the output range.
# log.invert(y)
Returns the value in the input domain x for the corresponding value in the output range y. This represents the inverse mapping from range to domain. For a valid value y in the output range, log(log.invert(y)) equals y; similarly, for a valid value x in the input domain, log.invert(log(x)) equals x. Equivalently, you can construct the invert operator by building a new scale while swapping the domain and range. The invert operator is particularly useful for interaction, say to determine the value in the input domain that corresponds to the pixel location under the mouse.
Note: the invert operator is only supported if the output range is numeric! D3 allows the output range to be any type; under the hood, d3.interpolate or a custom interpolator of your choice is used to map the normalized parameter t to a value in the output range. Thus, the output range may be colors, strings, or even arbitrary objects. As there is no facility to "uninterpolate" arbitrary types, the invert operator is currently supported only on numeric ranges.
# log.domain([values])
If numbers is specified, sets the scale's input domain to the specified array of numbers. The array must contain two or more numbers. If the elements in the given array are not numbers, they will be coerced to numbers; this coercion happens similarly when the scale is called. Thus, a log scale can be used to encode any type that can be converted to numbers. If numbers is not specified, returns the scale's current input domain.
As with linear scales (see linear.domain), log scales can also accept more than two values for the domain and range, thus resulting in polylog scale.
# log.range([values])
If values is specified, sets the scale's output range to the specified array of values. The array must contain two or more values, to match the cardinality of the input domain. The elements in the given array need not be numbers; any value that is supported by the underlying interpolator will work. However, numeric ranges are required for the invert operator. If values is not specified, returns the scale's current output range.
# log.rangeRound(values)
Sets the scale's output range to the specified array of values, while also setting the scale's interpolator to d3.interpolateRound. This is a convenience routine for when the values output by the scale should be exact integers, such as to avoid antialiasing artifacts. It is also possible to round the output values manually after the scale is applied.
# log.interpolate([interpolator])
If factory is specified, sets the scale's output interpolator using the specified factory. The interpolator factory defaults to d3.interpolate, and is used to map the normalized domain parameter t in [0,1] to the corresponding value in the output range. The interpolator factory will be used to construct interpolators for each adjacent pair of values from the output range. If factory is not specified, returns the scale's interpolator factory.
# log.clamp([boolean])
If boolean is specified, enables or disables clamping accordingly. By default, clamping is disabled, such that if a value outside the input domain is passed to the scale, the scale may return a value outside the output range through linear extrapolation. For example, with the default domain and range of [0,1], an input value of 2 will return an output value of 2. If clamping is enabled, the normalized domain parameter t is clamped to the range [0,1], such that the return value of the scale is always within the scale's output range. If boolean is not specified, returns whether or not the scale currently clamps values to within the output range.
# log.nice()
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. The nearest round value is based on the nearest power of ten. Nicing is useful if the domain is computed from data and may be irregular. For example, for a domain of [0.20147987687960267, 0.996679553296417], 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.
# log.ticks()
Returns representative values from the scale's input domain. The returned tick values are uniformly spaced within each power of ten, and are guaranteed to be within the extent of the input domain. Ticks are often used to display reference lines, or tick marks, in conjunction with the visualized data. Note that the number of ticks cannot be customized (due to the nature of log scales); however, you can filter the returned array of values if you want to reduce the number of ticks.
# log.tickFormat([count, [format]])
Returns a number format function suitable for displaying a tick value. The returned tick format is implemented as d.toPrecision(1). If a count is specified, then some of the tick labels may not be displayed; this is useful if there is not enough room to fit all of the tick labels. However, note that the tick marks will still be displayed (so that the log scale distortion remains visible). When specifying a count, you may also override the format function. For example, to display 20 ticks of a currency:
var formatNumber = d3.format(",.0f"), // for formatting integers
formatCurrency = function(d) { return "$" + formatNumber(d); };
scale.ticks(20, formatCurrency);# log.copy()
Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
Quantize scales are a variant of linear scales with a discrete rather than continuous range. The input domain is still continuous, and divided into uniform segments based on the number of values in (the cardinality of) the output range. The mapping is linear in that the output range value y can be expressed as a linear function of the input domain value x: y = mx + b. The input domain is typically a dimension of the data that you want to visualize, such as the height of students (measured in meters) in a sample population. The output range is typically a dimension of the desired output visualization, such as the height of bars (measured in pixels) in a histogram.
# d3.scale.quantize()
Constructs a new quantize scale with the default domain [0,1] and the default range [0,1]. Thus, the default quantize scale is equivalent to the round function for numbers; for example quantize(0.49) returns 0, and quantize(0.51) returns 1.
# quantize(x)
Given a value x in the input domain, returns the corresponding value in the output range.
# quantize.domain([numbers])
If numbers is specified, sets the scale's input domain to the specified two-element array of numbers. If the array contains more than two numbers, only the first and last number are used. If the elements in the given array are not numbers, they will be coerced to numbers; this coercion happens similarly when the scale is called. Thus, a quantize scale can be used to encode any type that can be converted to numbers. If numbers is not specified, returns the scale's current input domain.
# quantize.range([values])
If values is specified, sets the scale's output range to the specified array of values. The array may contain any number of discrete values. The elements in the given array need not be numbers; any value or type will work. If values is not specified, returns the scale's current output range.
# quantize.copy()
Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.
Quantile scales map an input domain to a discrete range. Although the input domain is continuous and the scale will accept any reasonable input value, the input domain is specified as a discrete set of values. The number of values in (the cardinality of) the output range determines the number of quantiles that will be computed from the input domain. To compute the quantiles, the input domain is sorted, and treated as a population of discrete values. The input domain is typically a dimension of the data that you want to visualize, such as the daily change of the stock market. The output range is typically a dimension of the desired output visualization, such as a diverging color scale.
# d3.scale.quantile()
Constructs a new quantile scale with an empty domain and an empty range. The quantile scale is invalid until both a domain and range is specified.
# quantile(x)
Given a value x in the input domain, returns the corresponding value in the output range.
# quantile.domain([numbers])
If numbers is specified, sets the input domain of the quantile scale to the specified set of discrete numeric values. The array must not be empty, and must contain at least one numeric value; NaN, null and undefined values are ignored and not considered part of the sample population. If the elements in the given array are not numbers, they will be coerced to numbers; this coercion happens similarly when the scale is called. A copy of the input array is sorted and stored internally. Thus, a quantile scale can be used to encode any type that can be converted to numbers. If numbers is not specified, returns the scale's current input domain.
# quantile.range([values])
If values is specified, sets the discrete values in the output range. The array must not be empty, and may contain any type of value. The number of values in (the cardinality, or length, of) the values array determines the number of quantiles that are computed. For example, to compute quartiles, values must be an array of four elements such as [0, 1, 2, 3]. If values is not specified, returns the current output range.
# quantile.quantiles()
Returns the quantile thresholds. If the output range contains n discrete values, the returned threshold array will contain n - 1 values. Values less than the first element in the thresholds array, quantiles()[0], are considered in the first quantile; greater values less than the second threshold are in the second quantile, and so on. Internally, the thresholds array is used with d3.bisect to find the output quantile associated with the given input value.
# quantile.copy()
Returns an exact copy of this scale. Changes to this scale will not affect the returned scale, and vice versa.