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

lets_plot/geo_data/gis/response.py

@@ -0,0 +1,247 @@
+import enum
+from typing import List, Optional, Dict, Union
+
+from .geometry import GeometryBase, GeoPoint, GeoRect, Polygon, Multipolygon
+from .request import LevelKind
+from ..type_assertion import assert_list_type, assert_optional_type, assert_type, assert_optional_list_type
+
+
+class Status(enum.Enum):
+    success = 'success'
+    ambiguous = 'ambiguous'
+    error = 'error'
+
+
+class NamesakeParent:
+    def __init__(self, name: str, level: LevelKind):
+        assert_type(name, str)
+        assert_type(level, LevelKind)
+
+        self.name: str = name
+        self.level: LevelKind = level
+
+
+class Namesake:
+    def __init__(self, name: str, parents: List[NamesakeParent]):
+        assert_type(name, str)
+        assert_list_type(parents, NamesakeParent)
+
+        self.name: str = name
+        self.parents: List[NamesakeParent] = parents
+
+
+class Boundary(GeometryBase):
+    def __init__(self, geometry: Union[Multipolygon, Polygon, GeoPoint]):
+        self.geometry: Union[Multipolygon, Polygon, GeoPoint] = geometry
+
+
+class GeocodedFeature:
+    def __init__(self,
+                 id: str, name: str,
+                 highlights: Optional[List[str]] = None,
+                 boundary: Optional[Boundary] = None,
+                 centroid: Optional[GeoPoint] = None,
+                 limit: Optional[GeoRect] = None,
+                 position: Optional[GeoRect] = None):
+        assert_type(id, str)
+        assert_type(name, str)
+        assert_optional_list_type(highlights, str)
+        assert_optional_type(boundary, Boundary)
+        assert_optional_type(centroid, GeoPoint)
+        assert_optional_type(limit, GeoRect)
+        assert_optional_type(position, GeoRect)
+
+        self.id: str = id
+        self.name: str = name
+        self.highlights: Optional[List[str]] = highlights
+        self.boundary: Optional[Boundary] = boundary
+        self.centroid: Optional[GeoPoint] = centroid
+        self.limit: Optional[GeoRect] = limit
+        self.position: Optional[GeoRect] = position
+
+
+class AmbiguousFeature:
+    def __init__(self, query: str, total_namesake_count: int, namesake_examples: List[Namesake]):
+        assert_type(query, str)
+        assert_type(total_namesake_count, int)
+        assert_list_type(namesake_examples, Namesake)
+
+        self.query: str = query
+        self.total_namesake_count: int = total_namesake_count
+        self.namesake_examples: List[Namesake] = namesake_examples
+
+
+class Response:
+    def __init__(self, message: str):
+        assert_type(message, str)
+        self.message: str = message
+
+
+class Answer:
+    def __init__(self, features: List[GeocodedFeature]):
+        assert_list_type(features, GeocodedFeature)
+        self.features: List[GeocodedFeature] = features
+
+
+class SuccessResponse(Response):
+    def __init__(self, message: str, level: LevelKind, answers: List[Answer]):
+        super().__init__(message)
+
+        assert_type(message, str)
+        assert_optional_type(level, LevelKind)
+        assert_list_type(answers, Answer)
+
+        self.level: LevelKind = level
+        self.answers: List[Answer] = answers
+
+        features = []
+        for answer in answers:
+            features.extend(answer.features)
+
+        self.features: List[GeocodedFeature] = features
+
+
+class AmbiguousResponse(Response):
+    def __init__(self, message: str, level: LevelKind, features: List[AmbiguousFeature]):
+        super().__init__(message)
+
+        assert_type(message, str)
+        assert_optional_type(level, LevelKind)
+        assert_list_type(features, AmbiguousFeature)
+
+        self.level: LevelKind = level
+        self.features: List[AmbiguousFeature] = features
+
+
+class ErrorResponse(Response):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class FeatureBuilder:
+    def __init__(self):
+        self.query: Optional[str] = None
+        self.id: Optional[str] = None
+        self.name: Optional[str] = None
+        self.highlights: Optional[List[str]] = None
+        self.boundary: Optional[Boundary] = None
+        self.centroid: Optional[GeoPoint] = None
+        self.limit: Optional[GeoRect] = None
+        self.position: Optional[GeoRect] = None
+        self.total_namesake_count: Optional[int] = None
+        self.namesake_examples: List[Namesake] = []
+
+    def set_query(self, v: Optional[str]) -> 'FeatureBuilder':
+        assert_optional_type(v, str)
+        self.query = v
+        return self
+
+    def set_id(self, v: str) -> 'FeatureBuilder':
+        assert_type(v, str)
+        self.id = v
+        return self
+
+    def set_name(self, v: str) -> 'FeatureBuilder':
+        assert_type(v, str)
+        self.name = v
+        return self
+
+    def set_highlights(self, v: List[str]) -> 'FeatureBuilder':
+        assert_list_type(v, str)
+        self.highlights = v
+        return self
+
+    def set_boundary(self, v: Union[Multipolygon, Polygon, GeoPoint]) -> 'FeatureBuilder':
+        assert_type(v, (Multipolygon, Polygon, GeoPoint))
+        self.boundary = Boundary(v)
+        return self
+
+    def set_centroid(self, v: GeoPoint) -> 'FeatureBuilder':
+        assert_type(v, GeoPoint)
+        self.centroid = v
+        return self
+
+    def set_limit(self, v: GeoRect) -> 'FeatureBuilder':
+        assert_type(v, GeoRect)
+        self.limit = v
+        return self
+
+    def set_position(self, v: GeoRect) -> 'FeatureBuilder':
+        assert_type(v, GeoRect)
+        self.position = v
+        return self
+
+    def set_total_namesake_count(self, v: int) -> 'FeatureBuilder':
+        assert_type(v, int)
+        self.total_namesake_count = v
+        return self
+
+    def set_namesake_examples(self, v: List[Namesake]) -> 'FeatureBuilder':
+        assert_list_type(v, Namesake)
+        self.namesake_examples = v
+        return self
+
+    def add_namesake(self, namesake: Namesake) -> 'FeatureBuilder':
+        assert_type(namesake, Namesake)
+        self.namesake_examples.append(namesake)
+        return self
+
+    def build_ambiguous(self) -> AmbiguousFeature:
+        return AmbiguousFeature(self.query, self.total_namesake_count, self.namesake_examples)
+
+    def build_geocoded(self) -> GeocodedFeature:
+        return GeocodedFeature(self.id, self.name, self.highlights, self.boundary, self.centroid, self.limit,
+                               self.position)
+
+
+class ResponseBuilder:
+    def __init__(self):
+        self.status: Status = None
+        self.level: LevelKind = None
+        self.message: str = None
+        self.answers: List[Answer] = None
+        self.ambiguous_features: List[AmbiguousFeature] = None
+        self.data: Dict = None
+
+    def set_status(self, v: Status) -> 'ResponseBuilder':
+        assert_type(v, Status)
+        self.status = v
+        return self
+
+    def set_level(self, v: LevelKind) -> 'ResponseBuilder':
+        assert_type(v, LevelKind)
+        self.level = v
+        return self
+
+    def set_message(self, v: str) -> 'ResponseBuilder':
+        assert_type(v, str)
+        self.message = v
+        return self
+
+    def set_ambiguous_features(self, v: List[AmbiguousFeature]) -> 'ResponseBuilder':
+        assert_list_type(v, AmbiguousFeature)
+        self.ambiguous_features = v
+        return self
+
+    def set_answers(self, v: List[Answer]) -> 'ResponseBuilder':
+        assert_list_type(v, Answer)
+        self.answers = v
+        return self
+
+    def set_geocoded_features(self, v: List[GeocodedFeature]):
+        '''
+        Exactly matching non-exploding features, i.e. one feature per answer
+        '''
+        assert_list_type(v, GeocodedFeature)
+        self.answers = [Answer([f]) for f in v]
+        return self
+
+    def build(self) -> Response:
+        if self.status == Status.error:
+            return ErrorResponse(self.message)
+        elif self.status == Status.success:
+            return SuccessResponse(self.message, self.level, self.answers)
+        elif self.status == Status.ambiguous:
+            return AmbiguousResponse(self.message, self.level, self.ambiguous_features)
+        else:
+            raise ValueError('Unknown status: ' + str(self.status))

lets_plot/geo_data/livemap_helper.py

@@ -0,0 +1,65 @@
+from enum import Enum
+from typing import Union, Optional, List
+
+from pandas import DataFrame
+
+from .geocodes import Geocodes
+
+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))
+
+
+class RegionKind(Enum):
+    region_ids = 'region_ids'
+    region_name = 'region_name'
+    coordinates = 'coordinates'
+    data_frame = 'data_frame'
+
+
+def _prepare_parent(parent: Union[str, Geocodes]) -> Optional[dict]:
+    if not parent:
+        return None
+
+    if isinstance(parent, Geocodes):
+        kind = RegionKind.region_ids
+        value = parent.unique_ids()
+
+    elif isinstance(parent, str):
+        kind = RegionKind.region_name
+        value = parent
+
+    else:
+        raise ValueError('Wrong parent type: ' + parent.__str__())
+
+    return {'type': kind.value, 'data': value}
+
+
+def _prepare_location(location: Union[str, Geocodes, List[float], DataFrame]) -> Optional[dict]:
+    if location is None:
+        return None
+
+    value = location
+    if isinstance(location, Geocodes):
+        kind = RegionKind.region_ids
+        value = location.unique_ids()
+
+    elif 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 isinstance(location, 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/geo_data/to_geo_data_frame.py

@@ -0,0 +1,141 @@
+from typing import List
+
+import shapely
+from geopandas import GeoDataFrame
+from pandas import DataFrame
+from shapely.geometry import box
+
+from lets_plot.geo_data import PlacesDataFrameBuilder, abstractmethod
+from lets_plot.geo_data.geocodes import _zip_answers
+from lets_plot.geo_data.gis.request import RegionQuery, LevelKind
+from lets_plot.geo_data.gis.response import Answer, GeocodedFeature, GeoRect, Boundary, Multipolygon, Polygon, GeoPoint
+
+ShapelyPoint = shapely.geometry.Point
+ShapelyLinearRing = shapely.geometry.LinearRing
+ShapelyPolygon = shapely.geometry.Polygon
+ShapelyMultiPolygon = shapely.geometry.MultiPolygon
+
+
+def _create_geo_data_frame(data, geometry) -> DataFrame:
+    return GeoDataFrame(
+        data,
+        crs='EPSG:4326',
+        geometry=geometry
+    )
+
+
+class RectGeoDataFrame:
+    def __init__(self):
+        super().__init__()
+        self._lonmin: List[float] = []
+        self._latmin: List[float] = []
+        self._lonmax: List[float] = []
+        self._latmax: List[float] = []
+
+    def to_data_frame(self, answers: List[Answer], queries: List[RegionQuery], level_kind: LevelKind) -> DataFrame:
+        assert len(answers) == len(queries)
+        places = PlacesDataFrameBuilder(level_kind)
+
+        for query, answer in _zip_answers(queries, answers):
+            for feature in answer.features:
+                rects: List[GeoRect] = self._read_rect(feature)
+                for rect in rects:
+                    places.append_row(query, feature)
+                    self._lonmin.append(rect.start_lon)
+                    self._latmin.append(rect.min_lat)
+                    self._lonmax.append(rect.end_lon)
+                    self._latmax.append(rect.max_lat)
+
+        geometry = [
+            box(lmt[0], lmt[1], lmt[2], lmt[3]) for lmt in zip(self._lonmin, self._latmin, self._lonmax, self._latmax)
+        ]
+        return _create_geo_data_frame(places.build_dict(), geometry=geometry)
+
+    def _read_rect(self, feature: GeocodedFeature) -> List[GeoRect]:
+        rect: GeoRect = self._select_rect(feature)
+        if rect.crosses_antimeridian():
+            return [
+                GeoRect(start_lon=rect.start_lon, end_lon=180., min_lat=rect.min_lat, max_lat=rect.max_lat),
+                GeoRect(start_lon=-180., end_lon=rect.end_lon, min_lat=rect.min_lat, max_lat=rect.max_lat)
+            ]
+        else:
+            return [rect]
+
+    @abstractmethod
+    def _select_rect(self, feature: GeocodedFeature) -> GeoRect:
+        pass
+
+
+class CentroidsGeoDataFrame:
+    def __init__(self):
+        super().__init__()
+        self._lons: List[float] = []
+        self._lats: List[float] = []
+
+    def to_data_frame(self, answers: List[Answer], queries: List[RegionQuery], level_kind: LevelKind) -> DataFrame:
+        places = PlacesDataFrameBuilder(level_kind)
+
+        for query, answer in _zip_answers(queries, answers):
+            for feature in answer.features:
+                places.append_row(query, feature)
+                self._lons.append(feature.centroid.lon)
+                self._lats.append(feature.centroid.lat)
+
+        geometry = [ShapelyPoint(pnt[0], pnt[1]) for pnt in zip(self._lons, self._lats)]
+        return _create_geo_data_frame(places.build_dict(), geometry)
+
+
+class BoundariesGeoDataFrame:
+    def __init__(self):
+        super().__init__()
+
+    def to_data_frame(self, answers: List[Answer], queries: List[RegionQuery], level_kind: LevelKind) -> DataFrame:
+        places = PlacesDataFrameBuilder(level_kind)
+
+        geometry = []
+        for query, answer in _zip_answers(queries, answers):
+            for feature in answer.features:
+                places.append_row(query, feature)
+                geometry.append(self._geo_parse_geometry(feature.boundary))
+
+        return _create_geo_data_frame(places.build_dict(), geometry=geometry)
+
+    def _geo_parse_geometry(self, boundary: Boundary):
+        geometry = boundary.geometry
+        if isinstance(geometry, GeoPoint):
+            return self._geo_parse_point(geometry)
+
+        if isinstance(geometry, Polygon):
+            return self._geo_parse_polygon(geometry)
+
+        if isinstance(geometry, Multipolygon):
+            return self._geo_parse_multipolygon(geometry)
+
+        raise ValueError('Invalid geometry type')
+
+    def _geo_parse_multipolygon(self, geometry: Multipolygon) -> ShapelyMultiPolygon:
+        geo_polygons: List[ShapelyPolygon] = [self._geo_parse_polygon(polygon) for polygon in geometry.polygons]
+        return ShapelyMultiPolygon(geo_polygons)
+
+    def _geo_parse_polygon(self, polygon: Polygon) -> ShapelyPolygon:
+        geo_rings: List[ShapelyLinearRing] = [
+            ShapelyLinearRing([(p.lon, p.lat) for p in ring.points]) for ring in polygon.rings
+        ]
+
+        if len(geo_rings) == 0:
+            return ShapelyPolygon()
+        else:
+            return ShapelyPolygon(shell=geo_rings[0], holes=geo_rings[1:])
+
+    def _geo_parse_point(self, geometry_data: GeoPoint) -> ShapelyPoint:
+        return ShapelyPoint((geometry_data.lon, geometry_data.lat))
+
+
+class LimitsGeoDataFrame(RectGeoDataFrame):
+    def _select_rect(self, feature: GeocodedFeature) -> GeoRect:
+        return feature.limit
+
+
+class PositionsGeoDataFrame(RectGeoDataFrame):
+    def _select_rect(self, feature: GeocodedFeature) -> GeoRect:
+        return feature.position

lets_plot/geo_data/type_assertion.py

@@ -0,0 +1,34 @@
+def assert_type(obj, *types):
+    assert isinstance(obj, types), 'Invalid type: \nActual: ' + str(type(obj)) + ' (' + str(obj) + ')\nExpected: ' + str(types)
+
+
+def assert_optional_type(obj, *types):
+    if obj is None:
+        return
+    assert_type(obj, *types)
+
+
+def assert_list_type(obj, *types):
+    assert_type(obj, list, tuple)
+    for v in obj:
+        assert_type(v, *types)
+
+
+def assert_optional_list_type(obj, *types):
+    if obj is None:
+        return
+    assert_list_type(obj, *types)
+
+
+def assert_optional_tuple_type(obj, *types):
+    if obj is None:
+        return
+    assert_tuple_type(obj, *types)
+
+
+def assert_tuple_type(obj, *types):
+    assert_type(obj, tuple)
+    assert len(obj) == len(types)
+
+    for v, t in zip(obj, types):
+        assert_type(v, t)

lets_plot/geo_data_internals/__init__.py

@@ -0,0 +1,4 @@
+#  Copyright (c) 2021. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+#  This module is designed to be used from code as it won't cause the OSM attribution to appear

lets_plot/geo_data_internals/constants.py

@@ -0,0 +1,13 @@
+#  Copyright (c) 2021. JetBrains s.r.o.
+#  Use of this source code is governed by the MIT license that can be found in the LICENSE file.
+
+DF_COLUMN_ID = 'id'
+DF_COLUMN_POSITION = 'position'
+DF_COLUMN_LIMIT = 'limit'
+DF_COLUMN_CENTROID = 'centroid'
+DF_COLUMN_FOUND_NAME = 'found name'
+DF_COLUMN_HIGHLIGHTS = 'highlights'
+DF_COLUMN_CITY = 'city'
+DF_COLUMN_COUNTRY = 'country'
+DF_COLUMN_STATE = 'state'
+DF_COLUMN_COUNTY = 'county'

lets_plot/geo_data_internals/utils.py

@@ -0,0 +1,33 @@
+#  Copyright (c) 2021. 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 List, Any
+
+from lets_plot.geo_data_internals.constants import DF_COLUMN_CITY, DF_COLUMN_COUNTY, DF_COLUMN_STATE, DF_COLUMN_COUNTRY
+
+
+def find_geo_names(obj) -> List[str]:
+    if is_geocoder(obj):
+        data = obj.get_geocodes()
+    else:
+        data = obj
+
+    names = []
+    if DF_COLUMN_CITY in data:
+        names.append(DF_COLUMN_CITY)
+    if DF_COLUMN_COUNTY in data:
+        names.append(DF_COLUMN_COUNTY)
+    if DF_COLUMN_STATE in data:
+        names.append(DF_COLUMN_STATE)
+    if DF_COLUMN_COUNTRY in data:
+        names.append(DF_COLUMN_COUNTRY)
+
+    return names
+
+
+def is_geocoder(v: Any) -> bool:
+    # do not import Geocoder directly to suppress OSM attribution from geo_data package
+    if v is None:
+        return False
+
+    return any(base.__name__ == 'Geocoder' for base in type(v).mro())
+

lets_plot/mapping.py

@@ -0,0 +1,115 @@
+#  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.
+
+__all__ = ['as_discrete']
+
+
+class MappingMeta:
+    def __init__(self, variable, annotation, levels, **parameters):
+        if variable is None:
+            raise ValueError("variable can't be none")
+
+        if annotation is None:
+            raise ValueError("annotation can't be none")
+
+        self.variable = variable
+        self.annotation = annotation
+        self.levels = levels
+        self.parameters = parameters
+
+
+def as_discrete(variable, label=None, order_by=None, order=None, levels=None):
+    """
+    The function converts a column to a discrete scale and allows you to specify the order of its values.
+
+    Parameters
+    ----------
+    variable : str
+        The name of the variable.
+    label : str
+        The name of the scale - used as the axis label or the legend title.
+    order_by : str
+        The variable name to order by.
+    order : int
+        The ordering direction. 1 for ascending, -1 for descending.
+    levels : list
+        The list of values that defines a specific order of categories.
+
+    Returns
+    -------
+    ``MappingMeta`` or list
+        Variable meta information.
+
+    Notes
+    -----
+    The plot will use a discrete scale for the aesthetic mapping.
+    It is similar to the ``factor()`` function from R but works differently - there is no data transformation.
+
+    To enable ordering mode, at least one ordering parameter (``order_by`` or ``order``) should be specified.
+    By the default, it will use descending direction and ordering by eigenvalues.
+    You cannot specify different order settings for the same variable.
+    But if these settings don't contradict each other, they will be combined.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(size=n),
+            'y': np.random.normal(size=n),
+            'c': np.random.randint(5, size=n),
+        }
+        ggplot(data, aes('x', 'y')) + \\
+            geom_point(aes(color=as_discrete('c')))
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 11
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.uniform(size=100),
+            'c': np.random.choice(list('abcde'), size=100),
+        }
+        ggplot(data) + \\
+            geom_boxplot(aes(as_discrete('c', label='class', order=1), 'x'))
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 12-13
+
+        import numpy as np
+        from lets_plot import *
+        LetsPlot.setup_html()
+        n = 100
+        np.random.seed(42)
+        data = {
+            'x': np.random.normal(size=n),
+            'c': np.random.choice(list('abcde'), size=n),
+            'i': np.random.randint(3, size=n),
+        }
+        ggplot(data) + \\
+            geom_bar(aes(as_discrete('c', order=1, order_by='..count..'), 'x', \\
+                         fill=as_discrete('i', order=1, order_by='..count..')))
+
+    """
+    if isinstance(variable, str):
+        label = variable if label is None else label
+        return MappingMeta(variable, 'as_discrete', levels=levels, label=label, order_by=order_by, order=order)
+    # aes(x=as_discrete([1, 2, 3])) - pass as is
+    return variable