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 * https://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
18 /*
19 * This is not the original file distributed by the Apache Software Foundation
20 * It has been modified by the Hipparchus project
21 */
22 package org.hipparchus.stat.interval;
23
24 import org.hipparchus.exception.LocalizedCoreFormats;
25 import org.hipparchus.exception.MathIllegalArgumentException;
26 import org.hipparchus.stat.LocalizedStatFormats;
27
28 /**
29 * Represents an interval estimate of a population parameter.
30 */
31 public class ConfidenceInterval {
32
33 /** Lower endpoint of the interval */
34 private double lowerBound;
35
36 /** Upper endpoint of the interval */
37 private double upperBound;
38
39 /**
40 * The asserted probability that the interval contains the population
41 * parameter
42 */
43 private double confidenceLevel;
44
45 /**
46 * Create a confidence interval with the given bounds and confidence level.
47 * <p>
48 * Preconditions:
49 * </p>
50 * <ul>
51 * <li>{@code lower} must be strictly less than {@code upper}</li>
52 * <li>{@code confidenceLevel} must be strictly between 0 and 1 (exclusive)</li>
53 * </ul>
54 *
55 * @param lowerBound lower endpoint of the interval
56 * @param upperBound upper endpoint of the interval
57 * @param confidenceLevel coverage probability
58 * @throws MathIllegalArgumentException if the preconditions are not met
59 */
60 public ConfidenceInterval(double lowerBound, double upperBound, double confidenceLevel) {
61 checkParameters(lowerBound, upperBound, confidenceLevel);
62 this.lowerBound = lowerBound;
63 this.upperBound = upperBound;
64 this.confidenceLevel = confidenceLevel;
65 }
66
67 /** Get lower endpoint of the interval.
68 * @return the lower endpoint of the interval
69 */
70 public double getLowerBound() {
71 return lowerBound;
72 }
73
74 /** Get upper endpoint of the interval.
75 * @return the upper endpoint of the interval
76 */
77 public double getUpperBound() {
78 return upperBound;
79 }
80
81 /** Get asserted probability that the interval contains the population parameter.
82 * @return the asserted probability that the interval contains the
83 * population parameter
84 */
85 public double getConfidenceLevel() {
86 return confidenceLevel;
87 }
88
89 /** Get String representation of the confidence interval.
90 * @return String representation of the confidence interval
91 */
92 @Override
93 public String toString() {
94 return "[" + lowerBound + ";" + upperBound + "] (confidence level:" + confidenceLevel + ")";
95 }
96
97 /**
98 * Verifies that (lower, upper) is a valid non-empty interval and confidence
99 * is strictly between 0 and 1.
100 *
101 * @param lower lower endpoint
102 * @param upper upper endpoint
103 * @param confidence confidence level
104 */
105 private void checkParameters(double lower, double upper, double confidence) {
106 if (lower >= upper) {
107 throw new MathIllegalArgumentException(LocalizedCoreFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND,
108 lower, upper);
109 }
110 if (confidence <= 0 || confidence >= 1) {
111 throw new MathIllegalArgumentException(LocalizedStatFormats.OUT_OF_BOUNDS_CONFIDENCE_LEVEL,
112 confidence, 0, 1);
113 }
114 }
115 }