<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div>On Jan 22, 2015, at 21:54, Guido van Rossum <<a href="mailto:guido@python.org">guido@python.org</a>> wrote:</div><div><br></div><blockquote type="cite"><div>I'd use an example with round numbers. "For example, to set a tolerance of 5%, pass tol=0.05. The default tolerance is 1e-8."<br></div></blockquote><div><br></div>Hard to beat that for simplicity. +1 on this wording or something similar instead of the current abstract version.<br><blockquote type="cite"><div><br>On Thursday, January 22, 2015, Chris Barker <<a href="mailto:chris.barker@noaa.gov">chris.barker@noaa.gov</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div><div><div><div>Andrew,<br><br></div>I totally agree that it's not going to be that clear to folks -- but I'm as stumped as you as to how to make it clear without getting really wordy.<br><br></div></div>Also, I think the percent error use case is infrequent, more likely would be that a relative tolerance of 1e-8 means that the numbers are the same to within about 8 significant decimal figures. After all, not many people think in terms of 0.0000001%<br><br>Suggestions gladly accepted!<br><br></div>-Chris<br><br><br><div><div><div><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Jan 22, 2015 at 7:30 PM, Andrew Barnert <span dir="ltr"><<a href="javascript:_e(%7B%7D,'cvml','abarnert@yahoo.com');" target="_blank">abarnert@yahoo.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Overall I like it, but I'm not sure the help on the tol parameter is clear enough for people who don't already know what they want--in other words, the very people this function should be helping.<br>
<br>
In my experience, novices understand relative tolerance immediately if you put it in terms of "within X% of expected", but don't always understand it if you put it in terms of "within X * expected" or, worse, "relative to the magnitude of the expected value". Just using % in there somewhere makes people get the concept.<br>
<br>
Unfortunately, since the API doesn't actually use a percentage--and shouldn't--I'm not sure how to get this across in a one-liner in the help. You can always add something like "(e.g., a relative tolerance of .005 means that the actual value must be within 0.5% of the expected value)", but that's way too verbose.<br>
<br>
(Also, I should note that the people I've explained this to have mostly been people with a US 1960-1990-style basic math education; I can't be sure that people who learned in another country, or in the post-post-new-math era in the US, etc. will respond the same way, although I do have a bit of anecdotal evidence from helping a few people on forums like StackOverflow that seems to imply they do.)<br>
<br>
Sent from a random iPhone<br>
<div><div><br>
On Jan 22, 2015, at 16:40, Chris Barker <<a href="javascript:_e(%7B%7D,'cvml','chris.barker@noaa.gov');" target="_blank">chris.barker@noaa.gov</a>> wrote:<br>
<br>
> is the relative tolerance -- it is the amount of error<br>
> allowed, relative to the magnitude of the expected value.<br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br><div><br>Christopher Barker, Ph.D.<br>Oceanographer<br><br>Emergency Response Division<br>NOAA/NOS/OR&R            (206) 526-6959   voice<br>7600 Sand Point Way NE   (206) 526-6329   fax<br>Seattle, WA  98115       (206) 526-6317   main reception<br><br><a href="javascript:_e(%7B%7D,'cvml','Chris.Barker@noaa.gov');" target="_blank">Chris.Barker@noaa.gov</a></div>
</div></div></div></div></div></div></div>
</blockquote><br><br>-- <br>--Guido van Rossum (on iPad)<br>
</div></blockquote></body></html>