Hide keyboard shortcuts

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 

6 

7 

8class VarianceFunction(object): 

9 """ 

10 Relates the variance of a random variable to its mean. Defaults to 1. 

11 

12 Methods 

13 ------- 

14 call 

15 Returns an array of ones that is the same shape as `mu` 

16 

17 Notes 

18 ----- 

19 After a variance function is initialized, its call method can be used. 

20 

21 Alias for VarianceFunction: 

22 constant = VarianceFunction() 

23 

24 See Also 

25 -------- 

26 statsmodels.genmod.families.family 

27 """ 

28 

29 def __call__(self, mu): 

30 """ 

31 Default variance function 

32 

33 Parameters 

34 ---------- 

35 mu : array_like 

36 mean parameters 

37 

38 Returns 

39 ------- 

40 v : ndarray 

41 ones(mu.shape) 

42 """ 

43 mu = np.asarray(mu) 

44 return np.ones(mu.shape, np.float64) 

45 

46 def deriv(self, mu): 

47 """ 

48 Derivative of the variance function v'(mu) 

49 """ 

50 return np.zeros_like(mu) 

51 

52 

53constant = VarianceFunction() 

54constant.__doc__ = """ 

55The call method of constant returns a constant variance, i.e., a vector of 

56ones. 

57 

58constant is an alias of VarianceFunction() 

59""" 

60 

61 

62class Power(object): 

63 """ 

64 Power variance function 

65 

66 Parameters 

67 ---------- 

68 power : float 

69 exponent used in power variance function 

70 

71 Methods 

72 ------- 

73 call 

74 Returns the power variance 

75 

76 Notes 

77 ----- 

78 Formulas 

79 V(mu) = numpy.fabs(mu)**power 

80 

81 Aliases for Power: 

82 mu = Power() 

83 mu_squared = Power(power=2) 

84 mu_cubed = Power(power=3) 

85 """ 

86 

87 def __init__(self, power=1.): 

88 self.power = power 

89 

90 def __call__(self, mu): 

91 """ 

92 Power variance function 

93 

94 Parameters 

95 ---------- 

96 mu : array_like 

97 mean parameters 

98 

99 Returns 

100 ------- 

101 variance : ndarray 

102 numpy.fabs(mu)**self.power 

103 """ 

104 return np.power(np.fabs(mu), self.power) 

105 

106 def deriv(self, mu): 

107 """ 

108 Derivative of the variance function v'(mu) 

109 

110 May be undefined at zero. 

111 """ 

112 

113 der = self.power * np.fabs(mu) ** (self.power - 1) 

114 ii = np.flatnonzero(mu < 0) 

115 der[ii] *= -1 

116 return der 

117 

118 

119mu = Power() 

120mu.__doc__ = """ 

121Returns np.fabs(mu) 

122 

123Notes 

124----- 

125This is an alias of Power() 

126""" 

127mu_squared = Power(power=2) 

128mu_squared.__doc__ = """ 

129Returns np.fabs(mu)**2 

130 

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 

138 

139Notes 

140----- 

141This is an alias of statsmodels.family.links.Power(power=3) 

142""" 

143 

144 

145class Binomial(object): 

146 """ 

147 Binomial variance function 

148 

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) 

154 

155 Methods 

156 ------- 

157 call 

158 Returns the binomial variance 

159 

160 Notes 

161 ----- 

162 Formulas : 

163 

164 V(mu) = p * (1 - p) * n 

165 

166 where p = mu / n 

167 

168 Alias for Binomial: 

169 binary = Binomial() 

170 

171 A private method _clean trims the data by machine epsilon so that p is 

172 in (0,1) 

173 """ 

174 

175 def __init__(self, n=1): 

176 self.n = n 

177 

178 def _clean(self, p): 

179 return np.clip(p, FLOAT_EPS, 1 - FLOAT_EPS) 

180 

181 def __call__(self, mu): 

182 """ 

183 Binomial variance function 

184 

185 Parameters 

186 ---------- 

187 mu : array_like 

188 mean parameters 

189 

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 

197 

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 

204 

205 

206binary = Binomial() 

207binary.__doc__ = """ 

208The binomial variance function for n = 1 

209 

210Notes 

211----- 

212This is an alias of Binomial(n=1) 

213""" 

214 

215 

216class NegativeBinomial(object): 

217 ''' 

218 Negative binomial variance function 

219 

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. 

225 

226 Methods 

227 ------- 

228 call 

229 Returns the negative binomial variance 

230 

231 Notes 

232 ----- 

233 Formulas : 

234 

235 V(mu) = mu + alpha*mu**2 

236 

237 Alias for NegativeBinomial: 

238 nbinom = NegativeBinomial() 

239 

240 A private method _clean trims the data by machine epsilon so that p is 

241 in (0,inf) 

242 ''' 

243 

244 def __init__(self, alpha=1.): 

245 self.alpha = alpha 

246 

247 def _clean(self, p): 

248 return np.clip(p, FLOAT_EPS, np.inf) 

249 

250 def __call__(self, mu): 

251 """ 

252 Negative binomial variance function 

253 

254 Parameters 

255 ---------- 

256 mu : array_like 

257 mean parameters 

258 

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 

266 

267 def deriv(self, mu): 

268 """ 

269 Derivative of the negative binomial variance function. 

270 """ 

271 

272 p = self._clean(mu) 

273 return 1 + 2 * self.alpha * p 

274 

275 

276nbinom = NegativeBinomial() 

277nbinom.__doc__ = """ 

278Negative Binomial variance function. 

279 

280Notes 

281----- 

282This is an alias of NegativeBinomial(alpha=1.) 

283"""