Updatees

Author: dcherian

docs/source/index.md

@@ -1,13 +1,17 @@
 # flox: fast & furious GroupBy reductions for `dask.array`
-
-## Overview
-
 [![GitHub Workflow CI Status](https://img.shields.io/github/workflow/status/xarray-contrib/flox/CI?logo=github&style=flat)](https://github.com/xarray-contrib/flox/actions)
-[![GitHub Workflow Code Style Status](https://img.shields.io/github/workflow/status/xarray-contrib/flox/code-style?label=Code%20Style&style=flat)](https://github.com/xarray-contrib/flox/actions)
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/xarray-contrib/flox/main.svg)](https://results.pre-commit.ci/latest/github/xarray-contrib/flox/main)
 [![image](https://img.shields.io/codecov/c/github/xarray-contrib/flox.svg?style=flat)](https://codecov.io/gh/xarray-contrib/flox)
+[![Documentation Status](https://readthedocs.org/projects/flox/badge/?version=latest)](https://flox.readthedocs.io/en/latest/?badge=latest)
+
 [![PyPI](https://img.shields.io/pypi/v/flox.svg?style=flat)](https://pypi.org/project/flox/)
 [![Conda-forge](https://img.shields.io/conda/vn/conda-forge/flox.svg?style=flat)](https://anaconda.org/conda-forge/flox)
 
+[![NASA-80NSSC18M0156](https://img.shields.io/badge/NASA-80NSSC18M0156-blue)](https://earthdata.nasa.gov/esds/competitive-programs/access/pangeo-ml)
+[![NASA-80NSSC22K0345](https://img.shields.io/badge/NASA-80NSSC22K0345-blue)](https://science.nasa.gov/open-science-overview)
+
+## Overview
+
 `flox` mainly provides strategies for fast GroupBy reductions with dask.array. `flox` uses the MapReduce paradigm (or a "tree reduction")
 to run the GroupBy operation in a parallel-native way totally avoiding a sort or shuffle operation. It was motivated by
 

docs/source/xarray.md

@@ -1 +1,27 @@
 # Xarray
+
+Xarray will use flox by default for numpy and dask array backed Xarray objects if it is installed. By default, it will use `method="cohorts"` which generalizes
+the best. Pass flox-specific kwargs to the specific reduction method:
+```python
+ds.groupby("time.month").mean(method="map-reduce", engine="flox")
+ds.groupby_bins("lon", bins=[0, 10, 20]).mean(method="map-reduce")
+ds.resample(time="M").mean(method="blockwise")
+```
+
+Xarray's GroupBy operations are currently limited:
+1. One can only group by a single variable.
+1. When grouping by a dask array, that array will be computed to discover the unique group labels, and their locations
+
+These limitations can be avoided by using {py:func}`flox.xarray.xarray_reduce` which allows grouping by multiple variables, lazy grouping by dask variables,
+as well as an arbitrary combination of categorical grouping and binning. For example,
+```python
+flox.xarray.xarray_reduce(
+    ds,
+    ds.time.dt.month,
+    ds.lon,
+    func="mean",
+    expected_groups=[None, [0, 10, 20]],
+    isbin=[False, True],
+    method="map-reduce",
+)
+```