Composition from Rasterio and GeoPandas

GeoUtils’ main classes Raster and Vector are linked to Rasterio and GeoPandas, respectively, through class composition.

They directly rely on their robust geospatial handling functionalities, as well of that of PyProj, and add a layer on top for interfacing between rasters and vectors with higher-level operations, performing easier numerical analysis, and adding more advanced geospatial functionalities.

The Raster class composition

The Raster is a composition class with four main attributes:

1. a numpy.ma.MaskedArray as data,

2. an affine.Affine as transform,

3. a pyproj.crs.CRS as crs, and

4. a float or int as nodata.

import geoutils as gu

# Instantiate a raster from a filename on disk
filename_rast = gu.examples.get_path("exploradores_aster_dem")
rast = gu.Raster(filename_rast)
rast

Show code cell output

Hide code cell output

Raster(
  data=not_loaded; shape on disk (1, 618, 539); will load (618, 539)
  transform=| 30.00, 0.00, 627175.00|
            | 0.00,-30.00, 4852085.00|
            | 0.00, 0.00, 1.00|
  crs=EPSG:32718
  nodata=-9999.0)

From these four main attributes, many other derivatives attributes exist, such as bounds or res to describe georeferencing. When a Raster is based on an on-disk dataset, other attributes exist such as name or driver, see The georeferenced raster (Raster) for a summary, or the dedicated sections of the API for a full listing.

Note

By default, data is not loaded during instantiation. See Implicit lazy loading for more details.

# Show summarized information
rast.info()

Show code cell output

Hide code cell output

Driver:               GTiff 
Opened from file:     /home/docs/checkouts/readthedocs.org/user_builds/adebardo-geoutils/checkouts/latest/geoutils/example_data/Exploradores_ASTER/AST_L1A_00303182012144228_Z.tif 
Filename:             /home/docs/checkouts/readthedocs.org/user_builds/adebardo-geoutils/checkouts/latest/geoutils/example_data/Exploradores_ASTER/AST_L1A_00303182012144228_Z.tif 
Loaded?               False 
Modified since load?  False 
Grid size:            539, 618
Number of bands:      1
Data types:           float32
Coordinate system:    ['EPSG:32718']
Nodata value:         -9999.0
Pixel interpretation: Area
Pixel size:           30.0, 30.0
Upper left corner:    627175.0, 4852085.0
Lower right corner:   643345.0, 4833545.0

Important

The Raster is not a composition of either a rasterio.io.DatasetReader, a rasterio.io.MemoryFile or a rasterio.io.DatasetWriter. It is only linked to those objects to initiate a Raster instance which first loads the metadata (notably the three main metadata attributes crs, transform and nodata). Then, explicitly or implicitly, it can also load the array data when an on-disk dataset exists, or to_file the in-memory dataset to a file.

A Raster generally exists only as an in-memory dataset, not linked to anything else than a numpy.ma.MaskedArray in data (for instance, when creating from from_array()). If a numerical operation is performed on a Raster opened from an on-disk dataset, the new dataset will be modified in-memory.

Note

To check if a Raster was loaded from the on-disk data, use the is_loaded attribute.

To check if the Raster was modified since loading from the on-disk data, use the is_modified attribute.

See The georeferenced raster (Raster) for more details.

The Vector class composition

A Vector is a composition class with a single main attribute: a GeoDataFrame as ds.

A Vector’s dataframe ds is directly loaded in-memory (might evolve towards lazy behaviour soon through Dask-GeoPandas).

# Instantiate a vector from a filename on disk
filename_vect = gu.examples.get_path("exploradores_rgi_outlines")
vect = gu.Vector(filename_vect)
vect

Show code cell output

Hide code cell output

Vector(
  ds=             RGIId         GLIMSId   BgnDate   EndDate   CenLon   CenLat  \
       0   RGI60-17.08409  G286876E46647S  20009999  20030531 -73.1236 -46.6473   
       1   RGI60-17.08414  G286891E46646S  20009999  20030531 -73.1091 -46.6458   
       2   RGI60-17.08421  G286879E46639S  20009999  20030531 -73.1212 -46.6385   
       3   RGI60-17.08422  G286891E46638S  20009999  20030531 -73.1089 -46.6378   
       4   RGI60-17.08440  G286866E46604S  20009999  20030531 -73.1340 -46.6040   
       5   RGI60-17.08444  G286927E46605S  20009999  20030531 -73.0726 -46.6047   
       6   RGI60-17.08461  G286886E46584S  20009999  20030531 -73.1144 -46.5838   
       7   RGI60-17.08470  G286905E46592S  20009999  20030531 -73.0947 -46.5923   
       8   RGI60-17.08481  G286896E46574S  20009999  20030531 -73.1036 -46.5743   
       9   RGI60-17.08503  G286874E46559S  20009999  20030531 -73.1262 -46.5587   
       10  RGI60-17.08517  G286877E46552S  20009999  20030531 -73.1227 -46.5517   
       11  RGI60-17.08519  G286862E46546S  20009999  20030531 -73.1381 -46.5463   
       12  RGI60-17.08523  G286917E46559S  20009999  20030531 -73.0834 -46.5588   
       13  RGI60-17.08531  G286925E46542S  20009999  20030531 -73.0746 -46.5418   
       14  RGI60-17.08558  G286902E46514S  20009999  20030531 -73.0980 -46.5142   
       15  RGI60-17.08613  G286738E46487S  20009999  20030531 -73.2620 -46.4874   
       16  RGI60-17.08618  G286734E46482S  20009999  20030531 -73.2661 -46.4821   
       17  RGI60-17.08626  G286720E46478S  20009999  20030531 -73.2801 -46.4777   
       18  RGI60-17.08631  G286750E46481S  20009999  20030531 -73.2499 -46.4810   
       19  RGI60-17.08639  G286646E46474S  20009999  20030531 -73.3538 -46.4741   
       20  RGI60-17.08642  G286734E46476S  20009999  20030531 -73.2656 -46.4758   
       21  RGI60-17.08643  G286854E46466S  20009999  20030531 -73.1460 -46.4663   
       22  RGI60-17.08646  G286650E46467S  20009999  20030531 -73.3498 -46.4665   
       23  RGI60-17.08651  G286871E46459S  20009999  20030531 -73.1288 -46.4589   
       24  RGI60-17.08658  G286874E46454S  20009999  20030531 -73.1264 -46.4541   
       25  RGI60-17.08663  G286838E46450S  20009999  20030531 -73.1619 -46.4501   
       26  RGI60-17.08664  G286661E46457S  20009999  20030531 -73.3390 -46.4568   
       27  RGI60-17.08668  G286843E46450S  20009999  20030531 -73.1569 -46.4498   
       28  RGI60-17.08673  G286610E46451S  20009999  20030531 -73.3900 -46.4507   
       29  RGI60-17.08703  G286615E46454S  20009999  20030531 -73.3851 -46.4538   
       30  RGI60-17.15808  G286520E46720S  20011103  -9999999 -73.4800 -46.7200   
       31  RGI60-17.15809  G286570E46600S  20011103  -9999999 -73.4300 -46.6000   
       32  RGI60-17.15815  G286550E46560S  20011103  -9999999 -73.4500 -46.5600   
       33  RGI60-17.15821  G286530E46483S  20011103  -9999999 -73.4700 -46.4830   
       34  RGI60-17.15822  G286287E46621S  20011103  -9999999 -73.7130 -46.6210   
       35  RGI60-17.15825  G286620E46550S  20011103  -9999999 -73.3800 -46.5500   
       36  RGI60-17.15826  G286735E46710S  20011103  -9999999 -73.2650 -46.7100   
       37  RGI60-17.15827  G286705E46538S  20011103  -9999999 -73.2950 -46.5380   
       38  RGI60-17.15828  G286731E46517S  20011103  -9999999 -73.2690 -46.5170   
       39  RGI60-17.15829  G286746E46519S  20011103  -9999999 -73.2540 -46.5190   
       40  RGI60-17.15830  G286735E46710S  20011103  -9999999 -73.2650 -46.7100   
       41  RGI60-17.15831  G286716E46597S  20011103  -9999999 -73.2840 -46.5970   
       42  RGI60-17.15832  G286735E46710S  20011103  -9999999 -73.2650 -46.7100   
       43  RGI60-17.15833  G286767E46628S  20011103  -9999999 -73.2330 -46.6280   
       44  RGI60-17.15834  G286765E46650S  20011103  -9999999 -73.2350 -46.6500   
       45  RGI60-17.15835  G286735E46710S  20011103  -9999999 -73.2650 -46.7100   
       46  RGI60-17.15836  G286697E46659S  20011103  -9999999 -73.3030 -46.6590   
       
          O1Region O2Region     Area  Zmin  ...  Aspect   Lmax  Status  Connect  \
       0        17        1    0.520  1182  ...     196    797       0        0   
       1        17        1    1.342  1181  ...     152   1381       0        0   
       2        17        1    0.530  1443  ...     302    977       0        0   
       3        17        1    0.924  1354  ...      89   1264       0        0   
       4        17        1    0.156  1124  ...     156    524       0        0   
       5        17        1    3.895   967  ...     219   3499       0        0   
       6        17        1    0.087  1405  ...     232    361       0        0   
       7        17        1    9.866   741  ...     199   5967       0        0   
       8        17        1    2.200  1006  ...     278   1890       0        0   
       9        17        1    1.919  1003  ...     202   1885       0        0   
       10       17        1    2.252   995  ...      32   1271       0        0   
       11       17        1    0.596  1166  ...     326    813       0        0   
       12       17        1    5.487   800  ...     308   2465       0        0   
       13       17        1    2.191   948  ...      62   2125       0        0   
       14       17        1    0.094  1251  ...     154    236       0        0   
       15       17        1    0.036  1275  ...     139    396       0        0   
       16       17        1    0.109  1361  ...       0    355       0        0   
       17       17        1    0.109  1373  ...      71    215       0        0   
       18       17        1    0.506  1227  ...     141    499       0        0   
       19       17        1    0.234  1074  ...     130    316       0        0   
       20       17        1    1.587  1136  ...     344   1935       0        0   
       21       17        1    0.210  1243  ...     145    451       0        0   
       22       17        1    0.118  1170  ...     102    293       0        0   
       23       17        1    0.187  1245  ...     165    379       0        0   
       24       17        1    0.030  1216  ...      87    180       0        0   
       25       17        1    0.038  1310  ...     182    250       0        0   
       26       17        1    0.197  1189  ...     131    325       0        0   
       27       17        1    0.123  1136  ...     139    526       0        0   
       28       17        1    0.681   790  ...     196    864       0        0   
       29       17        1    1.322   940  ...     116    995       0        0   
       30       17        1  721.950    43  ...     265  53509       0        0   
       31       17        1  126.949    23  ...     287  17716       0        0   
       32       17        1   71.511    47  ...     302  22268       0        0   
       33       17        1    7.013   289  ...      53   6261       0        0   
       34       17        1    1.453   846  ...     124    735       0        0   
       35       17        1   65.501   218  ...      24  17953       0        0   
       36       17        1    0.442  1218  ...      78    466       0        0   
       37       17        1    4.470  1210  ...     350   1574       0        0   
       38       17        1    1.624  1186  ...      39   2221       0        0   
       39       17        1    0.891  1111  ...      96    937       0        0   
       40       17        1    0.180   796  ...     150    736       0        0   
       41       17        1   85.788   158  ...      54  19749       0        0   
       42       17        1    1.025   904  ...     118    560       0        0   
       43       17        1   13.403   340  ...      68  10501       0        0   
       44       17        1   10.522   510  ...     113   7012       0        0   
       45       17        1    7.632   775  ...     231   1184       0        0   
       46       17        1   41.513   380  ...     123  13262       0        0   
       
           Form  TermType  Surging  Linkages          Name  \
       0      0         0        9         9          None   
       1      0         0        9         9          None   
       2      0         0        9         9          None   
       3      0         0        9         9          None   
       4      0         0        9         9          None   
       5      0         0        9         9          None   
       6      0         0        9         9          None   
       7      0         2        9         9          None   
       8      0         0        9         9          None   
       9      1         0        9         9          None   
       10     1         0        9         9          None   
       11     0         0        9         9          None   
       12     0         0        9         9          None   
       13     0         0        9         9          None   
       14     0         0        9         9          None   
       15     0         0        9         9          None   
       16     0         0        9         9          None   
       17     0         0        9         9          None   
       18     0         0        9         9          None   
       19     0         0        9         9          None   
       20     0         0        9         9          None   
       21     0         0        9         9          None   
       22     0         0        9         9          None   
       23     0         0        9         9          None   
       24     0         0        9         9          None   
       25     0         0        9         9          None   
       26     0         0        9         9          None   
       27     0         0        9         9          None   
       28     0         0        9         9          None   
       29     0         0        9         9          None   
       30     0         1        9         9    San Rafael   
       31     0         2        9         9        Gualas   
       32     0         2        9         9      Reichert   
       33     0         2        9         9         Verde   
       34     0         0        9         9          None   
       35     0         2        9         9        Grosse   
       36     0         0        9         9          None   
       37     0         0        9         9          None   
       38     0         0        9         9          None   
       39     0         0        9         9          None   
       40     0         0        9         9          None   
       41     0         0        9         9  Exploradores   
       42     0         0        9         9          None   
       43     0         0        9         9          Bayo   
       44     0         0        9         9           U-6   
       45     0         0        9         9          None   
       46     0         2        9         9         Fiero   
       
                                                    geometry  
       0   MULTIPOLYGON (((-73.11803 -46.649, -73.11829 -...  
       1   MULTIPOLYGON (((-73.10885 -46.64261, -73.10886...  
       2   MULTIPOLYGON (((-73.11682 -46.63879, -73.11678...  
       3   MULTIPOLYGON (((-73.10885 -46.64261, -73.10924...  
       4   MULTIPOLYGON (((-73.13223 -46.60028, -73.13225...  
       5   MULTIPOLYGON (((-73.06497 -46.59154, -73.06456...  
       6   MULTIPOLYGON (((-73.11366 -46.58218, -73.11259...  
       7   MULTIPOLYGON (((-73.06988 -46.57715, -73.06988...  
       8   MULTIPOLYGON (((-73.1074 -46.5641, -73.107 -46...  
       9   MULTIPOLYGON (((-73.13354 -46.55352, -73.1334 ...  
       10  MULTIPOLYGON (((-73.11662 -46.54876, -73.11676...  
       11  MULTIPOLYGON (((-73.12973 -46.54177, -73.12953...  
       12  MULTIPOLYGON (((-73.0815 -46.54548, -73.08151 ...  
       13  MULTIPOLYGON (((-73.06693 -46.54848, -73.06715...  
       14  MULTIPOLYGON (((-73.09498 -46.5129, -73.09496 ...  
       15  MULTIPOLYGON (((-73.26343 -46.48548, -73.26342...  
       16  MULTIPOLYGON (((-73.26768 -46.48257, -73.26798...  
       17  MULTIPOLYGON (((-73.27852 -46.47776, -73.27857...  
       18  MULTIPOLYGON (((-73.25453 -46.48264, -73.25492...  
       19  MULTIPOLYGON (((-73.35668 -46.47795, -73.3567 ...  
       20  MULTIPOLYGON (((-73.26943 -46.48095, -73.26939...  
       21  MULTIPOLYGON (((-73.14301 -46.46434, -73.14303...  
       22  MULTIPOLYGON (((-73.34771 -46.46459, -73.34769...  
       23  MULTIPOLYGON (((-73.12796 -46.45651, -73.12799...  
       24  MULTIPOLYGON (((-73.12474 -46.45528, -73.12476...  
       25  MULTIPOLYGON (((-73.16107 -46.44905, -73.16106...  
       26  MULTIPOLYGON (((-73.33401 -46.45251, -73.3344 ...  
       27  MULTIPOLYGON (((-73.15723 -46.4471, -73.1569 -...  
       28  MULTIPOLYGON (((-73.39064 -46.44468, -73.39045...  
       29  MULTIPOLYGON (((-73.38584 -46.45433, -73.3858 ...  
       30  MULTIPOLYGON (((-73.79749 -46.66563, -73.79788...  
       31  MULTIPOLYGON (((-73.35278 -46.60069, -73.35277...  
       32  MULTIPOLYGON (((-73.56531 -46.5474, -73.56492 ...  
       33  MULTIPOLYGON (((-73.41283 -46.50246, -73.41283...  
       34  MULTIPOLYGON (((-73.40283 -46.49692, -73.40284...  
       35  MULTIPOLYGON (((-73.31737 -46.5424, -73.31698 ...  
       36  MULTIPOLYGON (((-73.30579 -46.52468, -73.30657...  
       37  MULTIPOLYGON (((-73.2729 -46.51339, -73.27289 ...  
       38  MULTIPOLYGON (((-73.25946 -46.51777, -73.25946...  
       39  MULTIPOLYGON (((-73.25347 -46.52173, -73.25386...  
       40  MULTIPOLYGON (((-73.24741 -46.52785, -73.24742...  
       41  MULTIPOLYGON (((-73.21109 -46.59721, -73.2107 ...  
       42  MULTIPOLYGON (((-73.19973 -46.58543, -73.19973...  
       43  MULTIPOLYGON (((-73.22511 -46.63577, -73.22785...  
       44  MULTIPOLYGON (((-73.22215 -46.66623, -73.22213...  
       45  MULTIPOLYGON (((-73.24759 -46.65583, -73.2472 ...  
       46  MULTIPOLYGON (((-73.30945 -46.70913, -73.30945...  
       
       [47 rows x 23 columns]
  crs=EPSG:4326
  bounds=BoundingBox(left=np.float64(-73.85175999999996), bottom=np.float64(-46.83761999999996), right=np.float64(-73.05486243399997), top=np.float64(-46.431213112999956)))

# Show summarized information
vect.info()

Show code cell output

Hide code cell output

Filename:           /home/docs/checkouts/readthedocs.org/user_builds/adebardo-geoutils/checkouts/latest/geoutils/example_data/Exploradores_ASTER/17_rgi60_glacier_outlines.gpkg 
Coordinate system:  EPSG:4326
Extent:             [-73.85175999999996, -46.83761999999996, -73.05486243399997, -46.431213112999956] 
Number of features: 47 
Attributes:         ['RGIId', 'GLIMSId', 'BgnDate', 'EndDate', 'CenLon', 'CenLat', 'O1Region', 'O2Region', 'Area', 'Zmin', 'Zmax', 'Zmed', 'Slope', 'Aspect', 'Lmax', 'Status', 'Connect', 'Form', 'TermType', 'Surging', 'Linkages', 'Name', 'geometry']

All geospatial methods of GeoDataFrame are directly available into Vector, and cast the output logically depending on its type: to a Vector for a geometric output (e.g., boundary), or to pandas.Series that can be immediately appended to the Vector for a per-feature non-geometric output (e.g., area).

# Compute the vector's boundary
vect.boundary

Show code cell output

Hide code cell output

Vector(
  ds=                                             geometry
       0   MULTILINESTRING ((-73.11803 -46.649, -73.11829...
       1   MULTILINESTRING ((-73.10885 -46.64261, -73.108...
       2   MULTILINESTRING ((-73.11682 -46.63879, -73.116...
       3   MULTILINESTRING ((-73.10885 -46.64261, -73.109...
       4   MULTILINESTRING ((-73.13223 -46.60028, -73.132...
       5   MULTILINESTRING ((-73.06497 -46.59154, -73.064...
       6   MULTILINESTRING ((-73.11366 -46.58218, -73.112...
       7   MULTILINESTRING ((-73.06988 -46.57715, -73.069...
       8   MULTILINESTRING ((-73.1074 -46.5641, -73.107 -...
       9   MULTILINESTRING ((-73.13354 -46.55352, -73.133...
       10  MULTILINESTRING ((-73.11662 -46.54876, -73.116...
       11  MULTILINESTRING ((-73.12973 -46.54177, -73.129...
       12  MULTILINESTRING ((-73.0815 -46.54548, -73.0815...
       13  MULTILINESTRING ((-73.06693 -46.54848, -73.067...
       14  MULTILINESTRING ((-73.09498 -46.5129, -73.0949...
       15  MULTILINESTRING ((-73.26343 -46.48548, -73.263...
       16  MULTILINESTRING ((-73.26768 -46.48257, -73.267...
       17  MULTILINESTRING ((-73.27852 -46.47776, -73.278...
       18  MULTILINESTRING ((-73.25453 -46.48264, -73.254...
       19  MULTILINESTRING ((-73.35668 -46.47795, -73.356...
       20  MULTILINESTRING ((-73.26943 -46.48095, -73.269...
       21  MULTILINESTRING ((-73.14301 -46.46434, -73.143...
       22  MULTILINESTRING ((-73.34771 -46.46459, -73.347...
       23  MULTILINESTRING ((-73.12796 -46.45651, -73.127...
       24  MULTILINESTRING ((-73.12474 -46.45528, -73.124...
       25  MULTILINESTRING ((-73.16107 -46.44905, -73.161...
       26  MULTILINESTRING ((-73.33401 -46.45251, -73.334...
       27  MULTILINESTRING ((-73.15723 -46.4471, -73.1569...
       28  MULTILINESTRING ((-73.39064 -46.44468, -73.390...
       29  MULTILINESTRING ((-73.38584 -46.45433, -73.385...
       30  MULTILINESTRING ((-73.79749 -46.66563, -73.797...
       31  MULTILINESTRING ((-73.35278 -46.60069, -73.352...
       32  MULTILINESTRING ((-73.56531 -46.5474, -73.5649...
       33  MULTILINESTRING ((-73.41283 -46.50246, -73.412...
       34  MULTILINESTRING ((-73.40283 -46.49692, -73.402...
       35  MULTILINESTRING ((-73.31737 -46.5424, -73.3169...
       36  MULTILINESTRING ((-73.30579 -46.52468, -73.306...
       37  MULTILINESTRING ((-73.2729 -46.51339, -73.2728...
       38  MULTILINESTRING ((-73.25946 -46.51777, -73.259...
       39  MULTILINESTRING ((-73.25347 -46.52173, -73.253...
       40  MULTILINESTRING ((-73.24741 -46.52785, -73.247...
       41  MULTILINESTRING ((-73.21109 -46.59721, -73.210...
       42  MULTILINESTRING ((-73.19973 -46.58543, -73.199...
       43  MULTILINESTRING ((-73.22511 -46.63577, -73.227...
       44  MULTILINESTRING ((-73.22215 -46.66623, -73.222...
       45  MULTILINESTRING ((-73.24759 -46.65583, -73.247...
       46  MULTILINESTRING ((-73.30945 -46.70913, -73.309...
  crs=EPSG:4326
  bounds=BoundingBox(left=np.float64(-73.85175999999996), bottom=np.float64(-46.83761999999996), right=np.float64(-73.05486243399997), top=np.float64(-46.431213112999956)))

See The georeferenced vector (Vector) for more details.