Document significance of macro vs micro averaging

[robmarkcole]

Issue

In the segmentation trainer, MulticlassAccuracy MulticlassJaccardIndex uses average="micro" rather than the torchmetrics default macro.

From slack: Macro weights per patch (what is the average accuracy of each patch?), whereas micro weights per pixel (what is the average accuracy of each pixel across the entire dataset?). These two metrics very greatly when the number of nodata pixels varies between patches. If one patch is mostly nodata pixels, and another patch is mostly data pixels, then macro will take the average of the two patches, while micro will sum up all pixels

Macro might be okay for some applications (such as pre-chipped datasets) but is definitely not what you want for others (such as geospatial datasets)

Further discussion: proposal: add both macro and micro and just name them appropriately OA vs AA - Overall (micro) Accuracy (OA). Average (macro) Accuracy (AA)

Fix

Refine the description above and document at https://torchgeo.readthedocs.io/en/stable/api/trainers.html#torchgeo.trainers.SemanticSegmentationTask.configure_metrics

[jdilger]

Hey there, I'd be happy to take this on. It seems pretty straightforward, but is there anything I should be aware of when building the docs?

[adamjstewart]

Everything you need to know is here: https://torchgeo.readthedocs.io/en/stable/user/contributing.html#documentation

Although you probably don't actually need to build the docs yourself, this is a pretty straightforward update and CI will test the docs for you.

Note that one of our other users has suggested adding both OA and AA, so the docs may need to change in the near future.

[jdilger]

Ok sounds great. I submitted a PR that covers the micro accuracy. I'd be keen to add the option for AA if it's picked for implementation (or even updating the docs again).