001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math3.stat.interval;
018
019import org.apache.commons.math3.exception.MathIllegalArgumentException;
020import org.apache.commons.math3.exception.util.LocalizedFormats;
021
022/**
023 * Represents an interval estimate of a population parameter.
024 *
025 * @since 3.3
026 */
027public class ConfidenceInterval {
028
029    /** Lower endpoint of the interval */
030    private double lowerBound;
031
032    /** Upper endpoint of the interval */
033    private double upperBound;
034
035    /**
036     * The asserted probability that the interval contains the population
037     * parameter
038     */
039    private double confidenceLevel;
040
041    /**
042     * Create a confidence interval with the given bounds and confidence level.
043     * <p>
044     * Preconditions:
045     * <ul>
046     * <li>{@code lower} must be strictly less than {@code upper}</li>
047     * <li>{@code confidenceLevel} must be strictly between 0 and 1 (exclusive)</li>
048     * </ul>
049     * </p>
050     *
051     * @param lowerBound lower endpoint of the interval
052     * @param upperBound upper endpoint of the interval
053     * @param confidenceLevel coverage probability
054     * @throws MathIllegalArgumentException if the preconditions are not met
055     */
056    public ConfidenceInterval(double lowerBound, double upperBound, double confidenceLevel) {
057        checkParameters(lowerBound, upperBound, confidenceLevel);
058        this.lowerBound = lowerBound;
059        this.upperBound = upperBound;
060        this.confidenceLevel = confidenceLevel;
061    }
062
063    /**
064     * @return the lower endpoint of the interval
065     */
066    public double getLowerBound() {
067        return lowerBound;
068    }
069
070    /**
071     * @return the upper endpoint of the interval
072     */
073    public double getUpperBound() {
074        return upperBound;
075    }
076
077    /**
078     * @return the asserted probability that the interval contains the
079     *         population parameter
080     */
081    public double getConfidenceLevel() {
082        return confidenceLevel;
083    }
084
085    /**
086     * @return String representation of the confidence interval
087     */
088    @Override
089    public String toString() {
090        return "[" + lowerBound + ";" + upperBound + "] (confidence level:" + confidenceLevel + ")";
091    }
092
093    /**
094     * Verifies that (lower, upper) is a valid non-empty interval and confidence
095     * is strictly between 0 and 1.
096     *
097     * @param lower lower endpoint
098     * @param upper upper endpoint
099     * @param confidence confidence level
100     */
101    private void checkParameters(double lower, double upper, double confidence) {
102        if (lower >= upper) {
103            throw new MathIllegalArgumentException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper);
104        }
105        if (confidence <= 0 || confidence >= 1) {
106            throw new MathIllegalArgumentException(LocalizedFormats.OUT_OF_BOUNDS_CONFIDENCE_LEVEL, confidence, 0, 1);
107        }
108    }
109}