Refine/improve collect_training_data

[cbur24]

Proposed changes

The collect_training_data function has been refactored to improve error handling, fix several bugs, and enhance the documentation. Additionally, the multiprocessing has switched from using mp.Pool.apply_async to mp.Pool.imap to ensure results are returned in the order they are input, as well as to increase the overall robustness of the multiprocessing.

The function now returns a pandas.DataFrame instead of the previous NumPy array plus separate list of column names. This introduces a breaking change, so the ML notebooks have been updated accordingly. Minor improvements were also made to those notebooks during this process.

Another breaking change is the time_delta parameter has been removed. To provide custom time-ranges for each row in the input, the user now needs to provide a column in the input gdf that contains time(ranges). These can be in any format that datacube.load accepts. Overall, this makes the function more flexible.

Its now also possible to return time series from the feature_func, where previously it was enforced that only 2D (x,y) datasets could be returned. To faciliate understanding what has been returned, a new paramters return_time_coords has been introduced where the resulting dataframe will contain a new column with time-stamps for each sample.

I've also added a "how-to-guide" notebook to the repo to make more visible the fuctionality of collect_training_data, which is quite flexible and helpful for any task that requires loading many small but sparse data loads, not only training/validation data collection.

A small test suite has been added under Tests/test_classification.py

If reviewing, I suggest focusing on the classification.py, test_classification.py, and the Collect_training_and_validation_data.ipynb files, changes to other files are minor.

Checklist

If this is a notebook, then have you:

• Checked the structure of the notebook follows our DEA-notebooks template
• Removed any unused Python packages from Load packages
• Removed any unused/empty code cells
• Removed any guidance cells (e.g. General advice)
• Ensured that all code cells follow the PEP8 standard for code. The jupyterlab_code_formatter tool can be used to format code cells to a consistent style: select each code cell, then click Edit and then one of the Apply X Formatter options (YAPF or Black are recommended).
• Included relevant tags in the final notebook cell (refer to the DEA Tags Index, and re-use tags if possible)
• Tested notebook on the DEA Sandbox
• Cleared all outputs, run notebook from start to finish, and save the notebook in the state where all cells have been sequentially evaluated
• If applicable, update the Notebook currently compatible with line below the notebook title to reflect the environments the notebook is compatible with
• Check for any spelling mistakes using the DEA Sandbox's built-in spellchecker (double click on markdown cells then right-click on pink highlighted words). For example:

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[GL-S]

Reviewed and provided feedback in the past few days while the improvements were added.
The function is now better performing and allows for more flexibility regarding what information to include in the output.
The notebook on how to use the updated function is very detailed and easy to follow at the same time, very useful in getting familiar with collect_training_data

[cbur24]

Seems like the testing is failing for a reason unrelated to these changes:

ImportError: cannot import name 'configure_rio' from 'odc.loader' (unknown location).

For the stable image which uses datacube v1.8, configure rio is located in datacube.utils.aws.configure_s3_access

[robbibt]

Hey @cbur24, this is an incredible piece of work! The updated function is fantastic, and should be so much easier to use.

I have pushed a few changes to clear up the tests by ignoring several problematic notebooks (they work fine on Sandbox, but return 403 errors in the tests). I think most of the odc-loader issues should already be fixed externally.

Only two suggested changes to the new notebook:

• There's a few cells that need Black etc formatting
• We've been trying to remove use of rio_slurp_xarray as it requires datacube. In this case you're already using datacube so it's not a major issue, but it would be nice to replace it with load_reproject if you can: it also exists to load small sections of a larger COG, but is fully contained within dea-tools. See example here: https://github.com/GeoscienceAustralia/dea-notebooks/blob/refine_collect_td/How_to_guides/Downloading_data_with_STAC.ipynb and here: https://knowledge.dea.ga.gov.au/notebooks/Tools/gen/dea_tools.datahandling/#dea_tools.datahandling.load_reproject

[cbur24]

Many thanks for reviewing, @robbibt! On the use of load_reproject, I've been finding it uses about 40 % more memory than rio_slurp_xarray, which is okay for these demonstrator notebooks, but when doing heavier work with lots of CPUs and larger sized geotiffs (high-res, float), it can become a bottleneck for scaling. However, I can see the argument for not adding more datacube dependencies into the repo. Would changing the code to using load_reproject but leaving a markdown comment that rio_slurp_xarray may be preferable in some situations be acceptable?

[robbibt]

@cbur24 Ah, I didn't know that - in that case, it's probably fine either way (maybe a note explaining that there are different options would be good).

I am offline today but I realise I broke the tests yesterday with my change... seems like a simple formatting thing. Will have a look next week if it's still an issue!