API design for pointwise indexing

[jhamman]

There have been a number of threads discussing possible improvements/extensions to xray indexing. The current indexing behavior for isel is orthogonal indexing - in other words, each coordinate is treated independently (see #214 and #411 for more discussion).

So the question: what is the best way to incorporate diagonal or pointwise indexing in xray? I see two main goals / applications:

1. support simple form of numpy style integer array indexing
2. support pointwise array indexing along coordinates via computation of nearest-neighbor indexes - I think this can also be thought of as a form of resampling.

Input from @WeatherGod, @wholmgren, and @shoyer would be great.

[shoyer]

So, the good news is that once we figure out the API for pointwise indexing, I think the nearest-neighbor part could be as simple as supplying method='nearest'.

The challenge is that we want to go from an DataArray that looks like this:

In [4]: arr = xray.DataArray([[1, 2], [3, 4]], dims=['x', 'y'])

In [5]: arr
Out[5]:
<xray.DataArray (x: 2, y: 2)>
array([[1, 2],
       [3, 4]])
Coordinates:
  * x        (x) int64 0 1
  * y        (y) int64 0 1

To one that looks like that:

In [6]: xray.DataArray([1, 4], {'x': ('c', [0, 1]), 'y': ('c', [0, 1])}, dims='c')
Out[6]:
<xray.DataArray (c: 2)>
array([1, 4])
Coordinates:
    y        (c) int64 0 1
    x        (c) int64 0 1
  * c        (c) int64 0 1

Somehow, we need to figure out the name for the new dimension (c in this example).

My thought would be to have methods sel_points and isel_points that work similarly to sel and isel. This is straightforward if you already have xray 1D objects with a labeled dimension: arr.sel_points(x=x, y=y), where x and y are along the c dimension.

If you don't already have 1D xray objects, I suppose we could also allow arr.sel_points(x=('c', [0, 1]), y=('c', [0, 1])) or arr.sel_points('c', x=[0, 1], y=[0, 1]).

[wholmgren]

Seems like if your method is going to be named sel_points then points is a reasonable dimension name. Maybe support a name kwarg?

One thing to keep in mind is that for many of us the "nearest-neighbor" part isn't really method='nearest', but instead more like, method='ingridcell' where the grid cell might be roughly square or might be something pretty different. At least that's how I think of my data. Maybe what I really want is some other kind of more explicit support for gridded data, although my thoughts on this are too half-baked to clearly write down. I thought there was another issue related to this, but I couldn't find it.

[shoyer]

Seems like if your method is going to be named sel_points then points is a reasonable dimension name.

Yes, this is a reasonable choice for the case of 1d indexers.

Maybe support a name kwarg?

This is also a good idea, though I would probably call the parameter dim, not name.

One thing to keep in mind is that for many of us the "nearest-neighbor" part isn't really method='nearest', but instead more like, method='ingridcell' where the grid cell might be roughly square or might be something pretty different.

Indeed. As a start, we should be able to do nearest neighbor lookups with a tolerance soon -- I have a pandas PR that should add some of that basic functionality (pandas-dev/pandas#10411). In the long term, it would be useful to have some sort of representation of grid cells in the index itself, possibly something similar to IntervalIndex (pandas-dev/pandas#8707).

[jhamman]

I like:

DataArray.isel_points(x=[1, 2, 3], y=[0, 1, 2], dim='points')

I also like the nearest-neighbor / resample API of:

DataArray.sel_points(lon=[-123.25, -140.0, 72.5], lat=[45.0, 72.25, 65.75],
                     dim='points', method='nearest')

How do we want to do the nearest-neighbor selection? The simplest case would be to follow the cKDTree example from #214. However, when you're using lat/lon coordinates, it is usually best to map these coordinates from the spherical coordinates to a Cartesian coordinates (see here for a simple example using cKDTree. Is that a road we want to go down here?

Further along that subject, but not directly relate - has anyone used pyresample.

[wholmgren]

Unidata also has a blog post benchmarking cKDTree and other methods and concludes "Your Mileage May Vary". I'd probably just go with a KDTree, but something to aware of.

[rabernat]

There is a great kdtree-based geospatial resampling package you might want to consider building on:
https://github.com/pytroll/pyresample
It is fast (multithreaded) and has support for different map projections.

[rabernat]

Maybe this is off topic, but are the plans to support more general spatial resampling / regridding? Like if I have two DataArrays a and b with different spatial coords, it would be great to be able to do

c = a.regrid_like(b)

This is a pretty common practice in climate science, since different datasets are provided on different grids with different resolutions.

[shoyer]

I agree that regridding and resample would be very nice, and pyresample looks like a decent option. I have no immediate plans to implement these features but contributions would be very welcome.

For n-dimensional indexing, kdtree seems sensible, especially if we can cache it on the coordinates. We probably want an explicit API for methods that add new coordinates -- something like ds.set_kdtree(['latitude', 'longitude']).

[jhamman]

As a first step, I'll volunteer (unless someone else is more keen on doing this work) to put together a pull request for isel_points.

After that, we'll want to add the sel_points and kdtree API, which will depend on isel_points.

Later on, I'm also interested in regridding and resampling between grids - let's open another issue for that. Maybe we use pyresample for that.

[shoyer]

@jhamman it would be great if you could put together a PR for isel_points. The main complexity is that you'll want to write a version that also works with dask arrays. Let me know if that part is confusing, I can certainly help with that.

As for sel_points, we only need a kdtree if the underlying coordinates are 2D. If latitude and longitude (for example) are 1d, we can just use the existing machinery for remapping label based indexers to integers. This should be pretty straightforward, following the example of isel:
https://github.com/xray/xray/blob/v0.5.1/xray/core/dataset.py#L1024
https://github.com/xray/xray/blob/v0.5.1/xray/core/indexing.py#L157

[jhamman]

Good point on the dask array business. From the dask docs:

Dask.array supports most of the NumPy slicing syntax.
...
It does not currently support the following:

Slicing one dask.array with another x[x > 0]
Slicing with lists in multiple axes x[[1, 2, 3], [3, 2, 1]]

Both of these are straightforward to add though. If you have a use case then raise an issue.

So, from browsing the closed dask issues, it seems like dask has similar support for multi-dimension slicing and indexing as xray. This throws a bit of a wrench in my plan for how I was going to implement isel_points as I had not fully considered the dask array complexities.

I'll have to put a bit more thought into this. Any suggestions on how to index the dask array without looping through individual points would be great.

[shoyer]

Any suggestions on how to index the dask array without looping through individual points would be great.

For now, I actually think selecting individual points and then concatenating the resulting arrays together would be a reasonable start. Yes, it's kind of slow, but once you have a first draft put together that way with the right API we can optimize later.