lets-plot 4.8.0rc1__cp313-cp313-macosx_12_0_arm64.whl

lets_plot/frontend_context/_static_html_page_ctx.py

@@ -0,0 +1,27 @@
+#
+# 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 Dict
+
+from ._frontend_ctx import FrontendContext
+from .. import _kbridge as kbr
+from .._version import __version__
+
+
+# noinspection PyPackageRequirements
+
+
+class StaticHtmlPageContext(FrontendContext):
+
+    def __init__(self, offline: bool) -> None:
+        super().__init__()
+        self.connected = not offline
+
+    def configure(self, verbose: bool):
+        # Nothing here because the entire html page is created per each cell output.
+        if not self.connected:
+            print("WARN: Embedding Lets-Plot JS library for offline usage is not supported.")
+
+    def as_str(self, plot_spec: Dict) -> str:
+        return kbr._generate_static_html_page(plot_spec, iframe=False)

lets_plot/frontend_context/_static_svg_ctx.py

@@ -0,0 +1,26 @@
+#
+# 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 typing import Dict
+
+from ._frontend_ctx import FrontendContext
+from .. import _kbridge as kbr
+from .._version import __version__
+
+
+class StaticSvgImageContext(FrontendContext):
+
+    def configure(self, verbose: bool):
+        if verbose:
+            message = '<div style="color:darkblue;">Lets-Plot v{}: static SVG output configured.</div>'.format(
+                __version__)
+            try:
+                from IPython.display import display_html
+                display_html(message, raw=True)
+            except ImportError:
+                pass
+                print(message)
+
+    def as_str(self, plot_spec: Dict) -> str:
+        return kbr._generate_svg(plot_spec)

lets_plot/frontend_context/_webbr_html_page_ctx.py

@@ -0,0 +1,29 @@
+#
+# 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.
+#
+import io
+import webbrowser
+import tempfile
+from typing import Dict
+
+from ._frontend_ctx import FrontendContext
+from .. import _kbridge as kbr
+
+
+class WebBrHtmlPageContext(FrontendContext):
+
+    def __init__(self, exec: str, new: bool) -> None:
+        super().__init__()
+        self.exec = exec
+        self.new = new
+
+    def show(self, plot_spec: Dict) -> str:
+        html_page = kbr._generate_static_html_page(plot_spec, iframe=False)
+
+        path = tempfile.NamedTemporaryFile(mode='w+t', suffix=".html", delete=False)
+        try:
+            io.open(path.name, 'w+t').write(html_page)
+            webbrowser.get(self.exec).open('file://' + path.name, new=1 if self.new else 2)
+        finally:
+            path.close()

lets_plot/frontend_context/sandbox.py

@@ -0,0 +1,5 @@
+#
+# 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.
+#
+

lets_plot/geo_data/__init__.py

@@ -0,0 +1,19 @@
+try:
+    import geopandas
+except ImportError:
+    print("geopandas is required for using the geo_data package")
+    raise
+
+from .core import *
+from .geocoder import *
+from .geocodes import *
+
+__all__ = core.__all__
+
+#  Use geo_data package only for executing geocoding requests.
+#  For accessing variuous checks, contants, types etc use package geo_data_internals
+#  as it won't cause the OSM attribution to appear.
+
+# print on the package import
+print("The geodata is provided by © OpenStreetMap contributors"
+      " and is made available here under the Open Database License (ODbL).")

lets_plot/geo_data/core.py

@@ -0,0 +1,335 @@
+from typing import Any
+
+import numpy as np
+
+from .geocoder import Geocoder, ReverseGeocoder, NamesGeocoder
+
+__all__ = [
+    'distance',
+
+    'geocode',
+    'geocode_cities',
+    'geocode_counties',
+    'geocode_states',
+    'geocode_countries',
+    'reverse_geocode'
+]
+
+UNITS_DICT = {
+    'mi': 3959,
+    'km': 6371
+}
+
+GEOFUNC_TYPES = {
+    'centroids': 'centroids',
+    'boundaries': 'boundaries',
+    'limits': 'limits',
+    'region': 'regions'
+}
+
+
+def geocode(level=None, names=None, countries=None, states=None, counties=None, scope=None) -> NamesGeocoder:
+    """
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    scope that limits area of geocoding or with parents.
+
+    Parameters
+    ----------
+    level : {'country', 'state', 'county', 'city'}
+        The level of administrative division. Autodetection by default.
+    names : list or str
+        Names of objects to be geocoded.
+        For 'state' level: 'US-48' returns continental part of United States (48 states)
+        in a compact form.
+    countries : list
+        Parent countries. Should have same size as names. Can contain strings or ``Geocoder`` objects.
+    states : list
+        Parent states. Should have same size as names. Can contain strings or ``Geocoder`` objects.
+    counties : list
+        Parent counties. Should have same size as names. Can contain strings or ``Geocoder`` objects.
+    scope : str or ``Geocoder``
+        Limits area of geocoding. If parent country is set then error will be generated.
+        If type is a string - geoobject should have geocoded scope in parents.
+        If type is a ``Geocoder`` - geoobject should have geocoded scope in parents.
+        Scope should contain only one entry.
+
+    Returns
+    -------
+    ``NamesGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        states = geocode('state').scope('Italy').get_boundaries(6)
+        display(states.head())
+        ggplot() + geom_map(data=states)
+
+    |
+
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5, 8
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        states = geocode(level='state', scope='US').get_geocodes()
+        display(states.head())
+        names = ['York'] * len(states.state)
+        cities = geocode(names=names, states=states.state).ignore_not_found().get_centroids()
+        display(cities.head())
+        ggplot() + \\
+            geom_livemap() + \\
+            geom_point(data=cities, tooltips=layer_tooltips().line('@{found name}'))
+
+    """
+    return NamesGeocoder(level, names) \
+        .scope(scope) \
+        .countries(countries) \
+        .states(states) \
+        .counties(counties)
+
+
+def geocode_cities(names=None) -> NamesGeocoder:
+    """
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for cities.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
+
+    Parameters
+    ----------
+    names : str or list
+        Names of objects to be geocoded.
+
+    Returns
+    -------
+    ``NamesGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        cities = geocode_cities(['York', 'Jersey'])\\
+                 .where(name='Jersey', scope='New Jersey').get_boundaries()
+        display(cities)
+        ggplot() + geom_map(aes(fill='found name'), data=cities, color='white')
+
+    """
+    return NamesGeocoder('city', names)
+
+
+def geocode_counties(names=None) -> NamesGeocoder:
+    """
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for counties.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
+
+    Parameters
+    ----------
+    names : str or list
+        Names of objects to be geocoded.
+
+    Returns
+    -------
+    ``NamesGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        counties = geocode_counties().scope('NY').get_boundaries(9)
+        display(counties.head())
+        ggplot() + geom_map(data=counties) + ggtitle('New York State Counties')
+
+    """
+    return NamesGeocoder('county', names)
+
+
+def geocode_states(names=None) -> NamesGeocoder:
+    """
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for states.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method,
+    with a scope that limits area of geocoding or with parents.
+
+    Parameters
+    ----------
+    names : str or list
+        Names of objects to be geocoded.
+
+    Returns
+    -------
+    ``NamesGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        states = geocode_states().scope('UK').get_boundaries()
+        display(states)
+        ggplot() + \\
+            geom_map(aes(fill='found name'), data=states, color='white') + \\
+            ggtitle('UK States')
+
+    """
+    return NamesGeocoder('state', names)
+
+
+def geocode_countries(names=None) -> NamesGeocoder:
+    """
+    Create a `NamesGeocoder <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html>`__ object for countries.
+    Allow to refine ambiguous request with `where() <https://lets-plot.org/python/pages/api/lets_plot.geo_data.NamesGeocoder.html#lets_plot.geo_data.NamesGeocoder.where>`__ method.
+
+    Parameters
+    ----------
+    names : str or list
+        Names of objects to be geocoded.
+
+    Returns
+    -------
+    ``NamesGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        countries = geocode_countries(['Germany', 'Poland']).inc_res().get_boundaries()
+        display(countries)
+        ggplot() + geom_map(aes(fill='found name'), data=countries, color='white')
+
+    """
+    return NamesGeocoder('country', names)
+
+
+def reverse_geocode(lon, lat, level=None, scope=None) -> ReverseGeocoder:
+    """
+    Convert a location as described by geographic coordinates to a ``ReverseGeocoder`` object.
+
+    Parameters
+    ----------
+    lon : float
+        Longitude coordinate of the geoobject.
+    lat : float
+        Latitude coordinate of the geoobject.
+    level : {'country', 'state', 'county', 'city'}
+        The level of administrative division.
+    scope : str or ``Geocoder``
+        Specify this for resolving conflicts for disputed territories.
+
+    Returns
+    -------
+    ``ReverseGeocoder``
+        Geocoder object specification.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 5
+
+        from IPython.display import display
+        from lets_plot import *
+        from lets_plot.geo_data import *
+        LetsPlot.setup_html()
+        city = reverse_geocode(-73.87, 40.68, level='city').get_boundaries()
+        display(city)
+        ggplot() + geom_map(data=city) + ggtitle(city.iloc[0]['found name'])
+
+    """
+    return ReverseGeocoder(lon, lat, level, scope)
+
+
+def distance(lon0, lat0, lon1, lat1, units='km'):
+    """
+    Calculate the distance between two points. Return result in kilometers or miles.
+
+    Parameters
+    ----------
+    lon0 : float
+        Longitude coordinate of the first point.
+    lat0 : float
+        Latitude coordinate of the first point.
+    lon1 : float
+        Longitude coordinate of the second point.
+    lat1 : float
+        Latitude coordinate of the second point.
+    units : {'mi', 'km'}, default='km'
+        The units in which the result will be obtained.
+        There are shorthands for values: 'mi' (miles), 'km' (kilometers).
+
+    Returns
+    -------
+    float
+        Distance between the points.
+
+    Examples
+    --------
+    .. jupyter-execute::
+        :linenos:
+        :emphasize-lines: 3
+
+        from lets_plot.geo_data import *
+        cities = geocode_cities(['New York', 'Chicago']).get_centroids().geometry
+        distance(cities[0].x, cities[0].y, cities[1].x, cities[1].y, units='mi')
+
+    """
+    return _calc_distance(lon0, lat0, lon1, lat1, units)
+
+
+def _calc_distance(lon0, lat0, lon1, lat1, u):
+    r = _prepare_units(u)
+
+    lon0, lat0, lon1, lat1 = map(np.radians, [lon0, lat0, lon1, lat1])
+
+    dlon = lon1 - lon0
+    dlat = lat1 - lat0
+
+    a = np.sin(dlat / 2.0) ** 2 + np.cos(lat0) * np.cos(lat1) * np.sin(dlon / 2.0) ** 2
+
+    c = 2 * np.arcsin(np.sqrt(a))
+    return c * r
+
+
+def _prepare_units(units: Any) -> float:
+    try:
+        return UNITS_DICT[units]
+    except KeyError:
+        raise ValueError('Wrong units: {}. The units can take the following values: '
+                         'mi (miles), km (kilometers).'.format(units))