lets-plot 4.8.1rc1__cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

lets_plot/plot/util.py

@@ -0,0 +1,267 @@
+#
+# Copyright (c) 2019. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from typing import Any, Tuple, Sequence, Optional, Dict, List
+
+from lets_plot._type_utils import is_pandas_data_frame, is_polars_dataframe
+from lets_plot.geo_data_internals.utils import find_geo_names
+from lets_plot.mapping import MappingMeta
+from lets_plot.plot.core import aes, FeatureSpec, PlotSpec
+from lets_plot.plot.series_meta import _infer_type, TYPE_UNKNOWN, TYPE_DATE_TIME, _detect_time_zone
+
+
+def as_boolean(val, *, default):
+    if val is None:
+        return default
+
+    return bool(val) and val != 'False'
+
+
+def update_plot_aes_mapping(plot: PlotSpec, add_mapping: FeatureSpec):
+    existing_spec = plot.props().get('mapping', aes())
+    merged_mapping = {**existing_spec.as_dict(), **add_mapping.as_dict()}
+
+    # Re-annotate the data with the merged mapping.
+    data = plot.props().get('data', None)
+    data, processed_mapping, data_meta = as_annotated_data(data, aes(**merged_mapping))
+    plot.props()['data'] = data
+    plot.props()['mapping'] = processed_mapping
+
+    # Add data_meta to plot properties
+    for key, value in data_meta.items():
+        plot.props()[key] = value
+
+
+def as_annotated_data(data: Any, mapping_spec: FeatureSpec) -> Tuple:
+    data_type_by_var: Dict[str, str] = {}  # VarName to Type
+    mapping_meta_by_var: Dict[str, Dict[str, MappingMeta]] = {}  # VarName to Dict[Aes, MappingMeta]
+    mappings = {}  # Aes to VarName
+
+    # fill mapping_meta_by_var, mappings and data_type_by_var.
+    if mapping_spec is not None:
+        for key, spec in mapping_spec.props().items():
+            # the key is either an aesthetic name or 'name' (FeatureSpec.name property)
+            if key == 'name':  # ignore FeatureSpec.name property
+                continue
+
+            if isinstance(spec, MappingMeta):
+                mappings[key] = spec.variable
+                mapping_meta_by_var.setdefault(spec.variable, {})[key] = spec
+                data_type_by_var[spec.variable] = TYPE_UNKNOWN
+            else:
+                mappings[key] = spec  # spec is a variable name
+
+    data_type_by_var.update(_infer_type(data))
+
+    # Detect the tome zone - one for the entire data set.
+    time_zone_by_var_name = {}
+    for var_name, data_type in data_type_by_var.items():
+        if data_type == TYPE_DATE_TIME:
+            time_zone = _detect_time_zone(var_name, data)
+            if time_zone is not None:
+                time_zone_by_var_name[var_name] = time_zone
+
+    # fill series annotations
+    series_annotations = {}  # var to series_annotation
+    for var_name, data_type in data_type_by_var.items():
+        series_annotation = {}
+
+        if data_type != TYPE_UNKNOWN:
+            series_annotation['type'] = data_type
+
+        if var_name in time_zone_by_var_name:
+            series_annotation['time_zone'] = time_zone_by_var_name[var_name]
+
+        if is_pandas_data_frame(data) and data[var_name].dtype.name == 'category' and data[var_name].dtype.ordered:
+            series_annotation['factor_levels'] = data[var_name].cat.categories.to_list()
+
+        elif is_polars_dataframe(data):
+            import polars
+
+            col_dtype = data[var_name].dtype
+            if isinstance(col_dtype, polars.datatypes.Enum):
+                series_annotation['factor_levels'] = list(col_dtype.categories)
+            elif isinstance(col_dtype, polars.datatypes.Categorical):
+                # # It does not seem possible to get categories in correct order from the Categorical dtype.
+                # categories_series = data[var_name].cat.get_categories()
+                # indises = [col_dtype.categories[cat] for cat in categories_series]
+                # cats = [col_dtype.categories[i] for i in indises]
+                # series_annotation['factor_levels'] = categories_series.to_list()
+                pass
+
+        elif var_name in mapping_meta_by_var:
+            levels = last_not_none(list(map(lambda mm: mm.levels, mapping_meta_by_var[var_name].values())))
+            if levels is not None:
+                series_annotation['factor_levels'] = levels
+
+        if 'factor_levels' in series_annotation and var_name in mapping_meta_by_var:
+            order = last_not_none(list(map(lambda mm: mm.parameters['order'], mapping_meta_by_var[var_name].values())))
+            if order is not None:
+                series_annotation['order'] = order
+
+        if len(series_annotation) > 0:
+            series_annotation['column'] = var_name
+            series_annotations[var_name] = series_annotation
+
+    # fill mapping annotations
+    mapping_annotations = []
+    for var_name, meta_data in mapping_meta_by_var.items():
+        for aesthetic, mapping_meta in meta_data.items():
+            if mapping_meta.annotation == 'as_discrete':
+                if 'factor_levels' in series_annotations.get(var_name, {}):
+                    #  there is a bug - if label is set then levels are not applied
+                    continue
+
+                mapping_annotation = {}
+
+                # Note that the label is always set; otherwise, the scale title will appear as 'color.cyl'
+                label = mapping_meta.parameters.get('label')
+                if label is not None:
+                    mapping_annotation.setdefault('parameters', {})['label'] = label
+
+                if mapping_meta.levels is not None:
+                    mapping_annotation['levels'] = mapping_meta.levels
+
+                order_by = mapping_meta.parameters.get('order_by')
+                if order_by is not None:
+                    mapping_annotation.setdefault('parameters', {})['order_by'] = order_by
+
+                order = mapping_meta.parameters.get('order')
+                if order is not None:
+                    mapping_annotation.setdefault('parameters', {})['order'] = order
+
+                # add mapping meta if a custom label is set or if series annotation for var doesn't contain order options
+                # otherwise don't add mapping meta - it's redundant, nothing unique compared to series annotation
+                if len(mapping_annotation):
+                    mapping_annotation['aes'] = aesthetic
+                    mapping_annotation['annotation'] = 'as_discrete'
+                    mapping_annotations.append(mapping_annotation)
+
+    data_meta = {}
+
+    if len(series_annotations) > 0:
+        data_meta.update({'series_annotations': list(series_annotations.values())})
+
+    if len(mapping_annotations) > 0:
+        data_meta.update({'mapping_annotations': mapping_annotations})
+
+    return data, aes(**mappings), {'data_meta': data_meta}
+
+
+def is_data_pub_stream(data: Any) -> bool:
+    # try:
+    #     from lets_plot.display import DataPubStream
+    #     return isinstance(data, DataPubStream)
+    # except ImportError:
+    #     return False  # no pub-sub in standalone deployment
+    return False
+
+
+def normalize_map_join(map_join):
+    if map_join is None:
+        return None
+
+    def invalid_map_join_format():
+        return ValueError("map_join must be a str, list[str] or pair of list[str]")
+
+    if isinstance(map_join, str):  # 'foo' -> [['foo'], None]
+        data_names = [map_join]
+        map_names = None
+    elif isinstance(map_join, Sequence):
+        if all(isinstance(v, str) for v in map_join):  # all items are strings
+            if len(map_join) == 1:  # ['foo'] -> [['foo'], None]
+                data_names = map_join
+                map_names = None
+            elif len(map_join) == 2:  # ['foo', 'bar'] -> [['foo'], ['bar']]
+                data_names = [map_join[0]]
+                map_names = [map_join[1]]
+            elif len(map_join) > 2:  # ['foo', 'bar', 'baz'] -> error
+                raise ValueError(
+                    "map_join of type list[str] expected to have 1 or 2 items, but was {}".format(len(map_join)))
+            else:
+                raise invalid_map_join_format()
+        elif all(isinstance(v, Sequence) and not isinstance(v, str) for v in map_join):  # all items are lists
+            if len(map_join) == 1:  # [['foo', 'bar']] -> [['foo', 'bar'], None]
+                data_names = map_join[0]
+                map_names = None
+            elif len(map_join) == 2:  # [['foo', 'bar'], ['baz', 'qux']] -> [['foo', 'bar'], ['baz', 'qux']]
+                data_names = map_join[0]
+                map_names = map_join[1]
+            else:
+                raise invalid_map_join_format()
+        else:
+            raise invalid_map_join_format()
+
+    else:
+        raise invalid_map_join_format()
+
+    return [data_names, map_names]
+
+
+def auto_join_geo_names(map_join: Any, gdf):
+    if map_join is None:
+        return None
+
+    data_names = map_join[0]
+    map_names = map_join[1]
+
+    if map_names is None:
+        map_names = find_geo_names(gdf)
+        if len(map_names) == 0:
+            raise ValueError(
+                "Can't deduce joining keys.\n"
+                "Define both data and map key columns in map_join "
+                "explicitly: map_join=[['data_column'], ['map_column']]."
+            )
+
+        if len(data_names) > len(map_names):
+            raise ValueError(
+                "Data key columns count exceeds map key columns count: {} > {}".format(len(data_names), len(map_names))
+            )
+
+        map_names = map_names[:len(data_names)]  # use same number of key columns
+
+    return [data_names, map_names]
+
+
+def is_geo_data_frame(data: Any) -> bool:
+    try:
+        from geopandas import GeoDataFrame
+        return isinstance(data, GeoDataFrame)
+    except ImportError:
+        return False
+
+
+def get_geo_data_frame_meta(geo_data_frame) -> dict:
+    return {
+        'geodataframe': {
+            'geometry': geo_data_frame.geometry.name
+        }
+    }
+
+
+def geo_data_frame_to_crs(gdf: 'GeoDataFrame', use_crs: Optional[str]):
+    if gdf.crs is None:
+        return gdf
+
+    return gdf.to_crs('EPSG:4326' if use_crs is None else use_crs)
+
+
+def key_int2str(data):
+    if is_pandas_data_frame(data):
+        if data.columns.inferred_type == 'integer' or data.columns.inferred_type == 'mixed-integer':
+            data.columns = data.columns.astype(str)
+        return data
+
+    if isinstance(data, dict):
+        return {(str(k) if isinstance(k, int) else k): v for k, v in data.items()}
+
+    return data
+
+
+def last_not_none(lst: List) -> Optional[Any]:
+    for i in reversed(lst):
+        if i is not None:
+            return i
+    return None

lets_plot/settings_utils.py

@@ -0,0 +1,244 @@
+#  Copyright (c) 2020. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+from ._global_settings import GEOCODING_PROVIDER_URL, MAPTILES_SOLID_FILL_COLOR, TILES_CHESSBOARD, \
+    _DATALORE_TILES_SERVICE
+from ._global_settings import MAPTILES_KIND, MAPTILES_URL, MAPTILES_THEME, MAPTILES_ATTRIBUTION, MAPTILES_MIN_ZOOM, \
+    MAPTILES_MAX_ZOOM, TILES_VECTOR_LETS_PLOT, TILES_RASTER_ZXY, TILES_SOLID, _DATALORE_TILES_ATTRIBUTION
+from ._global_settings import has_global_value, get_global_val, _DATALORE_TILES_MIN_ZOOM, _DATALORE_TILES_MAX_ZOOM
+
+__all__ = ['maptiles_zxy', 'maptiles_lets_plot', 'maptiles_solid']
+
+
+def maptiles_lets_plot(url: str = None, theme: str = None) -> dict:
+    """
+    Make vector tiles config. Can be used individually in `geom_livemap() <https://lets-plot.org/python/pages/api/lets_plot.geom_livemap.html>`__
+    or in every livemap via `LetsPlot.set() <https://lets-plot.org/python/pages/api/lets_plot.LetsPlot.html#lets_plot.LetsPlot.set>`__.
+
+    Parameters
+    ----------
+    url : str
+        Address of the tile server. Can be omitted if URL is already set in global settings.
+
+    theme : {'color', 'light', 'dark', 'bw'}
+        Tiles theme.
+
+    Returns
+    -------
+    dict
+        Tile provider settings.
+
+    Notes
+    -----
+    If you are using Safari and having trouble loading tiles, try disabling the NSURLSession Websocket feature.
+    Go to `Develop -> Experimental Features -> NSURLSession Websocket` to turn it off.
+
+    Also, you could use raster tiles from ``lets_plot.tilesets``, e.g.
+    ``ggplot() + geom_livemap(tiles=tilesets.OPEN_TOPO_MAP)``.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 3
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        tiles = maptiles_lets_plot(url='wss://tiles.datalore.jetbrains.com', theme='light')
+        ggplot() + geom_livemap(tiles=tiles)
+
+    """
+    assert isinstance(url, (str, type(None))), "'url' argument is not str: {}".format(type(url))
+    assert isinstance(theme, (str, type(None))), "'theme' argument is not str: {}".format(type(theme))
+
+    if url is None:
+        global_maptiles_kind = get_global_val(MAPTILES_KIND) if has_global_value(MAPTILES_KIND) else None
+        global_maptiles_url = get_global_val(MAPTILES_URL) if has_global_value(MAPTILES_URL) else None
+
+        # try to read url from global settings
+        if global_maptiles_kind == TILES_VECTOR_LETS_PLOT:
+            if global_maptiles_url is None:
+                # global URL is somehow broken - use default URL
+                url = _DATALORE_TILES_SERVICE
+            else:
+                url = global_maptiles_url
+        else:
+            # User input:
+            # LetsPlot.set(maptiles_zxy(...))
+            # LetsPlot.set(maptiles_lets_plot(...))
+            # In this case global_maptiles_url will contain not-applicable raster tile URL.
+            # Use hardcoded lets_plot tiles URL.
+            url = _DATALORE_TILES_SERVICE
+
+    if url is None:
+        raise ValueError('lets_plot tiles service URL is not defined')
+
+    return {
+        MAPTILES_KIND: TILES_VECTOR_LETS_PLOT,
+        MAPTILES_URL: url,
+        MAPTILES_THEME: theme,
+        MAPTILES_ATTRIBUTION: _DATALORE_TILES_ATTRIBUTION,
+        MAPTILES_MIN_ZOOM: _DATALORE_TILES_MIN_ZOOM,
+        MAPTILES_MAX_ZOOM: _DATALORE_TILES_MAX_ZOOM,
+    }
+
+
+def maptiles_zxy(url: str, attribution: str = None, min_zoom: int = None, max_zoom: int = None, subdomains: str = None,
+                 **other_args) -> dict:
+    """
+    Make raster tiles config. Can be used individually in `geom_livemap() <https://lets-plot.org/python/pages/api/lets_plot.geom_livemap.html>`__
+    or in every livemap via `LetsPlot.set() <https://lets-plot.org/python/pages/api/lets_plot.LetsPlot.html#lets_plot.LetsPlot.set>`__.
+
+    Parameters
+    ----------
+    url : str
+        Template for a standard raster ZXY tile provider with {z}, {x}, {y} and {s} placeholders,
+        e.g. ``"https://{s}.tile.com/{z}/{x}/{y}.png"``. Where {z} means zoom, {x} and {y} means
+        tile coordinate, {s} means subdomains.
+    attribution : str
+        An attribution or a copyright notice to display on the map as required by the tile license.
+        Supports HTML links: ``'<a href="http://www.example.com">Example</a>'``.
+    min_zoom : int
+        Minimal zoom limit, an integer from 1 to 15. Should be less than or equal to ``max_zoom``.
+    max_zoom : int
+        Maximal zoom limit, an integer from 1 to 15. Should be greater than or equal to ``min_zoom``.
+    subdomains : str
+        Each character of this list is interpreted as standalone tile servers, so an interactive map
+        can request tiles from any of these servers independently for better load balance. If url
+        contains {s} placeholder and subdomains parameter is not set default string 'abc' will be used.
+    other_args
+        Any key-value pairs that can be substituted into the URL template, e.g.
+        ``maptiles_zxy(url='http://maps.example.com/{z}/{x}/{y}.png?access_key={key}', key='MY_ACCESS_KEY')``.
+
+    Returns
+    -------
+    dict
+        Tile provider settings.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 3-7
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        tiles = maptiles_zxy(
+            url="https://gibs.earthdata.nasa.gov/wmts/epsg3857/best/VIIRS_CityLights_2012/default/GoogleMapsCompatible_Level8/{z}/{y}/{x}.jpg",
+            attribution='<a href="https://earthdata.nasa.gov/eosdis/science-system-description/eosdis-components/gibs">© NASA Global Imagery Browse Services (GIBS)</a>',
+            max_zoom=8
+        )
+        ggplot() + geom_livemap(tiles=tiles)
+
+    """
+    assert isinstance(url, str), "'url' argument is not str: {}".format(type(url))
+    assert isinstance(attribution, (str, type(None))), "'attribution' argument is not str: {}".format(type(url))
+    if subdomains is not None and "{s}" not in url:
+        raise ValueError("Subdomains are set but {s} placeholder is not found in url: " + subdomains)
+
+    for k, v in other_args.items():
+        assert k not in ["x", "y", "z", "s"], "other_args can't contain keys x, y, z and s"
+        url = url.replace("{" + k + "}", v)
+
+    if subdomains is not None and "{s}" in url:
+        url = url.replace("{s}", '[' + subdomains + ']')
+    elif subdomains is None and "{s}" in url:
+        url = url.replace("{s}", '[abc]')
+
+    return {
+        MAPTILES_KIND: TILES_RASTER_ZXY,
+        MAPTILES_URL: url,
+        MAPTILES_ATTRIBUTION: _build_attribution(attribution),
+        MAPTILES_MIN_ZOOM: min_zoom,
+        MAPTILES_MAX_ZOOM: max_zoom
+    }
+
+
+def maptiles_solid(color: str):
+    """
+    Make solid color tiles config. Can be used individually in `geom_livemap() <https://lets-plot.org/python/pages/api/lets_plot.geom_livemap.html>`__
+    or in every livemap via `LetsPlot.set() <https://lets-plot.org/python/pages/api/lets_plot.LetsPlot.html#lets_plot.LetsPlot.set>`__.
+
+    Parameters
+    ----------
+    color : str
+        Color in HEX format.
+
+    Returns
+    -------
+    dict
+        Tile provider settings.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        nyc = geocode_cities('New York').get_boundaries()
+        tiles = maptiles_solid(color='#d3d3d3')
+        ggplot() + geom_livemap(tiles=tiles) + geom_map(data=nyc)
+
+    """
+    return {
+        MAPTILES_KIND: TILES_SOLID,
+        MAPTILES_SOLID_FILL_COLOR: color
+    }
+
+
+def maptiles_chessboard():
+    """
+    Make solid color tiles with chessboard pattern. Can be used individually in `geom_livemap() <https://lets-plot.org/python/pages/api/lets_plot.geom_livemap.html>`__
+    or in every livemap via `LetsPlot.set() <https://lets-plot.org/python/pages/api/lets_plot.LetsPlot.html#lets_plot.LetsPlot.set>`__.
+
+    Returns
+    -------
+    dict
+        Tile provider settings.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 3
+
+        from lets_plot.settings_utils import maptiles_chessboard
+        LetsPlot.setup_html()
+        ggplot() + geom_livemap(tiles=maptiles_chessboard())
+
+    """
+    return {
+        MAPTILES_KIND: TILES_CHESSBOARD
+    }
+
+
+def geocoding_service(url: str):
+    """
+    Make geocoding service config.
+    Can be applied via LetsPlot.set(...)
+
+    Parameters
+    ----------
+    url : string
+        Address of the geocoding server
+
+    Returns
+    -------
+        Geocoding service settings
+    """
+    assert isinstance(url, str), "'url' argument is not str: {}".format(type(url))
+
+    return {
+        GEOCODING_PROVIDER_URL: url
+    }
+
+
+def _build_attribution(other_attributions):
+    map_attribution = '<a href="https://lets-plot.org">\u00a9 Lets-Plot</a>'
+    if other_attributions is None:
+        return map_attribution
+    else:
+        return map_attribution + ', ' + other_attributions