ENH: add Series & DataFrame .agg/.aggregate to provide convienent

function application that mimics the groupby(..).agg/.aggregate
interface

.apply is now a synonym for .agg, and will accept dict/list-likes
for aggregations

CLN: rename .name attr -> ._selection_name from SeriesGroupby for compat (didn't exist on DataFrameGroupBy)
resolves conflicts w.r.t. setting .name on a groupby object

closes #1623
closes #14464

custom .describe
closes #14483
closes #7014

Author: jreback

pandas/core/base.py

@@ -289,7 +289,9 @@ class SelectionMixin(object):
     }
 
     @property
-    def name(self):
+    def _selection_name(self):
+        """ return a name for myself; this would ideally be the 'name' property, but
+        we cannot conflict with the Series.name property which can be set """
         if self._selection is None:
             return None  # 'result'
         else:
@@ -404,6 +406,26 @@ def aggregate(self, func, *args, **kwargs):
 
     agg = aggregate
 
+    def _try_aggregate_string_function(self, arg, *args, **kwargs):
+        """
+        if arg is a string, then try to operate on it:
+        - try to find a function on ourselves
+        - try to find a numpy function
+        - raise
+
+        """
+        assert isinstance(arg, compat.string_types)
+
+        f = getattr(self, arg, None)
+        if f is not None:
+            return f(*args, **kwargs)
+
+        f = getattr(np, arg, None)
+        if f is not None:
+            return f(self, *args, **kwargs)
+
+        raise ValueError("{} is an unknown string function".format(arg))
+
     def _aggregate(self, arg, *args, **kwargs):
         """
         provide an implementation for the aggregators
@@ -427,14 +449,19 @@ def _aggregate(self, arg, *args, **kwargs):
         is_aggregator = lambda x: isinstance(x, (list, tuple, dict))
         is_nested_renamer = False
 
+        _axis = kwargs.pop('_axis', None)
+        if _axis is None:
+            _axis = getattr(self, 'axis', 0)
         _level = kwargs.pop('_level', None)
+
         if isinstance(arg, compat.string_types):
-            return getattr(self, arg)(*args, **kwargs), None
+            return self._try_aggregate_string_function(arg, *args,
+                                                       **kwargs), None
 
         if isinstance(arg, dict):
 
             # aggregate based on the passed dict
-            if self.axis != 0:  # pragma: no cover
+            if _axis != 0:  # pragma: no cover
                 raise ValueError('Can only pass dict with axis=0')
 
             obj = self._selected_obj
@@ -560,26 +587,33 @@ def _agg(arg, func):
                             ABCDataFrame):
                 result = concat([result[k] for k in keys], keys=keys, axis=1)
             else:
-                from pandas import DataFrame
-                result = DataFrame(result)
+                from pandas import DataFrame, Series
+                try:
+                    result = DataFrame(result)
+                except ValueError:
+                    # we have a dict of scalars
+                    result = Series(result, name=self.name)
 
             return result, True
-        elif hasattr(arg, '__iter__'):
-            return self._aggregate_multiple_funcs(arg, _level=_level), None
+        elif is_list_like(arg) and arg not in compat.string_types:
+            # we require a list, but not an 'str'
+            return self._aggregate_multiple_funcs(arg,
+                                                  _level=_level,
+                                                  _axis=_axis), None
         else:
             result = None
 
-        cy_func = self._is_cython_func(arg)
-        if cy_func and not args and not kwargs:
-            return getattr(self, cy_func)(), None
+        f = self._is_cython_func(arg)
+        if f and not args and not kwargs:
+            return getattr(self, f)(), None
 
         # caller can react
         return result, True
 
-    def _aggregate_multiple_funcs(self, arg, _level):
+    def _aggregate_multiple_funcs(self, arg, _level, _axis):
         from pandas.tools.merge import concat
 
-        if self.axis != 0:
+        if _axis != 0:
             raise NotImplementedError("axis other than 0 is not supported")
 
         if self._selected_obj.ndim == 1:
@@ -617,7 +651,17 @@ def _aggregate_multiple_funcs(self, arg, _level):
                 except SpecificationError:
                     raise
 
-        return concat(results, keys=keys, axis=1)
+        try:
+            return concat(results, keys=keys, axis=1)
+        except TypeError:
+            # shape change
+            from pandas.types.cast import _is_nested_object
+            from pandas import Series
+            result = Series(results, index=keys, name=self.name)
+            if _is_nested_object(result):
+                raise ValueError("cannot combine transform and "
+                                 "aggregation operations")
+            return result
 
     def _shallow_copy(self, obj=None, obj_type=None, **kwargs):
         """ return a new object with the replacement attributes """

pandas/core/frame.py

@@ -4073,6 +4073,39 @@ def diff(self, periods=1, axis=0):
     # ----------------------------------------------------------------------
     # Function application
 
+    def _gotitem(self, key, ndim, subset=None):
+        """
+        sub-classes to define
+        return a sliced object
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : 1,2
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        if subset is None:
+            subset = self
+
+        # TODO: _shallow_copy(subset)?
+        return self[key]
+
+    @Appender(_shared_docs['aggregate'] % _shared_doc_kwargs)
+    def aggregate(self, func, axis=0, *args, **kwargs):
+        axis = self._get_axis_number(axis)
+
+        # TODO: flipped axis
+        result = None
+        if axis == 0:
+            result, how = self._aggregate(func, axis=0, *args, **kwargs)
+        if result is None:
+            return self.apply(func, axis=axis, args=args, **kwargs)
+        return result
+
+    agg = aggregate
+
     def apply(self, func, axis=0, broadcast=False, raw=False, reduce=None,
               args=(), **kwds):
         """
@@ -4128,22 +4161,28 @@ def apply(self, func, axis=0, broadcast=False, raw=False, reduce=None,
         See also
         --------
         DataFrame.applymap: For elementwise operations
+        DataFrame.agg: only perform aggregating type operations
+        DataFrame.transform: only perform transformating type operations
 
         Returns
         -------
         applied : Series or DataFrame
         """
         axis = self._get_axis_number(axis)
-        if kwds or args and not isinstance(func, np.ufunc):
 
+        # dispatch to agg
+        if axis == 0 and isinstance(func, (list, dict)):
+            return self.aggregate(func, axis=axis, *args, **kwds)
+
+        if len(self.columns) == 0 and len(self.index) == 0:
+            return self._apply_empty_result(func, axis, reduce, *args, **kwds)
+
+        if kwds or args and not isinstance(func, np.ufunc):
             def f(x):
                 return func(x, *args, **kwds)
         else:
             f = func
 
-        if len(self.columns) == 0 and len(self.index) == 0:
-            return self._apply_empty_result(func, axis, reduce, *args, **kwds)
-
         if isinstance(f, np.ufunc):
             with np.errstate(all='ignore'):
                 results = f(self.values)

pandas/core/generic.py

@@ -33,7 +33,7 @@
                                 SettingWithCopyError, SettingWithCopyWarning,
                                 AbstractMethodError)
 
-from pandas.core.base import PandasObject
+from pandas.core.base import PandasObject, SelectionMixin
 from pandas.core.index import (Index, MultiIndex, _ensure_index,
                                InvalidIndexError)
 import pandas.core.indexing as indexing
@@ -91,7 +91,7 @@ def _single_replace(self, to_replace, method, inplace, limit):
     return result
 
 
-class NDFrame(PandasObject):
+class NDFrame(PandasObject, SelectionMixin):
     """
     N-dimensional analogue of DataFrame. Store multi-dimensional in a
     size-mutable, labeled data structure
@@ -428,6 +428,16 @@ def size(self):
         """number of elements in the NDFrame"""
         return np.prod(self.shape)
 
+    @property
+    def _selected_obj(self):
+        """ internal compat with SelectionMixin """
+        return self
+
+    @property
+    def _obj_with_exclusions(self):
+        """ internal compat with SelectionMixin """
+        return self
+
     def _expand_axes(self, key):
         new_axes = []
         for k, ax in zip(key, self.axes):
@@ -2707,6 +2717,61 @@ def pipe(self, func, *args, **kwargs):
         else:
             return func(self, *args, **kwargs)
 
+    _shared_docs['aggregate'] = ("""
+    Aggregate using input function or dict of {column ->
+    function}
+
+    .. versionadded:: 0.19.2
+
+    Parameters
+    ----------
+    arg : function or dict
+        Function to use for aggregating groups. If a function, must either
+        work when passed a DataFrame or when passed to DataFrame.apply. If
+        passed a dict, the keys must be DataFrame column names.
+
+        Accepted Combinations are:
+          - string cythonized function name
+          - function
+          - list of functions
+          - dict of columns -> functions
+          - nested dict of names -> dicts of functions
+
+    Notes
+    -----
+    Numpy functions mean/median/prod/sum/std/var are special cased so the
+    default behavior is applying the function along axis=0
+    (e.g., np.mean(arr_2d, axis=0)) as opposed to
+    mimicking the default Numpy behavior (e.g., np.mean(arr_2d)).
+
+    Returns
+    -------
+    aggregated : %(klass)s
+
+    See also
+    --------
+    """)
+
+    _shared_docs['transform'] = ("""
+    Call function producing a like-indexed %(klass)s
+    and return a %(klass)s with the transformed values`
+
+    .. versionadded:: 0.19.2
+
+    Parameters
+    ----------
+    func : function, callable or string
+        To apply to column
+
+    Examples
+    --------
+    >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
+
+    Returns
+    -------
+    transformed : %(klass)s
+    """)
+
     # ----------------------------------------------------------------------
     # Attribute access
 
@@ -5517,6 +5582,17 @@ def ewm(self, com=None, span=None, halflife=None, alpha=None,
 
         cls.ewm = ewm
 
+        @Appender(_shared_docs['transform'] % _shared_doc_kwargs)
+        def transform(self, func, *args, **kwargs):
+            result = self.agg(func, *args, **kwargs)
+            if is_scalar(result) or len(result) != len(self):
+                raise ValueError("transforms cannot produce"
+                                 "aggregated results")
+
+            return result
+
+        cls.transform = transform
+
 
 def _doc_parms(cls):
     """Return a tuple of the doc parms."""