NetCDF4 data can be saved as chunks on disk, which has several benefits including efficient reads when using a compatible chunk shape. This is particularly important for files with chunk-based compression (ie all nc4 files with compression) or on HPC and parallel file systems (eg), where IO is typically dominated by the number of reads and chunks-from-disk are often cached. Caches are also common in network data backends such as Thredds OPeNDAP, in which case using disk-compatible chunks will reduce cache pressure as well as latency.

Xarray can use chunks, of course, but as of v0.9 the chunk size has to be specified manually - and the easiest way to discover it is to open the file and look at the _Chunksizes attribute for each variable. I propose that xr.open_dataset (and array, and mfdataset) change their default behaviour.

If Dask is available and chunks=None (the default), chunks should be taken from the file on disk. This may lead to a chunked or unchunked dataset. To force an un-chunked load, users can specify chunks={}, or simple .load() the dataset after opening it.

Hypothesis is a library for writing property-based tests in Python: you describe input data and make assertions that should be true for all examples, then Hypothesis tries to find a counterexample. This came up in #1840, because data == decode(encode(data)) is a classic property.

We could add a (initially small) suite of property-based tests, to complement the traditional example-based tests Xarray is already using. Keeping them in independent files will ensure that they run in CI but the dependency on Hypothesis remains optional for local development.

I have moved jobs and don't have time to do this myself, but I'd be very happy to help anyone who does 😄

Here's a hypothetical dataset:

<xarray.Dataset> Dimensions: (time: 3, x: 988, y: 822) Coordinates: * x (x) float64 ... * y (y) float64 ... * time (time) datetime64[ns] ... Data variables: rainfall (time, y, x) float32 ... max_temp (time, y, x) float32 ...

It would be really nice if the units of the coordinates and of the data variables were shown in the Dataset repr, for example as:

<xarray.Dataset> Dimensions: (time: 3, x: 988, y: 822) Coordinates: * x, in metres (x) float64 ... * y, in metres (y) float64 ... * time (time) datetime64[ns] ... Data variables: rainfall, in mm (time, y, x) float32 ... max_temp, in deg C (time, y, x) float32 ...

I've regularly had to debug problems with unusual or slightly broken data - or my misunderstanding of various layers of the software stack -, and I can't be the only one. For example:

• open_mfdataset tries to open an invalid file. Which file? Why is it invalid?
  (one was truncated when the download crashed - I had to find it by size)
• Xarray can't convert a dtype. What dtype couldn't it convert? And of what variable? (it was a boolean mask)

And of course there are many more examples. This manifesto has some good advice, but in essence:

• Think about the information a new user will need to understand what has gone wrong and fix their code. It's good to be verbose here, because new users need this information most and experienced users won't see it anyway (or might be glad it's there on occasion!).
• Report:
• The value that was invalid (or a summary that rules out validity; eg shape and dtype for arrays)
• The operation that was attempted
• Why the value was invalid in this operation
• If possible, what the user can do to fix this

This is quite an open-ended issue; as well as the code changes it probably requires some process changes to ensure that new errors are equally helpful. Ultimately, the goal is for errors to become a positive aid to learning rather than a frustrating barrier.

Problem description

Using the name of the first element to concatenate as the name of the concatenated array is only correct if all names are identical. When names vary, using a clear placeholder name or the name of the new dimension would avoid misleading data users.

This came up for me recently when stacking several bands of a satellite image to produce a faceted plot - the resulting colorbar was labelled "blue", even though that was clearly incorrect.

A similar process is probably also desirable for aggregation of units across concatenated arrays - use first if identical, otherwise discard or error depending on the compat argument.

Code Sample, a copy-pastable example if possible

```python ds = xr.Dataset({ k: xr.DataArray(np.random.random((2, 2)), dims="x y".split(), name=k) for k in "blue green red".split() })

arr.name == "blue", could be "band" or "concat_dim"

arr = xr.concat([ds.blue, ds.green, ds.red], dim="band")

label of colorbar is "blue", which is meaningless

arr.plot.imshow(col="band") ```

One implementation that would certainly be nice for this use-case (though perhaps not generally) is that concatenating DataArrays along an entirely new dimension with unique array names and dim passed a string could create a new Index as well, as pd.Index([a.name for a in objs], name=dim).

I'd be happy to write a PR for this if it would be accepted.

• [x] Closes #2775
• [x] Tests added
• [x] Fully documented, including whats-new.rst for all changes and api.rst for new API

This is really nice to have when producing faceted plots of satellite observations in various bands, and should be somewhere between useful and harmless in other cases.

Example code:

python ds = xr.Dataset({ k: xr.DataArray(np.random.random((2, 2)), dims="x y".split(), name=k) for k in "blue green red".split() }) xr.concat([ds.blue, ds.green, ds.red], dim="band").plot.imshow(col="band")

Before - facets have an index, colorbar has misleading label:

After - facets have meaningful labels, colorbar has no label:

Closes #2441 - Hypothesis 3.72.0 turned a common no-op into an explicit error. Apparently this was such a common misunderstanding that I had done it too :disappointed:

Anyway: while it hasn't been using the deadline at all until now, I've still translated it into the correct form rather than deleting it in order to avoid flaky tests if the Travis VM is slow.

• [x] Closes #1842
• [x] Tests added
• [x] Tests passed
• [x] Passes flake8 xarray (now part of tests)
• [x] Fully documented, including whats-new.rst for all changes

Most satellites produce images with color depth in the range of eight to sixteen bits, which are therefore often stored as unsigned integers (with the quality mask in another variable). If you're lucky, they also have a scale_factor attribute and Xarray can automatically convert the integers to floats representing albedo.

This is fantastically convenient, and avoids all the bit-depth bugs from misremembered specifications. However, loading data as float64 when float32 is sufficient doubles memory usage in IO (even on multi-TB datasets...). While immediately downcasting helps, it's no substitute for doing the right thing first.

So this patch does some conservative checks, and if we can be sure float32 is safe we use that instead.

• [x] Closes #1846
• [x] Tests added - you bet
• [x] Tests passed - well, the code under test hasn't changed...

This is a small property-based test suite, to give two examples of the kinds of tests that we could write for Xarray using Hypothesis.

1. For any array, encoding and decoding it with a CF coder outputs an identical array. As you would hope, these tests pass.
2. For any 2D array, you can call the 2D plotting methods without raising an exception. Alas, this is not the case, and Hypothesis will show you the failing inputs (and matplotlib-related tracebacks) to prove it. (Contributing a very small feature to matplotlib was shockingly painful, so I'm not planning to take a similar suite upstream myself unless something changes)

Things that I would like to know:

• Have I build-wrangled something reasonable here?
• Will anyone else contribute property-based tests? I'm happy to help people debug or work out how to test something, but I simply don't have the time to write another test suite for free.
• Is this something you want?

• [x] Closes #1966
• [x] Tests added (for all bug fixes or enhancements)
• [x] Tests passed (for all non-documentation changes)
• [x] Fully documented, including whats-new.rst for all changes

Not much more to say, really. Thanks to @fmaussion for pinging me - definitely faster to track down when you know the code!

• [x] Closes #1880
• [x] Tests added (for all bug fixes or enhancements)
• [ ] Tests passed (for all non-documentation changes)
• [x] Fully documented (bugfix for earlier change, no additional note)

The cause of the bug in #1880 was that I had forgotten to specify the dtype when creating an alpha channel, and therefore concatenating it cast the all the data to float64. I've fixed that, corrected the alpha value for integer arrays, and avoided a pointless copy to save memory.

• [x] Closes #1630
• [x] Tests passed
• [x] Passes git diff upstream/master **/*py | flake8 --diff
• [x] Fully documented, including whats-new.rst for all changes - details of label not previously documented

Follow-up to #1796, where normalisation and clipping of RGB[A] values were deferred so that we could match any upstream API. matplotlib/matplotlib#10220 implements clipping to the valid range, but a strong consensus against RGB normalisation in matplotlib has emerged.

This pull therefore implements normalisation, and clips values only where our normalisation has pushed them out of range.

Closes #1741 by @mrocklin (who did most of the work I'm presenting here). I had an evening free, so I rebased the previous pull on master, fixed the conflicts, and then made everything pass with flake8's default settings (including line length). My condolences to whoever gets to review this diff!

The single change any non-pedant will notice: Travis now fails if there is a flake8 warning anywhere. My experience in other projects is that this is the only way to actually keep flake8 passing - it's just unrealistic to expect perfect attention to detail from every contributor, but "make the build green before we merge" is widely understood 😄

• [x] Tests added (for all bug fixes or enhancements)
• [x] Tests passed (for all non-documentation changes)
• [x] Passes git diff upstream/master **/*py | flake8 --diff
• [x] Fully documented, including whats-new.rst for all changes

This patch brings xarray.plot.imshow up to parity with matplotlib.pyplot.imshow:

• As well as 2D images (greyscale / luminance, using a colormap), it now supports a third dimension for RGB or RGBA channels. For consistency with 2D arrays, missing data is plotted as transparent pixels
• Being Xarray, users need not care about the order of their dimensions - we infer the right one for color, and warn if it's ambiguous.
• ~~Using robust=True for easy saturation is really nice. Having it adjust each channel and facet in the same way is essential for this to work, which it does.~~
• ~~Matplotlib wraps out-of-range colors, leading to crazy maps and serious interpretation problems if it's only a small region. Xarray clips (ie saturates) to the valid range instead.~~

I'm going to implement clip-to-range and color normalization upstream in matplotlib, then open a second PR here so that Xarray can use the same interface.

And that's the commit log! It's not really a big feature, but each of the parts can be fiddly so I've broken the commits up logically 😄

Finally, a motivating example: visible-light Landsat data before, during (top-right), and after a fire at Sampson's Flat, Australia:

arr = ds['red green blue'.split()].to_array(dim='band') / (2 ** 12)
arr.plot.imshow(col='time', col_wrap=5, robust=True)

• [x] Closes #1780
• [x] Tests added (for all bug fixes or enhancements)
• [x] Tests passed (for all non-documentation changes)
• [x] Passes git diff upstream/master **/*py | flake8 --diff (remove if you did not edit any Python files)
• [x] Fully documented, including whats-new.rst for all changes

CC @fmaussion for review; @BexDunn for interest

Code Sample, a copy-pastable example if possible

python xr.DataArray(np.full((2, 2), 0)).plot.imshow() # works xr.DataArray(np.full((2, 2), np.nan)).plot.imshow() # doesn't

Problem description

If you try to plot a DataArray which is entirely filled with NaN, you get an exception. This is really, really annoying for people doing satellite image analysis, especially with timeseries where just one step might be very cloudy.

Expected Output

Plot of the array extent, entirely in the missing-value colour as for partially-missing data.

Output of xr.show_versions()

Confirmed on Windows/Linux/OSX, Xarray 0.9.6 and 0.10.0; sample show_versions below. It's a pretty obvious error though in failing to handle the no-non-missing-data case when determining data range.

This pull updates the comparison between Xarray and Pandas ND-Panels, fixes the zenodo links, and improves our configuration for the docs build. Closes #1541.

to_dataframe should return a Dask Dataframe, instead of eagerly loading data. This is probably pretty easy to implement (thanks to dask), but will require some care to ensure that no intermediate results (or indices!) are loaded. We should also check the to_series method.

NetCDF files often have tens of attributes, including multi-paragraph summaries or the full modification history of the file. It's great to have this available in the .attrs, but we can truncate it substantially in the repr! Hopefully this will stop people writing data.attrs = {} and discarding metadata in interactive workflows for the sake of cleaner output.

• [x] closes #1319
• [x] test data adjusted
• [x] passes git diff upstream/master | flake8 --diff
• [x] whatsnew entry

When loading from NetCDF, Dataset.attrs often has a few long strings, which may even have embedded newlines (eg a multi-paragraph summary or references section). It's lovely that these are available, but they tend to make the repr very long and poorly formatted - to the point that many Jupyter notebooks begin by discarding the attrs, which makes it rather pointless to store or display metadata at all!

Given that these values are already truncated at 500 characters (including the indicative ..., but not the start point), I propose that they should instead be truncated to 80 characters including the indentation and key (as values are). For the sake of pretty-printing, this should also replace newlines or tabs with spaces and truncate early if an empty line is encountered.

Another solution would be add appropriate indentation following newlines or wrapping, so that the structure remains clear. However, I think that it is better to print a fairly minimal representation of the metadata by default.

```

xr.open_dataset('http://dapds00.nci.org.au/thredds/dodsC/uc0/rs0_dev/20170215-stacked_sample/LS7_ETM_NBART_3577_15_-40.ncml')

<xarray.Dataset> Dimensions: (time: 246, x: 4000, y: 4000) Coordinates: * y (y) float64 -3.9e+06 -3.9e+06 -3.9e+06 -3.9e+06 -3.9e+06 ... * x (x) float64 1.5e+06 1.5e+06 1.5e+06 1.5e+06 1.5e+06 1.5e+06 ... * time (time) datetime64[ns] 1999-07-16T23:49:39 1999-07-25T23:43:07 ... Data variables: crs int32 ... blue (time, y, x) float64 ... green (time, y, x) float64 ... red (time, y, x) float64 ... nir (time, y, x) float64 ... swir1 (time, y, x) float64 ... swir2 (time, y, x) float64 ... Attributes: date_created: 2017-03-07T11:57:26.511217 Conventions: CF-1.6, ACDD-1.3 history: 2017-03-07T11:57:26.511307+11:00 adh547 datacube-ncml (1.2.2+23.gd1f3512.dirty) ls7_nbart_albers.yaml, 1.0.6a, /short/v10/datacube/002/LS7_ETM_NBART/LS7_ETM_NBART_3577_15_-40.ncml, (15, -40) # Created NCML file to aggregate multiple NetCDF files along the time dimension geospatial_bounds: POLYGON ((148.49626113888138 -34.828378308133452,148.638689676063308 -35.720318326735864,149.734176111491877 -35.599556747691196,149.582601578289143 -34.708911907843387,148.49626113888138 -34.828378308133452)) geospatial_bounds_crs: EPSG:4326 geospatial_lat_min: -35.7203183267 geospatial_lat_max: -34.7089119078 geospatial_lat_units: degrees_north geospatial_lon_min: 148.496261139 geospatial_lon_max: 149.734176111 geospatial_lon_units: degrees_east comment: - Ground Control Points (GCP): new GCP chips released by USGS in Dec 2015 are used for re-processing - Geometric QA: each product undergoes geometric assessment and the assessment result will be recorded within v2 AGDC for filtering/masking purposes. - Processing parameter settings: the minimum number of GCPs for Ortho-rectified product generation has been reduced from 30 to 10. - DEM: 1 second SRTM DSM is used for Ortho-rectification. - Updated Calibration Parameter File (CPF): the latest/cu... product_suite: Surface Reflectance NBAR+T 25m publisher_email: earth.observation@ga.gov.au keywords_vocabulary: GCMD product_version: 2 cdm_data_type: Grid references: - Berk, A., Anderson, G.P., Acharya, P.K., Hoke, M.L., Chetwynd, J.H., Bernstein, L.S., Shettle, E.P., Matthew, M.W., and Adler-Golden, S.M. (2003) Modtran 4 Version 3 Revision 1 User s manual. Airforce Research Laboratory, Hanscom, MA, USA. - Chander, G., Markham, B.L., and Helder, D.L. (2009) Summary of current radiometric calibration coefficients for Landsat MSS, TM, ETM+, and EO-1 ALI sensors. Remote Sensing of Environment 113, 893-903. - Edberg, R., and Oliver, S. (2013) Projection-Indep... platform: LANDSAT-7 keywords: AU/GA,NASA/GSFC/SED/ESD/LANDSAT,REFLECTANCE,ETM+,TM,OLI,EARTH SCIENCE publisher_name: Section Leader, Operations Section, NEMO, Geoscience Australia institution: Commonwealth of Australia (Geoscience Australia) acknowledgment: Landsat data is provided by the United States Geological Survey (USGS) through direct reception of the data at Geoscience Australias satellite reception facility or download. license: CC BY Attribution 4.0 International License title: Surface Reflectance NBAR+T 25 v2 summary: Surface Reflectance (SR) is a suite of Earth Observation (EO) products from GA. The SR product suite provides standardised optical surface reflectance datasets using robust physical models to correct for variations in image radiance values due to atmospheric properties, and sun and sensor geometry. The resulting stack of surface reflectance grids are consistent over space and time which is instrumental in identifying and quantifying environmental change. SR is based on radiance data from the... instrument: ETM source: LANDSAT 7 ETM+ surface observation publisher_url: http://www.ga.gov.au ```