Integrate band references into portable signature files

[marisn]

This PR is a continuation of band reference refactoring PR #1272. It goes on the top of PR #1272.

The main aim is to create reusable signature files – create in one imagery group, use in any imagery group containing same bands. E.g. if one creates signature file for a Landsat 8 scene, he should be able to use the same signature file to classify any Landsat 8 scene.

To reach the aim, three goals must be fulfilled:

• move signatures out of group/subgroup to MAPSET/signatures/TYPE/name
• add a list of band references in signature file at its generation time
• check if list of band references in a signature file matches band references of imagery group members at classification time

List of areas to fix:

• reading / writing sig (better name?) files
• i.gensig
• i.cluster
• i.cca
• i.maxlik
• reading / writing sigset (better name?) files
• i.gensigset
• i.smap
• management functions in the library

[nilason]

(I accidentally switched the checkboxes, didn't realise there is no need to start "editing", however I did reset it as it was. Sorry!)

[marisn]

The amount of changes will shrink after merge of #1272 (it will be easier to do a review after that has been done).

[marisn]

Anyone willing to review the code?

[nilason]

Anyone willing to review the code?

Unfortunately I have not got time to get to it yet. I hope to take a look next week.

[wenzeslaus]

First, the tests look great. What a great example of how heavy C can be tested.

I looked mostly at the new mapset structure additions. signatures/signature_type/{name} seems to be a totally new kind of thing in mapset structure (or?), so I think some library additions and further considerations are needed.

If you provide some examples (or point to existing ones) people can now try in Binder without risk of messing up their mapsets. The link is https://mybinder.org/v2/gh/marisn/grass/imsigs?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fexample_notebook.ipynb

I have two additional questions. Does the band reference naming fit into these new signature files? (This goes back to getting the band reference (image collection?) naming right.) Does this totally remove signatures from groups (or is there still some relation)?

[nilason]

A bunch of changes, additions, a lot to look into. The present comments are the result of my first pass.

[nilason]

Running on Mac gives:

FAIL: test_roundtrip_sigset_v1_one_band (__main__.SigSetFileTestCase)
Test writing and reading back sigset file (v1)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Volumes/dev/grass/lib/imagery/testsuite/test_imagery_sigsetfile.py", line 98, in test_roundtrip_sigset_v1_one_band
    self.assertEqual(ret, 1)
AssertionError: -1 != 1

[marisn]

As there where memory handling related changes, please re-run the test.

[nilason]

Running on Mac gives:

FAIL: test_roundtrip_sigset_v1_two_bands (__main__.SigSetFileTestCase)
Test writing and reading back sigset (v1) with two bands
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/Volumes/dev/grass/lib/imagery/testsuite/test_imagery_sigsetfile.py", line 194, in test_roundtrip_sigset_v1_two_bands
    self.assertEqual(ret, 1)
AssertionError: -1 != 1

[marisn]

As there where memory handling related changes, please re-run the test.

[marisn]

First, the tests look great. What a great example of how heavy C can be tested.

Getting tests right was a hard thing but it really helps to iron out various problems with code, especially if tests do memory handling well – one can run them under valgrind then.

I looked mostly at the new mapset structure additions. signatures/signature_type/{name} seems to be a totally new kind of thing in mapset structure (or?), so I think some library additions and further considerations are needed.

Yes, it is a new thing in a mapset structure as signatures do not belong to rasters, vectors or groups but are on their own. Please clarify regarding "library additions and further considerations". I sent out a RFC to dev mailinglist and got only a bit of feedback.

If you provide some examples (or point to existing ones) people can now try in Binder without risk of messing up their mapsets. The link is https://mybinder.org/v2/gh/marisn/grass/imsigs?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fexample_notebook.ipynb

An example in Spearfish location (warning – total nonsense!):

# Copy rasters to set their band references
g.copy rast=elevation.dem,elevation.dem
g.copy rast=landcover.orig,landcover.orig
g.copy rast=elevation.10m,elevation.10m
g.copy rast=landcover.30m,landcover.30m
# Prepare group for signature generation
r.support map=elevation.dem bandref=sp_elevation
r.support map=landcover.orig bandref=sp_landcover
i.group group=ingroup input=elevation.dem,landcover.orig subgroup=all
# Generate a portable signature file
i.gensig trainingmap=geology group=ingroup subgroup=all signaturefile=by_geology
# Prepare group to use for classification
r.support map=elevation.10m bandref=sp_elevation
r.support map=landcover.30m bandref=sp_landcover
i.group group=outgroup input=landcover.30m,elevation.10m subgroup=all
# Use signatures of "ingroup" to classify data of "outgroup"
i.maxlik group=outgroup subgroup=all signaturefile=by_geology output=predicted_geology

I have two additional questions. Does the band reference naming fit into these new signature files? (This goes back to getting the band reference (image collection?) naming right.) Does this totally remove signatures from groups (or is there still some relation)?

Band reference names can be anything as long as they allow to identify rasters containing data with identical semantic and value meaning (e.g. a single band of same satellite sensor from different days). Thus current band references are fine.
There is no relation between groups and signatures:

• during creation of signature a mapping between raster band and its values is written into a signature file
• before use of signature, signature values are reordered to match order of raster bands in a group (or bail-out if there is mismatch between band references in group used to create signatures and group used to apply signatures)

This allows to create signatures in one group and use them in any other group as long as groups are identical by meaning (=band references) and not necessary by band order or naming. Thus need for a new location for signature storage.

[marisn]

It seems that I have lost some stuff during merging/rebase when Python was moved around as signature prompting is not operational any more. As I have force pushed after rebase, I'll have to look into GUI code again and retest all parts of code to see if nothing else has been broken (it is!). Either this slips G8 or will have to wait for G9 :(

[wenzeslaus]

+1 from the perspective of the "element" API. It has tests. So I approve for that part. The rest is comments.

It seems it lacks documentation unless I missed something or is that so obvious that the few added sentences are enough? (I mean no sarcasm, I'm asking.)

I didn't test it nor reviewed the functionality and user interface.

[wenzeslaus]

...I sent out a RFC to dev mailinglist and got only a bit of feedback.

I see it now, but I forgot about that email and didn't make a connection - the conversation there seemed to die out (last posts I see are from Luca, Sajid and myself).

The link is https://mybinder.org/v2/gh/marisn/grass/imsigs?urlpath=lab%2Ftree%2Fdoc%2Fnotebooks%2Fexample_notebook.ipynb

An example in Spearfish location...

Any NC SPM examples for the manual? Or at least as a test where "non-sense" is fine. Spearfish is not readily available in Binder or CI.

[marisn]

Any NC SPM examples for the manual? Or at least as a test where "non-sense" is fine. Spearfish is not readily available in Binder or CI.

I updated a bit documentation of modules. As these changes are more internal than external, there are almost no changes for previous workflows. Only new thing is the requirement of having band references set for all rasters used for classification. The rest stays the same.

With current content of NC location I do not see how to nicely expose new opportunities revealed by move to portable signature files. That would need e.g. another set of LANDSAT 7 scenes.

Overall – I wouldn't call work on new signature files complete – I did all work in the library part, but a module for signature file management is still missing. Also, as you noted, would be nice to have an example displaying benefits of the new approach. But never the less, I would like to merge this ASAP to be able to move forward with 8.0 release. Missing bits can be added also later.
@nilason could you, please, re-run tests on your machine to see if all issues are now fixed?