How to Create a Scale Using Plotrb

Acknowledgment: This tutorial is based on Vega's documentation.


This is the second post of the tutorial series. Today I'm going to introduce how to create a Scale using Plotrb.

(Scales are) functions that transform a domain of data values (numbers, dates, strings, etc) to a range of visual values (pixels, colors, sizes).

As mentioned in the previous article, all the attributes of a Scale listed below can be set in three standard ways. The following is some recommended grammar that would hopefully make the code shorter and more readable.

name

Set the unique name of the scale.

type

You can directly set the type when creating a new scale in a visualization. The valid types are linear, log, pow, sqrt, quantile, quantize, threshold, time, utc, and ordinal.

vis = Plotrb::Visualization.new
scale = vis.linear_scale

domain

You can also use from to set the domain of the scale. A domain is a reference which specifies the name of data source and the field.

scale.from('some_data_source.some_field')

By default, if the data field is not provided, Plotrb will assume that the field is the implicit index of the data. Of course, you may explicitly specify to use index.

scale.from('some_data_source.index')

It's also possible to set the domain directly without reference to any other data sources. For quantitative data, you can pass in an array of two numbers representing the minimum and maximum values.

scale.from([1, 100])

For ordinal/categorical data, you simply list all of them in an array.

scale.from(%w(Mon Tue Wed Thu Fri Sat Sun))

In addition, you can pass in two more arguments, specifying the minimum and maximum values of the domain.

scale.from('some_population.ages', 0, 150)

domain_min

Set the minimum value of the domain. It can be a single value, or a data reference similar to the one used for domain.

domain_max

Set the maximum value of the domain. See domain_min.

range

The range is a set of visual values. You can use to to set the range of the scale. Similar to domain, you can pass in an array of two numbers representing the minimum and the maximum for numerical range, or all values for ordinal data.

scale.from('some_data.some_field').to([0, 20])
scale.from([1, 7]).to(%w(Mon Tue Wed Thu Fri Sat Sun))

There are more goodies for ordinal data. The following is a list of pre-defined range values that often come very handy.

# set the range to [0, width of the data rectangle]
scale.to_width

# set the range to [0, height of the data rectangle]
scale.to_height

# set the range to 6 different shapes,
# namely circle, cross, diamond, square, triangle-down, and triangle-up
scale.to_shapes

# set the range to a 10-color categorical palette
scale.to_colors

# set the range to a 20-color categorical palette
scale.to_more_colors

range_min

See domain_min.

range_max

See domain_max.

reverse

Specify if flips the scale range.

round

Specify if rounds numerical range to integers.

points

You can use as_points or as_bands to specify whether to distribute the ordinal values at uniformly spaced points or evenly spaced bands.

padding

Set the spacing among ordinal elements in the range. For more information please refer to Vega's wiki and D3's documentation.

sort

Specify if the scale domain will be sorted according to natural order.

exponent

Only for pow type of scale, set the exponent of the transformation.

nice

You can use nicely for quantitative scales to modifies the domain to a more human-friendly number range.

scale.from('some_data.decimal_numbers').to([0, 100]).nicely

For time scales (time or utc types), you can specify the time interval to a more human-friendly range as follows,

scale.from('some_data.some_time').in_seconds

Available options are in_seconds, in_minutes, in_hours, in_days, in_weeks, in_months, and in_years.

zero

You can use include_zero to specify if zero baseline is included in the domain (for quantitative scale only).

clamp

Specify if exceeded domain values are clamped to either the minimum or maximum.


comments powered by Disqus