hvplot 0.9.3a1__py3-none-any.whl

hvplot/__init__.py

@@ -0,0 +1,322 @@
+"""
+hvPlot makes data analysis and visualization simple
+===================================================
+
+hvPlot provides a familiar, high-level API for interactive data exploration and visualization,
+based on the Pandas `.plot` API and the innovative `.interactive` API.
+
+hvPlot
+
+- supports a wide range of data sources including Pandas, Dask, XArray
+Rapids cuDF, Streamz, Intake, Geopandas, NetworkX and Ibis.
+- supports the plotting backends Bokeh (default), Matplotlib and Plotly.
+- exposes the powerful tools from the HoloViz ecosystem in a familiar and convenient API, while
+letting you drop down into the underlying HoloViz tools when more power or flexibility is needed.
+
+hvPlot is the recommend entrypoint to the HoloViz ecosystem.
+
+To learn more check out https://hvplot.holoviz.org/. To report issues or contribute go to
+https://github.com/holoviz/hvplot. To join the community go to
+https://discourse.holoviz.org/.
+
+How to use hvPlot in 3 simple steps
+-----------------------------------
+
+Work with the data source you already know and ❤️
+
+>>> import pandas as pd, numpy as np
+>>> idx = pd.date_range('1/1/2000', periods=1000)
+>>> df  = pd.DataFrame(np.random.randn(1000, 4), index=idx, columns=list('ABCD')).cumsum()
+
+Import the hvplot extension for your data source and optionally set the plotting backend
+
+>>> import hvplot.pandas
+>>> # hvplot.extension('matplotlib')
+
+Use the `.hvplot` API as you would use the Pandas `.plot` API.
+
+>>> df.hvplot()
+
+In a Jupyter Notebook, this will display a line plot of the A, B, C and D time series.
+
+For more check out the user guide https://hvplot.holoviz.org/user_guide/index.html
+
+How to get help
+---------------
+
+To see the available arguments for a specific `kind` of plot run
+
+>>> import hvplot
+>>> hvplot.help(kind='scatter')
+
+In a notebook or ipython environment the usual
+
+- `help` and `?` will provide you with documentation.
+- `TAB` and `SHIFT+TAB` completion will help you navigate.
+
+To ask the community go to https://discourse.holoviz.org/.
+To report issues go to https://github.com/holoviz/holoviews.
+"""
+
+import inspect
+import os
+import textwrap
+
+import panel as _pn
+import holoviews as _hv
+
+from holoviews import Store, render  # noqa
+
+from .converter import HoloViewsConverter
+from .interactive import Interactive
+from .ui import explorer  # noqa
+from .utilities import hvplot_extension, output, save, show  # noqa
+from .plotting import (
+    hvPlot,
+    hvPlotTabular,  # noqa
+    andrews_curves,  # noqa
+    lag_plot,  # noqa
+    parallel_coordinates,  # noqa
+    scatter_matrix,  # noqa
+    plot,  # noqa
+)
+
+# Define '__version__'
+try:
+    # For performance reasons on imports, avoid importing setuptools_scm
+    # if not in a .git folder
+    if os.path.exists(os.path.join(os.path.dirname(__file__), '..', '.git')):
+        # If setuptools_scm is installed (e.g. in a development environment with
+        # an editable install), then use it to determine the version dynamically.
+        from setuptools_scm import get_version
+
+        # This will fail with LookupError if the package is not installed in
+        # editable mode or if Git is not installed.
+        __version__ = get_version(root='..', relative_to=__file__)
+    else:
+        raise FileNotFoundError
+except (ImportError, LookupError, FileNotFoundError):
+    # As a fallback, use the version that is hard-coded in the file.
+    try:
+        # __version__ was added in _version in setuptools-scm 7.0.0, we rely on
+        # the hopefully stable version variable.
+        from ._version import version as __version__
+    except (ModuleNotFoundError, ImportError):
+        # Either _version doesn't exist (ModuleNotFoundError) or version isn't
+        # in _version (ImportError). ModuleNotFoundError is a subclass of
+        # ImportError, let's be explicit anyway.
+
+        # Try something else:
+        from importlib.metadata import version as mversion, PackageNotFoundError
+
+        try:
+            __version__ = mversion('hvplot')
+        except PackageNotFoundError:
+            # The user is probably trying to run this without having installed
+            # the package.
+            __version__ = '0.0.0+unknown'
+
+_METHOD_DOCS = {}
+
+
+def _get_doc_and_signature(
+    cls, kind, completions=False, docstring=True, generic=True, style=True, signature=None
+):
+    converter = HoloViewsConverter
+    method = getattr(cls, kind)
+    kind_opts = converter._kind_options.get(kind, [])
+    eltype = converter._kind_mapping[kind]
+
+    formatter = ''
+    if completions:
+        formatter = 'hvplot.{kind}({completions})'
+    if docstring:
+        if formatter:
+            formatter += '\n'
+        formatter += '{docstring}'
+    if generic:
+        if formatter:
+            formatter += '\n'
+        formatter += '{options}'
+
+    # Bokeh is the default backend
+    backend = hvplot_extension.compatibility or Store.current_backend
+    if eltype in Store.registry[backend]:
+        valid_opts = Store.registry[backend][eltype].style_opts
+        if style:
+            formatter += '\n{style}'
+    else:
+        valid_opts = []
+
+    style_opts = 'Style options\n-------------\n\n' + '\n'.join(sorted(valid_opts))
+
+    parameters = []
+    extra_kwargs = _hv.core.util.unique_iterator(
+        valid_opts + kind_opts + converter._axis_options + converter._op_options
+    )
+
+    sig = signature or inspect.signature(method)
+    for name, p in list(sig.parameters.items())[1:]:
+        if p.kind == 1:
+            parameters.append((name, p.default))
+
+    filtered_signature = [
+        p for p in sig.parameters.values() if p.kind != inspect.Parameter.VAR_KEYWORD
+    ]
+    extra_params = [
+        inspect.Parameter(k, inspect.Parameter.KEYWORD_ONLY)
+        for k in extra_kwargs
+        if k not in [p.name for p in filtered_signature]
+    ]
+    all_params = (
+        filtered_signature
+        + extra_params
+        + [inspect.Parameter('kwargs', inspect.Parameter.VAR_KEYWORD)]
+    )
+    signature = inspect.Signature(all_params)
+
+    parameters += [(o, None) for o in extra_kwargs]
+    completions = ', '.join([f'{n}={v}' for n, v in parameters])
+    options = textwrap.dedent(converter.__doc__)
+    method_doc = _METHOD_DOCS.get(kind, method.__doc__)
+    _METHOD_DOCS[kind] = method_doc
+    docstring = formatter.format(
+        kind=kind,
+        completions=completions,
+        docstring=textwrap.dedent(method_doc),
+        options=options,
+        style=style_opts,
+    )
+    return docstring, signature
+
+
+def help(kind=None, docstring=True, generic=True, style=True):
+    """
+    Provide a docstring with all valid options which apply to the plot
+    type.
+
+    Parameters
+    ----------
+    kind: str
+        The kind of plot to provide help for
+    docstring: boolean (default=True)
+        Whether to display the docstring
+    generic: boolean (default=True)
+        Whether to provide list of generic options
+    style: boolean (default=True)
+        Whether to provide list of style options
+    """
+    doc, sig = _get_doc_and_signature(
+        cls=hvPlot, kind=kind, docstring=docstring, generic=generic, style=style
+    )
+    print(doc)
+
+
+def post_patch(extension='bokeh', logo=False):
+    if extension and not getattr(_hv.extension, '_loaded', False):
+        hvplot_extension(extension, logo=logo)
+
+
+def _patch_doc(cls, kind, signature=None):
+    method = getattr(cls, kind)
+    docstring, signature = _get_doc_and_signature(cls, kind, False, signature=signature)
+    method.__doc__ = docstring
+    method.__signature__ = signature
+
+
+class _PatchHvplotDocstrings:
+    def __init__(self):
+        # Store the original signatures because the method signatures
+        # are going to be patched every time an extension is changed.
+        signatures = {}
+        for cls in [hvPlot, hvPlotTabular]:
+            for _kind in HoloViewsConverter._kind_mapping:
+                if hasattr(cls, _kind):
+                    method = getattr(cls, _kind)
+                    sig = inspect.signature(method)
+                    signatures[(cls, _kind)] = sig
+        self.orig_signatures = signatures
+
+    def __call__(self):
+        for cls in [hvPlot, hvPlotTabular]:
+            for _kind in HoloViewsConverter._kind_mapping:
+                if hasattr(cls, _kind):
+                    signature = self.orig_signatures[(cls, _kind)]
+                    _patch_doc(cls, _kind, signature=signature)
+
+
+_patch_hvplot_docstrings = _PatchHvplotDocstrings()
+_patch_hvplot_docstrings()
+
+
+def _hook_patch_docstrings(backend):
+    # Patch or re-patch the docstrings/signatures to display
+    # the right styling options.
+    from . import _patch_hvplot_docstrings
+
+    _patch_hvplot_docstrings()
+
+
+Store._backend_switch_hooks.append(_hook_patch_docstrings)
+
+extension = hvplot_extension
+
+
+def bind(function, *args, **kwargs):
+    """
+    Returns a *reactive* function that can be used to start your `.interactive` pipeline by running
+    a model or loading data depending on inputs from widgets, parameters or python objects.
+
+    The widgets can be Panel or ipywidgets.
+
+    Reference: https://hvplot.holoviz.org/user_guide/Interactive.html#functions-as-inputs
+
+    Parameters
+    ----------
+    function : callable
+        The function to bind constant or dynamic args and kwargs to.
+    args : object, param.Parameter, panel.widget.Widget, or ipywidget
+        Positional arguments to bind to the function.
+    kwargs : object, param.Parameter, panel.widget.Widget, or ipywidget
+        Keyword arguments to bind to the function.
+
+    Returns
+    -------
+    Returns a new function with the args and kwargs bound to it and
+    annotated with all dependencies. This function has an `interactive`
+    attribute that can be called to instantiate an `Interactive` pipeline.
+
+    Examples
+    --------
+
+    Develop your **algorithm** or data extraction method with the tools you know and love.
+
+    >>> import pandas as pd
+    >>> import numpy as np
+
+    >>> def algorithm(alpha):
+    ...     # An example algorithm that uses alpha ...
+    ...     return pd.DataFrame({"output": (np.array(range(0,100)) ** alpha)*50})
+
+    Make it **interactive** using `.bind`, `.interactive` and widgets.
+
+    >>> import hvplot
+    >>> import panel as pn
+
+    >>> alpha = pn.widgets.FloatSlider(value=0.5, start=0, end=1.0, step=0.1, name="Alpha")
+    >>> top = pn.widgets.RadioButtonGroup(value=10, options=[5, 10, 25], name="Top")
+    >>> interactive_table = (
+    ...     hvplot
+    ...     .bind(algorithm, alpha=alpha)
+    ...     .interactive()
+    ...     .head(n=top)
+    ... )
+    >>> interactive_table
+
+    In a notebook or data app you can now select the appropriate `alpha` and `top` values via
+    widgets and see the `top` results of the algorithm in a table depending on the value of `alpha`
+    selected.
+    """
+    bound = _pn.bind(function, *args, **kwargs)
+    bound.interactive = lambda **kwargs: Interactive(bound, **kwargs)
+    return bound

hvplot/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.9.3a1'
+__version_tuple__ = version_tuple = (0, 9, 3)

hvplot/backend_transforms.py

@@ -0,0 +1,329 @@
+"""
+Set of transforms to go from a Bokeh option to another backend's option.
+"""
+
+from holoviews.core.overlay import CompositeOverlay
+from holoviews.core.options import Store
+from holoviews.plotting.util import COLOR_ALIASES
+
+
+UNSET = type('UNSET', (), {})
+
+
+def _transform_size_to_mpl(width, height, aspect):
+    opts = {}
+    if width and height:
+        opts = {'aspect': width / height, 'fig_size': (width / 300.0) * 100}
+    elif aspect and width:
+        opts = {'aspect': aspect, 'fig_size': (width / 300.0) * 100}
+    elif aspect and height:
+        opts = {'aspect': aspect, 'fig_size': (height / 300.0) * 100}
+    elif width:
+        opts = {'fig_size': (width / 300.0) * 100}
+    elif height:
+        opts = {'fig_size': (height / 300.0) * 100}
+    return opts
+
+
+def _transfer_opts(element, backend):
+    """
+    Transfer the bokeh options of an element to another backend
+    based on an internal mapping of option transforms.
+    """
+    elname = type(element).__name__
+    options = Store.options(backend=backend)
+    transforms = BACKEND_TRANSFORMS[backend]
+    if isinstance(element, CompositeOverlay):
+        element = element.apply(_transfer_opts, backend=backend, per_element=True)
+    new_opts = {}
+    el_options = element.opts.get(backend='bokeh', defaults=False).kwargs
+    for grp, el_opts in options[elname].groups.items():
+        for opt, val in el_options.items():
+            transform = transforms.get(grp, {}).get(opt, None)
+            # This condition could be applied to matplotlib only
+            # but is applied to plotly too since there seems to be
+            # no interactive options available like for the bokeh backend
+            if transform is None and _is_interactive_opt(opt):
+                transform = UNSET
+            if transform is UNSET:
+                continue
+            elif transform:
+                opt, val = transform(opt, val)
+                if val is UNSET:
+                    continue
+            if opt not in el_opts.allowed_keywords:
+                continue
+            new_opts[opt] = val
+    if backend == 'matplotlib':
+        size_opts = _transform_size_to_mpl(
+            el_options.get('width'), el_options.get('height'), el_options.get('aspect')
+        )
+        new_opts.update(size_opts)
+    return element.opts(**new_opts, backend=backend)
+
+
+def _is_interactive_opt(bk_opt):
+    """
+    Heuristics to detect if a bokeh option is about interactivity, like
+    'selection_alpha'.
+
+    >>> is_interactive_opt('height')
+    False
+    >>> is_interactive_opt('annular_muted_alpha')
+    True
+    """
+    interactive_flags = [
+        'hover',
+        'muted',
+        'nonselection',
+        'selection',
+    ]
+    return any(part in interactive_flags for part in bk_opt.split('_'))
+
+
+def _transfer_opts_cur_backend(element):
+    if Store.current_backend != 'bokeh':
+        element = element.apply(_transfer_opts, backend=Store.current_backend)
+    return element
+
+
+# Matplotlib transforms
+
+_line_cap_bk_mpl_mapping = {
+    'butt': 'butt',
+    'round': 'round',
+    'square': 'projecting',
+}
+
+_line_dash_bk_mpl_mapping = {
+    'solid': 'solid',
+    'dashed': 'dashed',
+    'dotted': 'dotted',
+    'dotdash': UNSET,
+    'dashdot': 'dashdot',
+}
+
+_text_baseline_bk_mpl_mapping = {
+    'top': 'top',
+    'middle': 'center',
+    'bottom': 'bottom',
+    'alphabetic': UNSET,
+    'hanging': UNSET,
+    'ideographic': UNSET,
+}
+
+MATPLOTLIB_TRANSFORMS = {
+    'plot': {
+        'height': UNSET,
+        'width': UNSET,
+        'min_height': UNSET,
+        'min_width': UNSET,
+        'max_height': UNSET,
+        'max_width': UNSET,
+        'frame_width': UNSET,
+        'frame_height': UNSET,
+        'sizing_mode': UNSET,
+        'responsive': UNSET,
+        'shared_axes': UNSET,
+        'shared_datasource': UNSET,
+        'selected': UNSET,
+        'tools': UNSET,
+        'active_tools': UNSET,
+        'default_tools': UNSET,
+        'toolbar': UNSET,
+        'align': UNSET,
+        'lod': UNSET,
+        'margin': UNSET,
+        'border': UNSET,
+        'jitter': UNSET,
+        'legend_muted': UNSET,
+        'legend_offset': UNSET,
+        'gridstyle': UNSET,
+        'colorbar_position': UNSET,
+        'violin_width': UNSET,
+    },
+    'style': {
+        'bar_width': UNSET,
+        'size': lambda k, v: ('s', v),
+        'fill_color': lambda k, v: ('facecolor', v),
+        'fill_alpha': UNSET,
+        'line_alpha': UNSET,
+        'line_cap': lambda k, v: ('capstyle', _line_cap_bk_mpl_mapping.get(v, UNSET)),
+        'line_color': lambda k, v: ('edgecolor', v),
+        'line_dash': lambda k, v: ('linestyle', _line_dash_bk_mpl_mapping.get(v, UNSET)),
+        'line_join': lambda k, v: ('joinstyle', v),
+        'line_width': lambda k, v: ('linewidth', v),
+        'palette': UNSET,
+        'click_policy': UNSET,
+        'annular_alpha': UNSET,
+        'annular_color': UNSET,
+        'annular_fill_alpha': UNSET,
+        'annular_fill_color': UNSET,
+        'annular_line_alpha': UNSET,
+        'annular_line_cap': UNSET,
+        'annular_line_color': lambda k, v: ('annular_edgecolors', v),
+        'annular_line_dash': UNSET,
+        'annular_line_join': UNSET,
+        'annular_line_width': lambda k, v: ('annular_linewidth', v),
+        'annular_visible': UNSET,
+        'dilate': UNSET,
+        'ticks_text_align': UNSET,
+        'ticks_text_alpha': UNSET,
+        'ticks_text_baseline': UNSET,
+        'ticks_text_color': UNSET,
+        'ticks_text_font': UNSET,
+        'ticks_text_font_size': UNSET,
+        'ticks_text_font_style': UNSET,
+        'xmarks_alpha': UNSET,
+        'xmarks_color': UNSET,
+        'xmarks_line_alpha': UNSET,
+        'xmarks_line_cap': UNSET,
+        'xmarks_line_color': lambda k, v: ('xmarks_edgecolor', v),
+        'xmarks_line_dash': UNSET,
+        'xmarks_line_join': UNSET,
+        'xmarks_line_width': lambda k, v: ('xmarks_linewidth', v),
+        'xmarks_visible': UNSET,
+        'ymarks_alpha': UNSET,
+        'ymarks_color': UNSET,
+        'ymarks_line_alpha': UNSET,
+        'ymarks_line_cap': UNSET,
+        'ymarks_line_color': lambda k, v: ('ymarks_edgecolor', v),
+        'ymarks_line_dash': UNSET,
+        'ymarks_line_join': UNSET,
+        'ymarks_line_width': lambda k, v: ('ymarks_linewidth', v),
+        'ymarks_visible': UNSET,
+        'lower_head': lambda k, v: ('lolims', v),
+        'upper_head': lambda k, v: ('uplims', v),
+        'whisker_color': UNSET,
+        'outlier_color': UNSET,
+        'text_align': lambda k, v: ('horizontalalignment', v),
+        'text_alpha': lambda k, v: ('alpha', v),
+        'text_baseline': lambda k, v: (
+            'verticalalignment',
+            _text_baseline_bk_mpl_mapping.get(v, UNSET),
+        ),
+        'text_color': lambda k, v: ('color', v),
+        'text_font': UNSET,
+        'text_font_size': lambda k, v: ('size', v),
+        'text_font_style': UNSET,
+        'box_alpha': UNSET,
+        'box_cmap': UNSET,
+        'box_fill_alpha': UNSET,
+        'box_fill_color': UNSET,
+        'box_line_alpha': UNSET,
+        'box_line_cap': UNSET,
+        'box_line_color': UNSET,
+        'box_line_dash': UNSET,
+        'box_line_join': UNSET,
+        'box_line_width': UNSET,
+        'box_visible': UNSET,
+        'median_alpha': UNSET,
+        'median_color': UNSET,
+        'outline_alpha': UNSET,
+        'outline_color': UNSET,
+        'outline_line_alpha': UNSET,
+        'outline_line_cap': UNSET,
+        'outline_line_color': UNSET,
+        'outline_line_dash': UNSET,
+        'outline_line_join': UNSET,
+        'outline_line_width': UNSET,
+        'outline_visible': UNSET,
+        'stats_alpha': UNSET,
+        'stats_line_alpha': UNSET,
+        'stats_line_cap': UNSET,
+        'stats_line_color': UNSET,
+        'stats_line_dash': UNSET,
+        'stats_line_join': UNSET,
+        'stats_line_width': UNSET,
+        'stats_visible': UNSET,
+        'violin_alpha': UNSET,
+        'violin_cmap': UNSET,
+        'violin_color': UNSET,
+        'violin_fill_alpha': UNSET,
+        'violin_fill_color': UNSET,
+        'violin_line_alpha': UNSET,
+        'violin_line_cap': UNSET,
+        'violin_line_color': UNSET,
+        'violin_line_dash': UNSET,
+        'violin_line_join': UNSET,
+        'violin_line_width': UNSET,
+        'violin_visible': UNSET,
+        'editable': UNSET,
+        'fit_columns': UNSET,
+        'index_position': UNSET,
+        'row_headers': UNSET,
+        'scroll_to_selection': UNSET,
+        'selectable': UNSET,
+        'sortable': UNSET,
+        'edge_alpha': lambda k, v: ('edge_alpha', v),
+        'edge_cmap': lambda k, v: ('edge_cmap', v),
+        'edge_color': lambda k, v: ('edge_color', v),
+        'edge_fill_alpha': UNSET,
+        'edge_fill_color': UNSET,
+        'edge_line_alpha': UNSET,
+        'edge_line_cap': UNSET,
+        'edge_line_color': lambda k, v: ('edge_color', v),
+        'edge_line_dash': lambda k, v: ('edge_linestyle', v),
+        'edge_line_join': UNSET,
+        'edge_line_width': lambda k, v: ('edge_linewidth', v),
+        'edge_visible': UNSET,
+        'node_alpha': lambda k, v: ('node_alpha', v),
+        'node_cmap': lambda k, v: ('node_cmap', v),
+        'node_color': lambda k, v: ('node_color', v),
+        'node_fill_alpha': UNSET,
+        'node_fill_color': lambda k, v: ('node_facecolors', v),
+        'node_line_alpha': UNSET,
+        'node_line_cap': UNSET,
+        'node_line_color': lambda k, v: ('node_edgecolors', v),
+        'node_line_dash': UNSET,
+        'node_line_join': UNSET,
+        'node_line_width': lambda k, v: ('node_linewidth', v),
+        'node_marker': lambda k, v: ('node_marker', v),
+        'node_radius': UNSET,
+        'node_size': lambda k, v: ('node_size', v),
+        'node_visible': lambda k, v: ('visible', v),
+    },
+}
+
+# Plotly transforms
+
+_line_dash_bk_plotly_mapping = {
+    'solid': 'solid',
+    'dashed': 'dash',
+    'dotted': 'dot',
+    'dotdash': UNSET,
+    'dashdot': 'dashdot',
+}
+
+PLOTLY_TRANSFORMS = {
+    'plot': {
+        'alpha': lambda k, v: ('opacity', v),
+        'min_height': UNSET,
+        'min_width': UNSET,
+        'max_height': UNSET,
+        'max_width': UNSET,
+        'frame_width': UNSET,
+        'frame_height': UNSET,
+        'batched': UNSET,
+        'legend_limit': UNSET,
+        'tools': UNSET,
+        'shared_xaxis': UNSET,
+        'shared_yaxis': UNSET,
+    },
+    'style': {
+        'alpha': lambda k, v: ('opacity', v),
+        'color': lambda k, v: (k, COLOR_ALIASES.get(v, v)),
+        'fill_color': lambda k, v: ('fillcolor', COLOR_ALIASES.get(v, v)),
+        'line_color': lambda k, v: (k, COLOR_ALIASES.get(v, v)),
+        'line_dash': lambda k, v: ('dash', _line_dash_bk_plotly_mapping.get(v, UNSET)),
+        'line_width': lambda k, v: ('line_width', v),
+        'muted_alpha': UNSET,
+        'palette': UNSET,
+    },
+}
+
+
+BACKEND_TRANSFORMS = dict(
+    matplotlib=MATPLOTLIB_TRANSFORMS,
+    plotly=PLOTLY_TRANSFORMS,
+)