Improving hvsampledata usage

[jbednar]

The new hvPlot docs improvements are great! Some notes and questions about streamlining how these sample datasets are accessed:

• Some of the examples are using hvsampledata, which means they need to import hvsampledata, which is then a distracting line of code that will likely stay around confusingly in user code when they copy and paste to create their own plots. To avoid these imports when accessing examples, I vote that the hvplot and hv namespaces should include a function like hv.sampledata.xxx() and hvplot.sampledata.xxx() as proposed in Add a sampledata module to mirror hvsampledata's API? #1496.

• Some examples also use what seems to be an older approach, i.e. a separate hvplot.sample_data module that itself needs to be imported. That's confusing, and maybe we could remove that code from our examples (without removing the module necessarily) and update them to use a function (not needing importing) instead.

• There are also lots of examples using Bokeh's sample data. Should those be updated to get sample data via the hvsampledata package instead?

• There are also a few examples using sample data from xarray. I propose that we maybe leave those as they are, because xarray users may already be familiar with the examples and will find it cognitively simpler to simply refer to these known examples rather than wonder how our versions differ from xarray's. (To me xarray examples are a different case from bokeh's, because hvplot is positioning itself as an alternative interface to Bokeh's API, meaning that most people who use hvplot + Bokeh are likely not to be Bokeh users, whereas any user of hvplot.xarray is also by definition an xarray user directly.)

[maximlt]

To avoid these imports when accessing examples, I vote that the hvplot and hv namespaces should include a function like hv.sampledata.xxx() and hvplot.sampledata.xxx() as proposed in #1496.

That's what I was aiming for originally but somehow got convinced that was not worth the trouble (after a discussion with Philipp I think?). Anyway, happy to reconsider that, though I don't think we can decide here what to do for HoloViews (or Panel, etc.). And that's an important point, as I wouldn't like the HoloViz libraries to offer data that differs between their sampledata modules! But if we go down that route, I guess one implementation could look like this. What do you think @hoxbro?

# hvplot/__init__.py

from . import hvsampledata

# hvplot/sampledata.py

_hvsampledata_available = False

try:
    from hvsampledata import *
    _hvsampledata_available = True
except ImportError:
    pass

def __getattr__(name):
    if not _hvsampledata_available:
        msg = (
            "Install the package 'hvsampledata' to access datasets from the "
            "'sampledata' module of hvPlot."
        )
        raise AttributeError(msg)
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

Actually, this looks simpler:

# hvplot/__init__.py

try:
    import hvsampledata as sampledata
except ImportError:
    from . import sampledata

# hvplot/sampledata.py

def __getattr__(name):
    msg = (
        "Install the package 'hvsampledata' to access datasets from the "
        "'sampledata' module of hvPlot."
    )
    raise AttributeError(msg)

Some examples also use what seems to be an older approach, i.e. a separate hvplot.sample_data module that itself needs to be imported. That's confusing, and maybe we could remove that code from our examples (without removing the module necessarily) and update them to use a function (not needing importing) instead.

There are also lots of examples using Bokeh's sample data. Should those be updated to get sample data via the hvsampledata package instead?

Yep that's planned, we've decided not to go through the whole site and change everything, but to do it gradually instead. The goal is to only load data from hvsampledata.

There are also a few examples using sample data from xarray. I propose that we maybe leave those as they are, because xarray users may already be familiar with the examples and will find it cognitively simpler to simply refer to these known examples rather than wonder how our versions differ from xarray's. (To me xarray examples are a different case from bokeh's, because hvplot is positioning itself as an alternative interface to Bokeh's API, meaning that most people who use hvplot + Bokeh are likely not to be Bokeh users, whereas any user of hvplot.xarray is also by definition an xarray user directly.)

We're already shipping a reduced version of air_temperature, see holoviz/hvsampledata#24.

[jbednar]

The goal is to only load data from hvsampledata.
We're already shipping a reduced version of air_temperature, see holoviz/hvsampledata#24.

Thanks. I'm happy with either approach, either always using hvsampledata, or always using hvsampledata unless we're using data as-is from a known, guaranteed available external source (such as xarray's sample data, when using xarray).

[hoxbro]

But if we go down that route, I guess one implementation could look like this. What do you think @hoxbro?

I think it looks good. We could altogether skip the sampledata file and inline a class, right? I would also have it raise an ImportError and not an AttributeError.

[maximlt]

+1 for the ImportError, not intentional on my end to raise an AttributeError in this case.

We could altogether skip the sampledata file and inline a class, right?

Not sure how exactly?

[hoxbro]

Not sure how exactly?

Create a class and then initialize it; I'm okay with either approach.

[maximlt]

I'd be fine with a class-based approach if it could always be a class, as I think having sampledata sometimes be a module or a class is a little unconventional.