On Mon, Jun 28, 2010 at 9:37 PM, Vincent Davis <span dir="ltr"><<a href="mailto:vincent@vincentdavis.net">vincent@vincentdavis.net</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div><div></div><div class="h5">On Mon, Jun 28, 2010 at 10:34 PM, Skipper Seabold <<a href="mailto:jsseabold@gmail.com">jsseabold@gmail.com</a>> wrote:<br>
> On Mon, Jun 28, 2010 at 11:14 PM, David Goldsmith<br>
> <<a href="mailto:d.l.goldsmith@gmail.com">d.l.goldsmith@gmail.com</a>> wrote:<br>
>><br>
>> On Mon, Jun 28, 2010 at 6:29 PM, Vincent Davis <<a href="mailto:vincent@vincentdavis.net">vincent@vincentdavis.net</a>> wrote:<br>
>>><br>
>>> On Mon, Jun 28, 2010 at 7:24 PM, Warren Weckesser<br>
>>> <<a href="mailto:warren.weckesser@enthought.com">warren.weckesser@enthought.com</a>> wrote:<br>
>>> > Vincent Davis wrote:<br>
>>> >> On Mon, Jun 28, 2010 at 7:11 PM, Vincent Davis <<a href="mailto:vincent@vincentdavis.net">vincent@vincentdavis.net</a>> wrote:<br>
>>> >><br>
>>> >>> According to the docs factorial2 should return a float or int, float<br>
>>> >>> in the case of exact=False, It does not.<br>
>>> >>><br>
>>> >>><br>
>>> >>>>>> import scipy.misc.common as sc<br>
>>> >>>>>> sc.factorial2(7, exact=False)<br>
>>> >>>>>><br>
>>> >>> array(105.00000000000001)<br>
>>> >>><br>
>>> >>>>>> sc.factorial2(7, exact=True)<br>
>>> >>>>>><br>
>>> >>> 105L<br>
>>> >>><br>
>>> >>>>>> sc.factorial2(8, exact=True)<br>
>>> >>>>>><br>
>>> >>> 384L<br>
>>> >>><br>
>>> >>>>>> sc.factorial2(8, exact=False)<br>
>>> >>>>>><br>
>>> >>> array(384.0)<br>
>>> >>><br>
>>> >>>>>> sc.factorial2(8, exact=False)<br>
>>> >>>>>><br>
>>> >><br>
>>> >> Same with factorial<br>
>>> >><br>
>>> >><br>
>>> >>>>> sc.factorial(5, exact=False)<br>
>>> >>>>><br>
>>> >> array(120.0)<br>
>>> >><br>
>>> >>>>> arr = np.array([3,4,5])<br>
>>> >>>>> sc.factorial(arr, exact=False)<br>
>>> >>>>><br>
>>> >> array([   6.,   24.,  120.])<br>
>>> >><br>
>>> >>>>> sc.factorial(5, exact=True)<br>
>>> >>>>><br>
>>> >> 120L<br>
>>> >><br>
>>> ><br>
>>> > I think the problem is simply that it is an awkward API.  After looking<br>
>>> > at the code for factorial, a more precise description is:<br>
>>> ><br>
>>> > If `exact` is True, `n` must be an integer, and an integer is returned.<br>
>>> ><br>
>>> > If `exact` is False, `n` is array_like, and an array the same shape as<br>
>>> > `n` is returned.<br>
>>><br>
>>> I am finding that when editing the docs it is not always clear if the<br>
>>> problem is the docs or the function.<br>
>>> comb() has a similar issue.<br>
>>><br>
>>> I guess my question is?<br>
>>> My thought is the you factoral(), or comb() return an array only if 1,<br>
>>> exact=False and n is not an array. Basically you get back the same<br>
>>> dtype as input.<br>
>>> That said fixing the docs is just a little easier.<br>
>><br>
>> This issue has come up many times; again, here's the "policy": document desired/intended behavior, not actual behavior - if they differ, and the doc specifies the desired/intended behavior correctly, then file a (code) bug report; if the function is behaving correctly, but the doc doesn't correctly document that behavior, correct the doc in the Wiki; if both are wrong (and there is precedent for this) then both actions must be taken.  What is the implication of this when you encounter this situation while editing the docs?  You must do what you've done: post to the appropriate list, asking which is correct, and wait a little while for a decision; if several days pass and no one responds, re-post; if several days pass and there remains disagreement on the matter, file a bug ticket, so the debate moves over there and "move on."<br>

>><br>
><br>
> Sound good?<br>
><br>
> <a href="http://docs.scipy.org/numpy/Questions+Answers/#documented-and-actual-behavior-differ" target="_blank">http://docs.scipy.org/numpy/Questions+Answers/#documented-and-actual-behavior-differ</a><br>
<br>
</div></div>So whats the desired/intended behavior? i.e. go with what Warren<br>
proposed for the docs or what I proposed for the behavior?<br></blockquote><div><br>This is where you play that waiting game for a bit: you can't count on everyone who has an opinion on the matter (and let's face it: some people's opinions matter more than others in this community, e.g., "when RK speaks, people listen") to have seen this so soon.  Wait a few days, then ask again (if necessary).<br>
<br>DG <br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<font color="#888888"><br>
Vincent<br>
</font><div><div></div><div class="h5"><br>
><br>
> Skipper<br>
> _______________________________________________<br>
> SciPy-Dev mailing list<br>
> <a href="mailto:SciPy-Dev@scipy.org">SciPy-Dev@scipy.org</a><br>
> <a href="http://mail.scipy.org/mailman/listinfo/scipy-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/scipy-dev</a><br>
><br>
_______________________________________________<br>
SciPy-Dev mailing list<br>
<a href="mailto:SciPy-Dev@scipy.org">SciPy-Dev@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/scipy-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/scipy-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br>Mathematician: noun, someone who disavows certainty when their uncertainty set is non-empty, even if that set has measure zero.<br><br>Hope: noun, that delusive spirit which escaped Pandora's jar and, with her lies, prevents mankind from committing a general suicide.  (As interpreted by Robert Graves)<br>