Sage: Ticket #11284: Document all options of Poset.show and Poset.plot
https://trac.sagemath.org/ticket/11284
<p>
This branch adds documentation to <code>FinitePoset.show</code> and <code>FinitePoset.plot</code>. It also lets one use a parameter of <code>plot</code> when calling <code>show</code>.
</p>
<p>
It also removes the <code>show</code> and <code>plot</code> methods from <code>HasseDiagram</code>: those two functions were never used anywhere as <code>FinitePoset.plot</code> calls <code>DiGraph.plot</code> directly. They also accepted parameters that were never used in the code.
</p>
<p>
As <code>HasseDiagram</code> is a internal class (not meant for users) no deprecation was added.
</p>
<p>
Nathann
</p>
<p>
P.S.: while it seems that the code removes arguments from show and plot it is not the case: these arguments are handled as they should by the subcall to the graph plot function.
</p>
en-usSagehttps://trac.sagemath.org/chrome/site/logo_sagemath_trac.png
https://trac.sagemath.org/ticket/11284
Trac 1.1.6nthieryTue, 03 May 2011 18:40:20 GMTkeywords changed
https://trac.sagemath.org/ticket/11284#comment:1
https://trac.sagemath.org/ticket/11284#comment:1
<ul>
<li><strong>keywords</strong>
<em>days30</em> added
</li>
</ul>
TicketjdemeyerTue, 13 Aug 2013 15:35:53 GMTmilestone changed
https://trac.sagemath.org/ticket/11284#comment:2
https://trac.sagemath.org/ticket/11284#comment:2
<ul>
<li><strong>milestone</strong>
changed from <em>sage-5.11</em> to <em>sage-5.12</em>
</li>
</ul>
Ticketvbraun_spamThu, 30 Jan 2014 21:20:52 GMTmilestone changed
https://trac.sagemath.org/ticket/11284#comment:3
https://trac.sagemath.org/ticket/11284#comment:3
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.1</em> to <em>sage-6.2</em>
</li>
</ul>
Ticketvbraun_spamTue, 06 May 2014 15:20:58 GMTmilestone changed
https://trac.sagemath.org/ticket/11284#comment:4
https://trac.sagemath.org/ticket/11284#comment:4
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.2</em> to <em>sage-6.3</em>
</li>
</ul>
Ticketvbraun_spamSun, 10 Aug 2014 16:51:03 GMTmilestone changed
https://trac.sagemath.org/ticket/11284#comment:5
https://trac.sagemath.org/ticket/11284#comment:5
<ul>
<li><strong>milestone</strong>
changed from <em>sage-6.3</em> to <em>sage-6.4</em>
</li>
</ul>
TicketjmantysaloThu, 02 Oct 2014 09:01:04 GMTcc changed
https://trac.sagemath.org/ticket/11284#comment:6
https://trac.sagemath.org/ticket/11284#comment:6
<ul>
<li><strong>cc</strong>
<em>jmantysalo</em> added
</li>
</ul>
TicketjmantysaloSat, 04 Oct 2014 08:08:10 GMT
https://trac.sagemath.org/ticket/11284#comment:7
https://trac.sagemath.org/ticket/11284#comment:7
<p>
Relating to this: Where is default pink color defined? For example
</p>
<pre class="wiki">G=DiGraph({0:[1]})
G.show(vertex_colors='pink')
G.show(vertex_colors={'#ff00ff':[0]})
</pre><p>
shows kind of a bug: color of element 1 changes from pink to blue when setting color of 0 to red.
</p>
<p>
Examples to <code>show()</code> could be something like
</p>
<pre class="wiki">P.show(vertex_colors={'red':P.maximal_elements()})
</pre><p>
or
</p>
<pre class="wiki">for c in P.maximal_chains():
P.show(vertex_colors={'red':c})
</pre><p>
Where P would be suitable poset.
</p>
TicketjmantysaloFri, 12 Dec 2014 12:14:43 GMTcc changed
https://trac.sagemath.org/ticket/11284#comment:8
https://trac.sagemath.org/ticket/11284#comment:8
<ul>
<li><strong>cc</strong>
<em>ncohen</em> added
</li>
</ul>
<p>
Comment fron ncohen on <a class="closed ticket" href="https://trac.sagemath.org/ticket/17477" title="enhancement: "Internal" documentation of posets (closed: wontfix)">#17477</a>: "The problem comes from <code>HasseDiagram.plot</code>. This argument [i.e. <code>label_font_size</code>], and two others, are totally ignored. Also, it seems that this <code>HasseDiagram.plot</code> function is never used: <code>Poset.plot</code> calls <code>GenericGraph.plot</code> directly."
</p>
TicketncohenSat, 13 Dec 2014 04:49:48 GMT
https://trac.sagemath.org/ticket/11284#comment:9
https://trac.sagemath.org/ticket/11284#comment:9
<p>
(running tests for public/11284 at the moment)
</p>
TicketncohenSat, 13 Dec 2014 05:53:34 GMTstatus, description changed; commit, branch, author set
https://trac.sagemath.org/ticket/11284#comment:10
https://trac.sagemath.org/ticket/11284#comment:10
<ul>
<li><strong>status</strong>
changed from <em>new</em> to <em>needs_review</em>
</li>
<li><strong>commit</strong>
set to <em>329de0c33099d582cede2d26c307cf3da4d7ae16</em>
</li>
<li><strong>description</strong>
modified (<a href="/ticket/11284?action=diff&version=10">diff</a>)
</li>
<li><strong>branch</strong>
set to <em>public/11284</em>
</li>
<li><strong>author</strong>
set to <em>Nathann Cohen</em>
</li>
</ul>
<p>
Ready for review !
</p>
<p>
Nathann
</p>
<hr />
<p>
New commits:
</p>
<table class="wiki">
<tr><td><a class="ext-link" href="http://git.sagemath.org/sage.git/commit/?id=329de0c33099d582cede2d26c307cf3da4d7ae16"><span class="icon"></span>329de0c</a></td><td><code>trac #11284: Document all options of Poset.show and Poset.plot</code>
</td></tr></table>
TicketncohenSat, 13 Dec 2014 05:54:58 GMTdescription changed
https://trac.sagemath.org/ticket/11284#comment:11
https://trac.sagemath.org/ticket/11284#comment:11
<ul>
<li><strong>description</strong>
modified (<a href="/ticket/11284?action=diff&version=11">diff</a>)
</li>
</ul>
TicketjmantysaloSat, 13 Dec 2014 09:07:38 GMT
https://trac.sagemath.org/ticket/11284#comment:12
https://trac.sagemath.org/ticket/11284#comment:12
<p>
Docstring "Displays the Hasse diagram of the poset." should be "Display the Hasse diagram of the poset." according to PEP whose number I don't remember.
</p>
TicketncohenSat, 13 Dec 2014 09:41:56 GMT
https://trac.sagemath.org/ticket/11284#comment:13
https://trac.sagemath.org/ticket/11284#comment:13
<p>
Okay. Well, if this is the only comment you have to make to give this patch a positive review I will add a commit, otherwise I will do it along with the other remarks if you do not mind <code>:-P</code>
</p>
<p>
Nathann
</p>
TicketjmantysaloSat, 13 Dec 2014 16:38:44 GMT
https://trac.sagemath.org/ticket/11284#comment:14
https://trac.sagemath.org/ticket/11284#comment:14
<p>
I still don't see how the user can find <code>figsize</code>-option. And IMO it is one of most important --- it is good to make smaller with poset of ~7 elements, almost necessary to make bigger with poset of 15 elements.
</p>
<p>
<code>cover_labels</code> put labels over the line, not near the line --- but this is place for another ticket.
</p>
<p>
Maybe <code>element_labels</code> could have explanation saying that it must be injective. And that <code>cover_labels</code> may be non-injective.
</p>
<p>
Hmm... how about some nice example of colors? Poset with top element and color by möbius function from top to element? Or a lattice where deleting some elements would make it non-lattice and those drawn as red? But there is no easy way to make graphics in documentation, so maybe no.
</p>
<p>
Thinking... Any opinions from others?
</p>
TicketncohenSat, 13 Dec 2014 16:57:38 GMT
https://trac.sagemath.org/ticket/11284#comment:15
https://trac.sagemath.org/ticket/11284#comment:15
<p>
Yo !
</p>
<blockquote class="citation">
<p>
I still don't see how the user can find <code>figsize</code>-option. And IMO it is one of most important
</p>
</blockquote>
<p>
True. Actually, it can be found in the doc of Poset.show which mentions the doc of Graphics.show, where it appears. Not exactly as trivial as it should.
</p>
<blockquote class="citation">
<p>
<code>cover_labels</code> put labels over the line, not near the line --- but this is place for another ticket.
</p>
</blockquote>
<p>
For this kind of stuff, I would say that people will try and see for themselves. The drawing is better than a long explanation <code>:-P</code>
</p>
<blockquote class="citation">
<p>
Maybe <code>element_labels</code> could have explanation saying that it must be injective. And that <code>cover_labels</code> may be non-injective.
</p>
</blockquote>
<p>
Of changing the code to support non-injective labellings ! That is the most proper way to solve it.
</p>
<blockquote class="citation">
<p>
Hmm... how about some nice example of colors? Poset with top element and color by möbius function from top to element? Or a lattice where deleting some elements would make it non-lattice and those drawn as red? But there is no easy way to make graphics in documentation, so maybe no.
</p>
</blockquote>
<p>
You can still add an example, even if the code figure does not appear... It may change someday <code>:-)</code>
</p>
<p>
Nathann
</p>
TicketjmantysaloSat, 13 Dec 2014 17:26:00 GMT
https://trac.sagemath.org/ticket/11284#comment:16
https://trac.sagemath.org/ticket/11284#comment:16
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/11284#comment:15" title="Comment 15">ncohen</a>:
</p>
<blockquote class="citation">
<blockquote class="citation">
<p>
I still don't see how the user can find <code>figsize</code>-option. And IMO it is one of most important
</p>
</blockquote>
<p>
True. Actually, it can be found in the doc of Poset.show which mentions the doc of Graphics.show, where it appears. Not exactly as trivial as it should.
</p>
</blockquote>
<p>
?? <code>P._hasse_diagram.show?</code> does not show it. I think that user must do at least two jumps to find it.
</p>
<blockquote class="citation">
<blockquote class="citation">
<p>
Maybe <code>element_labels</code> could have explanation saying that it must be injective. And that <code>cover_labels</code> may be non-injective.
</p>
</blockquote>
<p>
Of changing the code to support non-injective labellings ! That is the most proper way to solve it.
</p>
</blockquote>
<p>
Of course.
</p>
TicketncohenSat, 13 Dec 2014 17:37:34 GMT
https://trac.sagemath.org/ticket/11284#comment:17
https://trac.sagemath.org/ticket/11284#comment:17
<blockquote class="citation">
<blockquote class="citation">
<p>
True. Actually, it can be found in the doc of Poset.show which mentions the doc of Graphics.show, where it appears. Not exactly as trivial as it should.
</p>
</blockquote>
<p>
?? <code>P._hasse_diagram.show?</code> does not show it. I think that user must do at least two jumps to find it.
</p>
</blockquote>
<p>
Nonono, not <code>P._hasse_diagram.show</code>. This function does not even exist anymore when this branch is applied. I was talking of <code>P.show?</code> after this branch is applied. Though it is easier to read if you browse it through the html pages.
</p>
<p>
Nathann
</p>
TicketjmantysaloSat, 13 Dec 2014 18:03:44 GMTmilestone changed; reviewer set
https://trac.sagemath.org/ticket/11284#comment:18
https://trac.sagemath.org/ticket/11284#comment:18
<ul>
<li><strong>reviewer</strong>
set to <em>Jori Mäntysalo</em>
</li>
<li><strong>milestone</strong>
changed from <em>sage-6.4</em> to <em>sage-6.5</em>
</li>
</ul>
<p>
Replying to <a class="ticket" href="https://trac.sagemath.org/ticket/11284#comment:17" title="Comment 17">ncohen</a>:
</p>
<blockquote class="citation">
<p>
Nonono, not <code>P._hasse_diagram.show</code>. This function does not even exist anymore when this branch is applied.
</p>
</blockquote>
<p>
It does, because Hasse diagram is <code>DiGraph</code>. Just like for example <code>P._hasse_diagram.is_connected()</code> is available.
</p>
<p>
But in any case, you are right. I was looking <code>Graph.show?</code>, not <code>Graphics.show?</code>.
</p>
<p>
You can mark this as positive review if you want. If not, I'll get back to this on monday and think about adding some examples.
</p>
TicketncohenSun, 14 Dec 2014 01:53:09 GMTstatus changed
https://trac.sagemath.org/ticket/11284#comment:19
https://trac.sagemath.org/ticket/11284#comment:19
<ul>
<li><strong>status</strong>
changed from <em>needs_review</em> to <em>positive_review</em>
</li>
</ul>
<p>
Yoooooo !
</p>
<blockquote class="citation">
<p>
It does, because Hasse diagram is <code>DiGraph</code>. Just like for example <code>P._hasse_diagram.is_connected()</code> is available.
</p>
</blockquote>
<p>
Oops right sorry <code>:-D</code>
</p>
<p>
In this case, however, you should also see a mention of <code>Graphics.show</code>:
</p>
<p>
<a href="http://www.sagemath.org/doc/reference/graphs/sage/graphs/generic_graph.html#sage.graphs.generic_graph.GenericGraph.show">http://www.sagemath.org/doc/reference/graphs/sage/graphs/generic_graph.html#sage.graphs.generic_graph.GenericGraph.show</a>
</p>
<blockquote class="citation">
<p>
You can mark this as positive review if you want. If not, I'll get back to this on monday and think about adding some examples.
</p>
</blockquote>
<p>
Works for me, thanks !
</p>
<p>
Nathann
</p>
TicketjmantysaloMon, 15 Dec 2014 05:48:46 GMT
https://trac.sagemath.org/ticket/11284#comment:20
https://trac.sagemath.org/ticket/11284#comment:20
<p>
No more comments for now because of <a class="closed ticket" href="https://trac.sagemath.org/ticket/17498" title="enhancement: Pictures in the doc through ".. plot::" directive (closed: fixed)">#17498</a>. Maybe I'll get back to this after it has been applied.
</p>
TicketvbraunMon, 15 Dec 2014 17:50:55 GMTstatus, branch changed; resolution set
https://trac.sagemath.org/ticket/11284#comment:21
https://trac.sagemath.org/ticket/11284#comment:21
<ul>
<li><strong>status</strong>
changed from <em>positive_review</em> to <em>closed</em>
</li>
<li><strong>resolution</strong>
set to <em>fixed</em>
</li>
<li><strong>branch</strong>
changed from <em>public/11284</em> to <em>329de0c33099d582cede2d26c307cf3da4d7ae16</em>
</li>
</ul>
Ticket