Add custom RasterDataset notebook

[RitwikGupta]

Using xView3 as an example to address issue #280

[ghost]

All CLA requirements met.

[isaaccorley]

Can you add the tutorial name to docs/index.rst?

[RitwikGupta]

Goes to show I should finally learn how to use Sphinx...

[calebrob6]

Thanks @RitwikGupta!

Just reviewed this but it is hard to leave comments inline on notebooks...

• I'm not able to load "https://iuu.xview3.us/". Is this the right URL / is that server up?
• Does "Copyright (c) Ritwik Gupta. All rights reserved." conflict with the CLA (https://cla.opensource.microsoft.com/microsoft/torchgeo?pullRequest=283)? I'm reading the "You grant Microsoft, and those who receive the Submission directly or indirectly from Microsoft, a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license in the Submission to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute the Submission and such derivative works, and to sublicense any or all of the foregoing rights to third parties." part but am not sure.
• I'd like to be a bit more verbose with the descriptions of what is going on, something like:

"""
Assume we have the xView3 tiny dataset downloaded and unzipped in our local directory:

xview3tiny
├── 05bc615a9b0e1159t
│ ├── bathymetry.tif
│ ├── owiMask.tif
│ ├── owiWindDirection.tif
│ ├── owiWindQuality.tif
│ ├── owiWindSpeed.tif
│ ├── VH_dB.tif
│ └── VV_dB.tif
├── 2899cfb18883251bt
│ ├── bathymetry.tif
│ ├── owiMask.tif
│ ├── owiWindDirection.tif
│ ├── owiWindQuality.tif
│ ├── owiWindSpeed.tif
│ ├── VH_dB.tif
│ └── VV_dB.tif
|.......

We would like to create a custom Dataset class based off of RasterDataset for this xView3 data. This will let us use torchgeo features such as: random sampling, merging other layers, etc. To do this, we can simply subclass RasterDataset and define a filename_glob property to select which files in a root directory will be included in the dataset. For example:
"""

Thoughts?

[RitwikGupta]

1. I had committed prior to signing the CLA, fixed.
2. Typo in the URL, fixed.
3. Added the description!

[calebrob6]

I think we try to run each notebook as an integration test before new releases and this one would break because there is no way to auto download xView3 tiny. This is generally OK with me (as other notebooks have special test behavior and exist to show one-off things). @adamjstewart, thoughts?

see notebook render here https://github.com/RitwikGupta/torchgeo/blob/custom_rasterdataset_doc/docs/tutorials/custom_raster_dataset.ipynb

[RitwikGupta]

@calebrob6 if you want to self-host xView3 tiny like you self host your subset of xView2, that should be simple enough to add in.

At some point once we finish writing the paper for xView3 I can add the right citation for it too.

[calebrob6]

We don't self-host any real data as to not run into any licensing issues. I.e., all the data at tests/data/* should be dummy data for test purposes. Having dummy data would make the example notebook a lot less cool though... If we can put xview3 tiny on zenodo or someone's google drive that'd be the ideal solution.

[RitwikGupta]

How are the integration tests for xview.py currently run?

[calebrob6]

(Disclaimer, I might have my terminology mixed up, I'm new to this software engineering stuff)

I don't think we run "integration" tests on xview.py, but run "unit" tests (https://github.com/microsoft/torchgeo/blob/main/tests/datasets/test_xview2.py). These unit tests use dummy data that we create to be in the same format as the xview2 data (tests/data/xview2/*).

Some parts of the code take too long to run on every commit to a PR, so we mark these as "slow" and only run them occasionally (see https://github.com/microsoft/torchgeo/blob/main/tests/test_train.py#L12 for an example). These are what I'm calling "integration" tests and the notebooks fall in this category.

To run the unit tests you can do pytest or pytest --cov=. --cov-report=term-missing to see test coverage.
To run the integration tests you can do pytest -m slow.

[RitwikGupta]

Okay, how's this. I created completely empty xView3 rasters with the same geotransforms as original source files. The custom RasterDataset in the notebook wouldn't be a complete xView3 dataset, so any future xview3.py could be unit tested with those files. Thoughts? This still allows you to use this notebook to manually test the code (I assume you manually run these notebooks).

[calebrob6]

haha yes, that will definitely work! Note: I just wanted Adam to weigh in on how to handle these notebooks in general. It seems reasonable to me that we don't have to force these tutorial notebooks be fully executable by the github tests (at the cost of losing some usefulness / cool factor). However, if we decide that, then we'll have to be extra vigilant about running them ourselves periodically.

[adamjstewart]

I think it makes sense to expect all of our tutorials to actually run. Without this, we have no way of testing them, so they rapidly become out-of-date. Manually running tests is a perfect recipe for not running tests. If we just want to document a feature, it doesn't need to be in a notebook.

Note: there are actually two types of integration tests we run, the slow unit tests can be run with pytest -m slow, and the notebook tests can be run with pytest --nbmake docs/tutorials. Both of these are run when creating a new release as @calebrob6 mentioned.

[calebrob6]

Okay so last changes:

• Use the example data
• is it possible to shrink the VH_dB.tif file somehow? I see it is already using LZW with predictor=2, but is also 12MB.

[RitwikGupta]

Zipping all the files together brings the total file size down to 142 KB. What's the way to have TorchGeo automatically unzip files before using them?

[calebrob6]

torchgeo.datasets.utils.download_and_extract_archive

[RitwikGupta]

Try that on for size

[calebrob6]

Fits great!

[isaaccorley]

This lgtm but while I'm here looking at the notebook, I think you can simplify the dataset further from

class XView3Polarizations(RasterDataset):
    '''
    Load xView3 polarization data that ends in *_dB.tif
    '''

    filename_glob = "*_dB.tif"

    def __init__(
        self,
        root: Path = None,
        crs: Optional[CRS] = None,
        res: Optional[float] = None,
        transforms: Optional[Callable[[Dict[str, Tensor]], Dict[str, Tensor]]] = None,
        cache: bool = True
    ) -> None:
        self.root = root

        super().__init__(root, crs, res, transforms, cache)

to just:

class XView3Polarizations(RasterDataset):
    '''
    Load xView3 polarization data that ends in *_dB.tif
    '''

    filename_glob = "*_dB.tif"

[RitwikGupta]

This was a willful decision to be explicit. If people want to modify the root, they can! Should I add a markdown comment discussing this instead?

[adamjstewart]

I agree with @isaaccorley on this one, there's no need to reimplement methods of the parent class unless you need to change them. If a different root is needed, you can change the variable that is passed into the dataset when you instantiate it.

[isaaccorley]

In this case I think we should remove the boilerplate to show how simple it is for a new user to inherit and just change the glob. However, I do think we should come up with some more examples in a future PR which show how you can customize the dataset more.

[RitwikGupta]

Is this any better?

[isaaccorley]

lgtm

[calebrob6]

What is the difference in the new one? Is the idea XView3Polarizations("xview3/train/")?

[RitwikGupta]

Yeah. It's a pretty weak way of showing how you could change things up, to be honest.

[RitwikGupta]

But I think it does open your mind up to the fact that you can add additional args and things, and use them, in your constructor.

[calebrob6]

No problem, maybe like a final cell that says something to the effect of, "Now you can do this train_ds = XView3Polarizations("xview3/train/")", whereas before you couldn't." to make that explicit?

[adamjstewart]

You could do that before and after, I don't see any point of setting self.root, it's the same as what super().__init__(...) does. I think if we want to include this we need a better example of a more complex use case. This tutorial should tell users everything they could potentially need to know to when creating your own RasterDataset.

[adamjstewart]

Looks like the header levels are too high. Can you reduce the header levels so they match the other tutorials? Also, the plot is empty. Is it supposed to be?

[calebrob6]

I just did this on main. FYI for all of us (I didn't know this anyway) that level 0 headers in markdown ("# Headers") will get included in the sidebar on the docs, e.g.

[adamjstewart]

This directory doesn't exist on Colab, so this tutorial crashes immediately when you run it. We should really write these files ourselves using rasterio inside the notebook, or download them (from GitHub or just use real images).