#-----------------------------------------------------------------------------# Copyright (c) 2012 - 2022, Anaconda, Inc., and Bokeh Contributors.# All rights reserved.## The full license is in the file LICENSE.txt, distributed with this software.#-----------------------------------------------------------------------------''' Models for mapping values from one range or space to another in the client.Mappers (as opposed to scales) are not presumed to be invertible.'''#-----------------------------------------------------------------------------# Boilerplate#-----------------------------------------------------------------------------from__future__importannotationsimportlogging# isort:skiplog=logging.getLogger(__name__)#-----------------------------------------------------------------------------# Imports#-----------------------------------------------------------------------------# Bokeh importsfrom..importpalettesfrom..core.enumsimportPalettefrom..core.has_propsimportabstractfrom..core.propertiesimport(Bool,Color,Either,Enum,FactorSeq,Float,HatchPatternType,Instance,Int,List,MarkerType,Nullable,Seq,String,Tuple,)from..core.validationimportwarningfrom..core.validation.warningsimportPALETTE_LENGTH_FACTORS_MISMATCHfrom.transformsimportTransform#-----------------------------------------------------------------------------# Globals and constants#-----------------------------------------------------------------------------__all__=('Mapper','ColorMapper','CategoricalMapper','CategoricalColorMapper','CategoricalMarkerMapper','CategoricalPatternMapper','ContinuousColorMapper','LinearColorMapper','LogColorMapper','EqHistColorMapper',)#-----------------------------------------------------------------------------# General API#-----------------------------------------------------------------------------
[docs]@abstractclassMapper(Transform):''' Base class for mappers. '''pass
[docs]@abstractclassColorMapper(Mapper):''' Base class for color mapper types. '''palette=Seq(Color,help=""" A sequence of colors to use as the target palette for mapping. This property can also be set as a ``String``, to the name of any of the palettes shown in :ref:`bokeh.palettes`. """).accepts(Enum(Palette),lambdapal:getattr(palettes,pal))nan_color=Color(default="gray",help=""" Color to be used if data is NaN or otherwise not mappable. """)def__init__(self,palette=None,**kwargs)->None:ifpaletteisnotNone:kwargs['palette']=palettesuper().__init__(**kwargs)
[docs]@abstractclassCategoricalMapper(Mapper):''' Base class for mappers that map categorical factors to other values. '''factors=FactorSeq(help=""" A sequence of factors / categories that map to the some target range. For example the following color mapper: .. code-block:: python mapper = CategoricalColorMapper(palette=["red", "blue"], factors=["foo", "bar"]) will map the factor ``"foo"`` to red and the factor ``"bar"`` to blue. """)start=Int(default=0,help=""" A start index to "slice" data factors with before mapping. For example, if the data to color map consists of 2-level factors such as ``["2016", "sales"]`` and ``["2016", "marketing"]``, then setting ``start=1`` will perform color mapping only based on the second sub-factor (i.e. in this case based on the department ``"sales"`` or ``"marketing"``) """)end=Nullable(Int,help=""" A start index to "slice" data factors with before mapping. For example, if the data to color map consists of 2-level factors such as ``["2016", "sales"]`` and ``["2017", "marketing"]``, then setting ``end=1`` will perform color mapping only based on the first sub-factor (i.e. in this case based on the year ``"2016"`` or ``"2017"``) If ``None`` then all sub-factors from ``start`` to the end of the factor will be used for color mapping. """)
[docs]classCategoricalColorMapper(CategoricalMapper,ColorMapper):''' Map categorical factors to colors. Values that are passed to this mapper that are not in the factors list will be mapped to ``nan_color``. '''@warning(PALETTE_LENGTH_FACTORS_MISMATCH)def_check_palette_length(self):palette=self.palettefactors=self.factorsiflen(palette)<len(factors):extra_factors=factors[len(palette):]returnf"{extra_factors} will be assigned to `nan_color` {self.nan_color}"
[docs]classCategoricalMarkerMapper(CategoricalMapper):''' Map categorical factors to marker types. Values that are passed to this mapper that are not in the factors list will be mapped to ``default_value``. .. note:: This mappers is primarily only useful with the ``Scatter`` marker glyph that be parameterized by marker type. '''markers=Seq(MarkerType,help=""" A sequence of marker types to use as the target for mapping. """)default_value=MarkerType(default="circle",help=""" A marker type to use in case an unrecognized factor is passed in to be mapped. """)
[docs]classCategoricalPatternMapper(CategoricalMapper):''' Map categorical factors to hatch fill patterns. Values that are passed to this mapper that are not in the factors list will be mapped to ``default_value``. Added in version 1.1.1 '''patterns=Seq(HatchPatternType,help=""" A sequence of marker types to use as the target for mapping. """)default_value=HatchPatternType(default=" ",help=""" A hatch pattern to use in case an unrecognized factor is passed in to be mapped. """)
[docs]@abstractclassContinuousColorMapper(ColorMapper):''' Base class for continuous color mapper types. '''domain=List(Tuple(Instance("bokeh.models.renderers.GlyphRenderer"),Either(String,List(String))),default=[],help=""" A collection of glyph renderers to pool data from for establishing data metrics. If empty, mapped data will be used instead. """)low=Nullable(Float,help=""" The minimum value of the range to map into the palette. Values below this are clamped to ``low``. If ``None``, the value is inferred from data. """)high=Nullable(Float,help=""" The maximum value of the range to map into the palette. Values above this are clamped to ``high``. If ``None``, the value is inferred from data. """)low_color=Nullable(Color,help=""" Color to be used if data is lower than ``low`` value. If None, values lower than ``low`` are mapped to the first color in the palette. """)high_color=Nullable(Color,help=""" Color to be used if data is higher than ``high`` value. If None, values higher than ``high`` are mapped to the last color in the palette. """)
[docs]classLinearColorMapper(ContinuousColorMapper):''' Map numbers in a range [*low*, *high*] linearly into a sequence of colors (a palette). For example, if the range is [0, 99] and the palette is ``['red', 'green', 'blue']``, the values would be mapped as follows:: x < 0 : 'red' # values < low are clamped 0 <= x < 33 : 'red' 33 <= x < 66 : 'green' 66 <= x < 99 : 'blue' 99 <= x : 'blue' # values > high are clamped '''
[docs]classLogColorMapper(ContinuousColorMapper):''' Map numbers in a range [*low*, *high*] into a sequence of colors (a palette) on a natural logarithm scale. For example, if the range is [0, 25] and the palette is ``['red', 'green', 'blue']``, the values would be mapped as follows:: x < 0 : 'red' # values < low are clamped 0 <= x < 2.72 : 'red' # math.e ** 1 2.72 <= x < 7.39 : 'green' # math.e ** 2 7.39 <= x < 20.09 : 'blue' # math.e ** 3 20.09 <= x : 'blue' # values > high are clamped .. warning:: The ``LogColorMapper`` only works for images with scalar values that are non-negative. '''
[docs]classEqHistColorMapper(ScanningColorMapper):bins=Int(default=256*256,help="Number of histogram bins")rescale_discrete_levels=Bool(default=False,help=""" If there are only a few discrete levels in the values that are color mapped then ``rescale_discrete_levels=True`` decreases the lower limit of the span so that the values are rendered towards the top end of the palette. """)
#-----------------------------------------------------------------------------# Dev API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Private API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Code#-----------------------------------------------------------------------------