Scales

Scales are used in Rayon to map one set of data into another – for instance, mapping numeric values into color values or spatial coordinates. They are most often associated with data in plots or ticksets.

The simplest scale is a function that takes as its sole argument a point in the input space and returns a point in the output space. For instance, the following scale function coerces data into one of three positions on a numeric range from 0 to 1:

def step_scale(in_val):
    if in_val < 10:
       return 0.0
    elif in_val < 20:
       return .5
    else:
       return 1.0

Functions of this sort may be used wherever scales are called for. See Scales for more information.

This chapter describes scale objects, which may be used as scales. In addition to transforming data, scale objects can infer the range of input from sets of data automatically when they are associated with data in plots or ticksets.

Advanced Rayon users may wish to create custom scale objects. For more information on this, see Creating new Scale subclasses.

Exceptions

Rayon scales may raise the following exceptions.

class rayon.scales.RayonScaleException

Bases: rayon.RayonException

Base class of scale-related exceptions.

class rayon.scales.RayonLimitException

Bases: rayon.scales.RayonScaleException

Indicates that the user tried to generate an invalid scale, or to use the limits of a scale without properly specifying them. If a scale is not fixed and no data has been associated with it, a call to a scale’s get_input_min or get_output_max methods will raise this exception.

class rayon.scales.RayonRangeException

Bases: rayon.scales.RayonScaleException

Indicates that a user has passed a value that cannot be mapped using this scale.

Creating Scales

All scale objects are created from the Toolbox object using the new_scale method, supplying the label and arguments for the desired scale. The scale objects in this chapter are organized by the label used to create them in the new_scale method.

Scale Limits

Unlike functions, scale objects can automatically fit the limits of their input to the data that will be scaled. Before rendering a chart, Rayon first registers all the datasets used in a visualization with the scales that will transform them.

Users can override this behavior to specify fixed custom limits using the input_min and input_max parameters to new_scale. These parameters fix the lower and upper bounds of the scale input at the specified values.

If the fixed parameter to new_scale is set to False, input_min and input_max will be taken as initial minimum and maximum values; if values exceeding these limits are associated with the scale, the limits will grow to include them.

Range Scales

Most of the scales in this chapter map input data values to a single output value, but this isn’t appropriate in all cases. For instance, a bar plot draws its bars between two points on the X axis. This means that the bar plot requires a range scale like the catrange scale, which maps a set of categories into a set of non-overlapping ranges along the X axis.

Range scales can be converted into corresponding single-value scales that emit a point within the range; these single-value scales can, in turn, be converted back to range scales. For instance, a catrange scale may be converted into a categorical scale using the CategoricalRangeScale.to_categorical_scale method.

Categorical Scales

Categorical scales are used to display data that falls into distinct categories. Examples include zip codes, unique identifiers, or choices in a multiple choice question.

Categorical data is usually unordered; a unique ID of 1 isn’t necessarily “less than” a unique ID of 100, just different. When visualizing data, however, one may prefer to show categories in a certain order, either because it will be easier for users to navigate (e.g., alphabetical order), or to keep the order the same across multiple visualizations.

For this reason, categorical scales in Rayon maintain their categories in the order in which they were inserted.

categorical

toolbox.new_scale('categorical'[, categories : list, output_min=0, output_max=1 fixed=True, reverse=False])

Maps categories to evenly-spaced points on a numeric range. These points are located inside non-overlapping subranges within the output range.

categories is a sequence of input categories. The elements in the sequence may be of any type provided that they are unique and can be tested for equality. This parameter may be omitted; in that case, the categories will be determined by Rayon based on the data the scale is required to transform.

output_min and output_max define the boundaries of a numeric range. The scale will map categories to points evenly distributed within this range. When used as a scale on a spatial axis in a plot or border, the default values will use all the space allocated for the element being visualized.

alignment indicates where the output point will lie within the allotted subrange. Acceptable values are beginning, center or end, indicating that the point should be at the beginning, midpoint or end of the subrange, respectively.

If fixed is True, the value of categories will be the final value for the scale; no categories may be added or removed. Otherwise, the category list may change if new data is associated with the scale.

If reverse is False, categories will be ordered as they were added to the scale. Additional categories beyond the initial set will be appended in the order they were inserted. If reverse is True, this order will be reversed.

get_input_max()

Returns the last category added to the scale. If a sequence of categories was supplied to the scale when it was created and no additional data has been associated with the object, the last category in that sequence is returned. If data has been associated with this scale since it was created, this method returns the last unique category in the most recent set of data currently associated with it.

If the reverse parameter was passed to this scale when it was created, the order described above is reversed. The result of calling this method is then equivalent to calling get_input_min on a scale that has not been reversed.

If no categories are associated with this scale, this method returns None.

get_input_min()

Returns the first category added to the scale. If a sequence of categories was supplied to the scale when it was created, the first category in that sequence is returned. If the scale was created without categories and data has been associated with this scale, this method returns the first category in the oldest set of data currently associated with it.

If the reverse parameter was passed to this scale when it was created, the order described above is reversed. The result of calling this method is then equivalent to calling get_input_max on a scale that has not been reversed.

If no categories are associated with this scale, this method returns None.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over all the categories currently associated with this scale. The num_ticks and inside parameters are ignored.

If the reverse parameter was passed to this scale when it was created, this method is equivalent to calling reversed(get_nice_tick_positions) on a non-reversed version of this scale.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

to_categorical_range_scale([fixed=True])

Returns a catrange scale using the same categories and range bounds data as this scale.

The resulting catrange scale will be fixed (i.e., categories cannot be added to it) unless fixed is False.

catrange

toolbox.new_scale('catrange'[, categories : list, output_min=0, output_max=1, fixed=True, reverse=False])

Maps categories to contiguous, non-overlapping sub-ranges in a larger range. This scale is a ranged version of the categorical scale. (See Range Scales)

categories is a sequence of input categories. The elements in the sequence may be of any type provided that they are unique and can be tested for equality. This parameter may be omitted; in that case, the categories will be determined by Rayon based on the data the scale is required to transform.

output_min and output_max define the boundaries of a numeric range. The scale will map categories to contiguous subranges of equal size that cover the range. When used as a scale on a spatial axis in a plot or border, the default values for output_min and output_max will use all the space allocated for the element being visualized.

If fixed is True, the value of categories will be the final value for the scale; no categories may be added or removed. Otherwise, the category list may change if new data is associated with the scale.

If reverse is False, categories will be ordered as they were added to the scale. Additional categories beyond the initial set will be appended in the order they were inserted. If reverse is True, this order will be reversed.

get_input_max()

Returns the last category added to the scale. If a sequence of categories was supplied to the scale when it was created and no additional data has been associated with the object, the last category in that sequence is returned. If data has been associated with this scale since it was created, this method returns the last unique category in the most recent set of data currently associated with it.

If the reverse parameter was passed to this scale when it was created, the order described above is reversed. The result of calling this method is then equivalent to calling get_input_min on a scale that has not been reversed.

If no categories are associated with this scale, this method returns None.

get_input_min()

Returns the first category added to the scale. If a sequence of categories was supplied to the scale when it was created, the first category in that sequence is returned. If the scale was created without categories and data has been associated with this scale, this method returns the first category in the oldest set of data currently associated with it.

If the reverse parameter was passed to this scale when it was created, the order described above is reversed. The result of calling this method is then equivalent to calling get_input_max on a scale that has not been reversed.

If no categories are associated with this scale, this method returns None.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over all the categories currently associated with this scale. The num_ticks and inside parameters are ignored.

If the reverse parameter was passed to this scale when it was created, this method is equivalent to calling reversed(get_nice_tick_positions) on a non-reversed version of this scale.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

range_size()

Returns the size of the subranges allocated to each category, in terms of the output range. This value multiplied by the number of categories should equal the size of the output range.

to_categorical_scale([alignment="beginning", fixed=True])

Returns a CategoricalScale using the same categories and range bounds data as this scale.

alignment is where in the range to put the reference point for the categories; see :meth:CategoricalScale.__init__.

The resulting CategoricalScale will be fixed (i.e., categories cannot be added to it) unless fixed is False.

Color Scales

gradient

toolbox.new_scale('gradient'[, input_min : num, input_max : num, output_min="#FFFFFF", output_max="#000000", numsteps=255, fixed=True])

Maps a numeric range linearly to a range of colors along a gradient.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max are color specifications (see Specifying Colors) representing the beginning and end points of a color gradient. numsteps is the number of colors in the gradient, including the beginning and end points.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a sequence of aesthetically pleasing positions in the input range of the scale. These positions will be used for for placing tick marks.

num_ticks is the requested number of tick positions. This is only a request; get_nice_tick_positions may choose to honor it or not as appropriate to the scale.

If inside is True, the lowest and highest points in the set of positions will fall inside the minimum and maximum values in the input range. If it is False, the lowest and highest points in the set must fall on or outside the minimum and maximum values in the input range.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

loggrad

toolbox.new_scale('loggrad'[, input_min : num, input_max : num, output_min="#FFFFFF", output_max="#000000", numsteps=255, fixed=True])

Maps a numeric range to a range of colors along a gradient, using a log-transformed linear scale.

This scale’s relationship to the gradient scale is analogous to the log scale’s relationship to the linear scale. As with the log scale, valid input for this scale is any positive real number; zero and negative numbers are invalid input and will raise a RayonException (a RayonLimitException if invalid scale limits are specified, or a RayonRangeException if the user attempts to convert an invalid value).

If your data is integer data containing positive numbers and zero (such as most count data), consider using the cloggrad scale, which is designed for this kind of data.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max are color specifications (see Specifying Colors) representing the beginning and end points of a color gradient. numsteps is the number of colors in the gradient, including the beginning and end points.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a set of tick positions evenly spaced on the log scale for this range of data. (E.g. 10, 100, 1000,...) The value of num_ticks is ignored; inside is treated as True regardless of its value, meaning the range of data associated with this scale will always fall inside the range emitted by this method.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

cloggrad

toolbox.new_scale('cloggrad'[, input_min : num, input_max : num, output_min="#FFFFFF", output_max="#000000", numsteps=255, fixed=True])

Maps a numeric range to a range of colors along a gradient, using a modified log-transformed linear scale suitable for count data.

This scale is analogous to the clog scale. Its input range can include zeroes (but not negative numbers), and is suitable for integer data. However, it distorts non-integer data relative to a simple log scale. If the data being scaled contains only positive values and no zeroes, the loggrad scale is more appropriate.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max are color specifications (see Specifying Colors) representing the beginning and end points of a color gradient. numsteps is the number of colors in the gradient, including the beginning and end points.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a set of tick positions evenly spaced on the log scale for this range of data. (E.g. 10, 100, 1000,...) The value of num_ticks is ignored; inside is treated as True regardless of its value, meaning the range of data associated with this scale will always fall inside the range emitted by this method.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

Spatial Scales

linear

toolbox.new_scale('linear'[, input_min : num, input_max : num, output_min=0, output_max=1, fixed=True])

Maps values from one numeric range to another with linear scaling.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max specify the initial lower and upper bounds of the output range.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a sequence of aesthetically pleasing positions in the input range of the scale. These positions will be used for for placing tick marks.

num_ticks is the requested number of tick positions. This is only a request; get_nice_tick_positions may choose to honor it or not as appropriate to the scale.

If inside is True, the lowest and highest points in the set of positions will fall inside the minimum and maximum values in the input range. If it is False, the lowest and highest points in the set must fall on or outside the minimum and maximum values in the input range.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

linbins

toolbox.new_scale('linbins', bin_size[, input_min : num, input_max : num, output_min=0, output_max=1, fixed=True])
get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a sequence of aesthetically pleasing positions in the input range of the scale. These positions will be used for for placing tick marks.

num_ticks is the requested number of tick positions. This is only a request; get_nice_tick_positions may choose to honor it or not as appropriate to the scale.

If inside is True, the lowest and highest points in the set of positions will fall inside the minimum and maximum values in the input range. If it is False, the lowest and highest points in the set must fall on or outside the minimum and maximum values in the input range.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

log

toolbox.new_scale('log'[, input_min : num, input_max: num, output_min=0, output_max=1, fixed=True])

Maps values from one numeric range to another with log-transformed linear scaling.

Valid input for this scale is any positive real number; 0 and negative numbers are invalid input and will raise a RayonException (a RayonLimitException if invalid scale limits are specified, or a RayonRangeException if the user attempts to convert an invalid value).

If your data is integer data containing positive numbers and zero (such as most count data), consider using the clog scale, which is designed for this kind of data.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max specify the initial lower and upper bounds of the output range.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a set of tick positions evenly spaced on the log scale for this range of data. (E.g. 10, 100, 1000,...) The value of num_ticks is ignored; inside is treated as True regardless of its value, meaning the range of data associated with this scale will always fall inside the range emitted by this method.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

clog

toolbox.new_scale('clog'[, input_min : num, input_max: num, output_min=0, output_max=1, fixed=True])

Maps values from one numeric range to another using a modified log-transformed linear scale best suited to count data.

The input range for this scale can include zeroes (but not negative numbers), and is suitable for integer data. However, it distorts non-integer data relative to a simple log scale. If the data being scaled contains only positive values and no zeroes, the log scale is more appropriate.

input_min and input_max specify the initial lower and upper bounds of the input range. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max specify the initial lower and upper bounds of the output range.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a set of tick positions evenly spaced on the log scale for this range of data. (E.g. 10, 100, 1000,...) The value of num_ticks is ignored; inside is treated as True regardless of its value, meaning the range of data associated with this scale will always fall inside the range emitted by this method.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

time

toolbox.new_scale('time'[, input_min : datetime, input_max : datetime, output_min=0, output_max=1, fixed=True])

Maps values from a time range linearly to values in a numeric range.

input_min and input_max specify the initial lower and upper bounds of the input range, as datetime.datetime objects. If one or both of these parameters is not supplied, Rayon will select a value that will minimally contain the data associated with the scale.

output_min and output_max specify the initial lower and upper bounds of the output range.

If fixed is True, the values of input_min and input_max will be the final values for the scale; otherwise, Rayon may adjust the input range if new data is associated with the scale.

get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a sequence of aesthetically pleasing positions in the input range of the scale. These positions will be used for for placing tick marks.

num_ticks is the requested number of tick positions. This is only a request; get_nice_tick_positions may choose to honor it or not as appropriate to the scale.

If inside is True, the lowest and highest points in the set of positions will fall inside the minimum and maximum values in the input range. If it is False, the lowest and highest points in the set must fall on or outside the minimum and maximum values in the input range.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.

timebins

toolbox.new_scale('timebins', bin_size[, input_min : datetime, input_max : datetime, output_min=0, output_max=1, fixed=True])
get_input_max()

Returns the highest value in the input range.

get_input_min()

Returns the lowest value in the input range.

get_nice_tick_positions([num_ticks=5, inside=False])

Returns an iterator over a sequence of aesthetically pleasing positions in the input range of the scale. These positions will be used for for placing tick marks.

num_ticks is the requested number of tick positions. This is only a request; get_nice_tick_positions may choose to honor it or not as appropriate to the scale.

If inside is True, the lowest and highest points in the set of positions will fall inside the minimum and maximum values in the input range. If it is False, the lowest and highest points in the set must fall on or outside the minimum and maximum values in the input range.

get_output_max()

Returns the highest value in the output range.

get_output_min()

Returns the lowest value in the output range.