Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add top-level save and render utilities #3134

Merged
merged 20 commits into from Nov 16, 2018

Conversation

Projects
None yet
3 participants
@philippjfr
Copy link
Contributor

philippjfr commented Nov 4, 2018

This PR adds top-level hv.save and hv.render utilities which we have long wanted and are much more obvious than the obscure hv.renderer(backend).save(obj, filename, fmt) and hv.renderer(backend).get_plot(obj).state APIs.

  • hv.render: Renders the holoviews object to the representation in of the backend, e.g. for bokeh returns bokeh Figure objects. This is very useful for incorporating HoloViews into a workflow where you're working directly with the underlying library but want to take advantage of some plot type that's only provided by HoloViews.

  • hv.save: Convenient API for saving holoviews objects to any format, including png, svg, gif, mp4, and both scrubber and selection widgets.

Here is a notebook demonstrating what the API looks like in practice (note that because of the way exported HTML files are embedded some of the widget examples do not work but will work when working with the exported file directly).

  • Add documentation

@philippjfr philippjfr added the API label Nov 4, 2018

@philippjfr philippjfr added this to the v1.11.0 milestone Nov 4, 2018

@philippjfr philippjfr requested review from jlstevens and jbednar Nov 4, 2018

@philippjfr philippjfr force-pushed the save_render_utilities branch from 980f335 to 08eb817 Nov 5, 2018

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 5, 2018

If anyone has suggestions on where to document these that would be very helpful.

@jbednar

jbednar approved these changes Nov 5, 2018

Copy link
Contributor

jbednar left a comment

Looks really useful! I have wanted something like this for a long time, but never took the time to write it, so I am very glad you did.

The available output formats available depend on the backend being
used. By default and if the filename is a string the output format
will be inferred from the file extension. Otherwise an explicit
format will be specified. For ambiguous file extensions such as

This comment has been minimized.

@jbednar

jbednar Nov 5, 2018

Contributor

will need to be specified?

Show resolved Hide resolved holoviews/util/__init__.py
will be inferred from the file extension. Otherwise an explicit
format will be specified. For ambiguous file extensions such as
html it may be necessary to specify an explicit fmt to override
the default.

This comment has been minimized.

@jbednar

jbednar Nov 5, 2018

Contributor

That last bit is confusing to me -- what fmt other than 'html' would be more explicit? If you mean widgets vs. scrubber, please say that explicitly -- i.e. that .html will by default be XX, but if you don't want that, specify YY.

This comment has been minimized.

@philippjfr

philippjfr Nov 5, 2018

Author Contributor

Sounds good.


def render(obj, backend=None, **kwargs):
"""
Renders the object to a figure object.

This comment has been minimized.

@jbednar

jbednar Nov 5, 2018

Contributor

Renders the HoloViews object to the corresponding object in the specified backend, e.g. a Matplotlib or Bokeh figure.

The backend defaults to the currently declared default backend. The resulting object can then be used with other objects in the specified backend. For instance, if you want to make a multi-part Bokeh figure using a plot type only available in HoloViews, you can use this function to return a Bokeh figure that you can use like any hand-constructed Bokeh figure in a Bokeh layout.

This comment has been minimized.

@philippjfr

philippjfr Nov 5, 2018

Author Contributor

Sounds good.

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 8, 2018

Just noticed all the +1's on this issue: #1819 Adding this is really overdue. I'll try to add this to the getting started and user guides in the appropriate places.

if fmt == 'auto' and formats and formats[-1] != 'html':
fmt = formats[-1]
if formats[-1] in supported:
filename = '.'.join(formats[:-1])

This comment has been minimized.

@jlstevens

jlstevens Nov 8, 2018

Contributor

And if the format isn't supported?

This comment has been minimized.

@philippjfr

philippjfr Nov 9, 2018

Author Contributor

Renderer.save automatically adds the file extension no matter what file extension you supply (which I've found pretty annoying tbh). So if you don't supply a file extension it'll pick whatever the default is.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 8, 2018

I am happy with these utilities and I do think they are useful. I'm not entirely sure where in the docs this should go though I think save can be mentioned early on in our current exporting and archiving user guide.

Maybe render can be the first thing in 'Working with Plots and Renderers' though it would be nice to mention it earlier. Maybe at the first point where we show multiple backend support?

Happy to merge the code now for a subsequent docs PR or wait for that material to be added here.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented Nov 8, 2018

Wherever render is mentioned, please also mention finalize_hooks, because I think many of the things people think they need render for can be done more cleanly using finalize_hooks, allowing them to spend more of their time in the HV world instead of leaving it to start working with Bokeh directly (except where strictly necessary, using finalize_hooks).

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 8, 2018

I know we've already gone through the whole finalize_hooks vs. final_hooks mess, but how do you feel about renaming finalize_hooks to just hooks (with a proper deprecation cycle of course)? Initially we had considered adding initial_hooks but there is effectively no use for them and the current name is quite annoying to type out.

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 9, 2018

I am happy with these utilities and I do think they are useful. I'm not entirely sure where in the docs this should go though I think save can be mentioned early on in our current exporting and archiving user guide.

I think this is probably way to deep into the material, I'd like at least a mention in getting started section and I'll also add FAQ items.

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 9, 2018

I've overhauled the FAQ a bit with sections for save and render/finalize_hooks (also applied some unrelated edits). Will look at the getting started and user guides next.

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 9, 2018

@jlstevens @jbednar Ready for another round of review, here's what I've done for documentation:

  • FAQ items about hv.save and hv.render separately
  • Very short entry about hv.save in Getting Started Introduction
  • Mentioned hv.save as alternative to %%output filename=... in Exporting user guide
  • Detailed description of hv.render and finalize_hooks in Plots and Renderers.

@philippjfr philippjfr force-pushed the save_render_utilities branch from e494eff to 42265df Nov 9, 2018

Philipp Rudiger Philipp Rudiger
@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 9, 2018

I've now also aliased finalize_hooks to hooks and marked this PR with deprecated to make sure that when we write up the release notes the deprecation of finalize_hooks is mentioned.

@jbednar

jbednar approved these changes Nov 9, 2018

Copy link
Contributor

jbednar left a comment

Looks great, thanks! My wording suggestions are minor, and if any of them are not accurate, please disregard them but try to clarify it in the correct direction instead.

Show resolved Hide resolved doc/FAQ.rst Outdated
Show resolved Hide resolved doc/FAQ.rst Outdated
Show resolved Hide resolved doc/FAQ.rst
Show resolved Hide resolved doc/FAQ.rst Outdated
Show resolved Hide resolved doc/FAQ.rst Outdated
Show resolved Hide resolved examples/user_guide/Plots_and_Renderers.ipynb Outdated
Show resolved Hide resolved holoviews/plotting/bokeh/plot.py Outdated
Show resolved Hide resolved holoviews/plotting/bokeh/tabular.py Outdated
Show resolved Hide resolved holoviews/plotting/mpl/plot.py Outdated
Show resolved Hide resolved holoviews/util/__init__.py

jbednar and others added some commits Nov 9, 2018

Update doc/FAQ.rst
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update doc/FAQ.rst
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update doc/FAQ.rst
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update doc/FAQ.rst
Co-Authored-By: philippjfr <philippjfr@continuum.io>

jbednar and others added some commits Nov 9, 2018

Update doc/FAQ.rst
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update examples/getting_started/1-Introduction.ipynb
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update examples/user_guide/Plots_and_Renderers.ipynb
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update examples/user_guide/Plots_and_Renderers.ipynb
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update examples/user_guide/Plots_and_Renderers.ipynb
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update examples/user_guide/Plots_and_Renderers.ipynb
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update holoviews/plotting/bokeh/plot.py
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Update holoviews/plotting/mpl/plot.py
Co-Authored-By: philippjfr <philippjfr@continuum.io>
Philipp Rudiger Philipp Rudiger
@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 10, 2018

Review comments now addressed, ready to merge.

@jbednar

This comment has been minimized.

Copy link
Contributor

jbednar commented on 1ee41f7 Nov 10, 2018

Looks good, thanks.

@philippjfr

This comment has been minimized.

Copy link
Contributor Author

philippjfr commented Nov 15, 2018

@jlstevens Please review and merge this.

@jlstevens

This comment has been minimized.

Copy link
Contributor

jlstevens commented Nov 16, 2018

Looks good. Merging.

@jlstevens jlstevens merged commit 6f505a1 into master Nov 16, 2018

4 checks passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
continuous-integration/travis-ci/push The Travis CI build passed
Details
coverage/coveralls Coverage decreased (-0.05%) to 89.095%
Details
s3-reference-data-cache Tests passing no test data changes required.
Details

@philippjfr philippjfr deleted the save_render_utilities branch Dec 13, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.