Image Collection<a class="headerlink" href="#module-sgis.raster.image_collection" title="Link to this heading">¶

Returns:

Band with buffered values.

clip(mask)[source]¶

Clip band values to geometry mask while preserving bounds.

Return type:: Band
Parameters:: mask (GeoDataFrame | GeoSeries | Polygon | MultiPolygon)

property crs: CRS | None¶: Coordinate reference system.

property date: str¶: Tile name from filename_regex.

classmethod from_geopandas(gdf, *, res=None, out_shape=None, bounds=None, fill=0, all_touched=False, merge_alg=MergeAlg.replace, default_value=1, dtype=None, **kwargs)[source]¶

Create Band from a GeoDataFrame.

Return type:

None

Parameters:

gdf (GeoDataFrame | GeoSeries)
res (int | None)
out_shape (tuple[int, int] | None)
bounds (Any | None)
fill (int)
all_touched (bool)
merge_alg (Callable)
default_value (int)
dtype (Any | None)

get_n_largest(n, precision=1e-06, column='value')[source]¶

Get the largest values of the array as polygons in a GeoDataFrame.

Return type:

GeoDataFrame

Parameters:

n (int)
precision (float)
column (str)

get_n_smallest(n, precision=1e-06, column='value')[source]¶

Get the lowest values of the array as polygons in a GeoDataFrame.

Return type:

GeoDataFrame

Parameters:

n (int)
precision (float)
column (str)

gradient(degrees=False, copy=True)[source]¶

Get the slope of an elevation band.

Calculates the absolute slope between the grid cells based on the image resolution.

For multi-band images, the calculation is done for each band.

Parameters:

band – band instance.
degrees (bool) – If False (default), the returned values will be in ratios, where a value of 1 means 1 meter up per 1 meter forward. If True, the values will be in degrees from 0 to 90.
copy (bool) – Whether to copy or overwrite the original Raster. Defaults to True.

Return type:

Returns:

The class instance with new array values, or a copy if copy is True.

Examples:¶

Making an array where the gradient to the center is always 10.

>>> import sgis as sg
>>> import numpy as np
>>> arr = np.array(
...         [
...             [100, 100, 100, 100, 100],
...             [100, 110, 110, 110, 100],
...             [100, 110, 120, 110, 100],
...             [100, 110, 110, 110, 100],
...             [100, 100, 100, 100, 100],
...         ]
...     )

Now let’s create a Raster from this array with a resolution of 10.

>>> band = sg.Band(arr, crs=None, bounds=(0, 0, 50, 50), res=10)

The gradient will be 1 (1 meter up for every meter forward). The calculation is by default done in place to save memory.

>>> band.gradient(copy=False)
>>> band.values
array([[0., 1., 1., 1., 0.],
    [1., 1., 1., 1., 1.],
    [1., 1., 0., 1., 1.],
    [1., 1., 1., 1., 1.],
    [0., 1., 1., 1., 0.]])

property has_array: bool¶: Whether the array is loaded.

property height: int¶: Pixel heigth of the image band.

load(bounds=None, indexes=None, masked=True, file_system=None, **kwargs)[source]¶

Load and potentially clip the array.

The array is stored in the ‘values’ property.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)
masked (bool)

sample(size=1000, mask=None, **kwargs)[source]¶

Take a random spatial sample area of the Band.

Return type:

Parameters:

size (int)
mask (Any)

property tile: str¶: Tile name from filename_regex.

to_geopandas(column='value', dropna=True)[source]¶

Create a GeoDataFrame from the image Band.

Parameters:

column (str) – Name of resulting column that holds the raster values.
dropna (bool) – Whether to remove values that are NA or equal to the nodata value.

Return type:

GeoDataFrame

Returns:

A GeoDataFrame with a geometry column and array values.

to_numpy()[source]¶

Convert the raster to a numpy.ndarray.

Return type:: ndarray | MaskedArray

to_xarray()[source]¶

Convert the raster to an xarray.DataArray.

Return type:: DataArray

value_counts()[source]¶

Value count of each value of the band’s array.

Return type:: Series

property values: ndarray¶: The numpy array, if loaded.

property width: int¶: Pixel width of the image band.

write(path, driver='GTiff', compress='LZW', file_system=None, **kwargs)[source]¶

Write the array as an image file.

Return type:

None

Parameters:

path (str | Path)
driver (str)
compress (str)

zonal(polygons, aggfunc, array_func=None, dropna=True)[source]¶

Calculate zonal statistics in polygons.

Parameters:

polygons (GeoDataFrame) – A GeoDataFrame of polygon geometries.
aggfunc (str | Callable | list[Callable | str]) – Function(s) of which to aggregate the values within each polygon.
array_func (Callable | None) – Optional calculation of the raster array before calculating the zonal statistics.
dropna (bool) – If True (default), polygons with all missing values will be removed.

Return type:

GeoDataFrame

Returns:

A GeoDataFrame with aggregated values per polygon.

class BandMasking(band_id, values)[source]¶

Bases: object

Frozen dict with forced keys.

Parameters:

band_id (str)
values (Sequence[int] | dict[int, Any])

class DataArray[source]¶

Bases: object

Placeholder.

class Dataset[source]¶

Bases: object

Placeholder.

class GCSFile[source]¶

Bases: object

Placeholder.

class Image(data=None, res=<class 'sgis.raster.image_collection.None_'>, mask=None, processes=1, df=None, nodata=None, all_file_paths=None, **kwargs)[source]¶

Bases: _ImageBandBase

Image consisting of one or more Bands.

Parameters:

data (str | Path | Sequence[Band] | None)
res (int | None_)
mask (Band | None)
processes (int)
df (DataFrame | None)
nodata (int | None)
all_file_paths (list[str] | None)

apply(func, **kwargs)[source]¶

Apply a function to each band of the Image.

Return type:: Image
Parameters:: func (Callable)

band_class¶: alias of Band

property band_ids: list[str]¶: The Band ids.

property bands: list[Band]¶: The Image Bands.

property bounds: tuple[int, int, int, int] | None¶: Bounds of the Image (minx, miny, maxx, maxy).

clip(mask, copy=True)[source]¶

Clip band values to geometry mask while preserving bounds.

Return type:

Parameters:

mask (GeoDataFrame | GeoSeries | Polygon | MultiPolygon)
copy (bool)

copy()[source]¶

Copy the instance and its attributes.

Return type:: Image

property crs: str | None¶: Coordinate reference system of the Image.

property date: str¶: Tile name from filename_regex.

property file_paths: list[str]¶: The Band file paths.

get_brightness(bounds=None, rbg_bands=None)[source]¶

Get a Band with a brightness score of the Image’s RBG bands.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
rbg_bands (list[str] | None)

load(bounds=None, indexes=None, file_system=None, **kwargs)[source]¶

Load all image Bands with threading.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)

ndvi(red_band, nir_band, padding=0, copy=True)[source]¶

Calculate the NDVI for the Image.

Return type:

NDVIBand

Parameters:

red_band (str)
nir_band (str)
padding (int)
copy (bool)

sample(n=1, size=1000, mask=None, **kwargs)[source]¶

Take a random spatial sample of the image.

Return type:

Parameters:

n (int)
size (int)
mask (Any)

property tile: str¶: Tile name from filename_regex.

to_geopandas(column='value')[source]¶

Convert the array to a GeoDataFrame of grid polygons and values.

Return type:: GeoDataFrame
Parameters:: column (str)

to_xarray()[source]¶

Convert the raster to an xarray.DataArray.

Return type:: DataArray

class ImageCollection(data, res=<class 'sgis.raster.image_collection.None_'>, level=<class 'sgis.raster.image_collection.None_'>, processes=1, metadata=None, nodata=None, **kwargs)[source]¶

Bases: _ImageBase

Collection of Images.

Loops though Images.

Parameters:

data (str | Path | Sequence[Image] | Sequence[str | Path])
res (int | None_)
level (str | None_ | None)
processes (int)
metadata (str | dict | DataFrame | None)
nodata (int | None)

apply(func, **kwargs)[source]¶

Apply a function to all bands in each image of the collection.

Return type:: ImageCollection
Parameters:: func (Callable)

band_class¶: alias of Band

property bounds: tuple[int, int, int, int]¶: Total bounds for all Images combined.

clip(mask, dropna=True, copy=True)[source]¶

Clip all image Bands while preserving bounds.

Return type:

Parameters:

mask (Geometry | GeoDataFrame | GeoSeries)
dropna (bool)
copy (bool)

property crs: Any¶: Common coordinate reference system of the Images.

property date: Any¶: List of image dates.

explode(copy=True)[source]¶

Make all Images single-banded.

Return type:: ImageCollection
Parameters:: copy (bool)

filter(bands=None, date_ranges=None, bbox=None, intersects=None, max_cloud_cover=None, copy=True)[source]¶

Filter images and bands in the collection.

Return type:

Parameters:

bands (str | list[str] | None)
date_ranges (tuple[str | Timestamp | None, str | Timestamp | None] | tuple[tuple[str | Timestamp | None, str | Timestamp | None], ...])
bbox (GeoDataFrame | GeoSeries | Geometry | tuple[float] | None)
intersects (GeoDataFrame | GeoSeries | Geometry | tuple[float] | None)
max_cloud_cover (int | None)
copy (bool)

get_unique_band_ids()[source]¶

Get a list of unique band_ids across all images.

Return type:: list[str]

groupby(by, copy=True, **kwargs)[source]¶

Group the Collection by Image or Band attribute(s).

Return type:

ImageCollectionGroupBy

Parameters:

by (str | list[str])
copy (bool)

image_class¶: alias of Image

property image_paths: Any¶: List of image paths.

property images: list[Image]¶: List of images in the Collection.

load(bounds=None, indexes=None, file_system=None, **kwargs)[source]¶

Load all image Bands with threading.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
indexes (int | tuple[int] | None)

merge(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge all areas and all bands to a single Band.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str | Callable)
as_int (bool)
indexes (int | tuple[int] | None)

merge_by_band(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge all areas to a single tile, one band per band_id.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str)
as_int (bool)
indexes (int | tuple[int] | None)

pixelwise(func, kwargs=None, index_aligned_kwargs=None, masked=True, processes=None)[source]¶

Run a function for each pixel.

The function should take a 1d array as first argument. This will be the pixel values for all bands in all images in the collection.

Return type:

ndarray | tuple[ndarray] | None

Parameters:

func (Callable)
kwargs (dict | None)
index_aligned_kwargs (dict | None)
masked (bool)
processes (int | None)

plot_pixels(by=None, x_var='date', y_label='value', p=0.95, ylim=None, figsize=(20, 8), rounding=3)[source]¶

Plot each individual pixel in a dotplot for all dates.

Parameters:

by (str | list[str] | None) – Band attributes to groupby. Defaults to “bounds” and “band_id” if all bands have no-None band_ids, otherwise defaults to “bounds”.
x_var (str) – Attribute to use on the x-axis. Defaults to “date” if the ImageCollection is sortable by date, otherwise a range index. Can be set to “days_since_start”.
y_label (str) – Label to use on the y-axis.
p (float) – p-value for the confidence interval.
ylim (tuple[float, float] | None) – Limits of the y-axis.
figsize (tuple[int]) – Figure size as tuple (width, height).
rounding (int) – rounding of title n

Return type:

None

sample(n=1, size=500)[source]¶

Sample one or more areas of a given size and set this as mask for the images.

Return type:

Parameters:

n (int)
size (int)

sample_images(n)[source]¶

Sample one or more images in a copy of the ImageCollection.

Return type:: ImageCollection
Parameters:: n (int)

sample_tiles(n)[source]¶

Sample one or more tiles in a copy of the ImageCollection.

Return type:: ImageCollection
Parameters:: n (int)

sort_images(ascending=True)[source]¶

Sort Images by date, then file path if date attribute is missing.

Return type:: ImageCollection
Parameters:: ascending (bool)

to_geopandas(column='value')[source]¶

Convert each band in each Image to a GeoDataFrame.

Return type:: dict[str, GeoDataFrame]
Parameters:: column (str)

to_xarray(**kwargs)[source]¶

Convert the raster to an xarray.Dataset.

Images are converted to 2d arrays for each unique bounds. The spatial dimensions will be labeled “x” and “y”. The third dimension defaults to “date” if all images have date attributes. Otherwise defaults to the image name.

Return type:: Dataset

union_all()[source]¶

(Multi)Polygon representing the union of all image bounds.

Return type:: Polygon | MultiPolygon

class ImageCollectionGroupBy(data, by, collection)[source]¶

Bases: object

Iterator and merger class returned from groupby.

Can be iterated through like pandas.DataFrameGroupBy. Or use the methods merge_by_band or merge.

Parameters:

data (Iterable[tuple[Any], ImageCollection])
by (list[str])
collection (ImageCollection)

merge(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge each group into a single Band, returned as combined Image.

Return type:

Parameters:

bounds (tuple | Geometry | GeoDataFrame | GeoSeries | None)
method (str | Callable)
as_int (bool)
indexes (int | tuple[int] | None)

merge_by_band(bounds=None, method='mean', as_int=True, indexes=None, **kwargs)[source]¶

Merge each group into separate Bands per band_id, returned as an ImageCollection.

Return type: