Document /vsigzip/ convention when reading gzip files in docstring, examples and tutorial

[EwoutH]

Document the weird /vsigzip/ convention when reading gzip files in docstring, examples and tutorial. So basically this piece of infromation:

mesa-geo's from_file() immediately calls rasterio.open() without modifying the argument, you should do this:

raster_layer = mg.RasterLayer.from_file(
    f"/vsigzip/{elevation_file}", cell_cls=LakeCell, attr_name="elevation"
)

Rasterio (from GDAL) has gzip support built-in: https://gdal.org/user/virtual_file_systems.html#vsigzip-gzipped-file.

Here comes the plot twist: /vsigzip/ is not part of the data path, but a weird convention by GDAL:

/vsigzip/my.gz # (relative path to the .gz)
/vsigzip//home/even/my.gz # (absolute path to the .gz)
/vsigzip/c:\users\even\my.gz

This should be thoroughly documented in Mesa-geo, since this is a very specific piece of knowledge you won't otherwise find out and it's publicly exposed in our user example models.

Related tickets:

• Fix all GIS models mesa-examples#172
• rasterio.errors.RasterioIOError while reading gzip file rasterio/rasterio#2863

Todo

• Mention in tutorial
• Mention in docstring
• Mention in examples

[EwoutH]

Closed by #237.

[wang-boyu]

This may or may not be useful - just found a method from geopandas: geopandas.io.util.vsi_path that adds a prefix to zipped file paths and does nothing otherwise. geopandas handles vector data, but this method could be handy in converting file paths for our raster data.

[EwoutH]

Oh that’s interesting!