Source code for highcharts_maps.options.plot_options.flowmap

from decimal import Decimal
from typing import Optional, List

from validator_collection import validators

from highcharts_maps import constants
from highcharts_maps.decorators import class_sensitive
from highcharts_maps.options.plot_options.generic import GenericTypeOptions
from highcharts_maps.utility_classes.gradients import Gradient
from highcharts_maps.utility_classes.patterns import Pattern
from highcharts_maps.utility_classes.markers import FlowmapMarker
from highcharts_maps.options.plot_options.map import MapOptions


[docs]class FlowmapOptions(GenericTypeOptions): """A :term:`flowmap` series is a series laid out on top of a map series that displays route paths (e.g. flight or naval routes), or directional flows on a map. It creates a link between two points on a map chart. .. figure:: ../../../_static/flowmap-example.png :alt: Flowmap Example chart :align: center """ def __init__(self, **kwargs): self._animation_limit = None self._color_axis = None self._color_by_point = None self._color_index = None self._color_key = None self._colors = None self._curve_factor = None self._fill_color = None self._fill_opacity = None self._find_nearest_point_by = None self._line_width = None self._marker_end = None self._max_width = None self._min_width = None self._null_color = None self._null_interaction = None self._weight = None self._width = None self._z_index = None self.animation_limit = kwargs.get('animation_limit', None) self.color_axis = kwargs.get('color_axis', None) self.color_by_point = kwargs.get('color_by_point', None) self.color_index = kwargs.get('color_index', None) self.color_key = kwargs.get('color_key', None) self.colors = kwargs.get('colors', None) self.curve_factor = kwargs.get('curve_factor', None) self.fill_color = kwargs.get('fill_color', None) self.fill_opacity = kwargs.get('fill_opacity', None) self.find_nearest_point_by = kwargs.get('find_nearest_point_by', None) self.line_width = kwargs.get('line_width', None) self.marker_end = kwargs.get('marker_end', None) self.max_width = kwargs.get('max_width', None) self.min_width = kwargs.get('min_width', None) self.null_color = kwargs.get('null_color', None) self.null_interaction = kwargs.get('null_interaction', None) self.weight = kwargs.get('weight', None) self.width = kwargs.get('width', None) self.z_index = kwargs.get('z_index', None) super().__init__(**kwargs) @property def animation_limit(self) -> Optional[int | float | Decimal]: """For some series, there is a limit that shuts down initial animation by default when the total number of points in the chart is too high. Defaults to :obj:`None <python:None>`. For example, for a column chart and its derivatives, animation does not run if there is more than 250 points totally. To disable this cap, set ``animation_limit`` to ``float("inf")`` (which represents infinity). :rtype: numeric or :obj:`None <python:None>` """ return self._animation_limit @animation_limit.setter def animation_limit(self, value): if value == float('inf'): self._animation_limit = float('inf') else: self._animation_limit = validators.numeric(value, allow_empty = True, minimum = 0) @property def color_axis(self) -> Optional[str | int | bool]: """When using dual or multiple color axes, this setting defines which :term:`color axis` the particular series is connected to. It refers to either the :meth:`ColorAxis.id` or the index of the axis in the :class:`ColorAxis` array, with ``0`` being the first. Set this option to ``False`` to prevent a series from connecting to the default color axis. Defaults to ``0``. :rtype: :obj:`None <python:None>` or :class:`str <python:str>` or :class:`int <python:int>` or :class:`bool <python:bool>` """ return self._color_axis @color_axis.setter def color_axis(self, value): if value is None: self._color_axis = None elif value is False: self._color_axis = False else: try: self._color_axis = validators.string(value) except TypeError: self._color_axis = validators.integer(value, minimum = 0) @property def color_by_point(self) -> Optional[bool]: """When using automatic point colors pulled from the global colors or series-specific collections, this option determines whether the chart should receive one color per series (``False``) or one color per point (``True``). Defaults to ``False``. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._color_by_point @color_by_point.setter def color_by_point(self, value): if value is None: self._color_by_point = None else: self._color_by_point = bool(value) @property def color_index(self) -> Optional[int]: """When operating in :term:`styled mode`, a specific color index to use for the series, so that its graphic representations are given the class name ``highcharts-color-{n}``. Defaults to :obj:`None <python:None>`. :rtype: :class:`int <python:int>` or :obj:`None <python:None>` """ return self._color_index @color_index.setter def color_index(self, value): self._color_index = validators.integer(value, allow_empty = True, minimum = 0) @property def color_key(self) -> Optional[str]: """Determines what data value should be used to calculate point color if :meth:`FlowmapOptions.color_axis` is used. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._color_key @color_key.setter def color_key(self, value): self._color_key = validators.string(value, allow_empty = True) @property def colors(self) -> Optional[List[str | Gradient | Pattern]]: """A series-specific or series type-specific color set to apply instead of the global colors when :meth:`FlowmapOptions.color_by_point` is ``True``. :rtype: :class:`list <python:list>` of :class:`str <python:str>`, :class:`Gradient`, or :class:`Pattern` OR :obj:`None <python:None>` """ return self._colors @colors.setter def colors(self, value): from highcharts_maps.utility_functions import validate_color if not value: self._colors = None else: value = validators.iterable(value) self._colors = [validate_color(x) for x in value] @property def curve_factor(self) -> Optional[int | float | Decimal]: """The amount by which to curve the lines on a flowmap. Higher numbers makes the links more curved, while a value of ``0`` makes the lines straight. Defaults to :obj:`None <python:None>`. :rtype: numeric or :obj:`None <python:None>` """ return self._curve_factor @curve_factor.setter def curve_factor(self, value): self._curve_factor = validators.numeric(value, allow_empty = True) @property def fill_color(self) -> Optional[str | Gradient | Pattern | constants.EnforcedNullType]: """Fill color or gradient for the area. When :class:`EnforcedNullType`, the series' color is used with the series' :meth:`.fill_opacity <FlowmapOptions.fill_opacity>`. :rtype: :obj:`None <python:None>`, :class:`Gradient`, :class:`Pattern`, or :class:`EnforcedNullType` """ return self._fill_color @fill_color.setter def fill_color(self, value): from highcharts_maps.utility_functions import validate_color self._fill_color = validate_color(value) @property def fill_opacity(self) -> Optional[int | float | Decimal]: """Fill opacity for the area. Defaults to ``0.5``. When you set an explicit :meth:`fill_color <FlowmapOptions.fill_color>`, the ``fill_opacity`` is not applied. Instead, you should define the opacity in the :meth:`fill_color <FlowmapOptions.fill_color>` with an rgba color definition. The ``fill_opacity`` setting, also the default setting, overrides the alpha component of the color setting. :rtype: numeric or :obj:`None <python:None>` """ return self._fill_opacity @fill_opacity.setter def fill_opacity(self, value): self._fill_opacity = validators.numeric(value, allow_empty = True, minimum = 0) @property def find_nearest_point_by(self) -> Optional[str]: """Determines whether the series should look for the nearest point in both dimensions or just the x-dimension when hovering the series. If :obj:`None <python:None>`, defaults to ``'xy'`` for scatter series and ``'x'`` for most other series. If the data has duplicate x-values, it is recommended to set this to ``'xy'`` to allow hovering over all points. Applies only to series types using nearest neighbor search (not direct hover) for tooltip. :rtype: :class:`str <python:str>` or :obj:`None <python:None>` """ return self._find_nearest_point_by @find_nearest_point_by.setter def find_nearest_point_by(self, value): self._find_nearest_point_by = validators.string(value, allow_empty = True) @property def line_width(self) -> Optional[int | float | Decimal]: """Pixel width of the graph line. Defaults to :obj:`None <python:None>`. :rtype: numeric or :obj:`None <python:None>` """ return self._line_width @line_width.setter def line_width(self, value): self._line_width = validators.numeric(value, allow_empty = True, minimum = 0) @property def marker_end(self) -> Optional[FlowmapMarker]: """If enabled, creates an arrow symbol indicating the direction of the flow at the flow's destination. .. warning:: Setting/enabling this property in the :class:`FlowmapOptions <highcharts_maps.options.plot_options.flowmap.FlowmapOptions>` object rather than in the :class:`FlowmapSeries <highcharts_maps.options.series.flowmap.FlowmapSeries>` will apply a marker to the end of *every* flowmap series in your visualization. :rtype: :class:`FlowmapMarker <highcharts_maps.utility_classes.markers.FlowmapMarker>` or :obj:`None <python:None> """ return self._marker_end @marker_end.setter @class_sensitive(FlowmapMarker) def marker_end(self, value): self._marker_end = value @property def max_width(self) -> Optional[int | float | Decimal]: """The maximum width of a link expressed in pixels. Defaults to ``25``. :rtype: numeric or :obj:`None <python:None>` """ return self._max_width @max_width.setter def max_width(self, value): if value is None: self._max_width = None else: self._max_width = validators.numeric(value, allow_empty = True, minimum = 0) @property def min_width(self) -> Optional[int | float | Decimal]: """The minimum width of a link expressed in pixels. Defaults to ``5``. :rtype: numeric or :obj:`None <python:None>` """ return self._min_width @min_width.setter def min_width(self, value): if value is None: self._min_width = None else: self._min_width = validators.numeric(value, allow_empty = True, minimum = 0) @property def null_color(self) -> Optional[str | Gradient | Pattern]: """The color applied to null points. Defaults to ``'#f7f7f7'``. :rtype: :obj:`None <python:None>`, :class:`Gradient`, :class:`Pattern`, or :class:`str <python:str>` """ return self._null_color @null_color.setter def null_color(self, value): from highcharts_maps import utility_functions self._null_color = utility_functions.validate_color(value) @property def null_interaction(self) -> Optional[bool]: """If ``True``, allows pointer interactions (e.g. tooltips, mouse events, etc.) on null points. Defaults to :obj:`None <python:None>`. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._null_interaction @null_interaction.setter def null_interaction(self, value): if value is None: self._null_interaction = None else: self._null_interaction = bool(value) @property def weight(self) -> Optional[int | float | Decimal]: """he weight for all links with unspecified weights. The weight of a link determines its thickness compared to other links. Defaults to :obj:`None <python:None>`. :rtype: numeric or :obj:`None <python:None>` """ return self._weight @weight.setter def weight(self, value): self._weight = validators.numeric(value, allow_empty = True) @property def width(self) -> Optional[int | float | Decimal]: """If no :meth:`.weight <highcharts_maps.options.plot_options.flowmap.FlowmapOptions.weight>` has previously been specified, this will set the width of all the links without being compared to and scaled according to other weights. Defaults to ``1``. :rtype: numeric or :obj:`None <python:None>` """ return self._width @width.setter def width(self, value): self._width = validators.numeric(value, allow_empty = True) @property def z_index(self) -> Optional[int]: """The Z-Index for the series. Defaults to :obj:`None <python:None>`. :returns: The z-index for the series. :rtype: :class:`int <python:int>` or :obj:`None <python:None>` """ return self._z_index @z_index.setter def z_index(self, value): self._z_index = validators.integer(value, allow_empty = True) @classmethod def _get_kwargs_from_dict(cls, as_dict): kwargs = { 'accessibility': as_dict.get('accessibility', None), 'allow_point_select': as_dict.get('allowPointSelect', None), 'animation': as_dict.get('animation', None), 'class_name': as_dict.get('className', None), 'clip': as_dict.get('clip', None), 'color': as_dict.get('color', None), 'cursor': as_dict.get('cursor', None), 'custom': as_dict.get('custom', None), 'dash_style': as_dict.get('dashStyle', None), 'data_labels': as_dict.get('dataLabels', None), 'description': as_dict.get('description', None), 'enable_mouse_tracking': as_dict.get('enableMouseTracking', None), 'events': as_dict.get('events', None), 'include_in_data_export': as_dict.get('includeInDataExport', None), 'keys': as_dict.get('keys', None), 'label': as_dict.get('label', None), 'linked_to': as_dict.get('linkedTo', None), 'marker': as_dict.get('marker', None), 'on_point': as_dict.get('onPoint', None), 'opacity': as_dict.get('opacity', None), 'point': as_dict.get('point', None), 'point_description_formatter': as_dict.get('pointDescriptionFormatter', None), 'selected': as_dict.get('selected', None), 'show_checkbox': as_dict.get('showCheckbox', None), 'show_in_legend': as_dict.get('showInLegend', None), 'skip_keyboard_navigation': as_dict.get('skipKeyboardNavigation', None), 'sonification': as_dict.get('sonification', None), 'states': as_dict.get('states', None), 'sticky_tracking': as_dict.get('stickyTracking', None), 'threshold': as_dict.get('threshold', None), 'tooltip': as_dict.get('tooltip', None), 'turbo_threshold': as_dict.get('turboThreshold', None), 'visible': as_dict.get('visible', None), 'animation_limit': as_dict.get('animationLimit', None), 'color_axis': as_dict.get('colorAxis', None), 'color_by_point': as_dict.get('colorByPoint', None), 'color_index': as_dict.get('colorIndex', None), 'color_key': as_dict.get('colorKey', None), 'colors': as_dict.get('colors', None), 'curve_factor': as_dict.get('curveFactor', None), 'fill_color': as_dict.get('fillColor', None), 'fill_opacity': as_dict.get('fillOpacity', None), 'find_nearest_point_by': as_dict.get('findNearestPointBy', None), 'line_width': as_dict.get('lineWidth', None), 'marker_end': as_dict.get('markerEnd', None), 'max_width': as_dict.get('maxWidth', None), 'min_width': as_dict.get('minWidth', None), 'null_color': as_dict.get('nullColor', None), 'null_interaction': as_dict.get('nullInteraction', None), 'weight': as_dict.get('weight', None), 'width': as_dict.get('width', None), 'z_index': as_dict.get('zIndex', None), } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: from highcharts_maps.utility_functions import mro__to_untrimmed_dict untrimmed = { 'animationLimit': self.animation_limit, 'colorAxis': self.color_axis, 'colorByPoint': self.color_by_point, 'colorIndex': self.color_index, 'colorKey': self.color_key, 'colors': self.colors, 'curveFactor': self.curve_factor, 'fillColor': self.fill_color, 'fillOpacity': self.fill_opacity, 'findNearestPointBy': self.find_nearest_point_by, 'lineWidth': self.line_width, 'markerEnd': self.marker_end, 'maxWidth': self.max_width, 'minWidth': self.min_width, 'nullColor': self.null_color, 'nullInteraction': self.null_interaction, 'weight': self.weight, 'width': self.width, 'zIndex': self.z_index, } parent_as_dict = mro__to_untrimmed_dict(self, in_cls = in_cls) for key in parent_as_dict: untrimmed[key] = parent_as_dict[key] return untrimmed
[docs]class GeoHeatmapOptions(MapOptions, FlowmapOptions): """A :term:`geoheatmap` series is a variety of heatmap series, composed into the map projection, where the units are expressed in latitude and longitude, while individual values contained in a matrix are represented as colors. .. warning:: GeoHeatmaps require that ``modules/geoheatmap`` is loaded client-side. .. figure:: ../../../_static/geoheatmap-example.png :alt: GeoHeatmap Example Chart :align: center """ def __init__(self, **kwargs): self._border_color = None self._border_width = None self._colsize = None self._rowsize = None self.border_color = kwargs.get('border_color', None) self.border_width = kwargs.get('border_width', None) self.colsize = kwargs.get('colsize', None) self.rowsize = kwargs.get('rowsize', None) super().__init__(**kwargs) @property def all_areas(self) -> Optional[bool]: """If ``True``, all areas defined in the map's :meth:`.map_data <highcharts_maps.options.series.base.MapSeriesBase.map_data>` should be rendered, with areas that do not have a related data point rendered as null values. If ``False``, areas of the map that do not have a related data point are skipped and not rendered. Defaults to ``True``. :rtype: :class:`bool <python:bool>` or :obj:`None <python:None>` """ return self._all_areas @all_areas.setter def all_areas(self, value): self._all_areas = None @property def colsize(self) -> Optional[int]: """The column size - how many X axis units each column in the heatmap should span. Defaults to ``1``. :rtype: :class:`int <python:int>` or :obj:`None <python:None>` """ return self._colsize @colsize.setter def colsize(self, value): self._colsize = validators.integer(value, allow_empty = True, minimum = 1) @property def join_by(self) -> Optional[str | List[str] | constants.EnforcedNullType]: """The property which should be used to join the series' :meth:`.map_data <highcharts_maps.options.series.base.MapSeriesBase.map_data>` to its ``.data``. When :obj:`None <python:None>`, defaults to ``'hc-key'``. Accepts three possible types of value: * a string, which joins on the same property in both the ``.mapData`` and ``.data`` .. note:: For maps loaded from :term:`GeoJSON`, the keys may be held in each point's ``properties`` object. * a 2-member collection, where the first represents the key in ``.mapData`` and the second represents a (different) key in ``.data`` * :obj:`highcharts_maps.constants.EnforcedNull`, where items are joined by their positions in the ``.mapData`` and ``.data`` arrays .. tip:: Using :obj:`highcharts_maps.constants.EnforcedNull` performs much faster than the other two options. This is the recommended value when rendering more than a thousand data points, assuming that you are using a backend that can preprocess the data into parallel arrays. :rtype: :obj:`highcharts_maps.constants.EnforcedNull` or :class:`str <python:str>` or 2-member :class:`list <python:list>` of :class:`str <python:list>`, or :obj:`None <python:None>` :raises HighchartsValueError: if supplied an iterable that has more than 2 members """ return self._join_by @join_by.setter def join_by(self, value): self._join_by = None @property def rowsize(self) -> Optional[int]: """The row size - how many Y axis units each heatmap row should span. Defaults to ``1``. :rtype: :class:`int <python:int>` or :obj:`None <python:None>` """ return self._rowsize @rowsize.setter def rowsize(self, value): self._rowsize = validators.integer(value, allow_empty = True, minimum = 1) @classmethod def _get_kwargs_from_dict(cls, as_dict): kwargs = { 'accessibility': as_dict.get('accessibility', None), 'allow_point_select': as_dict.get('allowPointSelect', None), 'animation': as_dict.get('animation', None), 'class_name': as_dict.get('className', None), 'clip': as_dict.get('clip', None), 'color': as_dict.get('color', None), 'cursor': as_dict.get('cursor', None), 'custom': as_dict.get('custom', None), 'dash_style': as_dict.get('dashStyle', None), 'data_labels': as_dict.get('dataLabels', None), 'description': as_dict.get('description', None), 'enable_mouse_tracking': as_dict.get('enableMouseTracking', None), 'events': as_dict.get('events', None), 'include_in_data_export': as_dict.get('includeInDataExport', None), 'keys': as_dict.get('keys', None), 'label': as_dict.get('label', None), 'linked_to': as_dict.get('linkedTo', None), 'marker': as_dict.get('marker', None), 'on_point': as_dict.get('onPoint', None), 'opacity': as_dict.get('opacity', None), 'point': as_dict.get('point', None), 'point_description_formatter': as_dict.get('pointDescriptionFormatter', None), 'selected': as_dict.get('selected', None), 'show_checkbox': as_dict.get('showCheckbox', None), 'show_in_legend': as_dict.get('showInLegend', None), 'skip_keyboard_navigation': as_dict.get('skipKeyboardNavigation', None), 'sonification': as_dict.get('sonification', None), 'states': as_dict.get('states', None), 'sticky_tracking': as_dict.get('stickyTracking', None), 'threshold': as_dict.get('threshold', None), 'tooltip': as_dict.get('tooltip', None), 'turbo_threshold': as_dict.get('turboThreshold', None), 'visible': as_dict.get('visible', None), 'animation_limit': as_dict.get('animationLimit', None), 'color_axis': as_dict.get('colorAxis', None), 'color_by_point': as_dict.get('colorByPoint', None), 'color_index': as_dict.get('colorIndex', None), 'color_key': as_dict.get('colorKey', None), 'colors': as_dict.get('colors', None), 'curve_factor': as_dict.get('curveFactor', None), 'fill_color': as_dict.get('fillColor', None), 'fill_opacity': as_dict.get('fillOpacity', None), 'find_nearest_point_by': as_dict.get('findNearestPointBy', None), 'line_width': as_dict.get('lineWidth', None), 'marker_end': as_dict.get('markerEnd', None), 'max_width': as_dict.get('maxWidth', None), 'min_width': as_dict.get('minWidth', None), 'null_color': as_dict.get('nullColor', None), 'null_interaction': as_dict.get('nullInteraction', None), 'weight': as_dict.get('weight', None), 'width': as_dict.get('width', None), 'z_index': as_dict.get('zIndex', None), 'affects_map_view': as_dict.get('affectsMapView', None), 'border_color': as_dict.get('borderColor', None), 'border_width': as_dict.get('borderWidth', None), 'colsize': as_dict.get('colsize', None), 'rowsize': as_dict.get('rowsize', None), } return kwargs def _to_untrimmed_dict(self, in_cls = None) -> dict: from highcharts_maps.utility_functions import mro__to_untrimmed_dict untrimmed = { 'colsize': self.colsize, 'rowsize': self.rowsize, } parent_as_dict = mro__to_untrimmed_dict(self, in_cls = in_cls) for key in parent_as_dict: untrimmed[key] = parent_as_dict[key] return untrimmed