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.distribution; 018 019import org.apache.commons.math3.exception.NotStrictlyPositiveException; 020import org.apache.commons.math3.exception.OutOfRangeException; 021import org.apache.commons.math3.exception.util.LocalizedFormats; 022import org.apache.commons.math3.random.RandomGenerator; 023import org.apache.commons.math3.random.Well19937c; 024import org.apache.commons.math3.util.FastMath; 025import org.apache.commons.math3.util.MathUtils; 026 027/** 028 * This class implements the Logistic distribution. 029 * 030 * @see <a href="http://en.wikipedia.org/wiki/Logistic_distribution">Logistic Distribution (Wikipedia)</a> 031 * @see <a href="http://mathworld.wolfram.com/LogisticDistribution.html">Logistic Distribution (Mathworld)</a> 032 * 033 * @since 3.4 034 */ 035public class LogisticDistribution extends AbstractRealDistribution { 036 037 /** Serializable version identifier. */ 038 private static final long serialVersionUID = 20141003; 039 040 /** The location parameter. */ 041 private final double mu; 042 /** The scale parameter. */ 043 private final double s; 044 045 /** 046 * Build a new instance. 047 * <p> 048 * <b>Note:</b> this constructor will implicitly create an instance of 049 * {@link Well19937c} as random generator to be used for sampling only (see 050 * {@link #sample()} and {@link #sample(int)}). In case no sampling is 051 * needed for the created distribution, it is advised to pass {@code null} 052 * as random generator via the appropriate constructors to avoid the 053 * additional initialisation overhead. 054 * 055 * @param mu location parameter 056 * @param s scale parameter (must be positive) 057 * @throws NotStrictlyPositiveException if {@code beta <= 0} 058 */ 059 public LogisticDistribution(double mu, double s) { 060 this(new Well19937c(), mu, s); 061 } 062 063 /** 064 * Build a new instance. 065 * 066 * @param rng Random number generator 067 * @param mu location parameter 068 * @param s scale parameter (must be positive) 069 * @throws NotStrictlyPositiveException if {@code beta <= 0} 070 */ 071 public LogisticDistribution(RandomGenerator rng, double mu, double s) { 072 super(rng); 073 074 if (s <= 0.0) { 075 throw new NotStrictlyPositiveException(LocalizedFormats.NOT_POSITIVE_SCALE, s); 076 } 077 078 this.mu = mu; 079 this.s = s; 080 } 081 082 /** 083 * Access the location parameter, {@code mu}. 084 * 085 * @return the location parameter. 086 */ 087 public double getLocation() { 088 return mu; 089 } 090 091 /** 092 * Access the scale parameter, {@code s}. 093 * 094 * @return the scale parameter. 095 */ 096 public double getScale() { 097 return s; 098 } 099 100 /** {@inheritDoc} */ 101 public double density(double x) { 102 double z = (x - mu) / s; 103 double v = FastMath.exp(-z); 104 return 1 / s * v / ((1.0 + v) * (1.0 + v)); 105 } 106 107 /** {@inheritDoc} */ 108 public double cumulativeProbability(double x) { 109 double z = 1 / s * (x - mu); 110 return 1.0 / (1.0 + FastMath.exp(-z)); 111 } 112 113 /** {@inheritDoc} */ 114 @Override 115 public double inverseCumulativeProbability(double p) throws OutOfRangeException { 116 if (p < 0.0 || p > 1.0) { 117 throw new OutOfRangeException(p, 0.0, 1.0); 118 } else if (p == 0) { 119 return 0.0; 120 } else if (p == 1) { 121 return Double.POSITIVE_INFINITY; 122 } 123 return s * Math.log(p / (1.0 - p)) + mu; 124 } 125 126 /** {@inheritDoc} */ 127 public double getNumericalMean() { 128 return mu; 129 } 130 131 /** {@inheritDoc} */ 132 public double getNumericalVariance() { 133 return (MathUtils.PI_SQUARED / 3.0) * (1.0 / (s * s)); 134 } 135 136 /** {@inheritDoc} */ 137 public double getSupportLowerBound() { 138 return Double.NEGATIVE_INFINITY; 139 } 140 141 /** {@inheritDoc} */ 142 public double getSupportUpperBound() { 143 return Double.POSITIVE_INFINITY; 144 } 145 146 /** {@inheritDoc} */ 147 public boolean isSupportLowerBoundInclusive() { 148 return false; 149 } 150 151 /** {@inheritDoc} */ 152 public boolean isSupportUpperBoundInclusive() { 153 return false; 154 } 155 156 /** {@inheritDoc} */ 157 public boolean isSupportConnected() { 158 return true; 159 } 160 161}