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

1from textwrap import dedent 

2 

3from pandas.compat.numpy import function as nv 

4from pandas.util._decorators import Appender, Substitution 

5 

6from pandas.core.window.common import WindowGroupByMixin, _doc_template, _shared_docs 

7from pandas.core.window.rolling import _Rolling_and_Expanding 

8 

9 

10class Expanding(_Rolling_and_Expanding): 

11 """ 

12 Provide expanding transformations. 

13 

14 Parameters 

15 ---------- 

16 min_periods : int, default 1 

17 Minimum number of observations in window required to have a value 

18 (otherwise result is NA). 

19 center : bool, default False 

20 Set the labels at the center of the window. 

21 axis : int or str, default 0 

22 

23 Returns 

24 ------- 

25 a Window sub-classed for the particular operation 

26 

27 See Also 

28 -------- 

29 rolling : Provides rolling window calculations. 

30 ewm : Provides exponential weighted functions. 

31 

32 Notes 

33 ----- 

34 By default, the result is set to the right edge of the window. This can be 

35 changed to the center of the window by setting ``center=True``. 

36 

37 Examples 

38 -------- 

39 

40 >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]}) 

41 B 

42 0 0.0 

43 1 1.0 

44 2 2.0 

45 3 NaN 

46 4 4.0 

47 

48 >>> df.expanding(2).sum() 

49 B 

50 0 NaN 

51 1 1.0 

52 2 3.0 

53 3 3.0 

54 4 7.0 

55 """ 

56 

57 _attributes = ["min_periods", "center", "axis"] 

58 

59 def __init__(self, obj, min_periods=1, center=False, axis=0, **kwargs): 

60 super().__init__(obj=obj, min_periods=min_periods, center=center, axis=axis) 

61 

62 @property 

63 def _constructor(self): 

64 return Expanding 

65 

66 def _get_window(self, other=None, **kwargs): 

67 """ 

68 Get the window length over which to perform some operation. 

69 

70 Parameters 

71 ---------- 

72 other : object, default None 

73 The other object that is involved in the operation. 

74 Such an object is involved for operations like covariance. 

75 

76 Returns 

77 ------- 

78 window : int 

79 The window length. 

80 """ 

81 axis = self.obj._get_axis(self.axis) 

82 length = len(axis) + (other is not None) * len(axis) 

83 

84 other = self.min_periods or -1 

85 return max(length, other) 

86 

87 _agg_see_also_doc = dedent( 

88 """ 

89 See Also 

90 -------- 

91 DataFrame.expanding.aggregate 

92 DataFrame.rolling.aggregate 

93 DataFrame.aggregate 

94 """ 

95 ) 

96 

97 _agg_examples_doc = dedent( 

98 """ 

99 Examples 

100 -------- 

101 

102 >>> df = pd.DataFrame(np.random.randn(10, 3), columns=['A', 'B', 'C']) 

103 >>> df 

104 A B C 

105 0 -2.385977 -0.102758 0.438822 

106 1 -1.004295 0.905829 -0.954544 

107 2 0.735167 -0.165272 -1.619346 

108 3 -0.702657 -1.340923 -0.706334 

109 4 -0.246845 0.211596 -0.901819 

110 5 2.463718 3.157577 -1.380906 

111 6 -1.142255 2.340594 -0.039875 

112 7 1.396598 -1.647453 1.677227 

113 8 -0.543425 1.761277 -0.220481 

114 9 -0.640505 0.289374 -1.550670 

115 

116 >>> df.ewm(alpha=0.5).mean() 

117 A B C 

118 0 -2.385977 -0.102758 0.438822 

119 1 -1.464856 0.569633 -0.490089 

120 2 -0.207700 0.149687 -1.135379 

121 3 -0.471677 -0.645305 -0.906555 

122 4 -0.355635 -0.203033 -0.904111 

123 5 1.076417 1.503943 -1.146293 

124 6 -0.041654 1.925562 -0.588728 

125 7 0.680292 0.132049 0.548693 

126 8 0.067236 0.948257 0.163353 

127 9 -0.286980 0.618493 -0.694496 

128 """ 

129 ) 

130 

131 @Substitution( 

132 see_also=_agg_see_also_doc, 

133 examples=_agg_examples_doc, 

134 versionadded="", 

135 klass="Series/Dataframe", 

136 axis="", 

137 ) 

138 @Appender(_shared_docs["aggregate"]) 

139 def aggregate(self, func, *args, **kwargs): 

140 return super().aggregate(func, *args, **kwargs) 

141 

142 agg = aggregate 

143 

144 @Substitution(name="expanding") 

145 @Appender(_shared_docs["count"]) 

146 def count(self, **kwargs): 

147 return super().count(**kwargs) 

148 

149 @Substitution(name="expanding") 

150 @Appender(_shared_docs["apply"]) 

151 def apply(self, func, raw=False, args=(), kwargs={}): 

152 return super().apply(func, raw=raw, args=args, kwargs=kwargs) 

153 

154 @Substitution(name="expanding") 

155 @Appender(_shared_docs["sum"]) 

156 def sum(self, *args, **kwargs): 

157 nv.validate_expanding_func("sum", args, kwargs) 

158 return super().sum(*args, **kwargs) 

159 

160 @Substitution(name="expanding") 

161 @Appender(_doc_template) 

162 @Appender(_shared_docs["max"]) 

163 def max(self, *args, **kwargs): 

164 nv.validate_expanding_func("max", args, kwargs) 

165 return super().max(*args, **kwargs) 

166 

167 @Substitution(name="expanding") 

168 @Appender(_shared_docs["min"]) 

169 def min(self, *args, **kwargs): 

170 nv.validate_expanding_func("min", args, kwargs) 

171 return super().min(*args, **kwargs) 

172 

173 @Substitution(name="expanding") 

174 @Appender(_shared_docs["mean"]) 

175 def mean(self, *args, **kwargs): 

176 nv.validate_expanding_func("mean", args, kwargs) 

177 return super().mean(*args, **kwargs) 

178 

179 @Substitution(name="expanding") 

180 @Appender(_shared_docs["median"]) 

181 def median(self, **kwargs): 

182 return super().median(**kwargs) 

183 

184 @Substitution(name="expanding", versionadded="") 

185 @Appender(_shared_docs["std"]) 

186 def std(self, ddof=1, *args, **kwargs): 

187 nv.validate_expanding_func("std", args, kwargs) 

188 return super().std(ddof=ddof, **kwargs) 

189 

190 @Substitution(name="expanding", versionadded="") 

191 @Appender(_shared_docs["var"]) 

192 def var(self, ddof=1, *args, **kwargs): 

193 nv.validate_expanding_func("var", args, kwargs) 

194 return super().var(ddof=ddof, **kwargs) 

195 

196 @Substitution(name="expanding") 

197 @Appender(_doc_template) 

198 @Appender(_shared_docs["skew"]) 

199 def skew(self, **kwargs): 

200 return super().skew(**kwargs) 

201 

202 _agg_doc = dedent( 

203 """ 

204 Examples 

205 -------- 

206 

207 The example below will show an expanding calculation with a window size of 

208 four matching the equivalent function call using `scipy.stats`. 

209 

210 >>> arr = [1, 2, 3, 4, 999] 

211 >>> import scipy.stats 

212 >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") 

213 -1.200000 

214 >>> print(f"{scipy.stats.kurtosis(arr, bias=False):.6f}") 

215 4.999874 

216 >>> s = pd.Series(arr) 

217 >>> s.expanding(4).kurt() 

218 0 NaN 

219 1 NaN 

220 2 NaN 

221 3 -1.200000 

222 4 4.999874 

223 dtype: float64 

224 """ 

225 ) 

226 

227 @Appender(_agg_doc) 

228 @Substitution(name="expanding") 

229 @Appender(_shared_docs["kurt"]) 

230 def kurt(self, **kwargs): 

231 return super().kurt(**kwargs) 

232 

233 @Substitution(name="expanding") 

234 @Appender(_shared_docs["quantile"]) 

235 def quantile(self, quantile, interpolation="linear", **kwargs): 

236 return super().quantile( 

237 quantile=quantile, interpolation=interpolation, **kwargs 

238 ) 

239 

240 @Substitution(name="expanding") 

241 @Appender(_doc_template) 

242 @Appender(_shared_docs["cov"]) 

243 def cov(self, other=None, pairwise=None, ddof=1, **kwargs): 

244 return super().cov(other=other, pairwise=pairwise, ddof=ddof, **kwargs) 

245 

246 @Substitution(name="expanding") 

247 @Appender(_shared_docs["corr"]) 

248 def corr(self, other=None, pairwise=None, **kwargs): 

249 return super().corr(other=other, pairwise=pairwise, **kwargs) 

250 

251 

252class ExpandingGroupby(WindowGroupByMixin, Expanding): 

253 """ 

254 Provide a expanding groupby implementation. 

255 """ 

256 

257 @property 

258 def _constructor(self): 

259 return Expanding