Options style guide

1. The .opts() method call should normally be used immediately before the object is displayed. In a notebook this means it should appear only at the end of a cell, in a script it might mean it should appear just before rendering. One valid exception to this rule is when the contents of .options varies over a list/dict or set comprehension.

2. Use .opts() as few times as possible. If you are building a compositional object, build it and call .options just before display and not at any time prior. In a notebook, you can build a compositional object in stages if you view the pieces between cells, but don't sprinkle .options calls freely within a composite expression.

3. Inline the Options objects from opts.Curve etc into the .options call if possible. Only create a named handle if you need programatic/conditional control (i.e a data structure that isn't static). If you do need such a data structure, it is still preferable to declare it just prior to where it is used in .options and after the data/elements are declared.

4. Don't build a giant expression mixing declaration of elements/objects, composition and options. In notebooks this means the expression before .opts should be composed of handles and + and * and nothing else. THERE IS NOW ONE EXCEPTION BELOW. If necessary make new handles on the composed pieces to satisfy this rule or create a new handle on the overall object (e.g called composition) and call .opts on that. This is to avoid large, hard to read and potentially rather scary looking expressions and to help split up the declaration of the data/elements/displayed components from their appearance.

5. These rules apply for compositional objects only. For instance, if you are viewing a single element something like hv.Image(...).options(cmap='jet') is acceptable if the declaration of the element isn't too long. RULES FOR THIS EXPANDED BELOW. If it is long, declaring a handle is still recommended (e.g im.options(cmap='jet')). If the contents of .options does not fit comfortably in a single line, add a line break immediately afterwards and list the contents with a single extra indent.

6. If the contents of .opts does not fit comfortably in a single line, add a line break immediately afterwards and list the contents with a single extra indent.

(density_grid * point_grid).options(opts.Bivariate(bandwidth=0.5, cmap='Blues'), 
                                                          opts.Points(size=2, tools=['box_select']))

Should be:

(density_grid * point_grid).options(
    opts.Bivariate(bandwidth=0.5, cmap='Blues'), 
    opts.Points(size=2, tools=['box_select']))

When to inline the .opts call:

1. Options should be specified using .opts once, immediately before display, where feasible. There are situations where delaying option setting in this way is not reasonable and you would have to use groups or cycles to disambiguate collections of the same element type. In such situations, the recommendation is to associate the .options call as closely as possible to the element when it is created.

For example, you can use the template styled_element = hv.Element(data, ...).options(...) where the goal is to keep the declaration before .options as short and as readable as possible (e.g data should already be defined as a handle). You should not declare these custom style elements inside larger compositional expressions involving + or * (or containers such as HoloMap).

2. (The exception) You can inline a single simple .opts call in a composition if the composition is made up of handles. E.g this is okay penguins * bounds.opts(color='orange', linewidth=6) but foo.opts(..) * bar.opts(..) is not . The .opts call is not considered 'simple' if you use the opts utility or if there are more than three or four keywords.

3. Generally use title plot option instead of defining groups just to set a title.

Formatting the opts utility specs in the .opts method:

• (optional) In .options(...) try to list element names in alphanumeric order (e.g opts.Curve before opts.HLine)

• (recommendation) List container type options last (if present) with opts.Overlay appearing before opts.Layout.

• (optional) Try to list keywords in alphanumeric order.

• (recommendation) List normalization keywords last (axiswise before framewise). This is an exception to tha above alphanumeric sort when used.

When should I use inline keywords instead of the opts utility?

• If as an author you know the keywords offhand you can inline.

• If the keywords are commonly known (e.g height, width, color, cmap, fig_size, title , colorbar, alpha, line_width, size, marker) and there are no more than 3 or 4 of them at once. A keyword can always be considered common if it is mentioned in the immediately surrounding markdown text.

• If you are at all unsure about the keywords, use the opts utility. It will help with tab-completion and it is easier to remove it later.

• The reason not to use the opts utility is for readability e.g for one or two simple keywords.