This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author unutbu
Recipients georg.brandl, unutbu
Date 2008-09-12.21:41:30
SpamBayes Score 1.6172508e-11
Marked as misclassified No
Message-id <581721.76640.qm@web39606.mail.mud.yahoo.com>
In-reply-to <1220992931.31.0.275267255012.issue3318@psf.upfronthosting.co.za>
Content
Let B = the set of all possible times on a particular machine (the machine on which the timeit script is run).
Let x = the minimum of B. 
Then "the lowest value is an upper bound for x".
This is correct, accurate, not an oxymoron.
The above does not refer to an ideal machine, nor does it refer to the fastest machine.

Let's try to agree on a principle: Every statement made in documentation should be correct and have meaningful substance. 

If we can agree on this principle, then I think we will have to agree that the paragraph:

"""
Note: It's tempting to calculate mean and standard deviation from the result vector and report these. However, this is not very useful. In a typical case, the lowest value gives a lower bound for how fast your machine can run the given code snippet; higher values in the result vector are typically not caused by variability in Python's speed, but by other processes interfering with your timing accuracy. So the min() of the result is probably the only number you should be interested in. After that, you should look at the entire vector and apply common sense rather than statistics.
"""

can not stay the way it is.

Here is why:

The correctness of the sentence, "In a typical case, the lowest value gives a lower bound for how fast your machine can run the given code snippet" relies on the presence of the word "typical". But what does typical mean? Here we come to the second half of the principle: the sentence must have meaning and substance.

By relying on the word typical, we reduce the sentence to meaninglessness, because there is no way to endow the word "typical" with meaning without also making the sentence incorrect. For example, if we tried to make the sentence 

"In a typical case, the lowest value gives a lower bound for how fast your machine can run the given code snippet"

mean

"If you run the snippet 100 times, the lowest value would be less than the time in 50 cases"

then you run the risk of making a claim that may not be true.

The critical reader will be forced to simply throw away the entire paragraph as nonsense.

The uncritical reader may believe the output of timeit.repeat is less than or equal to x, which is simply not true. The output of timeit.repeat might not even be near x (whatever near means!) if for example, the script were being run on a server while lots of other processes were being run, or if there was a process with nice priority -19 running simultaneously.

What do you think we should do?
History
Date User Action Args
2008-09-12 21:41:33unutbusetrecipients: + unutbu, georg.brandl
2008-09-12 21:41:32unutbulinkissue3318 messages
2008-09-12 21:41:30unutbucreate