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.

Sign up for GitHub

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

Jump to bottom

Doc cleanup #401

Merged
merged 11 commits into from
Jan 16, 2016
Merged

Doc cleanup #401

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e4285a8
Improved docs for 1.4 with updates, fixes, and clarifications
jbednar Jan 8, 2016
a38d884
Updated tagline
jbednar Jan 8, 2016
128e8a5
Updated Showcase for 1.4
jbednar Jan 8, 2016
b08443f
Updated Introduction for 1.4
jbednar Jan 8, 2016
5245f1d
Updated About for 1.4
jbednar Jan 9, 2016
d7f443c
Updated for 1.4
jbednar Jan 9, 2016
230d220
Tracking master
jbednar Jan 13, 2016
adbe7e0
Added Bokeh data download if not already available
jbednar Jan 14, 2016
555e502
Updated description of Points and Scatter to match current indexing b…
jbednar Jan 14, 2016
8f5f7ef
Replaced links for Transforming Data to Sampling Data
jbednar Jan 14, 2016
d95bd06
Minor clarification to docs
jbednar Jan 14, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions doc/Examples/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Examples

This collection of examples demonstrate interesting uses of HoloViews
that go beyond the tutorial material. Suitable material includes
application of HoloViews to real-world data, examples of advanced
application of HoloViews to real-world data, and examples of advanced
usage and demonstrations of how HoloViews may be extended, including
third-party libraries that feature HoloViews integration.

Expand Down Expand Up @@ -36,8 +36,7 @@ HoloViews may be used:
Visualizing the marking results of an undergraduate assignment with
HoloViews.

* `The Hipster Effect <HipsterDynamics.html>`_: Adapted version of
`Jake Vanderplas' blog post
* `The Hipster Effect <HipsterDynamics.html>`_: Adapted version of `post from Jake Vanderplas
<https://jakevdp.github.io/blog/2014/11/11/the-hipster-effect-interactive>`_
about dynamic systems and modeling of conformity.

Expand All @@ -53,10 +52,16 @@ extended in new (and unexpected!) directions:
Example usage of the mpld3 rendering backend allowing you to
generate D3.js-based plots with interactive widgets.

* `Interfacing HoloViews with Julia
<http://philippjfr.com/blog/interfacing-holoviews-with-julia/>`_: A
prototype of a basic interface to the Julia programming language.
* `Using HoloViews from Julia
<http://philippjfr.com/blog/interfacing-holoviews-with-julia/>`_:
A prototype interface to allow HoloViews to be used from the Julia
programming language. (Contributions welcome!)

* `Experimental Plotly backend
<http://philippjfr.com/work/work-in-progress/plotly/>`_: A
prototype of a `Plotly`<https://plot.ly/python>`_-based backend for HoloViews,
with progress summarized in an ongoing `pull request <https://github.com/ioam/holoviews/pull/398>`_.
(Contributions welcome!)

External Projects
-----------------
Expand Down
102 changes: 68 additions & 34 deletions doc/FAQ.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ Here is a list of questions we have either been asked by users or
potential pitfalls we hope to help users avoid:


**Q: Can I use HoloViews without IPython?**
**Q: Can I use HoloViews without IPython/Jupyter?**

**A:** Yes! The IPython support makes a lot of tasks easier, and
**A:** Yes! The IPython/Jupyter notebook support makes a lot of tasks easier, and
helps keep your data objects separate from the customization options,
but everything available in IPython can also be done directly from
Python. For instance, in HoloViews 1.3.0 you can render an object
Expand All @@ -20,48 +20,54 @@ directly to disk, with custom options, like this:
renderer.save(my_object, 'example_I', style=dict(Image={'cmap':'jet'}))

This process is described in detail in the
`Options tutorial <Tutorials/Options>`_, and some more information is
on `this wiki page
<https://github.com/ioam/holoviews/wiki/HoloViews-without-IPython>`_.
`Options tutorial <Tutorials/Options>`_.
Of course, notebook-specific functionality like capturing the data in
notebook cells or saving cleared notebooks is only for IPython.
notebook cells or saving cleared notebooks is only for IPython/Jupyter.

**Q: How should I use HoloViews as a short qualified import?**

For a qualified import, we recommend importing HoloViews using ``import holoviews as hv``.
We recommend importing HoloViews using ``import holoviews as hv``.

**Q: My output looks different from what is shown on the website**

**A:** Matplotlib supports a variety of plotting backends, and these
can have inconsistent output. HoloViews will not switch the backend
for you, but we strongly recommend selecting the 'agg' backend in
general:
**A:** HoloViews is organized as data structures that have
corresponding plotting code implemented in different plotting-library
backends, and each library will have differences in behavior.
Moreover, the same library can give different results depending on its
own internal options and versions. For instance, Matplotlib supports
a variety of internal plotting backends, and these can have
inconsistent output. HoloViews will not switch Matplotlib backends for
you, but when using Matplotlib we strongly recommend selecting the
'agg' backend for consistency:

.. code:: python

from matplotlib import pyplot as plt
plt.switch_backend('agg')
from matplotlib import pyplot
pyplot.switch_backend('agg')

You can generally set options explicitly to make the output more
consistent across HoloViews backends, but in general HoloViews tries
to use each backend's defaults where possible.

**Q: Help! I don't know how to index into my object!**

**A:** If you are in the IPython Notebook you can use the cell magic
``%%output fig='repr' holomap='repr'`` at the top of your code cell to
see the structure of your object.

In a regular Python session, you can look at ``print repr(obj)``. For
In any Python session, you can look at ``print repr(obj)``. For
an explanation of how this information helps you index into your
object, see our `Composing Data tutorial <Tutorials/Composing_Data>`_.


**Q: Help! How do I find out the options for customizing the
appearance of my object?**

**A:** If you are in the IPython Notebook you can use the cell magic
**A:** If you are in the IPython/Jupyter Notebook you can use the cell magic
``%%output info=True`` at the top of your code cell. This will
present the available style and plotting options for that object.

The same information is also available using
The same information is also available in any Python session using
``holoviews.help(obj)``. For more
information on customizing the display of an object,
see our `Options Tutorial <Tutorials/Options>`_.
Expand All @@ -72,7 +78,7 @@ through to matplotlib?**

**A:** We have selected a subset of default allowable style options
that are most commonly useful in order to hide the more arcane
matplotlib options. If you do need to such an option to be passed to
matplotlib options. If you do need such an option to be passed to
the plotting system, you are welcome to declare that this is allowed.
For instance, say you may want the ``'filternorm'`` option to be passed
to matplotlib's ``imshow`` command when displaying an ``Image``
Expand All @@ -88,23 +94,26 @@ magic, including tab-completion!

**Q: I still can't tweak my figure in exactly the way I want. What can I do?**

HoloViews is designed to be as flexible as possible and should always
support all the common visualization options. We intend to add a new
tutorial soon to explain how you can continue to
`tweak and extend HoloViews <https://github.com/ioam/holoviews/issues/19>`_.
You can of course subclass any HoloViews object and modify
any of its behavior, but this tutorial will explain some simpler
and more maintainable alternatives once it is ready.
The parameters provided by HoloViews should normally cover the most
common plotting options needed. In case you need further control, you
can always subclass any HoloViews object and modify any of its
behavior, and the object will still normally interact with other
HoloViews objects (e.g. in Layout or Overlay configurations).

There are also much simpler and more easily maintainable options for
making customized modifications, and we expect to put together a new
tutorial to explain the methods for `tweaking and extending HoloViews
<https://github.com/ioam/holoviews/issues/19>`_.

**Q: How do I get a legend on my figure?**
**Q: How do I get a legend on my overlay figure?**

**A:** Legends are generated in two different ways, depending on the
``Overlay`` type you are using. When using ``*`` to generate an ``Overlay``,
``Overlay`` type you are using. When using ``*`` to generate a normal ``Overlay``,
the legends are generated from the labels of the Elements.
Alternatively, you can construct an ``NdOverlay``, where the key dimensions
and values will become part of the legend. An example of an ``NdOverlay``
in action may be `viewed here <Tutorials/Containers.html#NdOverlay>`_.

and values will become part of the legend. The
`Containers tutorial <Tutorials/Containers.html#NdOverlay>`_.
shows an example of an ``NdOverlay`` in action.

**Q: I wish to use special characters in my title, but then attribute
access becomes confusing.**
Expand All @@ -116,6 +125,20 @@ that let you refer to the object easily in the code, and then you can
set the plot title directly, using the plot option
``title_format="my new title"``.

For frequent cases you can define a dictionary of aliases, with short,
Pythonic names for complicated typeset strings:

```
al = hv.util.Aliases(Spectrum='Frequency spectrum',
Water='$H_2O$',
Glucose='$C_6H_{12}O_6$')

(hv.Image(np.random.rand(10,10), group=al.Spectrum, label=al.Glucose) +
hv.Image(np.random.rand(10,10), group=al.Spectrum, label=al.Water))
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think documenting this in the FAQ isn't too bad in the end. It is probably things like a collection of final_hooks examples that are hard to find a place for...


See this `pull request <https://github.com/ioam/holoviews/pull/312>`_
for more details.

**Q: Where have my custom styles gone after unpickling my object?**

Expand All @@ -132,10 +155,12 @@ customization. You can import ``Store`` from the main namespace with
my notebook?**

**A:** It is very easy to visualize large volumes of data with
HoloViews, and all available display data is embedded in the HTML
snapshot when sliders are used. It is therefore worth being aware of
file size when authoring a notebook to be made make public on the
web. Useful tricks to reduce file size include:
HoloMaps, and all available display data is embedded in the HTML
snapshot when sliders are used so that the result can be viewed
without using a Python server process. It is therefore worth being
aware of file size when authoring a notebook or web page to be
published on the web. Useful tricks to reduce file size of HoloMaps
include:

* Reducing the figure size.
* Selecting fewer frames for display (e.g selecting a smaller number
Expand All @@ -144,8 +169,17 @@ web. Useful tricks to reduce file size include:
``webm``, ``mp4`` or animated ``gif``, while being aware that those
formats may introduce visible artifacts.

It is also possible to generate web pages that do not actually include
all of the data shown, by specifying a `DynamicMap
<https://github.com/ioam/holoviews/blob/babac9e2916384e03cd189865d5ca59a6b490708/holoviews/core/spaces.py#L332>`_
rather than a HoloMap. The DynamicMap will request data only as
needed, and so requires a Python server to be running alongside the
viewable web page. Such pages are more difficult to share by email or
on web sites, but much more feasible for large datasets.


**Q: How do I create a Layout or Overlay object from an arbitrary list?**

You can supply the list of elements directly to the ``Layout`` and
You can supply a list of ``elements`` directly to the ``Layout`` and
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be Elements? Bit tricky as only the singular, Element is an actual class name but I think pluralizing it (with a capital) isn't too much of a stretch. To me elements looks a bit odd as I don't see why it should be formatted like code...

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just me not trying to get into too much explanation; obviously it needs more. It's formatted like code to imply that it's a Python list, which I didn't feel was clear before, but if you didn't catch that, then it's still not clear.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah ok, I didn't get that. The constructor accepts a list of elements but that argument isn't most likely called data because there are multiple ways it can be used.

``Overlay`` constructors. For instance, you can use
``hv.Layout(elements)`` or ``hv.Overlay(elements)``.
Loading