View Javadoc
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 }