#-----------------------------------------------------------------------------# Copyright (c) Anaconda, Inc., and Bokeh Contributors.# All rights reserved.## The full license is in the file LICENSE.txt, distributed with this software.#-----------------------------------------------------------------------------''' Helper functions for applying client-side computations such astransformations to data fields or ``ColumnDataSource`` expressions.'''#-----------------------------------------------------------------------------# Boilerplate#-----------------------------------------------------------------------------from__future__importannotationsimportlogging# isort:skiplog=logging.getLogger(__name__)#-----------------------------------------------------------------------------# Imports#-----------------------------------------------------------------------------# Standard library importsfromtypingimportTYPE_CHECKING,Sequence,TypeAlias# Bokeh importsfrom.core.property.vectorizationimportExpr,Fieldfrom.models.expressionsimportCumSum,Stackfrom.models.mappersimport(CategoricalColorMapper,CategoricalMarkerMapper,CategoricalPatternMapper,EqHistColorMapper,LinearColorMapper,LogColorMapper,)from.models.transformsimportDodge,JitterifTYPE_CHECKING:from.colorsimportColorLikefrom.core.enumsimportJitterRandomDistributionTypefrom.models.rangesimportRangefrom.models.transformsimportTransform#-----------------------------------------------------------------------------# Globals and constants#-----------------------------------------------------------------------------__all__=('cumsum','dodge','eqhist_cmap','factor_cmap','factor_hatch','factor_mark','jitter','linear_cmap','log_cmap','stack','transform',)#-----------------------------------------------------------------------------# General API#-----------------------------------------------------------------------------ifTYPE_CHECKING:Factors:TypeAlias=Sequence[str]|Sequence[tuple[str,str]]|Sequence[tuple[str,str,str]]
[docs]defcumsum(field_name:str,include_zero:bool=False)->Expr:''' Create a ``DataSpec`` dict to generate a ``CumSum`` expression for a ``ColumnDataSource``. Args: field_name (str) : a field name to configure ``CumSum`` with include_zero (bool, optional) : whether to include zero in the sum (default: False) Examples: .. code-block:: python p.wedge(start_angle=cumsum('angle', include_zero=True), end_angle=cumsum('angle'), ...) will generate a ``CumSum`` expressions that sum the ``"angle"`` column of a data source. For the ``start_angle`` value, the cumulative sums will start with a zero value. For ``end_angle``, no initial zero will be added (i.e. the sums will start with the first angle value, and include the last). '''returnExpr(CumSum(field=field_name,include_zero=include_zero))
[docs]defdodge(field_name:str,value:float,range:Range|None=None)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``Dodge`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with value (float) : the fixed offset to add to column data range (Range, optional) : a range to use for computing synthetic coordinates when necessary, e.g. a ``FactorRange`` when the column data is categorical (default: None) Returns: Field '''returnField(field_name,Dodge(value=value,range=range))
[docs]defeqhist_cmap(field_name:str,palette:Sequence[ColorLike],low:float,high:float,low_color:ColorLike|None=None,high_color:ColorLike|None=None,nan_color:ColorLike="gray",)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``EqHistColorMapper`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with palette (seq[color]) : a list of colors to use for colormapping low (float) : a minimum value of the range to map into the palette. Values below this are clamped to ``low``. high (float) : a maximum value of the range to map into the palette. Values above this are clamped to ``high``. low_color (color, optional) : 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. (default: None) high_color (color, optional) : 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. (default: None) nan_color (color, optional) : a default color to use when mapping data from a column does not succeed (default: "gray") '''returnField(field_name,EqHistColorMapper(palette=palette,low=low,high=high,nan_color=nan_color,low_color=low_color,high_color=high_color,),)
[docs]deffactor_cmap(field_name:str,palette:Sequence[ColorLike],factors:Factors,start:float=0,end:float|None=None,nan_color:ColorLike="gray",)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``CategoricalColorMapper`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with palette (seq[color]) : a list of colors to use for colormapping factors (seq) : a sequence of categorical factors corresponding to the palette start (int, optional) : a start slice index to apply when the column data has factors with multiple levels. (default: 0) end (int, optional) : an end slice index to apply when the column data has factors with multiple levels. (default: None) nan_color (color, optional) : a default color to use when mapping data from a column does not succeed (default: "gray") Returns: Field '''returnField(field_name,CategoricalColorMapper(palette=palette,factors=factors,start=start,end=end,nan_color=nan_color,),)
[docs]deffactor_hatch(field_name:str,patterns:Sequence[str],factors:Factors,start:float=0,end:float|None=None,)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``CategoricalPatternMapper`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with patterns (seq[string]) : a list of hatch patterns to use to map to factors (seq) : a sequences of categorical factors corresponding to the palette start (int, optional) : a start slice index to apply when the column data has factors with multiple levels. (default: 0) end (int, optional) : an end slice index to apply when the column data has factors with multiple levels. (default: None) Returns: Field Added in version 1.1.1 '''returnField(field_name,CategoricalPatternMapper(patterns=patterns,factors=factors,start=start,end=end,),)
[docs]deffactor_mark(field_name:str,markers:Sequence[str],factors:Factors,start:float=0,end:float|None=None,)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``CategoricalMarkerMapper`` transformation to a ``ColumnDataSource`` column. .. note:: This transform is primarily only useful with ``scatter``, which can be parameterized by glyph type. Args: field_name (str) : a field name to configure ``DataSpec`` with markers (seq[string]) : a list of markers to use to map to factors (seq) : a sequences of categorical factors corresponding to the palette start (int, optional) : a start slice index to apply when the column data has factors with multiple levels. (default: 0) end (int, optional) : an end slice index to apply when the column data has factors with multiple levels. (default: None) Returns: Field '''returnField(field_name,CategoricalMarkerMapper(markers=markers,factors=factors,start=start,end=end,),)
[docs]defjitter(field_name:str,width:float,mean:float=0,distribution:JitterRandomDistributionType="uniform",range:Range|None=None,)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``Jitter`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with width (float) : the width of the random distribution to apply mean (float, optional) : an offset to apply (default: 0) distribution (str, optional) : ``"uniform"`` or ``"normal"`` (default: ``"uniform"``) range (Range, optional) : a range to use for computing synthetic coordinates when necessary, e.g. a ``FactorRange`` when the column data is categorical (default: None) Returns: Field '''returnField(field_name,Jitter(mean=mean,width=width,distribution=distribution,range=range,),)
[docs]deflinear_cmap(field_name:str,palette:Sequence[ColorLike],low:float,high:float,low_color:ColorLike|None=None,high_color:ColorLike|None=None,nan_color:ColorLike="gray",)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``LinearColorMapper`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with palette (seq[color]) : a list of colors to use for colormapping low (float) : a minimum value of the range to map into the palette. Values below this are clamped to ``low``. high (float) : a maximum value of the range to map into the palette. Values above this are clamped to ``high``. low_color (color, optional) : 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. (default: None) high_color (color, optional) : 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. (default: None) nan_color (color, optional) : a default color to use when mapping data from a column does not succeed (default: "gray") '''returnField(field_name,LinearColorMapper(palette=palette,low=low,high=high,nan_color=nan_color,low_color=low_color,high_color=high_color,),)
[docs]deflog_cmap(field_name:str,palette:Sequence[ColorLike],low:float,high:float,low_color:ColorLike|None=None,high_color:ColorLike|None=None,nan_color:ColorLike="gray",)->Field:''' Create a ``DataSpec`` dict that applies a client-side ``LogColorMapper`` transformation to a ``ColumnDataSource`` column. Args: field_name (str) : a field name to configure ``DataSpec`` with palette (seq[color]) : a list of colors to use for colormapping low (float) : a minimum value of the range to map into the palette. Values below this are clamped to ``low``. high (float) : a maximum value of the range to map into the palette. Values above this are clamped to ``high``. low_color (color, optional) : 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. (default: None) high_color (color, optional) : 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. (default: None) nan_color (color, optional) : a default color to use when mapping data from a column does not succeed (default: "gray") '''returnField(field_name,LogColorMapper(palette=palette,low=low,high=high,nan_color=nan_color,low_color=low_color,high_color=high_color,),)
[docs]defstack(*fields:str)->Expr:''' Create a Create a ``DataSpec`` dict to generate a ``Stack`` expression for a ``ColumnDataSource``. Examples: .. code-block:: python p.vbar(bottom=stack("sales", "marketing"), ... will generate a ``Stack`` that sums the ``"sales"`` and ``"marketing"`` columns of a data source, and use those values as the ``top`` coordinate for a ``VBar``. '''returnExpr(Stack(fields=fields))
[docs]deftransform(field_name:str,transform:Transform)->Field:''' Create a ``DataSpec`` dict that applies an arbitrary client-side ``Transform`` to a ``ColumnDataSource`` column. Args: field_name (str) : A field name to configure ``DataSpec`` with transform (Transform) : A transforms to apply to that field Returns: Field '''returnField(field_name,transform)
#-----------------------------------------------------------------------------# Dev API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Private API#-----------------------------------------------------------------------------#-----------------------------------------------------------------------------# Code#-----------------------------------------------------------------------------