scale - Implementing a scale

According to On the theory of scales of measurement by S.S. Stevens, scales can be classified in four ways -- norminal, ordinal, interval and ratio. Using current(2016) terminology, norminal data is made up of unordered categories, ordinal data is made up of ordered categories and the two can be classified as discrete. On the other hand both interval and ratio data are continuous.

The scale classes below show how the rest of the Mizani package can be used to implement the two categories of scales. The key tasks are training and mapping and these correspond to the train and map methods.

To train a scale on data means, to make the scale learn the limits of the data. This is elaborate (or worthy of a dedicated method) for two reasons:

  • Practical -- data may be split up across more than one object, yet all will be represented by a single scale.
  • Conceptual -- training is a key action that may need to be inserted into multiple locations of the data processing pipeline before a graphic can be created.

To map data onto a scale means, to associate data values with values(potential readings) on a scale. This is perhaps the most important concept unpinning a scale.

The apply methods are simple examples of how to put it all together.

class mizani.scale.scale_continuous[source]

Continuous scale

classmethod apply(x, palette, na_value=None, trans=None)[source]

Scale data continuously

Parameters:
x : array_like

Continuous values to scale

palette : callable() f(x)

Palette to use

na_value : object

Value to use for missing values.

trans : trans

How to transform the data before scaling. If None, no transformation is done.

Returns:
out : array_like

Scaled values

classmethod train(new_data, old=None)[source]

Train a continuous scale

Parameters:
new_data : array_like

New values

old : array_like

Old range. Most likely a tuple of length 2.

Returns:
out : tuple

Limits(range) of the scale

classmethod map(x, palette, limits, na_value=None, oob=<function censor at 0x7f36388d21e0>)[source]

Map values to a continuous palette

Parameters:
x : array_like

Continuous values to scale

palette : callable() f(x)

palette to use

na_value : object

Value to use for missing values.

oob : callable() f(x)

Function to deal with values that are beyond the limits

Returns:
out : array_like

Values mapped onto a palette

class mizani.scale.scale_discrete[source]

Discrete scale

classmethod apply(x, palette, na_value=None)[source]

Scale data discretely

Parameters:
x : array_like

Discrete values to scale

palette : callable() f(x)

Palette to use

na_value : object

Value to use for missing values.

Returns:
out : array_like

Scaled values

classmethod train(new_data, old=None, drop=False, na_rm=False)[source]

Train a continuous scale

Parameters:
new_data : array_like

New values

old : array_like

Old range. List of values known to the scale.

drop : bool

Whether to drop(not include) unused categories

na_rm : bool

If True, remove missing values. Missing values are either NaN or None.

Returns:
out : list

Values covered by the scale

classmethod map(x, palette, limits, na_value=None)[source]

Map values to a discrete palette

Parameters:
palette : callable() f(x)

palette to use

x : array_like

Continuous values to scale

na_value : object

Value to use for missing values.

Returns:
out : array_like

Values mapped onto a palette