1#----------------------------------------------------------------------------- 2# Copyright (c) 2012 - 2021, Anaconda, Inc., and Bokeh Contributors. 3# All rights reserved. 4# 5# The full license is in the file LICENSE.txt, distributed with this software. 6#----------------------------------------------------------------------------- 7''' Renderers for various kinds of annotations that can be added to 8Bokeh plots 9 10''' 11#----------------------------------------------------------------------------- 12# Boilerplate 13#----------------------------------------------------------------------------- 14import logging # isort:skip 15log = logging.getLogger(__name__) 16 17#----------------------------------------------------------------------------- 18# Imports 19#----------------------------------------------------------------------------- 20 21# Bokeh imports 22from ..core.enums import ( 23 Anchor, 24 AngleUnits, 25 Dimension, 26 FontStyle, 27 LegendClickPolicy, 28 LegendLocation, 29 Orientation, 30 RenderMode, 31 SpatialUnits, 32 TextAlign, 33 TooltipAttachment, 34 VerticalAlign, 35) 36from ..core.has_props import abstract 37from ..core.properties import ( 38 Alpha, 39 Angle, 40 AngleSpec, 41 Auto, 42 Bool, 43 Color, 44 Datetime, 45 Dict, 46 Either, 47 Enum, 48 Float, 49 Include, 50 Instance, 51 Int, 52 List, 53 NonNullable, 54 Null, 55 Nullable, 56 NullStringSpec, 57 NumberSpec, 58 Override, 59 PropertyUnitsSpec, 60 Seq, 61 String, 62 StringSpec, 63 Tuple, 64 field, 65 value, 66) 67from ..core.property_mixins import ( 68 FillProps, 69 LineProps, 70 ScalarFillProps, 71 ScalarHatchProps, 72 ScalarLineProps, 73 ScalarTextProps, 74 TextProps, 75) 76from ..core.validation import error 77from ..core.validation.errors import ( 78 BAD_COLUMN_NAME, 79 NON_MATCHING_DATA_SOURCES_ON_LEGEND_ITEM_RENDERERS, 80) 81from ..model import Model 82from ..util.serialization import convert_datetime_type 83from .formatters import TickFormatter 84from .labeling import LabelingPolicy, NoOverlap 85from .mappers import ColorMapper 86from .renderers import GlyphRenderer, Renderer 87from .sources import ColumnDataSource, DataSource 88from .tickers import Ticker 89 90#----------------------------------------------------------------------------- 91# Globals and constants 92#----------------------------------------------------------------------------- 93 94__all__ = ( 95 'Annotation', 96 'Arrow', 97 'Band', 98 'BoxAnnotation', 99 'ColorBar', 100 'DataAnnotation', 101 'Label', 102 'LabelSet', 103 'Legend', 104 'LegendItem', 105 'PolyAnnotation', 106 'Slope', 107 'Span', 108 'TextAnnotation', 109 'Title', 110 'Tooltip', 111 'ToolbarPanel', 112 'Whisker', 113) 114 115#----------------------------------------------------------------------------- 116# Private API 117#----------------------------------------------------------------------------- 118 119# This only exists to prevent a circular import. 120def _DEFAULT_ARROW(): 121 from .arrow_heads import OpenHead 122 return OpenHead() 123 124# This only exists to prevent a circular import. 125def _DEFAULT_TEE(): 126 from .arrow_heads import TeeHead 127 return TeeHead(size=10) 128 129#----------------------------------------------------------------------------- 130# General API 131#----------------------------------------------------------------------------- 132 133@abstract 134class Annotation(Renderer): 135 ''' Base class for all annotation models. 136 137 ''' 138 139 level = Override(default="annotation") 140 141@abstract 142class DataAnnotation(Annotation): 143 ''' Base class for annotations that utilize a data source. 144 145 ''' 146 147 source = Instance(DataSource, default=lambda: ColumnDataSource(), help=""" 148 Local data source to use when rendering annotations on the plot. 149 """) 150 151@abstract 152class TextAnnotation(Annotation): 153 ''' Base class for text annotation models such as labels and titles. 154 155 ''' 156 157 render_mode = Enum(RenderMode, default="canvas", help=""" 158 Specifies whether the text is rendered as a canvas element or as a 159 CSS element overlaid on the canvas. The default mode is "canvas". 160 161 .. note:: 162 The CSS labels won't be present in the output using the "save" tool. 163 164 .. warning:: 165 Not all visual styling properties are supported if the render_mode is 166 set to "css". The border_line_dash property isn't fully supported and 167 border_line_dash_offset isn't supported at all. Setting text_alpha will 168 modify the opacity of the entire background box and border in addition 169 to the text. Finally, clipping Label annotations inside of the plot 170 area isn't supported in "css" mode. 171 172 """) 173 174class LegendItem(Model): 175 ''' 176 177 ''' 178 def __init__(self, *args, **kwargs): 179 super().__init__(*args, **kwargs) 180 if isinstance(self.label, str): 181 # Allow convenience of setting label as a string 182 self.label = value(self.label) 183 184 label = NullStringSpec(help=""" 185 A label for this legend. Can be a string, or a column of a 186 ColumnDataSource. If ``label`` is a field, then it must 187 be in the renderers' data_source. 188 """) 189 190 renderers = List(Instance(GlyphRenderer), help=""" 191 A list of the glyph renderers to draw in the legend. If ``label`` is a field, 192 then all data_sources of renderers must be the same. 193 """) 194 195 index = Nullable(Int, help=""" 196 The column data index to use for drawing the representative items. 197 198 If None (the default), then Bokeh will automatically choose an index to 199 use. If the label does not refer to a data column name, this is typically 200 the first data point in the data source. Otherwise, if the label does 201 refer to a column name, the legend will have "groupby" behavior, and will 202 choose and display representative points from every "group" in the column. 203 204 If set to a number, Bokeh will use that number as the index in all cases. 205 """) 206 207 @error(NON_MATCHING_DATA_SOURCES_ON_LEGEND_ITEM_RENDERERS) 208 def _check_data_sources_on_renderers(self): 209 if self.label and 'field' in self.label: 210 if len({r.data_source for r in self.renderers}) != 1: 211 return str(self) 212 213 @error(BAD_COLUMN_NAME) 214 def _check_field_label_on_data_source(self): 215 if self.label and 'field' in self.label: 216 if len(self.renderers) < 1: 217 return str(self) 218 source = self.renderers[0].data_source 219 if self.label.get('field') not in source.column_names: 220 return str(self) 221 222class Legend(Annotation): 223 ''' Render informational legends for a plot. 224 225 See :ref:`userguide_plotting_legends` for information on plotting legends. 226 227 ''' 228 229 location = Either(Enum(LegendLocation), Tuple(Float, Float), default="top_right", help=""" 230 The location where the legend should draw itself. It's either one of 231 ``bokeh.core.enums.LegendLocation``'s enumerated values, or a ``(x, y)`` 232 tuple indicating an absolute location absolute location in screen 233 coordinates (pixels from the bottom-left corner). 234 """) 235 236 orientation = Enum(Orientation, default="vertical", help=""" 237 Whether the legend entries should be placed vertically or horizontally 238 when they are drawn. 239 """) 240 241 title = Nullable(String, help=""" 242 The title text to render. 243 """) 244 245 title_props = Include(ScalarTextProps, help=""" 246 The %s values for the title text. 247 """) 248 249 title_text_font_size = Override(default="13px") 250 251 title_text_font_style = Override(default="italic") 252 253 title_standoff = Int(5, help=""" 254 The distance (in pixels) to separate the title from the legend. 255 """) 256 257 border_props = Include(ScalarLineProps, help=""" 258 The %s for the legend border outline. 259 """) 260 261 border_line_color = Override(default="#e5e5e5") 262 263 border_line_alpha = Override(default=0.5) 264 265 background_props = Include(ScalarFillProps, help=""" 266 The %s for the legend background style. 267 """) 268 269 inactive_props = Include(ScalarFillProps, help=""" 270 The %s for the legend item style when inactive. These control an overlay 271 on the item that can be used to obscure it when the corresponding glyph 272 is inactive (e.g. by making it semi-transparent). 273 """) 274 275 click_policy = Enum(LegendClickPolicy, default="none", help=""" 276 Defines what happens when a lengend's item is clicked. 277 """) 278 279 background_fill_color = Override(default="#ffffff") 280 281 background_fill_alpha = Override(default=0.95) 282 283 inactive_fill_color = Override(default="white") 284 285 inactive_fill_alpha = Override(default=0.7) 286 287 label_props = Include(ScalarTextProps, help=""" 288 The %s for the legend labels. 289 """) 290 291 label_text_baseline = Override(default='middle') 292 293 label_text_font_size = Override(default='13px') 294 295 label_standoff = Int(5, help=""" 296 The distance (in pixels) to separate the label from its associated glyph. 297 """) 298 299 label_height = Int(20, help=""" 300 The minimum height (in pixels) of the area that legend labels should occupy. 301 """) 302 303 label_width = Int(20, help=""" 304 The minimum width (in pixels) of the area that legend labels should occupy. 305 """) 306 307 glyph_height = Int(20, help=""" 308 The height (in pixels) that the rendered legend glyph should occupy. 309 """) 310 311 glyph_width = Int(20, help=""" 312 The width (in pixels) that the rendered legend glyph should occupy. 313 """) 314 315 margin = Int(10, help=""" 316 Amount of margin around the legend. 317 """) 318 319 padding = Int(10, help=""" 320 Amount of padding around the contents of the legend. Only applicable when 321 border is visible, otherwise collapses to 0. 322 """) 323 324 spacing = Int(3, help=""" 325 Amount of spacing (in pixels) between legend entries. 326 """) 327 328 items = List(Instance(LegendItem), help=""" 329 A list of :class:`~bokeh.model.annotations.LegendItem` instances to be 330 rendered in the legend. 331 332 This can be specified explicitly, for instance: 333 334 .. code-block:: python 335 336 legend = Legend(items=[ 337 LegendItem(label="sin(x)" , renderers=[r0, r1]), 338 LegendItem(label="2*sin(x)" , renderers=[r2]), 339 LegendItem(label="3*sin(x)" , renderers=[r3, r4]) 340 ]) 341 342 But as a convenience, can also be given more compactly as a list of tuples: 343 344 .. code-block:: python 345 346 legend = Legend(items=[ 347 ("sin(x)" , [r0, r1]), 348 ("2*sin(x)" , [r2]), 349 ("3*sin(x)" , [r3, r4]) 350 ]) 351 352 where each tuple is of the form: *(label, renderers)*. 353 354 """).accepts(List(Tuple(String, List(Instance(GlyphRenderer)))), lambda items: [LegendItem(label=item[0], renderers=item[1]) for item in items]) 355 356class ColorBar(Annotation): 357 ''' Render a color bar based on a color mapper. 358 359 See :ref:`userguide_plotting_color_bars` for information on plotting color bars. 360 361 ''' 362 363 location = Either(Enum(Anchor), Tuple(Float, Float), default="top_right", help=""" 364 The location where the color bar should draw itself. It's either one of 365 ``bokeh.core.enums.Anchor``'s enumerated values, or a ``(x, y)`` 366 tuple indicating an absolute location absolute location in screen 367 coordinates (pixels from the bottom-left corner). 368 369 .. warning:: 370 If the color bar is placed in a side panel, the location will likely 371 have to be set to `(0,0)`. 372 """) 373 374 orientation = Either(Enum(Orientation), Auto, default="auto", help=""" 375 Whether the color bar should be oriented vertically or horizontally. 376 """) 377 378 height = Either(Auto, Int, help=""" 379 The height (in pixels) that the color scale should occupy. 380 """) 381 382 width = Either(Auto, Int, help=""" 383 The width (in pixels) that the color scale should occupy. 384 """) 385 386 scale_alpha = Float(1.0, help=""" 387 The alpha with which to render the color scale. 388 """) 389 390 title = Nullable(String, help=""" 391 The title text to render. 392 """) 393 394 title_props = Include(ScalarTextProps, help=""" 395 The %s values for the title text. 396 """) 397 398 title_text_font_size = Override(default="13px") 399 400 title_text_font_style = Override(default="italic") 401 402 title_standoff = Int(2, help=""" 403 The distance (in pixels) to separate the title from the color bar. 404 """) 405 406 ticker = Either(Instance(Ticker), Auto, default="auto", help=""" 407 A Ticker to use for computing locations of axis components. 408 """) 409 410 formatter = Either(Instance(TickFormatter), Auto, default="auto", help=""" 411 A ``TickFormatter`` to use for formatting the visual appearance of ticks. 412 """) 413 414 major_label_overrides = Dict(Either(Float, String), String, default={}, help=""" 415 Provide explicit tick label values for specific tick locations that 416 override normal formatting. 417 """) 418 419 major_label_policy = Instance(LabelingPolicy, default=lambda: NoOverlap(), help=""" 420 Allows to filter out labels, e.g. declutter labels to avoid overlap. 421 """) 422 423 color_mapper = Instance(ColorMapper, help=""" 424 A color mapper containing a color palette to render. 425 426 .. warning:: 427 If the `low` and `high` attributes of the ``ColorMapper`` aren't set, ticks 428 and tick labels won't be rendered. Additionally, if a ``LogTicker`` is 429 passed to the `ticker` argument and either or both of the logarithms 430 of `low` and `high` values of the color_mapper are non-numeric 431 (i.e. `low=0`), the tick and tick labels won't be rendered. 432 """) 433 434 margin = Int(30, help=""" 435 Amount of margin (in pixels) around the outside of the color bar. 436 """) 437 438 padding = Int(10, help=""" 439 Amount of padding (in pixels) between the color scale and color bar border. 440 """) 441 442 major_label_props = Include(ScalarTextProps, help=""" 443 The %s of the major tick labels. 444 """) 445 446 major_label_text_font_size = Override(default="11px") 447 448 label_standoff = Int(5, help=""" 449 The distance (in pixels) to separate the tick labels from the color bar. 450 """) 451 452 major_tick_props = Include(ScalarLineProps, help=""" 453 The %s of the major ticks. 454 """) 455 456 major_tick_line_color = Override(default="#ffffff") 457 458 major_tick_in = Int(default=5, help=""" 459 The distance (in pixels) that major ticks should extend into the 460 main plot area. 461 """) 462 463 major_tick_out = Int(default=0, help=""" 464 The distance (in pixels) that major ticks should extend out of the 465 main plot area. 466 """) 467 468 minor_tick_props = Include(ScalarLineProps, help=""" 469 The %s of the minor ticks. 470 """) 471 472 minor_tick_line_color = Override(default=None) 473 474 minor_tick_in = Int(default=0, help=""" 475 The distance (in pixels) that minor ticks should extend into the 476 main plot area. 477 """) 478 479 minor_tick_out = Int(default=0, help=""" 480 The distance (in pixels) that major ticks should extend out of the 481 main plot area. 482 """) 483 484 bar_props = Include(ScalarLineProps, help=""" 485 The %s for the color scale bar outline. 486 """) 487 488 bar_line_color = Override(default=None) 489 490 border_props = Include(ScalarLineProps, help=""" 491 The %s for the color bar border outline. 492 """) 493 494 border_line_color = Override(default=None) 495 496 background_props = Include(ScalarFillProps, help=""" 497 The %s for the color bar background style. 498 """) 499 500 background_fill_color = Override(default="#ffffff") 501 502 background_fill_alpha = Override(default=0.95) 503 504class Arrow(DataAnnotation): 505 ''' Render arrows as an annotation. 506 507 See :ref:`userguide_plotting_arrows` for information on plotting arrows. 508 509 ''' 510 511 x_start = NumberSpec(default=field("x_start"), help=""" 512 The x-coordinates to locate the start of the arrows. 513 """) 514 515 y_start = NumberSpec(default=field("y_start"), help=""" 516 The y-coordinates to locate the start of the arrows. 517 """) 518 519 start_units = Enum(SpatialUnits, default='data', help=""" 520 The unit type for the start_x and start_y attributes. Interpreted as "data 521 space" units by default. 522 """) 523 524 start = Nullable(Instance('.models.arrow_heads.ArrowHead'), help=""" 525 Instance of ``ArrowHead``. 526 """) 527 528 x_end = NumberSpec(default=field("x_end"), help=""" 529 The x-coordinates to locate the end of the arrows. 530 """) 531 532 y_end = NumberSpec(default=field("y_end"), help=""" 533 The y-coordinates to locate the end of the arrows. 534 """) 535 536 end_units = Enum(SpatialUnits, default='data', help=""" 537 The unit type for the end_x and end_y attributes. Interpreted as "data 538 space" units by default. 539 """) 540 541 end = Nullable(Instance('.models.arrow_heads.ArrowHead'), default=_DEFAULT_ARROW, help=""" 542 Instance of ``ArrowHead``. 543 """) 544 545 body_props = Include(LineProps, use_prefix=False, help=""" 546 The %s values for the arrow body. 547 """) 548 549class BoxAnnotation(Annotation): 550 ''' Render a shaded rectangular region as an annotation. 551 552 See :ref:`userguide_plotting_box_annotations` for information on plotting box annotations. 553 554 ''' 555 556 left = Either(Null, Auto, NumberSpec(), help=""" 557 The x-coordinates of the left edge of the box annotation. 558 559 Datetime values are also accepted, but note that they are immediately 560 converted to milliseconds-since-epoch. 561 """) 562 563 left_units = Enum(SpatialUnits, default='data', help=""" 564 The unit type for the left attribute. Interpreted as "data space" units 565 by default. 566 """) 567 568 right = Either(Null, Auto, NumberSpec(), help=""" 569 The x-coordinates of the right edge of the box annotation. 570 571 Datetime values are also accepted, but note that they are immediately 572 converted to milliseconds-since-epoch. 573 """) 574 575 right_units = Enum(SpatialUnits, default='data', help=""" 576 The unit type for the right attribute. Interpreted as "data space" units 577 by default. 578 """) 579 580 bottom = Either(Null, Auto, NumberSpec(), help=""" 581 The y-coordinates of the bottom edge of the box annotation. 582 583 Datetime values are also accepted, but note that they are immediately 584 converted to milliseconds-since-epoch. 585 """) 586 587 bottom_units = Enum(SpatialUnits, default='data', help=""" 588 The unit type for the bottom attribute. Interpreted as "data space" units 589 by default. 590 """) 591 592 top = Either(Null, Auto, NumberSpec(), help=""" 593 The y-coordinates of the top edge of the box annotation. 594 595 Datetime values are also accepted, but note that they are immediately 596 converted to milliseconds-since-epoch. 597 """) 598 599 top_units = Enum(SpatialUnits, default='data', help=""" 600 The unit type for the top attribute. Interpreted as "data space" units 601 by default. 602 """) 603 604 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 605 The %s values for the box. 606 """) 607 608 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 609 The %s values for the box. 610 """) 611 612 hatch_props = Include(ScalarHatchProps, use_prefix=False, help=""" 613 The %s values for the box. 614 """) 615 616 line_alpha = Override(default=0.3) 617 618 line_color = Override(default="#cccccc") 619 620 fill_alpha = Override(default=0.4) 621 622 fill_color = Override(default="#fff9ba") 623 624 render_mode = Enum(RenderMode, default="canvas", help=""" 625 Specifies whether the box is rendered as a canvas element or as an 626 css element overlaid on the canvas. The default mode is "canvas". 627 628 .. note: 629 This property is deprecated and will be removed in bokeh 3.0. 630 631 .. warning:: 632 The line_dash and line_dash_offset attributes aren't supported if 633 the render_mode is set to "css" 634 635 """) 636 637class Band(DataAnnotation): 638 ''' Render a filled area band along a dimension. 639 640 See :ref:`userguide_plotting_bands` for information on plotting bands. 641 642 ''' 643 lower = PropertyUnitsSpec(default=field("lower"), units_type=Enum(SpatialUnits), units_default="data", help=""" 644 The coordinates of the lower portion of the filled area band. 645 """) 646 647 upper = PropertyUnitsSpec(default=field("upper"), units_type=Enum(SpatialUnits), units_default="data", help=""" 648 The coordinates of the upper portion of the filled area band. 649 """) 650 651 base = PropertyUnitsSpec(default=field("base"), units_type=Enum(SpatialUnits), units_default="data", help=""" 652 The orthogonal coordinates of the upper and lower values. 653 """) 654 655 dimension = Enum(Dimension, default='height', help=""" 656 The direction of the band can be specified by setting this property 657 to "height" (``y`` direction) or "width" (``x`` direction). 658 """) 659 660 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 661 The %s values for the band. 662 """) 663 664 line_alpha = Override(default=0.3) 665 666 line_color = Override(default="#cccccc") 667 668 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 669 The %s values for the band. 670 """) 671 672 fill_alpha = Override(default=0.4) 673 674 fill_color = Override(default="#fff9ba") 675 676class Label(TextAnnotation): 677 ''' Render a single text label as an annotation. 678 679 ``Label`` will render a single text label at given ``x`` and ``y`` 680 coordinates, which can be in either screen (pixel) space, or data (axis 681 range) space. 682 683 The label can also be configured with a screen space offset from ``x`` and 684 ``y``, by using the ``x_offset`` and ``y_offset`` properties. 685 686 Additionally, the label can be rotated with the ``angle`` property. 687 688 There are also standard text, fill, and line properties to control the 689 appearance of the text, its background, as well as the rectangular bounding 690 box border. 691 692 See :ref:`userguide_plotting_labels` for information on plotting labels. 693 694 ''' 695 696 x = NonNullable(Float, help=""" 697 The x-coordinate in screen coordinates to locate the text anchors. 698 699 Datetime values are also accepted, but note that they are immediately 700 converted to milliseconds-since-epoch. 701 """).accepts(Datetime, convert_datetime_type) 702 703 x_units = Enum(SpatialUnits, default='data', help=""" 704 The unit type for the x attribute. Interpreted as "data space" units 705 by default. 706 """) 707 708 y = NonNullable(Float, help=""" 709 The y-coordinate in screen coordinates to locate the text anchors. 710 711 Datetime values are also accepted, but note that they are immediately 712 converted to milliseconds-since-epoch. 713 """).accepts(Datetime, convert_datetime_type) 714 715 y_units = Enum(SpatialUnits, default='data', help=""" 716 The unit type for the y attribute. Interpreted as "data space" units 717 by default. 718 """) 719 720 text = String(default="", help=""" 721 The text value to render. 722 """) 723 724 angle = Angle(default=0, help=""" 725 The angle to rotate the text, as measured from the horizontal. 726 727 .. warning:: 728 The center of rotation for canvas and css render_modes is different. 729 For `render_mode="canvas"` the label is rotated from the top-left 730 corner of the annotation, while for `render_mode="css"` the annotation 731 is rotated around it's center. 732 """) 733 734 angle_units = Enum(AngleUnits, default='rad', help=""" 735 Acceptable values for units are ``"rad"`` and ``"deg"`` 736 """) 737 738 x_offset = Float(default=0, help=""" 739 Offset value to apply to the x-coordinate. 740 741 This is useful, for instance, if it is desired to "float" text a fixed 742 distance in screen units from a given data position. 743 """) 744 745 y_offset = Float(default=0, help=""" 746 Offset value to apply to the y-coordinate. 747 748 This is useful, for instance, if it is desired to "float" text a fixed 749 distance in screen units from a given data position. 750 """) 751 752 text_props = Include(ScalarTextProps, use_prefix=False, help=""" 753 The %s values for the text. 754 """) 755 756 background_props = Include(ScalarFillProps, use_prefix=True, help=""" 757 The %s values for the text bounding box. 758 """) 759 760 background_fill_color = Override(default=None) 761 762 border_props = Include(ScalarLineProps, use_prefix=True, help=""" 763 The %s values for the text bounding box. 764 """) 765 766 border_line_color = Override(default=None) 767 768class LabelSet(TextAnnotation): # TODO: DataAnnotation 769 ''' Render multiple text labels as annotations. 770 771 ``LabelSet`` will render multiple text labels at given ``x`` and ``y`` 772 coordinates, which can be in either screen (pixel) space, or data (axis 773 range) space. In this case (as opposed to the single ``Label`` model), 774 ``x`` and ``y`` can also be the name of a column from a 775 :class:`~bokeh.models.sources.ColumnDataSource`, in which case the labels 776 will be "vectorized" using coordinate values from the specified columns. 777 778 The label can also be configured with a screen space offset from ``x`` and 779 ``y``, by using the ``x_offset`` and ``y_offset`` properties. These offsets 780 may be vectorized by giving the name of a data source column. 781 782 Additionally, the label can be rotated with the ``angle`` property (which 783 may also be a column name.) 784 785 There are also standard text, fill, and line properties to control the 786 appearance of the text, its background, as well as the rectangular bounding 787 box border. 788 789 The data source is provided by setting the ``source`` property. 790 791 ''' 792 793 x = NumberSpec(default=field("x"), help=""" 794 The x-coordinates to locate the text anchors. 795 """) 796 797 x_units = Enum(SpatialUnits, default='data', help=""" 798 The unit type for the ``xs`` attribute. Interpreted as "data space" units 799 by default. 800 """) 801 802 y = NumberSpec(default=field("y"), help=""" 803 The y-coordinates to locate the text anchors. 804 """) 805 806 y_units = Enum(SpatialUnits, default='data', help=""" 807 The unit type for the ``ys`` attribute. Interpreted as "data space" units 808 by default. 809 """) 810 811 text = StringSpec(default=field("text"), help=""" 812 The text values to render. 813 """) 814 815 angle = AngleSpec(default=0, help=""" 816 The angles to rotate the text, as measured from the horizontal. 817 818 .. warning:: 819 The center of rotation for canvas and css render_modes is different. 820 For `render_mode="canvas"` the label is rotated from the top-left 821 corner of the annotation, while for `render_mode="css"` the annotation 822 is rotated around it's center. 823 """) 824 825 x_offset = NumberSpec(default=0, help=""" 826 Offset values to apply to the x-coordinates. 827 828 This is useful, for instance, if it is desired to "float" text a fixed 829 distance in screen units from a given data position. 830 """) 831 832 y_offset = NumberSpec(default=0, help=""" 833 Offset values to apply to the y-coordinates. 834 835 This is useful, for instance, if it is desired to "float" text a fixed 836 distance in screen units from a given data position. 837 """) 838 839 text_props = Include(TextProps, use_prefix=False, help=""" 840 The %s values for the text. 841 """) 842 843 background_props = Include(FillProps, use_prefix=True, help=""" 844 The %s values for the text bounding box. 845 """) 846 847 background_fill_color = Override(default=None) 848 849 border_props = Include(LineProps, use_prefix=True, help=""" 850 The %s values for the text bounding box. 851 """) 852 853 border_line_color = Override(default=None) 854 855 source = Instance(DataSource, default=lambda: ColumnDataSource(), help=""" 856 Local data source to use when rendering annotations on the plot. 857 """) 858 859class PolyAnnotation(Annotation): 860 ''' Render a shaded polygonal region as an annotation. 861 862 See :ref:`userguide_plotting_polygon_annotations` for information on 863 plotting polygon annotations. 864 865 ''' 866 867 xs = Seq(Float, default=[], help=""" 868 The x-coordinates of the region to draw. 869 """) 870 871 xs_units = Enum(SpatialUnits, default='data', help=""" 872 The unit type for the ``xs`` attribute. Interpreted as "data space" units 873 by default. 874 """) 875 876 ys = Seq(Float, default=[], help=""" 877 The y-coordinates of the region to draw. 878 """) 879 880 ys_units = Enum(SpatialUnits, default='data', help=""" 881 The unit type for the ``ys`` attribute. Interpreted as "data space" units 882 by default. 883 """) 884 885 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 886 The %s values for the polygon. 887 """) 888 889 fill_props = Include(ScalarFillProps, use_prefix=False, help=""" 890 The %s values for the polygon. 891 """) 892 893 hatch_props = Include(ScalarHatchProps, use_prefix=False, help=""" 894 The %s values for the polygon. 895 """) 896 897 line_alpha = Override(default=0.3) 898 899 line_color = Override(default="#cccccc") 900 901 fill_alpha = Override(default=0.4) 902 903 fill_color = Override(default="#fff9ba") 904 905class Slope(Annotation): 906 """ Render a sloped line as an annotation. 907 908 See :ref:`userguide_plotting_slope` for information on plotting slopes. 909 910 """ 911 912 gradient = Nullable(Float, help=""" 913 The gradient of the line, in data units 914 """) 915 916 y_intercept = Nullable(Float, help=""" 917 The y intercept of the line, in data units 918 """) 919 920 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 921 The %s values for the line. 922 """) 923 924class Span(Annotation): 925 """ Render a horizontal or vertical line span. 926 927 See :ref:`userguide_plotting_spans` for information on plotting spans. 928 929 """ 930 931 location = Nullable(Float, help=""" 932 The location of the span, along ``dimension``. 933 934 Datetime values are also accepted, but note that they are immediately 935 converted to milliseconds-since-epoch. 936 """).accepts(Datetime, convert_datetime_type) 937 938 location_units = Enum(SpatialUnits, default='data', help=""" 939 The unit type for the location attribute. Interpreted as "data space" 940 units by default. 941 """) 942 943 dimension = Enum(Dimension, default='width', help=""" 944 The direction of the span can be specified by setting this property 945 to "height" (``y`` direction) or "width" (``x`` direction). 946 """) 947 948 render_mode = Enum(RenderMode, default="canvas", help=""" 949 Specifies whether the span is rendered as a canvas element or as a 950 CSS element overlaid on the canvas. The default mode is "canvas". 951 952 .. note: 953 This property is deprecated and will be removed in bokeh 3.0. 954 955 .. warning:: 956 The line_dash and line_dash_offset attributes aren't supported if 957 the render_mode is set to "css" 958 959 """) 960 961 line_props = Include(ScalarLineProps, use_prefix=False, help=""" 962 The %s values for the span. 963 """) 964 965class Title(TextAnnotation): 966 ''' Render a single title box as an annotation. 967 968 See :ref:`userguide_plotting_titles` for information on plotting titles. 969 970 ''' 971 972 text = String(default="", help=""" 973 The text value to render. 974 """) 975 976 vertical_align = Enum(VerticalAlign, default='bottom', help=""" 977 Alignment of the text in its enclosing space, *across* the direction of the text. 978 """) 979 980 align = Enum(TextAlign, default='left', help=""" 981 Alignment of the text in its enclosing space, *along* the direction of the text. 982 """) 983 984 text_line_height = Float(default=1.0, help=""" 985 How much additional space should be allocated for the title. The value is provided 986 as a number, but should be treated as a percentage of font size. The default is 987 100%, which means no additional space will be used. 988 """) 989 990 offset = Float(default=0, help=""" 991 Offset the text by a number of pixels (can be positive or negative). Shifts the text in 992 different directions based on the location of the title: 993 994 * above: shifts title right 995 * right: shifts title down 996 * below: shifts title right 997 * left: shifts title up 998 999 """) 1000 1001 standoff = Float(default=10, help=""" 1002 """) 1003 1004 text_font = String(default="helvetica", help=""" 1005 Name of a font to use for rendering text, e.g., ``'times'``, 1006 ``'helvetica'``. 1007 1008 """) 1009 1010 text_font_size = String(default="13px") 1011 1012 text_font_style = Enum(FontStyle, default="bold", help=""" 1013 A style to use for rendering text. 1014 1015 Acceptable values are: 1016 1017 - ``'normal'`` normal text 1018 - ``'italic'`` *italic text* 1019 - ``'bold'`` **bold text** 1020 1021 """) 1022 1023 text_color = Color(default="#444444", help=""" 1024 A color to use to fill text with. 1025 """) 1026 1027 text_alpha = Alpha(help=""" 1028 An alpha value to use to fill text with. 1029 """) 1030 1031 background_props = Include(ScalarFillProps, use_prefix=True, help=""" 1032 The %s values for the text bounding box. 1033 """) 1034 1035 background_fill_color = Override(default=None) 1036 1037 border_props = Include(ScalarLineProps, use_prefix=True, help=""" 1038 The %s values for the text bounding box. 1039 """) 1040 1041 border_line_color = Override(default=None) 1042 1043class Tooltip(Annotation): 1044 ''' Render a tooltip. 1045 1046 .. note:: 1047 This model is currently managed by BokehJS and is not useful 1048 directly from python. 1049 1050 ''' 1051 level = Override(default="overlay") 1052 1053 attachment = Enum(TooltipAttachment, help=""" 1054 Whether the tooltip should be displayed to the left or right of the cursor 1055 position or above or below it, or if it should be automatically placed 1056 in the horizontal or vertical dimension. 1057 """) 1058 1059 inner_only = Bool(default=True, help=""" 1060 Whether to display outside a central plot frame area. 1061 1062 .. note: 1063 This property is deprecated and will be removed in bokeh 3.0. 1064 1065 """) 1066 1067 show_arrow = Bool(default=True, help=""" 1068 Whether tooltip's arrow should be shown. 1069 """) 1070 1071class Whisker(DataAnnotation): 1072 ''' Render a whisker along a dimension. 1073 1074 See :ref:`userguide_plotting_whiskers` for information on plotting whiskers. 1075 1076 ''' 1077 1078 lower = PropertyUnitsSpec(default=field("lower"), units_type=Enum(SpatialUnits), units_default="data", help=""" 1079 The coordinates of the lower end of the whiskers. 1080 """) 1081 1082 lower_head = Nullable(Instance('.models.arrow_heads.ArrowHead'), default=_DEFAULT_TEE, help=""" 1083 Instance of ``ArrowHead``. 1084 """) 1085 1086 upper = PropertyUnitsSpec(default=field("upper"), units_type=Enum(SpatialUnits), units_default="data", help=""" 1087 The coordinates of the upper end of the whiskers. 1088 """) 1089 1090 upper_head = Nullable(Instance('.models.arrow_heads.ArrowHead'), default=_DEFAULT_TEE, help=""" 1091 Instance of ``ArrowHead``. 1092 """) 1093 1094 base = PropertyUnitsSpec(default=field("base"), units_type=Enum(SpatialUnits), units_default="data", help=""" 1095 The orthogonal coordinates of the upper and lower values. 1096 """) 1097 1098 dimension = Enum(Dimension, default='height', help=""" 1099 The direction of the whisker can be specified by setting this property 1100 to "height" (``y`` direction) or "width" (``x`` direction). 1101 """) 1102 1103 line_props = Include(LineProps, use_prefix=False, help=""" 1104 The %s values for the whisker body. 1105 """) 1106 1107 level = Override(default="underlay") 1108 1109class ToolbarPanel(Annotation): # TODO: this shouldn't be an annotation 1110 1111 toolbar = Instance(".models.tools.Toolbar", help=""" 1112 A toolbar to display. 1113 """) 1114 1115#----------------------------------------------------------------------------- 1116# Dev API 1117#----------------------------------------------------------------------------- 1118 1119#----------------------------------------------------------------------------- 1120# Code 1121#----------------------------------------------------------------------------- 1122