1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.math4.legacy.stat.interval;
18
19 import org.apache.commons.math4.legacy.exception.NotPositiveException;
20 import org.apache.commons.math4.legacy.exception.NotStrictlyPositiveException;
21 import org.apache.commons.math4.legacy.exception.NumberIsTooLargeException;
22 import org.apache.commons.math4.legacy.exception.OutOfRangeException;
23
24 /**
25 * Interface to generate confidence intervals for a binomial proportion.
26 *
27 * @see <a
28 * href="http://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval">Binomial
29 * proportion confidence interval (Wikipedia)</a>
30 * @since 3.3
31 */
32 public interface BinomialConfidenceInterval {
33
34 /**
35 * Create a confidence interval for the true probability of success
36 * of an unknown binomial distribution with the given observed number
37 * of trials, successes and confidence level.
38 * <p>
39 * Preconditions:
40 * <ul>
41 * <li>{@code numberOfTrials} must be positive</li>
42 * <li>{@code numberOfSuccesses} may not exceed {@code numberOfTrials}</li>
43 * <li>{@code confidenceLevel} must be strictly between 0 and 1 (exclusive)</li>
44 * </ul>
45 *
46 * @param numberOfTrials number of trials
47 * @param numberOfSuccesses number of successes
48 * @param confidenceLevel desired probability that the true probability of
49 * success falls within the returned interval
50 * @return Confidence interval containing the probability of success with
51 * probability {@code confidenceLevel}
52 * @throws NotStrictlyPositiveException if {@code numberOfTrials <= 0}.
53 * @throws NotPositiveException if {@code numberOfSuccesses < 0}.
54 * @throws NumberIsTooLargeException if {@code numberOfSuccesses > numberOfTrials}.
55 * @throws OutOfRangeException if {@code confidenceLevel} is not in the interval {@code (0, 1)}.
56 */
57 ConfidenceInterval createInterval(int numberOfTrials, int numberOfSuccesses, double confidenceLevel)
58 throws NotStrictlyPositiveException, NotPositiveException,
59 NumberIsTooLargeException, OutOfRangeException;
60 }