com.github.gwtd3.api.scales

Class OrdinalScale

java.lang.Object

com.google.gwt.core.client.JavaScriptObject

com.github.gwtd3.api.scales.Scale<OrdinalScale>

com.github.gwtd3.api.scales.OrdinalScale

public class OrdinalScale
extends Scale<OrdinalScale>

Ordinal Scales have a discrete domain, such as a set of names or categories, and a discrete output range.

The first element in the domain array will be mapped to the first element in the output range, the second domain value to the second range value, and so on.

Domain values are stored internally in an associative array as a mapping from value to index; the resulting index is then used to retrieve a value from the output range.

Thus, an ordinal scale's values must be coercible to a string, and the stringified version of the domain value uniquely identifies the corresponding range value.

Setting the domain on an ordinal scale is optional: if no domain is set, each unique value that is passed to the scale function will be assigned a new value from the output range; in other words, the domain will be inferred implicitly from usage.

However, it is a good idea to assign the ordinal scale's domain to ensure deterministic behavior, as inferring the domain from usage will be dependent on ordering.

If the domain is set explicitly, values passed to the scale that were not explicitly part of the domain will be added.

If there are fewer elements in the range than in the domain, the scale will recycle values from the start of the range.

You may use Scale.range(double...) methods for when the set of discrete output values is computed explicitly, such as a set of categorical colors.

In other cases, such as determining the layout of an ordinal scatterplot or bar chart, you may find the #rangePoints(JsArrayInteger, double) or #rangeBands(JsArrayInteger, double) operators more convenient.

Author:

Anthony Schiochet

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	OrdinalScale()

Method Summary

Methods

Modifier and Type	Method and Description
double	rangeBand() Returns the band width.
OrdinalScale	rangeBands(double start, double end) See rangeBands(double, double, double, double) with a padding of 0.
OrdinalScale	rangeBands(double start, double end, double padding) See rangeBands(double, double, double, double) with a outerPadding of 0.
OrdinalScale	rangeBands(double start, double end, double padding, double outerPadding) Sets the output range from the continuous interval specified by its start and end bounds, representing the minimum and maximum numeric value.
Array<Double>	rangeExtent() Returns a two-element array representing the extent of the scale's range, i.e., the smallest and largest values.
OrdinalScale	rangePoints(double start, double end) Shortcut to rangePoints(double, double, double) with a default padding of 0.
OrdinalScale	rangePoints(double start, double end, double padding) Sets the output range from the continuous interval specified by its start and end bounds, representing the minimum and maximum numeric value.
OrdinalScale	rangeRoundBands(double start, double end) Like rangeBands(double, double, double, double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.
OrdinalScale	rangeRoundBands(double start, double end, double padding) Like rangeBands(double, double, double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.
OrdinalScale	rangeRoundBands(double start, double end, double padding, double outerPadding) Like rangeBands(double, double, double,double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.
OrdinalScale	rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval) Like rangeRoundBands(double, double, double, double).
OrdinalScale	rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval, double padding) Like rangeRoundBands(double, double, double, double).
OrdinalScale	rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval, double padding, double outerPadding) Like rangeRoundBands(double, double, double, double).
OrdinalScale	rangeRoundPoints(double start, double end) Shortcut to rangeRoundPoints(double, double, double) with a default padding of 0.
OrdinalScale	rangeRoundPoints(double start, double end, double padding) Like rangePoints(double, double, double), except guarantees that the range values are integers so as to avoid antialiasing artifacts.

Methods inherited from class com.github.gwtd3.api.scales.Scale

apply, apply, apply, copy, domain, domain, domain, domain, range, range, range, range

Methods inherited from class com.google.gwt.core.client.JavaScriptObject

cast, createArray, createArray, createFunction, createObject, equals, hashCode, toSource, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

OrdinalScale

protected OrdinalScale()

Method Detail

rangePoints

public final OrdinalScale rangePoints(double start,
                       double end,
                       double padding)

Sets the output range from the continuous interval specified by its start and end bounds, representing the minimum and maximum numeric value.

This interval is subdivided into n evenly-spaced points, where n is the number of (unique) values in the input domain.

The first and last point may be offset from the edge of the interval according to the specified padding.

The padding is expressed as a multiple of the spacing between points.

A reasonable value is 1.0, such that the first and last point will be offset from the minimum and maximum value by half the distance between points.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding

Returns:

this instance

rangePoints

public final OrdinalScale rangePoints(double start,
                       double end)

Shortcut to rangePoints(double, double, double) with a default padding of 0.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

Returns:

this instance

rangeRoundPoints

public final OrdinalScale rangeRoundPoints(double start,
                            double end,
                            double padding)

Like rangePoints(double, double, double), except guarantees that the range values are integers so as to avoid antialiasing artifacts.

Note that rounding necessarily introduces additional outer padding which is, on average, proportional to the length of the domain. For example, for a domain of size 50, an additional 25px of outer padding on either side may be required. Modifying the range extent to be closer to a multiple of the domain length may reduce the additional padding.

(Alternatively, you could round the output of the scale manually or apply shape-rendering: crispEdges. However, this will result in irregularly spaced points.)

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding

Returns:

this instance

rangeRoundPoints

public final OrdinalScale rangeRoundPoints(double start,
                            double end)

Shortcut to rangeRoundPoints(double, double, double) with a default padding of 0.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

Returns:

this instance

rangeBands

public final OrdinalScale rangeBands(double start,
                      double end,
                      double padding,
                      double outerPadding)

Sets the output range from the continuous interval specified by its start and end bounds, representing the minimum and maximum numeric value.

This interval is subdivided into n evenly-spaced bands, where n is the number of (unique) values in the input domain.

The bands may be offset from the edge of the interval and other bands according to the specified padding, which defaults to zero.

The padding is typically in the range [0,1] and corresponds to the amount of space in the range interval to allocate to padding.

A value of 0.5 means that the band width will be equal to the padding width.

The outerpadding argument is for the entire group of bands; a value of 0 means there will be padding only between rangeBands.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding to be set to between each band, between 0 and 1

outerPadding - the padding around the whole group of bands.

Returns:

this instance

rangeBands

public final OrdinalScale rangeBands(double start,
                      double end,
                      double padding)

See rangeBands(double, double, double, double) with a outerPadding of 0.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding to be set to between each band, between 0 and 1

Returns:

this instance

rangeBands

public final OrdinalScale rangeBands(double start,
                      double end)

See rangeBands(double, double, double, double) with a padding of 0.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval)

Like rangeRoundBands(double, double, double, double).

Parameters:

interval - a two-elements array

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval,
                           double padding)

Like rangeRoundBands(double, double, double, double).

Parameters:

interval - a two-elements array

padding - the padding

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(com.google.gwt.core.client.JavaScriptObject interval,
                           double padding,
                           double outerPadding)

Like rangeRoundBands(double, double, double, double).

Parameters:

interval - a two-elements array

padding - the padding

outerPadding - the outer padding

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(double start,
                           double end,
                           double padding,
                           double outerPadding)

Like rangeBands(double, double, double,double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding to be set to between each band, between 0 and 1

outerPadding - the padding around the whole group of bands.

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(double start,
                           double end,
                           double padding)

Like rangeBands(double, double, double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

padding - the padding to be set to between each band, between 0 and 1

Returns:

this instance

rangeRoundBands

public final OrdinalScale rangeRoundBands(double start,
                           double end)

Like rangeBands(double, double, double, double), except guarantees that the band width and offset are integer values, so as to avoid antialiasing artifacts.

Parameters:

start - the start bound of the interval

end - the end bound of the interval

Returns:

this instance

rangeBand

public final double rangeBand()

Returns the band width.

When the scale’s range is configured with rangeBands(double, double, double, double) or rangeRoundBands(double, double, double, double), the scale returns the lower value for the given input.

The upper value can then be computed by offsetting by the band width.

If the scale’s range is set using Scale.range() or rangePoints(double, double, double), the band width is zero.

Returns:

the band width

rangeExtent

public final Array<Double> rangeExtent()

Returns a two-element array representing the extent of the scale's range, i.e., the smallest and largest values.

Returns:

the extent of the scale's range