Class pv.Scale.ordinal
Extends
pv.Scale.
Represents an ordinal scale. An ordinal scale represents a
pairwise mapping from n discrete values in the input domain to
n discrete values in the output range. For example, an ordinal scale
might map a domain of species ["setosa", "versicolor", "virginica"] to colors
["red", "green", "blue"]. Thus, saying
.fillStyle(function(d) { switch (d.species) { case "setosa": return "red"; case "versicolor": return "green"; case "virginica": return "blue"; } })is equivalent to
.fillStyle(pv.Scale.ordinal("setosa", "versicolor", "virginica") .range("red", "green", "blue") .by(function(d) d.species))If the mapping from species to color does not need to be specified explicitly, the domain can be omitted. In this case it will be inferred lazily from the data:
.fillStyle(pv.colors("red", "green", "blue") .by(function(d) d.species))When the domain is inferred, the first time the scale is invoked, the first element from the range will be returned. Subsequent calls with unique values will return subsequent elements from the range. If the inferred domain grows larger than the range, range values will be reused. However, it is strongly recommended that the domain and the range contain the same number of elements.
A range can be discretized from a continuous interval (e.g., for pixel positioning) by using #split, #splitFlush or #splitBanded after the domain has been set. For example, if states is an array of the fifty U.S. state names, the state name can be encoded in the left position:
.left(pv.Scale.ordinal(states) .split(0, 640) .by(function(d) d.state))
N.B.: ordinal scales are not invertible (at least not yet), since the
domain and range and discontinuous. A workaround is to use a linear scale.
Defined in: OrdinalScale.js.
Constructor Attributes | Constructor Name and Description |
---|---|
Returns an ordinal scale for the specified domain.
|
Method Attributes | Method Name and Description |
---|---|
by(f)
Returns a view of this scale by the specified accessor function f.
|
|
domain()
Sets or gets the input domain.
|
|
range()
Sets or gets the output range.
|
|
split(min, max)
Sets the range from the given continuous interval.
|
|
splitBanded(min, max, band)
Sets the range from the given continuous interval.
|
|
splitFlush(min, max)
Sets the range from the given continuous interval.
|
- Parameters:
- {...} domain...
- optional domain values.
- See:
- pv.colors
- Parameters:
- {function} f
- an accessor function.
- Returns:
- {pv.Scale.ordinal} a view of this scale by the specified accessor function.
1. domain(values...)
Specifying the domain as a series of values is the most explicit and recommended approach. However, if the domain values are derived from data, you may find the second method more appropriate.
2. domain(array, f)
Rather than enumerating the domain values as explicit arguments to this method, you can specify a single argument of an array. In addition, you can specify an optional accessor function to extract the domain values from the array.
3. domain()
Invoking the domain method with no arguments returns the current domain as an array.
- Parameters:
- {...} domain...
- domain values.
- Returns:
- {pv.Scale.ordinal} this, or the current domain.
1. range(values...)
Specifying the range as a series of values is the most explicit and recommended approach. However, if the range values are derived from data, you may find the second method more appropriate.
2. range(array, f)
Rather than enumerating the range values as explicit arguments to this method, you can specify a single argument of an array. In addition, you can specify an optional accessor function to extract the range values from the array.
3. range()
Invoking the range method with no arguments returns the current range as an array.
- Parameters:
- {...} range...
- range values.
- Returns:
- {pv.Scale.ordinal} this, or the current range.
This method must be called after the domain is set.
- Parameters:
- {number} min
- minimum value of the output range.
- {number} max
- maximum value of the output range.
- Returns:
- {pv.Scale.ordinal} this.
- See:
- #splitFlush
- #splitBanded
The band width argument, band, is typically in the range [0, 1] and defaults to 1. This fraction corresponds to the amount of space in the range to allocate to the bands, as opposed to padding. A value of 0.5 means that the band width will be equal to the padding width. The computed absolute band width can be retrieved from the range as scale.range().band.
If the band width argument is negative, this method will allocate bands of a fixed width -band, rather than a relative fraction of the available space.
Tip: to inset the bands by a fixed amount p, specify a minimum value of min + p (or simply p, if min is 0). Then set the mark width to scale.range().band - p.
This method must be called after the domain is set.
- Parameters:
- {number} min
- minimum value of the output range.
- {number} max
- maximum value of the output range.
- {number} band Optional
- the fractional band width in [0, 1]; defaults to 1.
- Returns:
- {pv.Scale.ordinal} this.
- See:
- #split
This method must be called after the domain is set.
- Parameters:
- {number} min
- minimum value of the output range.
- {number} max
- maximum value of the output range.
- Returns:
- {pv.Scale.ordinal} this.
- See:
- #split