diff --git a/doc/faq.rst b/doc/faq.rst index 55fe933e598..68670d0f5a4 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -1,6 +1,14 @@ Frequently Asked Questions ========================== +.. ipython:: python + :suppress: + + import numpy as np + import pandas as pd + import xarray as xr + np.random.seed(123456) + Why is pandas not enough? ------------------------- @@ -58,6 +66,38 @@ fundamentally multi-dimensional. If your data is unstructured or one-dimensional, stick with pandas. +Why don't aggregations return Python scalars? +--------------------------------------------- + +xarray tries hard to be self-consistent: operations on a ``DataArray`` (resp. +``Dataset``) return another ``DataArray`` (resp. ``Dataset``) object. In +particular, operations returning scalar values (e.g. indexing or aggregations +like ``mean`` or ``sum`` applied to all axes) will also return xarray objects. + +Unfortunately, this means we sometimes have to explicitly cast our results from +xarray when using them in other libraries. As an illustration, the following +code fragment + +.. ipython:: python + + arr = xr.DataArray([1, 2, 3]) + pd.Series({'x': arr[0], 'mean': arr.mean(), 'std': arr.std()}) + +does not yield the pandas DataFrame we expected. We need to specify the type +conversion ourselves: + +.. ipython:: python + + pd.Series({'x': arr[0], 'mean': arr.mean(), 'std': arr.std()}, dtype=float) + +Alternatively, we could use the ``item`` method or the ``float`` constructor to +convert values one at a time + +.. ipython:: python + + pd.Series({'x': arr[0].item(), 'mean': float(arr.mean())}) + + .. _approach to metadata: What is your approach to metadata? diff --git a/doc/whats-new.rst b/doc/whats-new.rst index a65721451f0..7bfe5991b78 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -18,6 +18,13 @@ What's New v0.10.1 (unreleased) -------------------- +Documentation +~~~~~~~~~~~~~ + +- New entry `Why don’t aggregations return Python scalars?` in the + :doc:`faq` (:issue:`1726`). + By `0x0L `_. + Enhancements ~~~~~~~~~~~~