Tour API Demos Download Tests
Aperture version 1.0
Generated by: JsDoc Toolkit 2.4.0

Class aperture.Scalar

Represents a scalar model property range. Unlike in the case of Ordinals, Scalar property map keys use interpolation when mapping values to visual properties. If the desired visual mapping of a raw scalar value is ordinal rather than scalar (for instance a change value where positive is an 'up' color and negative is a 'down' color), call quantized to derive an ordinal view of the Scalar.

Class Summary
Constructor Attributes Constructor Name and Description
 
aperture.Scalar(name, values)
Constructs a new scalar range.

Method Summary

Class Detail

aperture.Scalar(name, values)
Constructs a new scalar range.
Parameters:
{String} name
the name of the property described.
{Array|Number|String|Date} values Optional
an optional array of values (or a single value) with which to populate the range. Equivalent to calling expand after construction.
Returns:
{this} a new Scalar

Method Detail

  • {aperture.Scalar} absolute()
    Returns a new scalar view which ranges from zero to the greatest absolute distance from zero and which maps the absolute magnitude of values. Views are dynamic, adapting to any subsequent changes in the base range.
    Returns:
    {aperture.Scalar} a new view of this Range.
  • {aperture.Scalar} banded(bands, roundTo)
    Returns a new banded scalar view of this range based on the specification supplied. Bands are used for axis articulation, or for subsequently quantizing scalars into labeled ordinals (e.g. up / down, or good / bad) for visual mapping (e.g. up color, down color). A banded view returns multiple band object values for get(), where each object has a min, label, and limit property.

    Banded views are live, meaning subsequent range changes are allowed. Multiple bands may be generated from the same range object for different visual applications. Scalar bands may be specified simply by supplying a desired approximate count, appropriate to the visual range available, or by specifying predefined labeled value bands based on the domain of the values, such as 'Very Good' or 'Very Poor'. Bounds are always evaluated by a minimum threshold condition and must be contiguous.

    Banded or quantized views must be the last in the chain of views - other optional views such as logarithmic, absolute, or symmetric can be the source of a banded view but cannot be derived from one.For example:
    // default banded view
    myTimeRange.banded();
    
    // view with around five bands, or a little less
    myTimeRange.banded(5);
    
    // view with around five bands, and don't round the edges
    myTimeRange.banded(5, false);
    
    // or, view banded every thousand
    myTimeRange.banded({ span: 1000 });
    
    // or, view with these exact bands
    myTimeRange.banded([{min: 0}, {min: 500}]);
    
    // or, using shortcut for above.
    myTimeRange.banded([0, 500]);
    Parameters:
    {Number|Object|Array} bands Optional, Default: 1(minimum)
    the approximate count of bands to create, OR a band specification object containing a span field indicating the regular interval for bands, OR an array of predefined bands supplied as objects with min and label properties, in ascending order. If this value is not supplied one band will be created, or two if the range extents span zero.
    {boolean} roundTo Optional, Default: true
    whether or not to round the range extents to band edges
    Returns:
    {aperture.Scalar} a new view of this Range, with limitations on further view creation.
  • {this} expand(value)
    Expands the property range to encompass the value, if necessary.
    Parameters:
    {Array|Number|String|Date} value
    a case or set of cases to include in the property range. Each must be a Number, a String representation of a number, or a Date.
    Returns:
    {this} a reference to this property.
  • {aperture.Scalar} logarithmic(zero)
    Returns a new scalar view which maps the order of magnitude of source values. Log views are constructed with a zero threshold specifying the absolute value under which values should be no longer be mapped logarithmically, even if in range. Specifying this value enables a range to safely approach or span zero and still map effectively. Log views can map negative or positive values and are dynamic, adapting to any subsequent changes in the base range.
    Parameters:
    zero
    the minimum absolute value above which to map logarithmically. if not supplied this value will default to 0.1.
    Returns:
    {aperture.Scalar} a new view of this Range.
  • {Number} map(value)
    Returns the value's normalized position within the Range object. The return value will be in the range of [0,1].
    Parameters:
    {Number} value
    the value to normalize by the Range
    Returns:
    {Number} the normalized value of the input in the range [0,1]
  • {aperture.MapKey} mappedTo(to)
    Creates and returns a key for mapping from this model range to a visual property range. Mappings are evaluated dynamically, meaning subsequent range changes are allowed. Multiple map keys may be generated from the same range object.
    Parameters:
    {Array} to
    the ordered set of colors or numbers to map to, from this property's range.
    Returns:
    {aperture.MapKey} a new map key.
  • {aperture.Scalar} quantized()
    Returns a quantized ordinal view of a banded scalar view range. Quantized views map ordinally (and produce ordinal mappings) and format scalar values by returning the ordinal band they fall into.
    Returns:
    {aperture.Scalar} a new view of this Range, with ordinal mapping.
  • {this} reset(values)
    Clears the property range, then optionally expands it with new values.
    Parameters:
    {Array|Number|String|Date} values Optional
    Returns:
    {this} a reference to this property.
  • {aperture.Scalar} symmetric()
    Returns a new scalar view of this range which is symmetric about zero. Views are dynamic, adapting to any subsequent changes in the base range.
    Returns:
    {aperture.Scalar} a new view of this Range.