DOC: Adding details on normalization for variance functions.

Author: dnmiller

doc/source/gotchas.rst

@@ -302,3 +302,13 @@ of the new set of columns rather than the original ones:
    :suppress:
 
    os.remove('tmp.csv')
+
+
+Differences with NumPy 
+----------------------
+For Series and DataFrame objects, ``var`` normalizes by ``N-1`` to produce
+unbiased estimates of the sample variance, while NumPy's ``var`` normalizes
+by N, which measures the variance of the sample. Note that ``cov``
+normalizes by ``N-1`` in both pandas and NumPy.
+
+

pandas/core/frame.py

@@ -4052,6 +4052,9 @@ def cov(self):
         Returns
         -------
         y : DataFrame
+
+        y contains the covariance matrix of the DataFrame's time series.
+        The covariance is normalized by N-1 (unbiased estimator).
         """
         numeric_df = self._get_numeric_data()
         cols = numeric_df.columns
@@ -4368,7 +4371,10 @@ def mad(self, axis=0, skipna=True, level=None):
 
     @Substitution(name='variance', shortname='var',
                   na_action=_doc_exclude_na, extras='')
-    @Appender(_stat_doc)
+    @Appender(_stat_doc +
+        """
+        Normalized by N-1 (unbiased estimator).
+        """)
     def var(self, axis=0, skipna=True, level=None, ddof=1):
         if level is not None:
             return self._agg_by_level('var', axis=axis, level=level,
@@ -4378,7 +4384,10 @@ def var(self, axis=0, skipna=True, level=None, ddof=1):
 
     @Substitution(name='standard deviation', shortname='std',
                   na_action=_doc_exclude_na, extras='')
-    @Appender(_stat_doc)
+    @Appender(_stat_doc + 
+        """
+        Normalized by N-1 (unbiased estimator).
+        """)
     def std(self, axis=0, skipna=True, level=None, ddof=1):
         if level is not None:
             return self._agg_by_level('std', axis=axis, level=level,

pandas/core/series.py

@@ -1151,7 +1151,10 @@ def max(self, axis=None, out=None, skipna=True, level=None):
 
     @Substitution(name='standard deviation', shortname='stdev',
                   na_action=_doc_exclude_na, extras='')
-    @Appender(_stat_doc)
+    @Appender(_stat_doc + 
+        """
+        Normalized by N-1 (unbiased estimator).
+        """)
     def std(self, axis=None, dtype=None, out=None, ddof=1, skipna=True,
             level=None):
         if level is not None:
@@ -1161,7 +1164,10 @@ def std(self, axis=None, dtype=None, out=None, ddof=1, skipna=True,
 
     @Substitution(name='variance', shortname='var',
                   na_action=_doc_exclude_na, extras='')
-    @Appender(_stat_doc)
+    @Appender(_stat_doc + 
+        """
+        Normalized by N-1 (unbiased estimator).
+        """)
     def var(self, axis=None, dtype=None, out=None, ddof=1, skipna=True,
             level=None):
         if level is not None:
@@ -1474,6 +1480,8 @@ def cov(self, other):
         Returns
         -------
         covariance : float
+
+        Normalized by N-1 (unbiased estimator).
         """
         this, other = self.align(other, join='inner')
         if len(this) == 0: