series#

class geowombat.series(filenames, time_names=None, band_names=None, transfer_lib='jax', crs=None, res=None, bounds=None, resampling='nearest', nodata=0, warp_mem_limit=256, num_threads=1, window_size=None, padding=None)[source]#

Bases: BaseSeries

A class for time series concurrent processing on a GPU.

Parameters:

  • filenames (list) – The list of filenames to open.

  • band_names (Optional[list]) – The band associated names.

  • transfer_lib (Optional[str]) – The library to transfer data to. Choices are [‘jax’, ‘keras’, ‘numpy’, ‘pytorch’, ‘tensorflow’].

  • crs (Optional[str]) – The coordinate reference system.

  • res (Optional[list | tuple]) – The cell resolution.

  • bounds (Optional[object]) – The coordinate bounds.

  • resampling (Optional[str]) – The resampling method.

  • nodata (Optional[float | int]) – The ‘no data’ value.

  • warp_mem_limit (Optional[int]) – The rasterio warping memory limit (in MB).

  • num_threads (Optional[int]) – The number of rasterio warping threads.

  • window_size (Optional[int | list | tuple]) – The concurrent processing window size (height, width) or -1 (i.e., entire array).

  • padding (Optional[list | tuple]) – Padding for each window. padding should be given as a tuple of (left pad, bottom pad, right pad, top pad). If padding is given, the returned list will contain a tuple of rasterio.windows.Window objects as (w1, w2), where w1 contains the normal window offsets and w2 contains the padded window offsets.

  • time_names (list) –

Requirement:

> # CUDA 11.1 > pip install –upgrade “jax[cuda111]” -f https://storage.googleapis.com/jax-releases/jax_releases.html

Attributes:
band_dict
blockxsize
blockysize
count
crs
height
nchunks
nodata
transform
width
Parameters:

  • filenames (list) –

  • time_names (list) –

  • band_names (list) –

  • transfer_lib (str) –

  • crs (str) –

  • res (list | tuple) –

  • bounds (BoundingBox | list | tuple) –

  • resampling (str) –

  • nodata (float | int) –

  • warp_mem_limit (int) –

  • num_threads (int) –

  • window_size (int | list | tuple) –

  • padding (list | tuple) –

Methods

apply(func, bands[, gain, offset, ...])

Applies a function concurrently over windows.

group_dates(data, image_dates, band_names)

Groups data by dates.

read(bands[, window, gain, offset, pool, ...])

Reads a window.

ndarray_to_darray

open

warp

Methods Summary

apply(func, bands[, gain, offset, ...])

Applies a function concurrently over windows.

read(bands[, window, gain, offset, pool, ...])

Reads a window.

Methods Documentation

apply(func, bands, gain=1.0, offset=0.0, processes=False, num_workers=1, monitor_progress=True, outfile=None, bigtiff='NO', kwargs={})[source]#

Applies a function concurrently over windows.

Parameters:

  • func (object | str | list | tuple) – The function to apply. If func is a string, choices are [‘cv’, ‘max’, ‘mean’, ‘min’].

  • bands (list | int) – The bands to read.

  • gain (Optional[float]) – A gain factor to apply.

  • offset (Optional[float | int]) – An offset factor to apply.

  • processes (Optional[bool]) – Whether to use process workers, otherwise use threads.

  • num_workers (Optional[int]) – The number of concurrent workers.

  • monitor_progress (Optional[bool]) – Whether to monitor progress with a tqdm bar.

  • outfile (Optional[Path | str]) – The output file.

  • bigtiff (Optional[str]) – Whether to create a BigTIFF file. Choices are [‘YES’, ‘NO’,”IF_NEEDED”, “IF_SAFER”]. Default is ‘NO’.

  • kwargs (Optional[dict]) – Keyword arguments passed to rasterio open profile.

Returns:

Window, array, [datetime, …] If outfile is not None:

None, writes to outfile

Return type:

If outfile is None

Example

>>> import itertools
>>> import geowombat as gw
>>> import rasterio as rio
>>>
>>> # Import an image with 3 bands
>>> from geowombat.data import l8_224078_20200518
>>>
>>> # Create a custom class
>>> class TemporalMean(gw.TimeModule):
>>>
>>>     def __init__(self):
>>>         super(TemporalMean, self).__init__()
>>>
>>>     # The main function
>>>     def calculate(self, array):
>>>
>>>         sl1 = (slice(0, None), slice(self.band_dict['red'], self.band_dict['red']+1), slice(0, None), slice(0, None))
>>>         sl2 = (slice(0, None), slice(self.band_dict['green'], self.band_dict['green']+1), slice(0, None), slice(0, None))
>>>
>>>         vi = (array[sl1] - array[sl2]) / ((array[sl1] + array[sl2]) + 1e-9)
>>>
>>>         return vi.mean(axis=0).squeeze()
>>>
>>> with rio.open(l8_224078_20200518) as src:
>>>     res = src.res
>>>     bounds = src.bounds
>>>     nodata = 0
>>>
>>> # Open many files, each with 3 bands
>>> with gw.series([l8_224078_20200518]*100,
>>>                band_names=['blue', 'green', 'red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply(TemporalMean(),
>>>               bands=-1,             # open all bands
>>>               gain=0.0001,          # scale from [0,10000] -> [0,1]
>>>               processes=False,      # use threads
>>>               num_workers=4,        # use 4 concurrent threads, one per window
>>>               outfile='vi_mean.tif')
>>>
>>> # Import a single-band image
>>> from geowombat.data import l8_224078_20200518_B4
>>>
>>> # Open many files, each with 1 band
>>> with gw.series([l8_224078_20200518_B4]*100,
>>>                band_names=['red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply('mean',               # built-in function over single-band images
>>>               bands=1,              # open all bands
>>>               gain=0.0001,          # scale from [0,10000] -> [0,1]
>>>               num_workers=4,        # use 4 concurrent threads, one per window
>>>               outfile='red_mean.tif')
>>>
>>> with gw.series([l8_224078_20200518_B4]*100,
>>>                band_names=['red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply(['mean', 'max', 'cv'],    # calculate multiple statistics
>>>               bands=1,                  # open all bands
>>>               gain=0.0001,              # scale from [0,10000] -> [0,1]
>>>               num_workers=4,            # use 4 concurrent threads, one per window
>>>               outfile='stack_mean.tif')
read(bands, window=None, gain=1.0, offset=0.0, pool=None, num_workers=None, tqdm_obj=None)[source]#

Reads a window.

Return type:

Any

Parameters:

  • bands (int | list) –

  • window (Window | None) –

  • gain (float) –

  • offset (float | int) –

  • pool (Any | None) –

  • num_workers (int | None) –

  • tqdm_obj (Any | None) –

apply(func, bands, gain=1.0, offset=0.0, processes=False, num_workers=1, monitor_progress=True, outfile=None, bigtiff='NO', kwargs={})[source]#

Applies a function concurrently over windows.

Parameters:

  • func (object | str | list | tuple) – The function to apply. If func is a string, choices are [‘cv’, ‘max’, ‘mean’, ‘min’].

  • bands (list | int) – The bands to read.

  • gain (Optional[float]) – A gain factor to apply.

  • offset (Optional[float | int]) – An offset factor to apply.

  • processes (Optional[bool]) – Whether to use process workers, otherwise use threads.

  • num_workers (Optional[int]) – The number of concurrent workers.

  • monitor_progress (Optional[bool]) – Whether to monitor progress with a tqdm bar.

  • outfile (Optional[Path | str]) – The output file.

  • bigtiff (Optional[str]) – Whether to create a BigTIFF file. Choices are [‘YES’, ‘NO’,”IF_NEEDED”, “IF_SAFER”]. Default is ‘NO’.

  • kwargs (Optional[dict]) – Keyword arguments passed to rasterio open profile.

Returns:

Window, array, [datetime, …] If outfile is not None:

None, writes to outfile

Return type:

If outfile is None

Example

>>> import itertools
>>> import geowombat as gw
>>> import rasterio as rio
>>>
>>> # Import an image with 3 bands
>>> from geowombat.data import l8_224078_20200518
>>>
>>> # Create a custom class
>>> class TemporalMean(gw.TimeModule):
>>>
>>>     def __init__(self):
>>>         super(TemporalMean, self).__init__()
>>>
>>>     # The main function
>>>     def calculate(self, array):
>>>
>>>         sl1 = (slice(0, None), slice(self.band_dict['red'], self.band_dict['red']+1), slice(0, None), slice(0, None))
>>>         sl2 = (slice(0, None), slice(self.band_dict['green'], self.band_dict['green']+1), slice(0, None), slice(0, None))
>>>
>>>         vi = (array[sl1] - array[sl2]) / ((array[sl1] + array[sl2]) + 1e-9)
>>>
>>>         return vi.mean(axis=0).squeeze()
>>>
>>> with rio.open(l8_224078_20200518) as src:
>>>     res = src.res
>>>     bounds = src.bounds
>>>     nodata = 0
>>>
>>> # Open many files, each with 3 bands
>>> with gw.series([l8_224078_20200518]*100,
>>>                band_names=['blue', 'green', 'red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply(TemporalMean(),
>>>               bands=-1,             # open all bands
>>>               gain=0.0001,          # scale from [0,10000] -> [0,1]
>>>               processes=False,      # use threads
>>>               num_workers=4,        # use 4 concurrent threads, one per window
>>>               outfile='vi_mean.tif')
>>>
>>> # Import a single-band image
>>> from geowombat.data import l8_224078_20200518_B4
>>>
>>> # Open many files, each with 1 band
>>> with gw.series([l8_224078_20200518_B4]*100,
>>>                band_names=['red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply('mean',               # built-in function over single-band images
>>>               bands=1,              # open all bands
>>>               gain=0.0001,          # scale from [0,10000] -> [0,1]
>>>               num_workers=4,        # use 4 concurrent threads, one per window
>>>               outfile='red_mean.tif')
>>>
>>> with gw.series([l8_224078_20200518_B4]*100,
>>>                band_names=['red'],
>>>                crs='epsg:32621',
>>>                res=res,
>>>                bounds=bounds,
>>>                nodata=nodata,
>>>                num_threads=4,
>>>                window_size=(1024, 1024)) as src:
>>>
>>>     src.apply(['mean', 'max', 'cv'],    # calculate multiple statistics
>>>               bands=1,                  # open all bands
>>>               gain=0.0001,              # scale from [0,10000] -> [0,1]
>>>               num_workers=4,            # use 4 concurrent threads, one per window
>>>               outfile='stack_mean.tif')
read(bands, window=None, gain=1.0, offset=0.0, pool=None, num_workers=None, tqdm_obj=None)[source]#

Reads a window.

Return type:

Any

Parameters:

  • bands (int | list) –

  • window (Window | None) –

  • gain (float) –

  • offset (float | int) –

  • pool (Any | None) –

  • num_workers (int | None) –

  • tqdm_obj (Any | None) –