Source code for bokeh.models.ranges

''' Models for describing different kinds of ranges of values
in different kinds of spaces (e.g., continuous or categorical)
and with options for "auto sizing".

'''
from __future__ import absolute_import

from ..core.enums import PaddingUnits, StartEnd
from ..core.has_props import abstract
from ..core.properties import (Auto, Bool, Datetime, Either, Enum, Float, Instance, Int,
                               List, MinMaxBounds, String, TimeDelta)
from ..model import Model

from .callbacks import Callback
from .renderers import Renderer


@abstract
[docs]class Range(Model): ''' A base class for all range types. ''' callback = Instance(Callback, help=""" A callback to run in the browser whenever the range is updated. """)
[docs]class Range1d(Range): ''' A fixed, closed range [start, end] in a continuous scalar dimension. In addition to supplying ``start`` and ``end`` keyword arguments to the ``Range1d`` initializer, you can also instantiate with the convenience syntax:: Range(0, 10) # equivalent to Range(start=0, end=10) ''' start = Either(Float, Datetime, Int, default=0, help=""" The start of the range. """) end = Either(Float, Datetime, Int, default=1, help=""" The end of the range. """) bounds = MinMaxBounds(accept_datetime=True, default=None, help=""" The bounds that the range is allowed to go to - typically used to prevent the user from panning/zooming/etc away from the data. If set to ``'auto'``, the bounds will be computed to the start and end of the Range. Bounds are provided as a tuple of ``(min, max)`` so regardless of whether your range is increasing or decreasing, the first item should be the minimum value of the range and the second item should be the maximum. Setting min > max will result in a ``ValueError``. By default, bounds are ``None`` and your plot to pan/zoom as far as you want. If you only want to constrain one end of the plot, you can set min or max to None. Examples: Range1d(0, 1, bounds='auto') # Auto-bounded to 0 and 1 (Default behavior) Range1d(start=0, end=1, bounds=(0, None)) # Maximum is unbounded, minimum bounded to 0 """) min_interval = Either(Float, TimeDelta, Int, default=None, help=""" The level that the range is allowed to zoom in, expressed as the minimum visible interval. If set to ``None`` (default), the minimum interval is not bound. Can be a timedelta. """) max_interval = Either(Float, TimeDelta, Int, default=None, help=""" The level that the range is allowed to zoom out, expressed as the maximum visible interval. Can be a timedelta. Note that ``bounds`` can impose an implicit constraint on the maximum interval as well. """) def __init__(self, *args, **kwargs): if args and ('start' in kwargs or 'end' in kwargs): raise ValueError("'start' and 'end' keywords cannot be used with positional arguments") if args and len(args) != 2: raise ValueError('Only Range1d(start, end) acceptable when using positional arguments') if args: kwargs['start'] = args[0] kwargs['end'] = args[1] super(Range1d, self).__init__(**kwargs)
@abstract
[docs]class DataRange(Range): ''' A base class for all data range types. ''' names = List(String, help=""" A list of names to query for. If set, only renderers that have a matching value for their ``name`` attribute will be used for autoranging. """) renderers = List(Instance(Renderer), help=""" An explicit list of renderers to autorange against. If unset, defaults to all renderers on a plot. """)
[docs]class DataRange1d(DataRange): ''' An auto-fitting range in a continuous scalar dimension. The upper and lower bounds are set to the min and max of the data. ''' range_padding = Float(default=0.1, help=""" How much padding to add around the computed data bounds. When ``range_padding_units`` is set to ``"percent"``, the span of the range span is expanded to make the range ``range_padding`` percent larger. When ``range_padding_units`` is set to ``"absolute"``, the start and end of the range span are extended by the amount ``range_padding``. """) range_padding_units = Enum(PaddingUnits, default="percent", help=""" Whether the ``range_padding`` should be interpreted as a percentage, or as an absolute quantity. (default: ``"percent"``) """) start = Float(help=""" An explicitly supplied range start. If provided, will override automatically computed start value. """) end = Float(help=""" An explicitly supplied range end. If provided, will override automatically computed end value. """) bounds = MinMaxBounds(accept_datetime=False, default=None, help=""" The bounds that the range is allowed to go to - typically used to prevent the user from panning/zooming/etc away from the data. By default, the bounds will be None, allowing your plot to pan/zoom as far as you want. If bounds are 'auto' they will be computed to be the same as the start and end of the DataRange1d. Bounds are provided as a tuple of ``(min, max)`` so regardless of whether your range is increasing or decreasing, the first item should be the minimum value of the range and the second item should be the maximum. Setting ``min > max`` will result in a ``ValueError``. If you only want to constrain one end of the plot, you can set ``min`` or ``max`` to ``None`` e.g. ``DataRange1d(bounds=(None, 12))`` """) min_interval = Float(default=None, help=""" The level that the range is allowed to zoom in, expressed as the minimum visible interval. If set to ``None`` (default), the minimum interval is not bound.""") max_interval = Float(default=None, help=""" The level that the range is allowed to zoom out, expressed as the maximum visible interval. Note that ``bounds`` can impose an implicit constraint on the maximum interval as well.""") flipped = Bool(default=False, help=""" Whether the range should be "flipped" from its normal direction when auto-ranging. """) follow = Enum(StartEnd, default=None, help=""" Configure the data to follow one or the other data extreme, with a maximum range size of ``follow_interval``. If set to ``"start"`` then the range will adjust so that ``start`` always corresponds to the minimum data value (or maximum, if ``flipped`` is ``True``). If set to ``"end"`` then the range will adjust so that ``end`` always corresponds to the maximum data value (or minimum, if ``flipped`` is ``True``). If set to ``None`` (default), then auto-ranging does not follow, and the range will encompass both the minimum and maximum data values. ``follow`` cannot be used with bounds, and if set, bounds will be set to ``None``. """) follow_interval = Float(default=None, help=""" If ``follow`` is set to ``"start"`` or ``"end"`` then the range will always be constrained to that:: abs(r.start - r.end) <= follow_interval is maintained. """) default_span = Float(default=2.0, help=""" A default width for the interval, in case ``start`` is equal to ``end`` (if used with a log axis, default_span is in powers of 10). """) def __init__(self, *args, **kwargs): if kwargs.get('follow') is not None: kwargs['bounds'] = None super(DataRange1d, self).__init__(**kwargs)
[docs]class FactorRange(Range): ''' A range in a categorical dimension. In addition to supplying ``factors`` keyword argument to the ``FactorRange`` initializer, you can also instantiate with the convenience syntax:: FactorRange("foo", "bar") # equivalent to FactorRange(factors=["foo", "bar"]) .. note:: ``FactorRange`` may be renamed to ``CategoricalRange`` in the future. ''' offset = Float(0, help=""" An offset to the (synthetic) range (default: 0) .. note:: The primary usage of this is to support compatibility and integration with other plotting systems, and will not generally of interest to most users. """) factors = Either(List(String), List(Int), help=""" A list of string or integer factors (categories) to comprise this categorical range. """) bounds = Either(Auto, List(String), List(Int), default=None, help=""" The bounds that the range is allowed to go to - typically used to prevent the user from panning/zooming/etc away from the data. Unlike Range1d and DataRange1d, factors do not have an order and so a min and max cannot be proved in the same way. bounds accepts a list of factors, that constrain the displayed factors. By default, bounds are ``None``, allows unlimited panning or zooming. If ``bounds='auto'``, bounds will be the same as factors and the plot will not be able to pan or zoom beyond the first and last factors. If you provide a list, then only the factors that are in that list will be displayed on the plot and the plot will not pan or zoom outside the first and last items in the shortened factors list. Note the order of factors is the defining order for your plot. Values of bounds that are not in factors are acceptable and will simply have no impact on the plot. Examples: Auto behavior: .. code-block:: python x_range = FactorRange( factors=["apples", "dogs", "peaches", "bananas", "pigs"], bounds='auto' ) The plot will display all the factors and you will not be able to pan left of apples or right of pigs. Constraining behavior: .. code-block:: python x_range = FactorRange( factors=["apples", "dogs", "peaches", "bananas", "pigs"], bounds=["apples", "bananas", "peaches"] ) Only the factors ``["apples", "peaches", "bananas"]`` (in that order) will appear in the plot, and the plot will not pan left of ``"apples"`` or right of ``"bananas"``. """) min_interval = Int(default=None, help=""" The level that the range is allowed to zoom in, expressed as the minimum number of visible categories. If set to ``None`` (default), the minimum interval is not bound.""") max_interval = Int(default=None, help=""" The level that the range is allowed to zoom out, expressed as the maximum number of visible categories. Note that ``bounds`` can impose an implicit constraint on the maximum interval as well.""") def __init__(self, *args, **kwargs): if args and "factors" in kwargs: raise ValueError("'factors' keyword cannot be used with positional arguments") elif args: kwargs['factors'] = list(args) super(FactorRange, self).__init__(**kwargs)