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.math4.legacy.stat.interval;
018
019import org.apache.commons.math4.legacy.exception.MathIllegalArgumentException;
020import org.apache.commons.math4.legacy.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     *
050     * @param lowerBound lower endpoint of the interval
051     * @param upperBound upper endpoint of the interval
052     * @param confidenceLevel coverage probability
053     * @throws MathIllegalArgumentException if the preconditions are not met
054     */
055    public ConfidenceInterval(double lowerBound, double upperBound, double confidenceLevel) {
056        checkParameters(lowerBound, upperBound, confidenceLevel);
057        this.lowerBound = lowerBound;
058        this.upperBound = upperBound;
059        this.confidenceLevel = confidenceLevel;
060    }
061
062    /**
063     * @return the lower endpoint of the interval
064     */
065    public double getLowerBound() {
066        return lowerBound;
067    }
068
069    /**
070     * @return the upper endpoint of the interval
071     */
072    public double getUpperBound() {
073        return upperBound;
074    }
075
076    /**
077     * @return the asserted probability that the interval contains the
078     *         population parameter
079     */
080    public double getConfidenceLevel() {
081        return confidenceLevel;
082    }
083
084    /**
085     * @return String representation of the confidence interval
086     */
087    @Override
088    public String toString() {
089        return "[" + lowerBound + ";" + upperBound + "] (confidence level:" + confidenceLevel + ")";
090    }
091
092    /**
093     * Verifies that (lower, upper) is a valid non-empty interval and confidence
094     * is strictly between 0 and 1.
095     *
096     * @param lower lower endpoint
097     * @param upper upper endpoint
098     * @param confidence confidence level
099     */
100    private void checkParameters(double lower, double upper, double confidence) {
101        if (lower >= upper) {
102            throw new MathIllegalArgumentException(LocalizedFormats.LOWER_BOUND_NOT_BELOW_UPPER_BOUND, lower, upper);
103        }
104        if (confidence <= 0 || confidence >= 1) {
105            throw new MathIllegalArgumentException(LocalizedFormats.OUT_OF_BOUNDS_CONFIDENCE_LEVEL, confidence, 0, 1);
106        }
107    }
108}