DOC: Improved the docstring of pandas.DataFrame.values

pandas-dev · jorisvandenbossche · Mar 10, 2018 · Mar 9, 2018 · Mar 9, 2018 · Mar 9, 2018
commit 4d510e175c9ae1c3fa2afc772dbf99fa8a6ab54d
diff --git a/pandas/core/generic.py b/pandas/core/generic.py
@@ -4245,22 +4245,37 @@ def values(self):
 
         Examples
         --------
-        >>> df = pd.DataFrame([('falcon', 'bird',    389.0),
-        ...                    ('parrot', 'bird',     24.0),
-        ...                    ('lion',   'mammal',   80.5),
-        ...                    ('monkey', 'mammal', np.nan)],
-        ...                   columns=('name', 'class', 'max_speed'))
+        A DataFrame where all columns are the same type (e.g., int64) results
+        in an ndarray of the same type.
+
+        >>> df = pd.DataFrame({'age':    [ 3,  29],
+        ...                    'height': [94, 170],
+        ...                    'weight': [31, 115]})
         >>> df
-             name   class  max_speed
-        0  falcon    bird      389.0
-        1  parrot    bird       24.0
-        2    lion  mammal       80.5
-        3  monkey  mammal        NaN
+           age  height  weight
+        0    3      94      31
+        1   29     170     115
         >>> df.values
-        array([['falcon', 'bird', 389.0],
-               ['parrot', 'bird', 24.0],
-               ['lion', 'mammal', 80.5],
-               ['monkey', 'mammal', nan]], dtype=object)
+        array([[  3,  94,  31],
+               [ 29, 170, 115]], dtype=int64)
+
+        A DataFrame with mixed type columns(e.g., str/object, int64, float32)
+        results in an ndarray of the broadest type encompasing these mixed
+        types (e.g., object).
+
+        >>> df2 = pd.DataFrame([('parrot',   24.0, 'second'),
+        ...                     ('lion',     80.5, 1),
+        ...                     ('monkey', np.nan, None)],
+        ...                   columns=('name', 'max_speed', 'rank'))
+        >>> df2.dtypes
+        name          object
+        max_speed    float64
+        rank          object
+        dtype: object
+        >>> df2.values
+        array([['parrot', 24.0, 'second'],
+               ['lion', 80.5, 1],
+               ['monkey', nan, None]], dtype=object)
 
         Notes
         -----
@@ -4272,7 +4287,13 @@ def values(self):
         e.g. If the dtypes are float16 and float32, dtype will be upcast to
         float32.  If dtypes are int32 and uint8, dtype will be upcast to
         int32. By :func:`numpy.find_common_type` convention, mixing int64
-        and uint64 will result in a flot64 dtype.
+        and uint64 will result in a float64 dtype.
+
+        See Also
+        --------
+        pandas.DataFrame.from_records : Creating a DataFrame from a numpy.ndarray
+        pandas.DataFrame.keys : Retrieving the 'info axis' (column names)
+        pandas.DataFrame.columns : Retrieving the column names
         """
         self._consolidate_inplace()
         return self._data.as_array(transpose=self._AXIS_REVERSED)