Documentation Issues from a Learner's Perspective

[mforbes]

As I am starting again to seriously consider using HoloViews, I come across deficiencies in the documentation from the perspective of a learner. I will collect these here:

Curve.html

• There is no explicit documentation about what the data parameter should be for a Curve. It can be either a single array in which case the the abscissa will be an array of indices, or it can be a tuple of arrays. Can the kdims and vdims also be passed in? If it is an xarray.DataArray or a Dataset, then the kdims etc. can be specified from there. I suppose if one has a good working knowledge of HoloViews, then this might all be obvious, but for a first time user, Curve is probably the entry point, and it would be nice to have at least a link to the appropriate discussion at this point. Some related questions that could be answered here:
  • The group and label options do not appear in any documentation I could easily find at the point of source.
  • Can data somehow specify group or label options?
• continuously indexable 1D coordinate system link broken.

[mforbes]

Visualization Options

I have learned that the list of options can be seen by using hv.help() or %%output info=True as specified in the FAQ, and that I can find out the visualization parameters by hv.help(visualization=True) (though for the life of me, I cannot see where I did learn this! I would have expected in Customizing_Plots.html or Customization.html but it does not seem to be there.) However, it is still quite a mystery to me how to actually set options.

• Could there be some instructions at the point of source in the help that gives me simple syntax for how to actually set the parameters? I.e. something that reminds the user that plot options should be [] and style options () in the magics, and more importantly, clearly telling the user which object/group/??? needs to be specified to change the appropriate parameter.
• It would help if the FAQ entry mentioned visualization=True and the equivalent option for %%output info=True (which I do not know).

Here is how I (failed) to figure things out. For example: suppose I want to change the height of the following plots:

x = np.linspace(0,1,100)
l = hv.Curve((x, x**2)) + hv.Curve((x, np.sin(x)))
l

First I need to know to do

>>> hv.help(l, visualization=True)
...
Target Specifications
...
Element: Curve.Curve
Container: Layout.Layout
...
To see the options info for one of these target specifications,
which are of the form {type}[.{group}[.{label}]], do holoviews.help({type}).  

Parameters of 'LayoutPlot'
==========================
...
Name                            Value                    Type       Bounds    Mode  
...
height                           300                   Integer                V RW  

My reading of this documentation is that something called LayoutPlot has a height parameter that I can customize. I also have no idea what the "{type}[.{group}[.{label}]], do holoviews.help({type})" construct means. The only thing in the documentation called "Type" is "Integer". Nothing is called a "type", "group", or "label".

Failures:

hv.help('LayoutPlot')     # no Python documentation found for 'LayoutPlot'
l.height = 100            # Silently fails to do anything.  Okay, this is python.
l.set_param(height=100)   # ValueError: 'height' is not a parameter of Layout10599
l.get_param_values()      # Ah, height is not a parameter... okay
l.opts(height=100)        # TypeError: 'int' object is not iterable??
l.opts(options=dict(height=100)) # AttributeError: 'int' object has no attribute 'items'???

# I give up for now... Let's go to options.
%%opts LayoutPlot [height=100] # WARNING: Unknown elements LayoutPlot not registered with any of the loaded backends.
%%opts Layout [height=100]  # Silently has no effect.
%%opts Curve (height=100)  # Unexpected style option 'height' for Curve... Clear
%%opts Curve [height=100]  # Works!

# Reads Dictionary format section of Customizing Plots
dict_spec = {'Layout.Curve': {'plot': dict(height=100)}}
dict_spec = {'Curve': {'plot': dict(height=100)}}
l.opts(dict_spec)
l   # Does nothing.

Successes:

%%opts Curve [height=100]  # Works!

dict_spec = {'Curve': {'plot': dict(height=100)}}
l.opts(dict_spec)   # This returns a clone that has the options set.

dict_spec = {'Curve': {'plot': dict(height=100)}}
hv.opts(dict_spec)   # Globally sets the options

It really surprised me that l.opts(dict_spec) modifies neither the previously displayed layout l or a subsequently displayed l, but returns a clone of the layout that is modified. From the documentation of opts() this is clear in hindsight, but I still have no idea how to programatically set the hight of the actual l layout I have already created, nor why I cannot set the height of the Layout instead of having to work with the individual Curve objects, though I suppose that the Layout probably encapsulates whatever height is needed. It would be extremely helpful if the generated documentation could somehow say that I need to modify the heights of the Curves rather than the Layout (and I do not know what use the height parameter of the Layout is then... can I view it or something?)

[mforbes]

Normalization

• Better discussion about normalization is needed.

For example, I expected the following with distinct Dimensions to not link the axes, but they were linked because they have the same textual name (I think).

x = np.linspace(0,1,100)
x1 = hv.Dimension('x')
x2 = hv.Dimension('x')
(hv.Curve((x, x**2), kdims=[x1], vdims=['t'])
 + hv.Curve((x, np.sin(x)), kdims=[x2], vdims=['z']))