Refactor all indices to one module.

[RitwikGupta]

All the indices currently included are just ratios of sums. The helper functions also depend on the user knowing what the index of the relevant bands are to begin with.

Since this knowledge of the underlying index is already required, it's cleaner to have one generalized module for difference indices.

[adamjstewart]

This won't work in general. Although all of our current indices are difference ratios, most indices are not: https://www.indexdatabase.de/db/i.php

We could have a single difference ratio index to represent all, but I'm not sure how much of an advantage that will give us. @isaaccorley thoughts?

[RitwikGupta]

That is my thought; one module for all difference indices and then we can add more specific ones as needed. Keeps it clean.

[isaaccorley]

This won't work in general because our current indices are all normalized difference indices but many indices have more than 2 bands, can be normalized in different ways, or some indices can be a function of other indices. The other reasoning for keeping a separate class per index is that we were including the correct DOI for each index. There seems to some confusion in the community on the original publication source of certain spectral indices and this would help these papers be cited properly.

The refactor plan was to break out the Append into it's own transform that can be used like Append(NDVI(...), dim=1). The other benefit of keeping the dimension as an argument is you can modify it to work as a transform in a dataset, a transform which operates on batches, or for time-series sample/batch.

Edit: although I do think the tests could be refactored some as they are repetitive.

[calebrob6]

our current indices are all normalized difference indices

I'm not sure I understand the significance of the "normalized" part. These indices are all just a function of some number of bands. In fact, our indices modules could take advantage of the fact that the RasterDatasets know which bands are which.

The other reasoning for keeping a separate class per index is that we were including the correct DOI for each index.

I think we can keep the DOIs around easily by making say AppendNDBI inherit from what @RitwikGupta is proposing (AppendIndex or a AppendDifferenceIndex).

We should definitely have https://www.indexdatabase.de/db/i.php in the documentation.

[RitwikGupta]

👆 I am still unfamiliar with the TorchGeo API (working on it!), but my suggestion was going to be to used NamedTensors (or the RasterDataset implementation equivalent) to make a difference index factory, essentially.

[adamjstewart]

No worries, our API is constantly evolving anyway, thanks for all the fresh ideas!

[calebrob6]

Okay, so how does everyone feel about a parent AppendDifferenceIndex with 4 (5 including your other PR) children? This should definitely remove some code, keep the DOIs around (I agree with Isaac that this is important!), and make the path to adding other classes of indices more straightforward.

[RitwikGupta]

Good by me. So that looks like a super + subclasses? __init__() can hold the properly named kwargs and we can pass them to super().__init__(band_a, band_b)

[adamjstewart]

AppendDifferenceIndex

I would call it AppendNormalizedDifferenceIndex. If it was just a difference, it would look like (x - y). This is a normalized difference since we also divide by the sum.

[adamjstewart]

@isaaccorley our "Indices" tutorial still uses torchgeo.transforms.ndvi which was removed in this PR. Can you modify the tutorial and submit a PR against the releases/v0.2 branch?