Group by enhancements

[uchchwhash]

Reason for this pull request

Basically #1153. Please test to see if this is fit for purpose @robbibt.

Proposed changes

• GroupBy object takes another optional parameter group_key which defines the coordinate values

• GroupBy is an actual class now

• Closes Unexpected use of GroupBy's sort_key to label output dimensions when applying custom grouping #1153

• Tests added / passed

• Fully documented, including docs/about/whats_new.rst for all changes

[codecov]

Codecov Report

Merging #1157 (66bfaff) into develop (37b8498) will increase coverage by 0.01%.
The diff coverage is 100.00%.

@@             Coverage Diff             @@
##           develop    #1157      +/-   ##
===========================================
+ Coverage    93.91%   93.93%   +0.01%     
===========================================
  Files          102      102              
  Lines        10293    10301       +8     
===========================================
+ Hits          9667     9676       +9     
+ Misses         626      625       -1     

Impacted Files	Coverage Δ
datacube/virtual/impl.py	84.40% <ø> (ø)
datacube/api/core.py	97.11% <100.00%> (+0.24%)	⬆️
datacube/api/query.py	94.81% <100.00%> (+0.25%)	⬆️
datacube/utils/masking.py	100.00% <100.00%> (ø)
datacube/utils/math.py	100.00% <100.00%> (ø)
datacube/virtual/transformations.py	79.39% <100.00%> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 37b8498...66bfaff. Read the comment docs.

[robbibt]

Thanks so much @uchchwhash , will test this this week!

[robbibt]

This works nicely: I've tested it with the following custom grouper designed to prioritise Landsat 8 > Landsat 5 > Landsat 7 geomedian, and it works great:

def _extract_time_from_ds(ds: Dataset) -> datetime.datetime:
    return normalise_dt(ds.center_time)

def sort_by_platform(ds):
    order = {'LANDSAT_5': 2, 'LANDSAT_7': 3, 'LANDSAT_8': 1}
    return order[ds.metadata.platform]


platform_grouper = GroupBy(dimension='time',
                           group_by_func=_extract_time_from_ds,
                           units='seconds since 1970-01-01 00:00:00',
                           sort_key=sort_by_platform)

As expected, I now get correct dates returned in the output xarray:

And my output nicely prioritises the correct sensors (e.g. no Landsat 7 striping from 2013 onward where both Landsat 8 and Landsat 7 data available):