Documentation Typos

[ea42gh]

Customizing_Plots.html

I made notes as I was reading the documentation. Here are observations and suggestions as they occurred to me. They are of course idiosyncratic...

• [x] Start with 3 types of options that can be specified by function arguments or by cell magics:

  • plot options '%opts Element []' control aspects of a plot such as ...
  • style options '%opts Element ()'
  • normalization options '%opts Element {}' Options are specific to the backend (different backends have different capabilities). The following examples use bokeh.

• [x] 'instance that normally work behind the scenes': work -> works

• [x] '(2) this customization syntax that is specific': that is specific -> is specific

• [x] 'Let's start with the one difference to how': difference compared to what? Just start with the effect of '.cols(2)'

• [x] 'Let's start with the one difference to how...with the curve above the spikes instead of next to it.': -> rephrase; default behavior is that plot elements appear on the same level: the spikes will be to the right of the curve. 'cols()' adjusts the relative positions of the plot.

• [x] '%%output size=150': sizing and element arrangement is very backend specific. You might consider a whole section describing how to control size and arrangement options in bokeh and in matplotlib: I struggled with it a lot when I got started with hv.

• [x] 'a corresponding cell line magic to set things globally': -> The corresponding cell line magic '%output size=150' sets this default globally for all cells in the notebook.

• [x] 'These list of keywords are plot options': -> 'These keywords are' or 'This list is'

• [x] 'spikes plot underneath which is why we specified': Interchange parts of the sentence. The height and width specifications yield an elongated curve plot ...

• [x] 'plot will give us a suitable millisecond below': a plot does not give milliseconds

• [x] ' style options with are Bokeh specific': ->'options which are' or maybe 'Bokeh specific style options'

• [x] 'Lastly we have use the %%opts cell magic to': -> The final cell magic customizes the Spikes element

• [x] 'Now we have worked through a concrete examples,...': -> 'Now that...example,...' Better yet, tighten the sentence.

• [x] 'Here are the three types of visualization options in HoloViews': This sentence is superfluous, especially if you introduce the notion of option types earlier.

• [x] 'The default backend is matplotlib,': default??? the notebook extension statement at the top of the notebook made Bokeh the default backend

• [x] 'to see the plotting library's own documentation': ->to read the documentation

• [x] 'if one of those backends were selected': -> the different capabilities of each backend would result in backened specific style options.

• [x] 'orthogonally to the above two types, to control normalization. Normalization': -> 'orthogonally to the above two types: normalization refers to'

• [x] 'For instance, two images normalized together': The first effect of normalization users would notice is shared axes, rather than shared color mapping in images. 'normalized together': ?? How about stating that hv by default chooses to share axes, colormaps, ..., and only then provide the examples of two plots with expanded axes and two images with common colormaps

• [x] 'For this reason, all options are fundamentally reduced to a simple dictionary format': ?? -> A simpler sentence such as 'All options are expressed using python dictionaries.' List the opts() call default names: opts(style=dict(), plot=dict(), normalization???= dict()), then show the example.

• [x] 'the succinct string format describe below, ': -> ... described...

• [x] ' use of yaml is that yaml to literals and cannot express': fix sentence

• [x] '[[path] [normalization] [plotting options] [style options]]+': this is not the grammar that is actually implemented? E.g., normalization typically follows style in the documentation examples.

• [x] 'cell magic : IPython specific syntax applies to displayed object': -> ... applies in the notebook cell in which the statement appears

• [x] 'As shown in the examples above, customizes a ': -> ... above, %%opts statements customize ...

• [x] 'If supplied with an object, acts like': sentence subject?

• [x] 'If not object is supplied': -> If no object...

[jlstevens]

@ea42gh Thanks for all these suggestions!

Skimming your suggested fixes, I think they look good and I am happy to implement them myself (but that will probably have to wait till after I get back from SciPy). Alternatively, I would be very happy to accept a PR!

[ea42gh]

Dimensioned_Containers.html

Overall component: work out the different representation options a bit more After reading this page, I came away with 'Holomap==sliders, other ways to represent data, uh, what were they again??

Might add scrubber output too?

• [x] 'to explore a multi-dimensional parameter spaces visually': -> to explore multi... space visually
• [x] 'positioning it on a grid or simply laying consecutively in a layout.': subject? -> positioning plots consecutively or on a grid
• [x] 'we could instead use a DynamicMap': why? mention lazy evaluation
• [x] 'when working with relatively small datasets a HoloMap is preferred':why?
• [x] 'then pass that dictionay': dictionary
• [ ] carrier freq.modulation freq graph: isn't there a way to display units with dimensions? use it here?
• [x] 'difficult to compare the data, therefore we can': therefore -> we can however
• [x] 'but have a visual representation': a different visual
• [x] 'GridSpace - An 1-2D': A 1D or 2D
• [x] ' Here we will overlay the carrier frequencies and grid the modulation frequency': what happened to the size of the last graph below this line?
• [x] 'Sice this simply represents': Since
• [x] 'ds = hv.Dataset(grid.table())': what is a Dataset? Add a 1 line explanation
• [x] ' want to merge to HoloMaps which vary ' : want to merge ?data
• [x] this doc comes to a very abrupt end

[ea42gh]

http://holoviews.org/user_guide/Composing_Elements.html (copied from issue 1661 to consolidate minor doc fixes in one place)

• [x] "These containers are unliked the dimensioned containers where you cannot mix types" replace unliked with unlike, "associated keys." with "associated key." Is it "dimensioned containers" or "dimension containers"? Both appear in this sentence
• [x] "As you can compose an mix of HoloViews elements" should read 'a mix'
• [x] The paragraph starting with "A Layout cannot contain NdLayouts but can otherwise contain" ends with "The one restriction on what you can put in a Layout". For clarity I suggest removing the restriction in the first sentence.
• [x] "First let us see how to index the the above example" remove one instance of "the" you might mention that 'print(layout)' will show the group and level names
• [x] 'A Overlay cannot contain any other container type other than NdOverlay ' should read ' can contain any container type other than'?? This sentence needs fixing
• [x] 'Overlay shared many of the same concepts as layout." replace 'shared' with'shares'
• [x] 'First composition with * instead of +:' just shows the resulting plot. Consider adding a sentence emphasizing the result.
• [x] 'As Overlay can be built explicitly from a list, just like a Layout :' change 'As Overlay' to 'An Overlay'
• [x] 'Like Layout , Overlay is fundamentally a tree-structures' replace tree-structures with tree-structure
• [x] Next sentence has ' Overlay obejcts' rather than objects.

[ea42gh]

Building_Composite_Objects.html

• [x] 'useful to look at the description': As you work through this guide, it will be useful to refer to
• [x] 'that violate this hierarchy': you have not really defined 'the' hierarchy The next paragraphs define it, move them up?
• [x] 'representation of entire Layout object': of the entire
• [x] 'print(layout)' appears twice
• [x] ' one of these HoloMap objects, by indexing': remove the comma
• [x] 'The NdOverlay is so named because it is an overlay of items indexed by dimensions, unlike the regular attribute-access overlay types.': should this be at the beginning?
• [x] 'indexes': indices
• [ ] 'Show map/traverse etc to go through the hierarchy': document is incomplete
• [x] ' construct an appropriate organization.. do want to organize': do want to represent(??) / an appropriate data hierarchy(??)
• [x] ' but only because of the extra dimension(s) provided by the enclosed HoloMap objects': Huh??? What does this really mean? Also 'act as if' seems no different from 'can be done'?? This paragraph should be reworded.

[ea42gh]

Live_Data.html

• [x] ' in the sense they only compute only as much data': remove second only
• [x] ' it support multiple different':it supported
• [x] ' Instead supplying some initial': instead of
• [x] ' we will supply the waves_image function instead': remove instead
• [x] 'the second suggestion proposed by the warning': second suggestion listed in(??)/ second suggestion in (??)
• [x] ' is set to that value. ': is set to a new value.
• [x] 'It is important to note that whenever the redim method is used': why important? 'Note that whenever'
• [x] 'This DynamicMap above allows exploration' : The DynamicMap
• [x] ' cell magic allows you to style DynamicMaps can be styled': remove can be styled
• [x] ' one of the most common way ': ways
• [x] Increase the sampling xs = np.linspace(0,2*np.pi) from 50 to 100 for theplotin the "partially discretize" section (subsampling artifact in last curve set)
• [x] ' display of elements according the minimum': using the
• [x] 'according the usual semantics': inaccord with
• [x] ' can always have the option': always use / always have (remove can)

[jlstevens]

@ea42gh Thanks again!

Just note that PR #1730 fixed a bunch of typos and has now been merged. I believe it only fixed typos that could be found with a spellchecker though...

[ea42gh]

@jlstevens I intend to start editing the actual pages sometimes after this coming weekend: I'll start from the latest docs in github, and will ask how best to transfer changes back. I expect "PR", however that is done, since I already have a checked out version

[jbednar]

If you haven't started editing, you might hold off until Wednesday night, because I'm about to take a transatlantic flight and will probably have some time to make general edits that will probably cover things that you've listed.

[jbednar]

http://holoviews.org/user_guide/Composing_Elements.html(copied from issue 1661 to consolidate minor doc fixes in one place)

All the above comments on 02_Composing_Elements should be addressed in PR https://github.com/ioam/holoviews/pull/1752 , which also cleans up 01_Annotating_Data. I checked all of the boxes in that section above to indicate that they have been dealt with. I don't have any other outstanding changes to the docs, so we'd welcome a PR covering any of the other guides listed above.

[ea42gh]

Plots_and_Renderers.html Code:

• [x] sorted(hv.Store.registry['matplotlib'].items())[0:5] fails with python3
• [x] model = bokeh_layout_plot.update(0) bokeh_layout_plot was not imported

[philippjfr]

Thanks @ea42gh!

[ea42gh]

There is also a print without parens that I fixed in my version together with some of the phrasing. I'll need to struggle with git some more to submit the changes...

[jlstevens]

We should fix the remaining issues shortly after 1.9.2 if we can. And yes, thanks @ea42gh!

[ea42gh]

waiting for those fixes, then I'll start reading the docs again! (some vacation time coming up...)

[jlstevens]

The PR referenced above will implement a subset of the remaining suggestions (not all as some suggestions require additional discussion).

[jlstevens]

Most of the checkboxes are ticked off now (once the PR above is merged). As there are a few outstanding items, I'll now assign this issue to 1.11.

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.