Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/statsmodels/genmod/families/varfuncs.py : 67%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2Variance functions for use with the link functions in statsmodels.family.links
3"""
4import numpy as np
5FLOAT_EPS = np.finfo(float).eps
8class VarianceFunction(object):
9 """
10 Relates the variance of a random variable to its mean. Defaults to 1.
12 Methods
13 -------
14 call
15 Returns an array of ones that is the same shape as `mu`
17 Notes
18 -----
19 After a variance function is initialized, its call method can be used.
21 Alias for VarianceFunction:
22 constant = VarianceFunction()
24 See Also
25 --------
26 statsmodels.genmod.families.family
27 """
29 def __call__(self, mu):
30 """
31 Default variance function
33 Parameters
34 ----------
35 mu : array_like
36 mean parameters
38 Returns
39 -------
40 v : ndarray
41 ones(mu.shape)
42 """
43 mu = np.asarray(mu)
44 return np.ones(mu.shape, np.float64)
46 def deriv(self, mu):
47 """
48 Derivative of the variance function v'(mu)
49 """
50 return np.zeros_like(mu)
53constant = VarianceFunction()
54constant.__doc__ = """
55The call method of constant returns a constant variance, i.e., a vector of
56ones.
58constant is an alias of VarianceFunction()
59"""
62class Power(object):
63 """
64 Power variance function
66 Parameters
67 ----------
68 power : float
69 exponent used in power variance function
71 Methods
72 -------
73 call
74 Returns the power variance
76 Notes
77 -----
78 Formulas
79 V(mu) = numpy.fabs(mu)**power
81 Aliases for Power:
82 mu = Power()
83 mu_squared = Power(power=2)
84 mu_cubed = Power(power=3)
85 """
87 def __init__(self, power=1.):
88 self.power = power
90 def __call__(self, mu):
91 """
92 Power variance function
94 Parameters
95 ----------
96 mu : array_like
97 mean parameters
99 Returns
100 -------
101 variance : ndarray
102 numpy.fabs(mu)**self.power
103 """
104 return np.power(np.fabs(mu), self.power)
106 def deriv(self, mu):
107 """
108 Derivative of the variance function v'(mu)
110 May be undefined at zero.
111 """
113 der = self.power * np.fabs(mu) ** (self.power - 1)
114 ii = np.flatnonzero(mu < 0)
115 der[ii] *= -1
116 return der
119mu = Power()
120mu.__doc__ = """
121Returns np.fabs(mu)
123Notes
124-----
125This is an alias of Power()
126"""
127mu_squared = Power(power=2)
128mu_squared.__doc__ = """
129Returns np.fabs(mu)**2
131Notes
132-----
133This is an alias of statsmodels.family.links.Power(power=2)
134"""
135mu_cubed = Power(power=3)
136mu_cubed.__doc__ = """
137Returns np.fabs(mu)**3
139Notes
140-----
141This is an alias of statsmodels.family.links.Power(power=3)
142"""
145class Binomial(object):
146 """
147 Binomial variance function
149 Parameters
150 ----------
151 n : int, optional
152 The number of trials for a binomial variable. The default is 1 for
153 p in (0,1)
155 Methods
156 -------
157 call
158 Returns the binomial variance
160 Notes
161 -----
162 Formulas :
164 V(mu) = p * (1 - p) * n
166 where p = mu / n
168 Alias for Binomial:
169 binary = Binomial()
171 A private method _clean trims the data by machine epsilon so that p is
172 in (0,1)
173 """
175 def __init__(self, n=1):
176 self.n = n
178 def _clean(self, p):
179 return np.clip(p, FLOAT_EPS, 1 - FLOAT_EPS)
181 def __call__(self, mu):
182 """
183 Binomial variance function
185 Parameters
186 ----------
187 mu : array_like
188 mean parameters
190 Returns
191 -------
192 variance : ndarray
193 variance = mu/n * (1 - mu/n) * self.n
194 """
195 p = self._clean(mu / self.n)
196 return p * (1 - p) * self.n
198 # TODO: inherit from super
199 def deriv(self, mu):
200 """
201 Derivative of the variance function v'(mu)
202 """
203 return 1 - 2*mu
206binary = Binomial()
207binary.__doc__ = """
208The binomial variance function for n = 1
210Notes
211-----
212This is an alias of Binomial(n=1)
213"""
216class NegativeBinomial(object):
217 '''
218 Negative binomial variance function
220 Parameters
221 ----------
222 alpha : float
223 The ancillary parameter for the negative binomial variance function.
224 `alpha` is assumed to be nonstochastic. The default is 1.
226 Methods
227 -------
228 call
229 Returns the negative binomial variance
231 Notes
232 -----
233 Formulas :
235 V(mu) = mu + alpha*mu**2
237 Alias for NegativeBinomial:
238 nbinom = NegativeBinomial()
240 A private method _clean trims the data by machine epsilon so that p is
241 in (0,inf)
242 '''
244 def __init__(self, alpha=1.):
245 self.alpha = alpha
247 def _clean(self, p):
248 return np.clip(p, FLOAT_EPS, np.inf)
250 def __call__(self, mu):
251 """
252 Negative binomial variance function
254 Parameters
255 ----------
256 mu : array_like
257 mean parameters
259 Returns
260 -------
261 variance : ndarray
262 variance = mu + alpha*mu**2
263 """
264 p = self._clean(mu)
265 return p + self.alpha*p**2
267 def deriv(self, mu):
268 """
269 Derivative of the negative binomial variance function.
270 """
272 p = self._clean(mu)
273 return 1 + 2 * self.alpha * p
276nbinom = NegativeBinomial()
277nbinom.__doc__ = """
278Negative Binomial variance function.
280Notes
281-----
282This is an alias of NegativeBinomial(alpha=1.)
283"""