[WIP] Custom fill value for reindex, align, and merge operations

[zdgriffith]

This PR adds an optional fill_value parameter for the following functions/methods:

xarray.core.alignment.align()
xarray.core.alignment.deep_align()

xarray.core.dataset.reindex()
xarray.core.dataset.reindex_like()
xarray.core.dataset.merge()

xarray.core.dataarray.DataArray.reindex()
xarray.core.dataarray.DataArray.reindex_like()

xarray.core.merge.merge_coords()
xarray.core.merge.merge_core()
xarray.core.merge.merge()
xarray.core.merge.dataset_merge_method()

The value given to fill_value is used to fill missing values in the new object after the operation. By default fill_value is NaN.

• Closes Custom fill value for align, reindex and reindex_like #2876
• Tests added
• Fully documented, including whats-new.rst for all changes and api.rst for new API

[pep8speaks]

Hello @zdgriffith! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

There are currently no PEP 8 issues detected in this Pull Request. Cheers! 🍻

Comment last updated at 2019-05-02 21:54:47 UTC

[shoyer]

@zdgriffith this is fantastic, thank you!

I think the only thing that is missing is a brief release announcement in whats-new.rst

[shoyer]

One small additional clean-up you could optionally do here: since we no longer support Python 2, these function signature could be moved from the docstring onto the function itself, e.g.,

def align(*objects, join='inner', copy=True, fill_value=dtypes.NA,
             indexes=None, exclude=frozenset())"

This would let you drop the calls to kwargs.pop() below, and would be a small win for efficiency/clean code.

[zdgriffith]

Thanks for the review @shoyer! Would edits to the docs be in-scope for this PR? For example where fill values are mentioned in http://xarray.pydata.org/en/latest/indexing.html#align-and-reindex.

[shoyer]

Would edits to the docs be in-scope for this PR?

Up to you. Would be happy to include any edits you think are appropriate but they aren't required. The API docs are the canonical reference for various function options but if you think there are good places to mention this option in the narrative docs that would also be welcome.

[dcherian]

+1 for a line in the docs, I don't think an example is needed

[shoyer]

thanks @zdgriffith!