lets-plot 4.7.0rc1__cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

lets_plot/plot/geom_livemap_.py

@@ -0,0 +1,310 @@
+#
+# 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 enum import Enum
+from typing import Union, Optional, List
+
+from lets_plot._global_settings import MAPTILES_KIND, MAPTILES_URL, MAPTILES_THEME, MAPTILES_ATTRIBUTION, \
+    GEOCODING_PROVIDER_URL, GEOCODING_ROUTE, \
+    TILES_RASTER_ZXY, TILES_VECTOR_LETS_PLOT, MAPTILES_MIN_ZOOM, MAPTILES_MAX_ZOOM, TILES_SOLID, \
+    MAPTILES_SOLID_FILL_COLOR, TILES_CHESSBOARD
+from lets_plot._global_settings import has_global_value, get_global_val
+from .geom import _geom
+
+try:
+    import pandas
+except ImportError:
+    pandas = None
+
+# from ..geo_data.livemap_helper import _prepare_location
+# from ..geo_data.livemap_helper import _prepare_parent
+# from ..geo_data.livemap_helper import _prepare_tiles
+
+__all__ = ['geom_livemap']
+
+
+def geom_livemap(*,
+                 location=None,
+                 zoom=None,
+                 projection=None,
+                 tiles=None,
+                 show_coord_pick_tools=None,
+                 data_size_zoomin=None,
+                 const_size_zoomin=None,
+                 **other_args):
+    """
+    Display an interactive map.
+
+    Parameters
+    ----------
+    location : list
+        Initial position of the map. If not set, display the United States.
+        There are [lon1, lat1, lon2, lat2,..., lonN, latN]:
+        lon1, lon2,..., lonN are longitudes in degrees (positive in the Eastern hemisphere);
+        lat1, lat2,..., latN are latitudes in degrees (positive in the Northern hemisphere).
+    zoom : int
+        Zoom of the map in the range 1 - 15.
+    projection : str, default='epsg3857'
+        The map projection. There are: 'epsg3857' for Mercator projection;
+        'epsg4326' for Equirectangular projection. `projection` only works
+        with vector map tiles (i.e. Lets-Plot map tiles).
+    tiles : str
+        Tile provider:
+
+        - pass a predefined constant from the `tilesets` module (Lets-Plot's vector tiles, e.g. `LETS_PLOT_COLOR`, or external raster tiles, e.g. `OPEN_TOPO_MAP`);
+        - pass a URL for a standard raster ZXY tile provider with {z}, {x} and {y} wildcards (e.g. 'http://my.tile.com/{z}/{x}/{y}.png') if the required tileset not present in the module;
+        - pass the result of a call to a `maptiles_zxy()` function if further customisation is required (e.g. attribution or zoom).
+
+        More information about tiles can be found here:
+        https://lets-plot.org/python/pages/basemap_tiles.html
+    show_coord_pick_tools : bool, default=False
+        Show buttons "copy location" and "draw geometry".
+    data_size_zoomin : int, default=0
+        Control how zooming-in of the map widget increases size of geometry objects (circles, lines etc.) on map
+        when the size is set by means of mapping between the data and the `size` aesthetic.
+        `0` - size never increases;
+        `-1` - size will be increasing without limits;
+        `n` - a number of zooming-in steps (counting from the initial state of the map widget)
+        when size of objects will be increasing. Farther zooming will no longer affect the size.
+    const_size_zoomin : int, default=-1
+        Control how zooming-in of the map widget increases size of geometry objects (circles, lines etc.) on map
+        when the size is not linked to a data (i.e. constant size).
+        `0` - size never increases;
+        `-1` - size will be increasing without limits;
+        `n` - a number of zooming-in steps (counting from the initial state of the map widget)
+        when size of objects will be increasing. Farther zooming will no longer affect the size.
+    other_args
+        Other arguments passed on to the layer.
+
+    Returns
+    -------
+    `LayerSpec`
+        Geom object specification.
+
+    Notes
+    -----
+    `geom_livemap()` draws a map, which can be dragged and zoomed.
+
+    ----
+
+    By default the livemap area has a non-zero inset. You can get rid of this with the theme: `theme(plot_inset=0)`.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 3
+
+        from lets_plot import *
+        LetsPlot.setup_html()
+        ggplot() + geom_livemap()
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10
+
+        from lets_plot import *
+        from lets_plot import tilesets
+        LetsPlot.setup_html()
+        data = {
+            'city': ['New York City', 'Prague'],
+            'lon': [-73.7997, 14.418540],
+            'lat': [40.6408, 50.073658],
+        }
+        ggplot(data, aes(x='lon', y='lat')) + \\
+            geom_livemap(projection='epsg4326', tiles=tilesets.LETS_PLOT_DARK) + \\
+            geom_path(color='white', geodesic=True) + \\
+            geom_point(color='white', tooltips=layer_tooltips().line('@city')) + \\
+            ggtitle("The shortest path between New York and Prague")
+
+    """
+    if 'symbol' in other_args:
+        print("WARN: The parameter 'symbol' is no longer supported. "
+              "Use separate geom_point() or geom_pie() geometry layers to display markers on the map.")
+        other_args.pop('symbol')
+
+    deprecated_params = set.intersection(
+        {'data', 'mapping', 'map', 'map_join', 'ontop', 'stat', 'position', 'show_legend', 'sampling', 'tooltips'},
+        other_args
+    )
+    if len(deprecated_params) > 0:
+        print(f"WARN: These parameters are not supported and will be ignored: {str(deprecated_params):s}. "
+              "Specify a separate geometry layer to display data on the livemap.")
+
+    for param in deprecated_params:
+        other_args.pop(param)
+
+    if location is not None:
+        location = _prepare_location(location)
+
+    tiles = _prepare_tiles(tiles)
+    geocoding = _prepare_geocoding()
+
+    return _geom('livemap',
+                 mapping=None,
+                 data=None,
+                 stat=None,
+                 position=None,
+                 show_legend=None,
+                 sampling=None,
+                 tooltips=None,
+                 map=None, map_join=None,
+                 location=location,
+                 zoom=zoom,
+                 projection=projection,
+                 tiles=tiles,
+                 geocoding=geocoding,
+                 show_coord_pick_tools=show_coord_pick_tools,
+                 data_size_zoomin=data_size_zoomin,
+                 const_size_zoomin=const_size_zoomin,
+                 **other_args
+                 )
+
+
+LOCATION_COORDINATE_COLUMNS = {'lon', 'lat'}
+LOCATION_RECTANGLE_COLUMNS = {'lonmin', 'latmin', 'lonmax', 'latmax'}
+LOCATION_LIST_ERROR_MESSAGE = "Expected: location = [double lon1, double lat1, ... , double lonN, double latN]"
+LOCATION_DATAFRAME_ERROR_MESSAGE = "Expected: location = DataFrame with [{}] or [{}] columns" \
+    .format(', '.join(LOCATION_COORDINATE_COLUMNS), ', '.join(LOCATION_RECTANGLE_COLUMNS))
+
+OPTIONS_MAPTILES_KIND = 'kind'
+OPTIONS_MAPTILES_URL = 'url'
+OPTIONS_MAPTILES_THEME = 'theme'
+OPTIONS_MAPTILES_ATTRIBUTION = 'attribution'
+OPTIONS_MAPTILES_MIN_ZOOM = 'min_zoom'
+OPTIONS_MAPTILES_MAX_ZOOM = 'max_zoom'
+OPTIONS_MAPTILES_FILL_COLOR = 'fill_color'
+OPTIONS_GEOCODING_PROVIDER_URL = 'url'
+
+
+class RegionKind(Enum):
+    region_ids = 'region_ids'
+    region_name = 'region_name'
+    coordinates = 'coordinates'
+    data_frame = 'data_frame'
+
+
+def _prepare_geocoding():
+    if has_global_value(GEOCODING_PROVIDER_URL):
+        return {
+            OPTIONS_GEOCODING_PROVIDER_URL: get_global_val(GEOCODING_PROVIDER_URL) + GEOCODING_ROUTE
+        }
+
+    return {}
+
+
+def _prepare_tiles(tiles: Optional[Union[str, dict]]) -> Optional[dict]:
+    if isinstance(tiles, str):
+        return {
+            OPTIONS_MAPTILES_KIND: TILES_RASTER_ZXY,
+            OPTIONS_MAPTILES_URL: tiles
+        }
+
+    if isinstance(tiles, dict):
+        if tiles.get(MAPTILES_KIND) == TILES_RASTER_ZXY:
+            _warn_deprecated_tiles(tiles)
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_RASTER_ZXY,
+                OPTIONS_MAPTILES_URL: tiles[MAPTILES_URL],
+                OPTIONS_MAPTILES_ATTRIBUTION: tiles[MAPTILES_ATTRIBUTION],
+                OPTIONS_MAPTILES_MIN_ZOOM: tiles[MAPTILES_MIN_ZOOM],
+                OPTIONS_MAPTILES_MAX_ZOOM: tiles[MAPTILES_MAX_ZOOM],
+            }
+        elif tiles.get(MAPTILES_KIND) == TILES_VECTOR_LETS_PLOT:
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_VECTOR_LETS_PLOT,
+                OPTIONS_MAPTILES_URL: tiles[MAPTILES_URL],
+                OPTIONS_MAPTILES_THEME: tiles[MAPTILES_THEME],
+                OPTIONS_MAPTILES_ATTRIBUTION: tiles[MAPTILES_ATTRIBUTION],
+            }
+        elif tiles.get(MAPTILES_KIND) == TILES_SOLID:
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_SOLID,
+                OPTIONS_MAPTILES_FILL_COLOR: tiles[MAPTILES_SOLID_FILL_COLOR]
+            }
+        elif tiles.get(MAPTILES_KIND) == TILES_CHESSBOARD:
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_CHESSBOARD
+            }
+        else:
+            raise ValueError("Unsupported 'tiles' kind: " + tiles.get(MAPTILES_KIND))
+
+    if tiles is not None:
+        raise ValueError("Unsupported 'tiles' parameter type: " + type(tiles))
+
+    # tiles are not set for this livemap - try to get global tiles config
+    if has_global_value(MAPTILES_KIND):
+        if not has_global_value(MAPTILES_URL):
+            raise ValueError('URL for tiles service is not set')
+
+        if get_global_val(MAPTILES_KIND) == TILES_RASTER_ZXY:
+            _warn_deprecated_tiles(None)
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_RASTER_ZXY,
+                OPTIONS_MAPTILES_URL: get_global_val(MAPTILES_URL),
+                OPTIONS_MAPTILES_ATTRIBUTION: get_global_val(MAPTILES_ATTRIBUTION) if has_global_value(
+                    MAPTILES_ATTRIBUTION) else None,
+                OPTIONS_MAPTILES_MIN_ZOOM: get_global_val(MAPTILES_MIN_ZOOM) if has_global_value(
+                    MAPTILES_MIN_ZOOM) else None,
+                OPTIONS_MAPTILES_MAX_ZOOM: get_global_val(MAPTILES_MAX_ZOOM) if has_global_value(
+                    MAPTILES_MAX_ZOOM) else None,
+            }
+
+        if get_global_val(MAPTILES_KIND) == TILES_VECTOR_LETS_PLOT:
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_VECTOR_LETS_PLOT,
+                OPTIONS_MAPTILES_URL: get_global_val(MAPTILES_URL),
+                OPTIONS_MAPTILES_THEME: get_global_val(MAPTILES_THEME) if has_global_value(MAPTILES_THEME) else None,
+                OPTIONS_MAPTILES_ATTRIBUTION: get_global_val(MAPTILES_ATTRIBUTION) if has_global_value(
+                    MAPTILES_ATTRIBUTION) else None,
+            }
+
+        if get_global_val(MAPTILES_KIND) == TILES_SOLID:
+            return {
+                OPTIONS_MAPTILES_KIND: TILES_SOLID,
+                OPTIONS_MAPTILES_FILL_COLOR: get_global_val(MAPTILES_SOLID_FILL_COLOR),
+            }
+
+    raise ValueError('Tile provider is not set.')
+
+
+def _warn_deprecated_tiles(tiles: Union[dict, None]):
+    if tiles is None:
+        maptiles_url = get_global_val(MAPTILES_URL)
+    else:
+        maptiles_url = tiles[MAPTILES_URL]
+
+    # Check if the current tiles should be deprecated and print a deprecation message. Otherwise, return.
+    return
+
+
+def _prepare_location(location: Union[str, List[float]]) -> Optional[dict]:
+    if location is None:
+        return None
+
+    value = location
+    # if isinstance(location, Geocoder):
+    #     kind = RegionKind.region_ids
+    #     value = location.unique_ids()
+
+    if isinstance(location, str):
+        kind = RegionKind.region_name
+
+    elif isinstance(location, list):
+        if len(location) == 0 or len(location) % 2 != 0:
+            raise ValueError(LOCATION_LIST_ERROR_MESSAGE)
+        kind = RegionKind.coordinates
+
+    elif pandas and isinstance(location, pandas.DataFrame):
+        if not LOCATION_COORDINATE_COLUMNS.issubset(location.columns) and not LOCATION_RECTANGLE_COLUMNS.issubset(
+                location.columns):
+            raise ValueError(LOCATION_DATAFRAME_ERROR_MESSAGE)
+        kind = RegionKind.data_frame
+
+    else:
+        raise ValueError('Wrong location type: ' + location.__str__())
+
+    return {'type': kind.value, 'data': value}

lets_plot/plot/ggbunch_.py

@@ -0,0 +1,96 @@
+#  Copyright (c) 2025. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+from numbers import Number
+from typing import List, Tuple
+
+from ._global_theme import _get_global_theme
+from .subplots import SupPlotsLayoutSpec
+from .subplots import SupPlotsSpec
+from .subplots_util import _strip_theme_if_global
+
+__all__ = ['ggbunch']
+
+
+def ggbunch(plots: List,
+            regions: List[Tuple[float, float, float, float, float, float]]
+            ) -> SupPlotsSpec:
+    """
+    Combine several plots into a single figure with custom layout.
+
+    Parameters
+    ----------
+    plots : List
+        A list where each element is one of:
+
+        - a plot specification
+        - a subplots specification
+        - None
+
+    regions : List[Tuple]
+        Layout parameters for each plot. Each region is specified as
+        (x, y, width, height, dx, dy) where:
+
+        - x, y: Position of the plot's top-left corner in relative coordinates ([0,0] is top-left corner, [1,1] is bottom-right corner of the container).
+        - width, height: Size of the plot relative to container dimensions (1 equal to the full container width/height).
+        - dx, dy: Pixel offsets to move the region (defaults to 0).
+
+    Returns
+    -------
+    `SupPlotsSpec`
+        A specification describing the combined figure with all plots and their layout.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 10-14
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        np.random.seed(42)
+        data = {'x': np.random.gamma(2.0, size=100)}
+        p1 = ggplot(data, aes(x='x')) + \\
+            geom_histogram(aes(color='x', fill='x'))
+        p2 = ggplot(data, aes(x='x')) + \\
+            geom_density() + theme_bw() + theme(axis='blank', panel_grid='blank')
+        ggbunch(
+            [p1, p2],
+            [(0, 0, 1, 1),
+             (0.5, 0.1, 0.3, 0.3)]
+        ) + ggsize(400, 300)
+
+    """
+
+    if not len(plots):
+        raise ValueError("Supplots list is empty.")
+
+    # Validate provided regions
+    for i, region in enumerate(regions):
+        if len(region) not in (4, 6):
+            raise ValueError(f"Region {i} must have 4 or 6 values, got {len(region)}")
+        if not all(isinstance(x, Number) for x in region):
+            raise ValueError(f"Region {i} contains non-numeric values: {region}")
+
+        # Validate size is positive
+        if any(x <= 0 for x in region[2:4]):
+            raise ValueError(f"Region {i} sizes must be positive: {region}")
+
+    # Convert regions tuples to lists
+    regions_list = [list(r) for r in regions]
+    layout = SupPlotsLayoutSpec(
+        name="free",
+        regions=regions_list
+    )
+
+    figures = [_strip_theme_if_global(fig) for fig in plots]
+
+    figure_spec = SupPlotsSpec(figures=figures, layout=layout)
+
+    # Apply global theme if defined
+    global_theme_options = _get_global_theme()
+    if global_theme_options is not None:
+        figure_spec += global_theme_options
+
+    return figure_spec

lets_plot/plot/gggrid_.py

@@ -0,0 +1,126 @@
+#
+# Copyright (c) 2023. 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_theme import _get_global_theme
+from .subplots import SupPlotsLayoutSpec
+from .subplots import SupPlotsSpec
+from .subplots_util import _strip_theme_if_global
+
+__all__ = ['gggrid']
+
+
+def gggrid(plots: list, ncol: int = None, *,
+           sharex: str = None,
+           sharey: str = None,
+           widths: list = None,
+           heights: list = None,
+           hspace: float = None,
+           vspace: float = None,
+           fit: bool = None,
+           align: bool = None
+           ) -> SupPlotsSpec:
+    """
+    Combine several plots on one figure, organized in a regular grid.
+
+    Parameters
+    ----------
+    plots : list
+        A list where each element is a plot specification, a subplots specification, or None.
+        Use value None to fill-in empty cells in grid.
+    ncol : int
+        Number of columns in grid.
+        If not specified, shows plots horizontally, in one row.
+    sharex, sharey : bool or str, default=False
+        Controls sharing of axis limits between subplots in the grid.
+
+        - 'all'/True - share limits between all subplots.
+        - 'none'/False - do not share limits between subplots.
+        - 'row' - share limits between subplots in the same row.
+        - 'col' - share limits between subplots in the same column.
+
+    widths : list of numbers
+        Relative width of each column of grid, left to right.
+    heights : list of numbers
+        Relative height of each row of grid, top-down.
+    hspace : float, default=4.0
+        Cell horizontal spacing in px.
+    vspace : float, default=4.0
+        Cell vertical spacing in px.
+    fit : bool, default=True
+        Whether to stretch each plot to match the aspect ratio of its cell (`fit=True`),
+        or to preserve the original aspect ratio of plots (`fit=False`).
+    align : bool, default=False
+        If True, align inner areas (i.e. "geom" bounds) of plots.
+        However, cells containing other (sub)grids are not participating in the plot "inner areas" layouting.
+
+    Returns
+    -------
+    `SupPlotsSpec`
+        The grid specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11, 14
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        np.random.seed(42)
+        n = 100
+        x = np.arange(n)
+        y = np.random.normal(size=n)
+        w, h = 200, 150
+        p = ggplot({'x': x, 'y': y}, aes(x='x', y='y')) + ggsize(w, h)
+        plot_list=[
+            gggrid([p+geom_point(), p+geom_histogram(bins=3)]),
+            p+geom_line()
+        ]
+        gggrid(plot_list, ncol=1) + ggsize(400, 300)
+
+    """
+
+    if not len(plots):
+        raise ValueError("Supplots list is empty.")
+
+    if ncol is None:
+        ncol = len(plots)
+        nrow = 1
+    else:
+        extended_list = plots + [None] * (ncol - 1)
+        nrow = len(extended_list) // ncol
+        length = ncol * nrow
+        plots = extended_list[0:length]
+
+    if sharex is not None and type(sharex) != str:
+        sharex = 'all' if sharex else 'none'
+    if sharey is not None and type(sharey) != str:
+        sharey = 'all' if sharey else 'none'
+
+    layout = SupPlotsLayoutSpec(
+        name="grid",
+        ncol=ncol,
+        nrow=nrow,
+        sharex=sharex,
+        sharey=sharey,
+        widths=widths,
+        heights=heights,
+        hspace=hspace,
+        vspace=vspace,
+        fit=fit,
+        align=align
+    )
+
+    figures = [_strip_theme_if_global(fig) for fig in plots]
+
+    figure_spec = SupPlotsSpec(figures=figures, layout=layout)
+
+    # Apply global theme if defined
+    global_theme_options = _get_global_theme()
+    if global_theme_options is not None:
+        figure_spec += global_theme_options
+
+    return figure_spec

lets_plot/plot/ggtb_.py

@@ -0,0 +1,55 @@
+#
+# Copyright (c) 2024. JetBrains s.r.o.
+# Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+#
+from .core import FeatureSpec
+
+__all__ = ['ggtb']
+
+
+def ggtb() -> FeatureSpec:
+    """
+    Add a toolbar to a chart.
+
+    This function adds a toolbar containing three tool-buttons (pan, rubber-band zoom,
+    and center-point zoom) to a chart. Each tool uses mouse-drag for its
+    specific functionality. Additionally, the mouse wheel can be used for zooming
+    in and out, regardless of the selected tool.
+
+    The toolbar includes:
+
+    - Pan: Drag to move the plot.
+    - Rubber-band zoom: Drag to define a rectangular area to zoom into.
+    - Center-point zoom: Drag up or down to zoom in or out from a center point.
+    - Reset button: Click to reset the plot and tools to their original state.
+
+    Double-clicking anywhere on the plot resets it to its original coordinates,
+    regardless of whether a tool is selected or not.
+
+    Limitations:
+
+    - The toolbar does not work with interactive maps.
+    - The toolbar cannot be used with plots using a polar coordinate system.
+
+    Returns
+    -------
+    `FeatureSpec`
+        Toolbar feature specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 8
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        x = np.linspace(-2 * np.pi, 2 * np.pi, 100)
+        y = np.sin(x)
+        ggplot({'x': x, 'y': y}, aes(x='x', y='y')) + \\
+            geom_point() + \\
+            ggtb()
+
+    """
+    return FeatureSpec(kind='ggtoolbar', name=None)