add example showing (proper) histogram legends

[kcrisman]

Apparently they don't always show up properly, and in any case our doc only has the labels, not the legend setting documented (directly in the hist doc, I mean). See ​this ask.sagemath question for more details.

[kcrisman]

​According to the doc:

The pad and spacing parameters are measured in font-size units. e.g., a fontsize of 10 points and a handlelength=5 implies a handlelength of 50 points.

So we would have to be careful in setting handlelength as in the ask.sagemath solution, looking at many legend examples.

[asutosh7hota]

The Legend class can be considered as a container of legend handles and legend texts. Creation of corresponding legend handles from the plot elements in the axes or figures (e.g., lines, patches, etc.) are specified by the handler map, which defines the mapping between the plot elements and the legend handlers to be used.

Using histogram legends can sometimes yield results in which nothing seems to happen even when the code has no error. There is a common problem that legend is not initialised and set_legend_options doesn't seem to do anything. However, it's not a bug rather it is the way it should be defined that would help to yield a result.

• labelspacing : the vertical space between the legend entries
• handlelength : the length of the legend handles
• handleheight : the height of the legend handles
• handletextpad: the pad between the legend handle and text
• borderaxespad: the pad between the axes and legend border
• columnspacing: the spacing between columns
• title : the legend title
• and many more parameters would decide how the labels would look like.

d1=[1,1,1,1,2,2,2,3,3,3]
d2=[4,4,4,4,3,3,3,2,2,2] 
h=histogram([ d1,d1 ],label=["d1","d2"],stacked=True, color=['blue', 'red'])
h.legend(True)
h.set_legend_options(handlelength=1,handleheight=1,handletextpad=1,borderaxespad=2)
h

In the above example h.set_legend_options() can take in numerous parameter to customize the representation of the labels in histograms.

d1=[randint(0,10) for i in range(20)]
d2=[randint(0,10) for i in range(20)]
h=histogram([d1,d2],label=["d1","d2"])

h.legend(True)
h.set_legend_options(handlelength=1,handleheight=1,fontsize=50,labelspacing=0,title="Parameters")
h

title, fontsize, handlerheight etc parameters can be modified as per the requirement of the user.

[asutosh7hota]

I would love to write a detailed documentation on the legend class in context to histograms and also extend to plot(). I would need ideas and insights on what other important points I should take into consideration. It would be highly appreciated from my side.

Thank you

[asutosh7hota]

New commits:

​a6223c1

added example showing (proper) histogram legends

[arpitdm]

Hi,

​a6223c1

added example showing (proper) histogram legends

Documentation does not compile.

Also, several Sage documentation ​ conventions are not being followed. For instance:

• labelspacing, handlelength, etc are defined in the matplotlib docs and should not be defined here again.
• Using histogram legends can sometimes yield results in which nothing seems to happen even when the code has no error. There is a common problem that legend is not initialised and set_legend_options doesn't seem to do anything.However, it's not a bug rather it is the way it should be defined that would help to yield a result. - This is bad explanation. This shouldn't be present. Please rewrite by having a small explanation for the new doctest(s) and the doctest(s) itself.

Best, Arpit.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​2a1c678

Wiki formatting & paraphrasing for examples

[arpitdm]

Hi,

There are a few more changes needed:

1. The Legend class can be considered as a container of legend handles and legend texts.Creation of corresponding legend handles from the plot elements in the axes or figures (e.g., lines, patches, etc.) are specified by the handler map, which defines the mapping between the plot elements and the legend handlers to be used. - is not very clear. Calling the Legend class a container is slightly incorrect. The docstrings are meant to be simple and informative enough for the user to understand what different functionalities they have access to. I don't think this is needed.
2. Histogram legends has a 'set_legend_options' which can take in various parameters that can customise the labels.Different parameters would decide how the labels would look like. Considering the following examples:: - The last line is unnecessary. Add a space after end of sentence and check grammar please. And use back ticks to denote special names like so set_legend_options.
3. pdf latex documentation does not build.
4. (Trivial) Add spaces. For instance, sage: d1 = [1,1,1,1,2,2,2,3,3,3].
5. The first two examples you added are nearly identical in that they don't really demonstrate different functionalities. Instead, you can just use one example and describe in the docstring that there are several options whose details can be found in matplotlib documentations by adding an appropriate hyperlink.
6. The third example you added is a repeat of one that has been written above. This is not redundant.
7. You haven't mentioned the output of the examples in the documentation. See previous examples to understand what you have to write.

The HTML documentation builds. But the latex documentation is showing errors. Can you check that once please?

Thanks.

-Arpit.

[git]

Branch pushed to git repo; I updated commit sha1. New commits:

​0508821

Removed redundant docstring

[asutosh7hota]

Replying to arpitdm:

Hi,

There are a few more changes needed:

1. The Legend class can be considered as a container of legend handles and legend texts.Creation of corresponding legend handles from the plot elements in the axes or figures (e.g., lines, patches, etc.) are specified by the handler map, which defines the mapping between the plot elements and the legend handlers to be used. - is not very clear. Calling the Legend class a container is slightly incorrect. The docstrings are meant to be simple and informative enough for the user to understand what different functionalities they have access to. I don't think this is needed.

I have removed this section as it makes the documentation complex for a new user.

2. Histogram legends has a 'set_legend_options' which can take in various parameters that can customise the labels.Different parameters would decide how the labels would look like. Considering the following examples:: - The last line is unnecessary. Add a space after end of sentence and check grammar please. And use back ticks to denote special names like so set_legend_options.

Removed the unnecessary line in the end.

3. pdf latex documentation does not build.

I would like to know more about latex doctest . I am currently checking just HTML testing.

4. (Trivial) Add spaces. For instance, sage: d1 = [1,1,1,1,2,2,2,3,3,3].

Spaces has been added .

5. The first two examples you added are nearly identical in that they don't really demonstrate different functionalities. Instead, you can just use one example and describe in the docstring that there are several options whose details can be found in matplotlib documentations by adding an appropriate hyperlink.

Example removed and refered by a hyperlink.

6. The third example you added is a repeat of one that has been written above. This is not redundant.

7. You haven't mentioned the output of the examples in the documentation. See previous examples to understand what you have to write.

Am I supposed to put the plot over here? because the output over here is a graphical representation of data.

The HTML documentation builds. But the latex documentation is showing errors. Can you check that once please?

Thanks.

-Arpit.

[chapoton]

red branch