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 pandas-dev#1623
closes pandas-dev#14464

custom .describe
closes pandas-dev#14483
closes pandas-dev#7014

Author: jreback

doc/source/basics.rst

@@ -700,7 +700,8 @@ on an entire ``DataFrame`` or ``Series``, row- or column-wise, or elementwise.
 
 1. `Tablewise Function Application`_: :meth:`~DataFrame.pipe`
 2. `Row or Column-wise Function Application`_: :meth:`~DataFrame.apply`
-3. Elementwise_ function application: :meth:`~DataFrame.applymap`
+3. `Aggregation API`_: :meth:`~DataFrame.agg` and :meth:`~DataFrame.transform`
+4. `Applying Elementwise Functions`_: :meth:`~DataFrame.applymap`
 
 .. _basics.pipe:
 
@@ -776,6 +777,13 @@ statistics methods, take an optional ``axis`` argument:
    df.apply(np.cumsum)
    df.apply(np.exp)
 
+``.apply()`` will also dispatch on a string method name.
+
+.. ipython:: python
+
+   df.apply('mean')
+   df.apply('mean', axis=1)
+
 Depending on the return type of the function passed to :meth:`~DataFrame.apply`,
 the result will either be of lower dimension or the same dimension.
 
@@ -825,16 +833,186 @@ set to True, the passed function will instead receive an ndarray object, which
 has positive performance implications if you do not need the indexing
 functionality.
 
-.. seealso::
+.. _basics.aggregate:
+
+Aggregation API
+~~~~~~~~~~~~~~~
+
+.. versionadded:: 0.20.0
+
+The aggregation APi allows one to express possibly multiple aggregation operations in a single concise way.
+This API is similar across pandas objects, :ref:`groupby aggregates <groupby.aggregate>`,
+:ref:`window functions <stats.aggregate>`, and the :ref:`resample API <timeseries.aggregate>`.
+
+We will use a similar starting frame from above.
+
+.. ipython:: python
+
+   tsdf = pd.DataFrame(np.random.randn(10, 3), columns=['A', 'B', 'C'],
+                       index=pd.date_range('1/1/2000', periods=10))
+   tsdf.iloc[3:7] = np.nan
+   tsdf
+
+Using a single function is equivalent to ``.apply``; You can also pass named methods as strings.
+This will return a Series of the output.
+
+.. ipython:: python
+
+   tsdf.agg(np.sum)
+
+   tsdf.agg('sum')
+
+On a Series this will result in a scalar value
+
+.. ipython:: python
+
+   tsdf.A.agg('sum')
+
+
+Aggregating multiple functions at once
+++++++++++++++++++++++++++++++++++++++
+
+You can pass arguments as a list. The results of each of the passed functions will be a row in the resultant DataFrame.
+These are naturally named from the aggregation function.
+
+.. ipython:: python
+
+   tsdf.agg(['sum'])
+
+Multiple functions yield multiple rows.
+
+.. ipython:: python
+
+   tsdf.agg(['sum', 'mean'])
+
+On a Series, multiple functions return a Series.
+
+.. ipython:: python
+
+   tsdf.A.agg(['sum', 'mean'])
+
+
+Aggregating with a dict of functions
+++++++++++++++++++++++++++++++++++++
+
+Passing a dictionary of column name to function or list of functions, to ``DataFame.agg``
+allows you to customize which functions are applied to which columns.
+
+.. ipython:: python
+
+   tsdf.agg({'A': 'mean', 'B': 'sum'})
+
+Passing a list-like will generate a DataFrame output. You will get a matrix-like output
+of all of the aggregators; some may be missing values.
+
+.. ipython:: python
+
+   tsdf.agg({'A': ['mean', 'min'], 'B': 'sum'})
+
+For a Series, you can pass a dict; the keys will set the name of the column
+
+.. ipython:: python
+
+   tsdf.A.agg({'foo' : ['sum', 'mean']})
+
+Multiple keys will yield multiple columns.
+
+.. ipython:: python
+
+    tsdf.A.agg({'foo' : ['sum', 'mean'], 'bar': ['min', 'max', lambda x: x.sum()+1]})
+
+
+.. _basics.transform:
+
+Transform API
+~~~~~~~~~~~~~
+
+.. versionadded:: 0.20.0
+
+The ``transform`` method returns an object that is indexed the same (same size)
+as the original. This API allows you to provide *multiple* operations at the same
+time rather than one-by-one. Its api is quite similar to the ``.agg`` API.
+
+Use a similar frame to the above sections.
+
+.. ipython:: python
+
+   tsdf = pd.DataFrame(np.random.randn(10, 3), columns=['A', 'B', 'C'],
+                       index=pd.date_range('1/1/2000', periods=10))
+   tsdf.iloc[3:7] = np.nan
+   tsdf
+
+Transform the entire frame. Transform allows functions to input as a numpy function, string
+function name and user defined function.
+
+.. ipython:: python
+
+   tsdf.transform(np.abs)
+   tsdf.transform('abs')
+   tsdf.transform(lambda x: x.abs())
+
+``.transform()`` with a single function is equivalent to applying a function across the
+columns.
+
+.. ipython:: python
+
+   tsdf.apply(np.abs, axis=1)
+
+Passing a single function to ``.transform()`` with a Series will yield a single Series in return.
+
+.. ipython:: python
+
+   tsdf.A.transform(np.abs)
 
-   The section on :ref:`GroupBy <groupby>` demonstrates related, flexible
-   functionality for grouping by some criterion, applying, and combining the
-   results into a Series, DataFrame, etc.
 
-.. _Elementwise:
+Transform with multiple functions
++++++++++++++++++++++++++++++++++
 
-Applying elementwise Python functions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Passing multiple functions will yield a column multi-indexed DataFrame.
+The first level will be the original frame column names; the second level
+will be the names of the transforming functions.
+
+.. ipython:: python
+
+   tsdf.transform([np.abs, lambda x: x+1])
+
+Passing multiple functions to a Series will yield a DataFrame. The
+resulting column names will be the transforming functions.
+
+.. ipython:: python
+
+   tsdf.A.transform([np.abs, lambda x: x+1])
+
+
+Transforming with a dict of functions
++++++++++++++++++++++++++++++++++++++
+
+
+Passing a dict of functions will will allow selective transforming per column.
+
+.. ipython:: python
+
+   tsdf.transform({'A': np.abs, 'B': lambda x: x+1})
+
+Passing a dict of lists will generate a multi-indexed DataFrame with these
+selective transforms.
+
+.. ipython:: python
+
+   tsdf.transform({'A': np.abs, 'B': [lambda x: x+1, 'sqrt']})
+
+On a Series, passing a dict allows renaming as in ``.agg()``
+
+.. ipython:: python
+
+   tsdf.A.transform({'foo': np.abs})
+   tsdf.A.transform({'foo': np.abs, 'bar': [lambda x: x+1, 'sqrt']})
+
+
+.. _basics.elementwise:
+
+Applying Elementwise Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Since not all functions can be vectorized (accept NumPy arrays and return
 another array or value), the methods :meth:`~DataFrame.applymap` on DataFrame

doc/source/computation.rst

@@ -560,7 +560,9 @@ Aggregation
 -----------
 
 Once the ``Rolling``, ``Expanding`` or ``EWM`` objects have been created, several methods are available to
-perform multiple computations on the data. This is very similar to a ``.groupby(...).agg`` seen :ref:`here <groupby.aggregate>`.
+perform multiple computations on the data. These operations are similar to the :ref:`aggregating API <basics.aggregate>`,
+:ref:`groupby aggregates <groupby.aggregate>`, and :ref:`resample API <timeseries.aggregate>`.
+
 
 .. ipython:: python
 

doc/source/groupby.rst

@@ -380,7 +380,9 @@ Aggregation
 -----------
 
 Once the GroupBy object has been created, several methods are available to
-perform a computation on the grouped data.
+perform a computation on the grouped data. These operations are similar to the
+:ref:`aggregating API <basics.aggregate>`, :ref:`window functions <stats.aggregate>`,
+and :ref:`resample API <timeseries.aggregate>`.
 
 An obvious one is aggregation via the ``aggregate`` or equivalently ``agg`` method:
 

doc/source/timeseries.rst

@@ -1404,11 +1404,13 @@ We can instead only resample those groups where we have points as follows:
 
     ts.groupby(partial(round, freq='3T')).sum()
 
+.. _timeseries.aggregate:
+
 Aggregation
 ~~~~~~~~~~~
 
-Similar to :ref:`groupby aggregates <groupby.aggregate>` and the :ref:`window functions <stats.aggregate>`, a ``Resampler`` can be selectively
-resampled.
+Similar to the :ref:`aggregating API <basics.aggregate>`, :ref:`groupby aggregates <groupby.aggregate>`, and :ref:`window functions <stats.aggregate>`,
+a ``Resampler`` can be selectively resampled.
 
 Resampling a ``DataFrame``, the default will be to act on all columns with the same function.
 

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=getattr(self, 'name', None))
 
             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, ValueError):
+            # 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 """