Class Index | File Index

Classes


Class pv.Scale.quantitative


Extends pv.Scale.
Represents an abstract quantitative scale; a function that performs a numeric transformation. This class is typically not used directly; see one of the quantitative scale implementations (linear, log, root, etc.) instead. A quantitative scale represents a 1-dimensional transformation from a numeric domain of input data [d0, d1] to a numeric range of pixels [r0, r1]. In addition to readability, scales offer several useful features:

1. The range can be expressed in colors, rather than pixels. For example:

    .fillStyle(pv.Scale.linear(0, 100).range("red", "green"))
will fill the marks "red" on an input value of 0, "green" on an input value of 100, and some color in-between for intermediate values.

2. The domain and range can be subdivided for a non-uniform transformation. For example, you may want a diverging color scale that is increasingly red for negative values, and increasingly green for positive values:

    .fillStyle(pv.Scale.linear(-1, 0, 1).range("red", "white", "green"))
The domain can be specified as a series of n monotonically-increasing values; the range must also be specified as n values, resulting in n - 1 contiguous linear scales.

3. Quantitative scales can be inverted for interaction. The #invert method takes a value in the output range, and returns the corresponding value in the input domain. This is frequently used to convert the mouse location (see pv.Mark#mouse) to a value in the input domain. Note that inversion is only supported for numeric ranges, and not colors.

4. A scale can be queried for reasonable "tick" values. The #ticks method provides a convenient way to get a series of evenly-spaced rounded values in the input domain. Frequently these are used in conjunction with pv.Rule to display tick marks or grid lines.

5. A scale can be "niced" to extend the domain to suitable rounded numbers. If the minimum and maximum of the domain are messy because they are derived from data, you can use #nice to round these values down and up to even numbers.
Defined in: QuantitativeScale.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Returns a default quantitative, linear, scale for the specified domain.
Method Summary
Method Attributes Method Name and Description
 
by(f)
Returns a view of this scale by the specified accessor function f.
 
Sets or gets the input domain.
 
invert(y)
Inverts the specified value in the output range, returning the corresponding value in the input domain.
 
nice()
"Nices" this scale, extending the bounds of the input domain to evenly-rounded values.
 
Sets or gets the output range.
 
Formats the specified tick value using the appropriate precision, based on the step interval between tick marks.
 
ticks(m)
Returns an array of evenly-spaced, suitably-rounded values in the input domain.
Class Detail
pv.Scale.quantitative()
Returns a default quantitative, linear, scale for the specified domain. The arguments to this constructor are optional, and equivalent to calling #domain. The default domain and range are [0,1].

This constructor is typically not used directly; see one of the quantitative scale implementations instead.

Parameters:
{number...} domain...
optional domain values.
See:
pv.Scale.linear
pv.Scale.log
pv.Scale.root
Method Detail
{pv.Scale.quantitative} by(f)
Returns a view of this scale by the specified accessor function f. Given a scale y, y.by(function(d) d.foo) is equivalent to function(d) y(d.foo).

This method is provided for convenience, such that scales can be succinctly defined inline. For example, given an array of data elements that have a score attribute with the domain [0, 1], the height property could be specified as:

    .height(pv.Scale.linear().range(0, 480).by(function(d) d.score))
This is equivalent to:
    .height(function(d) d.score * 480)
This method should be used judiciously; it is typically more clear to invoke the scale directly, passing in the value to be scaled.
Parameters:
{function} f
an accessor function.
Returns:
{pv.Scale.quantitative} a view of this scale by the specified accessor function.

{pv.Scale.quantitative} domain()
Sets or gets the input domain. This method can be invoked several ways:

1. domain(min, ..., max)

Specifying the domain as a series of numbers is the most explicit and recommended approach. Most commonly, two numbers are specified: the minimum and maximum value. However, for a diverging scale, or other subdivided non-uniform scales, multiple values can be specified. Values can be derived from data using pv.min and pv.max. For example:

    .domain(0, pv.max(array))
An alternative method for deriving minimum and maximum values from data follows.

2. domain(array, minf, maxf)

When both the minimum and maximum value are derived from data, the arguments to the domain method can be specified as the array of data, followed by zero, one or two accessor functions. For example, if the array of data is just an array of numbers:

    .domain(array)
On the other hand, if the array elements are objects representing stock values per day, and the domain should consider the stock's daily low and daily high:
    .domain(array, function(d) d.low, function(d) d.high)
The first method of setting the domain is preferred because it is more explicit; setting the domain using this second method should be used only if brevity is required.

3. domain()

Invoking the domain method with no arguments returns the current domain as an array of numbers.

Parameters:
{number...} domain...
domain values.
Returns:
{pv.Scale.quantitative} this, or the current domain.

{number} invert(y)
Inverts the specified value in the output range, returning the corresponding value in the input domain. This is frequently used to convert the mouse location (see pv.Mark#mouse) to a value in the input domain. Inversion is only supported for numeric ranges, and not colors.

Note that this method does not do any rounding or bounds checking. If the input domain is discrete (e.g., an array index), the returned value should be rounded. If the specified y value is outside the range, the returned value may be equivalently outside the input domain.

Parameters:
{number} y
a value in the output range (a pixel location).
Returns:
{number} a value in the input domain.

{pv.Scale.quantitative} nice()
"Nices" this scale, extending the bounds of the input domain to evenly-rounded values. Nicing is useful if the domain is computed dynamically from data, and may be irregular. For example, given a domain of [0.20147987687960267, 0.996679553296417], a call to nice() might extend the domain to [0.2, 1].

This method must be invoked each time after setting the domain.

Returns:
{pv.Scale.quantitative} this.

{pv.Scale.quantitative} range()
Sets or gets the output range. This method can be invoked several ways:

1. range(min, ..., max)

The range may be specified as a series of numbers or colors. Most commonly, two numbers are specified: the minimum and maximum pixel values. For a color scale, values may be specified as pv.Colors or equivalent strings. For a diverging scale, or other subdivided non-uniform scales, multiple values can be specified. For example:

    .range("red", "white", "green")

Currently, only numbers and colors are supported as range values. The number of range values must exactly match the number of domain values, or the behavior of the scale is undefined.

2. range()

Invoking the range method with no arguments returns the current range as an array of numbers or colors.

Parameters:
{...} range...
range values.
Returns:
{pv.Scale.quantitative} this, or the current range.

{string} tickFormat(t)
Formats the specified tick value using the appropriate precision, based on the step interval between tick marks. If #ticks has not been called, the argument is converted to a string, but no formatting is applied.
Parameters:
{number} t
a tick value.
Returns:
{string} a formatted tick value.

{number[]} ticks(m)
Returns an array of evenly-spaced, suitably-rounded values in the input domain. This method attempts to return between 5 and 10 tick values. These values are frequently used in conjunction with pv.Rule to display tick marks or grid lines.
Parameters:
{number} m Optional
optional number of desired ticks.
Returns:
{number[]} an array input domain values to use as ticks.

Documentation generated by JsDoc Toolkit 2.3.2 on Sun May 30 2010 18:10:25 GMT-0700 (PDT)