eolearn.core.eodata

The eodata module provides core objects for handling remote sensing multi-temporal data (such as satellite imagery).

class eolearn.core.eodata.EOPatch(*, data=None, mask=None, scalar=None, label=None, vector=None, data_timeless=None, mask_timeless=None, scalar_timeless=None, label_timeless=None, vector_timeless=None, meta_info=None, bbox=None, timestamps=None)

Bases: object

The basic data object for multi-temporal remotely sensed data, such as satellite imagery and its derivatives.

The EOPatch contains multi-temporal remotely sensed data of a single patch of earth’s surface defined by the bounding box in specific coordinate reference system. The patch can be a rectangle, polygon, or pixel in space. The EOPatch object can also be used to store derived quantities, such as for example means, standard deviations, etc., of a patch. In this case the ‘space’ dimension is equivalent to a pixel.

Primary goal of EOPatch is to store remotely sensed data, usually of a shape n_time x height x width x n_features images, where height and width are the numbers of pixels in y and x, n_features is the number of features (i.e. bands/channels, cloud probability, etc.), and n_time is the number of time-slices (the number of times this patch was recorded by the satellite; can also be a single image)

In addition to that other auxiliary information is also needed and can be stored in additional attributes of the EOPatch (thus extending the functionality of numpy ndarray). These attributes are listed in the FeatureType enum.

Currently, the EOPatch object doesn’t enforce that the length of timestamps be equal to n_times dimensions of numpy arrays in other attributes.

Parameters:

• data (Mapping[str, np.ndarray] | None) –

• mask (Mapping[str, np.ndarray] | None) –

• scalar (Mapping[str, np.ndarray] | None) –

• label (Mapping[str, np.ndarray] | None) –

• vector (Mapping[str, gpd.GeoDataFrame] | None) –

• data_timeless (Mapping[str, np.ndarray] | None) –

• mask_timeless (Mapping[str, np.ndarray] | None) –

• scalar_timeless (Mapping[str, np.ndarray] | None) –

• label_timeless (Mapping[str, np.ndarray] | None) –

• vector_timeless (Mapping[str, gpd.GeoDataFrame] | None) –

• meta_info (Mapping[str, Any] | None) –

• bbox (BBox | None) –

• timestamps (list[dt.datetime] | None) –

property timestamp: list[datetime.datetime] | None

A property for handling the deprecated timestamp attribute.

property timestamps: list[datetime.datetime] | None

A property for handling the timestamps attribute.

get_timestamps(message_on_failure='This EOPatch does not contain timestamps.')

Returns the timestamps attribute if the EOPatch is temporally defined. Fails otherwise.

Parameters:

message_on_failure (str) –

Return type:

list[datetime.datetime]

property bbox: BBox | None

A property for handling the bbox attribute.

copy(features=Ellipsis, deep=False, copy_timestamps='auto')

Get a copy of the current EOPatch.

Parameters:

• features (eolearn.core.types.FeaturesSpecification) – Features to be copied into a new EOPatch. By default, all features will be copied.

• deep (bool) – If True it will make a deep copy of all data inside the EOPatch. Otherwise, only a shallow copy of EOPatch will be made. Note that BBOX and TIMESTAMPS will be copied even with a shallow copy.

• copy_timestamps (bool | Literal['auto']) – Copy timestamps to the new EOPatch. By default copies them over if all features are copied or if any temporal features are getting copied.

Returns:

An EOPatch copy.

Return type:

EOPatch

get_spatial_dimension(feature_type, feature_name)

Returns a tuple of spatial dimensions (height, width) of a feature.

Parameters:

• feature_type (FeatureType) – Type of the feature

• feature_name (str) – Name of the feature

Return type:

tuple[int, int]

get_features()

Returns a list of all non-empty features of EOPatch.

Returns:

List of non-empty features

Return type:

list[Tuple[eolearn.core.constants.FeatureType, str]]

save(path, features=Ellipsis, overwrite_permission=OverwritePermission.ADD_ONLY, filesystem=None, *, save_timestamps='auto', use_zarr=False, temporal_selection=None, compress_level=None)

Method to save an EOPatch from memory to a storage.

Parameters:

• path (str) – A location where to save EOPatch. It can be either a local path or a remote URL path.

• features (eolearn.core.types.FeaturesSpecification) – A collection of features types specifying features of which type will be saved. By default, all features will be saved.

• overwrite_permission (OverwritePermission) – A level of permission for overwriting an existing EOPatch

• filesystem (FS | None) – An existing filesystem object. If not given it will be initialized according to the path parameter.

• use_zarr (bool) – Saves numpy-array based features into Zarr files. Requires ZARR extra dependencies.

• temporal_selection (None | slice | list[int] | Literal['infer']) – Writes all of the data to the chosen temporal indices of preexisting arrays. Can be used for saving data in multiple steps for memory optimization. When set to “infer” it will match the timestamps of the EOPatch to the timestamps of the stored EOPatch to calculate indices.

• save_timestamps (bool | Literal['auto']) –

• compress_level (int | None) –

Save_timestamps:

Save the timestamps of the EOPatch. With the “auto” setting timestamps are saved if features=… or if other temporal features are being saved.

Return type:

None

static load(path, features=Ellipsis, lazy_loading=False, filesystem=None, *, load_timestamps='auto', temporal_selection=None)

Method to load an EOPatch from a storage into memory.

Parameters:

• path (str) – A location from where to load EOPatch. It can be either a local path or a remote URL path.

• features (eolearn.core.types.FeaturesSpecification) – A collection of features to be loaded. By default, all features will be loaded.

• lazy_loading (bool) – If True features will be lazy loaded.

• filesystem (FS | None) – An existing filesystem object. If not given it will be initialized according to the path parameter.

• temporal_selection (None | slice | list[int] | Callable[[list[datetime.datetime]], list[bool]]) – Only loads data corresponding to the chosen indices. Can also be a callable that, given a list of timestamps, returns a list of booleans declaring which temporal slices to load.

• load_timestamps (bool | Literal['auto']) –

Load_timestamps:

Load the timestamps of the EOPatch. With the “auto” setting timestamps are loaded if features=… or if other temporal features are being loaded.

Returns:

Loaded EOPatch

Return type:

EOPatch

merge(*eopatches, features=Ellipsis, time_dependent_op=None, timeless_op=None)

Merge features of given EOPatches into a new EOPatch.

Parameters:

• eopatches (EOPatch) – Any number of EOPatches to be merged together with the current EOPatch

• features (eolearn.core.types.FeaturesSpecification) – A collection of features to be merged together. By default, all features will be merged.

• time_dependent_op (Literal[None, 'concatenate', 'min', 'max', 'mean', 'median'] | ~typing.Callable) –

  An operation to be used to join data for any time-dependent raster feature. Before joining time slices of all arrays will be sorted. Supported options are:

  • None (default): If time slices with matching timestamps have the same values, take one. Raise an error otherwise.

  • ’concatenate’: Keep all time slices, even the ones with matching timestamps

  • ’min’: Join time slices with matching timestamps by taking minimum values. Ignore NaN values.

  • ’max’: Join time slices with matching timestamps by taking maximum values. Ignore NaN values.

  • ’mean’: Join time slices with matching timestamps by taking mean values. Ignore NaN values.

  • ’median’: Join time slices with matching timestamps by taking median values. Ignore NaN values.

• timeless_op (Literal[None, 'concatenate', 'min', 'max', 'mean', 'median'] | ~typing.Callable) –

  An operation to be used to join data for any timeless raster feature. Supported options are:

  • None (default): If arrays are the same, take one. Raise an error otherwise.

  • ’concatenate’: Join arrays over the last (i.e. bands) dimension

  • ’min’: Join arrays by taking minimum values. Ignore NaN values.

  • ’max’: Join arrays by taking maximum values. Ignore NaN values.

  • ’mean’: Join arrays by taking mean values. Ignore NaN values.

  • ’median’: Join arrays by taking median values. Ignore NaN values.

Returns:

A merged EOPatch

Return type:

EOPatch

consolidate_timestamps(timestamps)

Removes all frames from the EOPatch with a date not found in the provided timestamps list.

Parameters:

timestamps (list[datetime.datetime]) – keep frames with date found in this list

Returns:

set of removed frames’ dates

Return type:

set[datetime.datetime]

temporal_subset(timestamps)

Returns an EOPatch that only contains data for the temporal subset corresponding to timestamps.

For array-based data appropriate temporal slices are extracted. For vector data a filtration is performed.

Parameters:

timestamps (Iterable[datetime] | Iterable[int] | Callable[[list[datetime.datetime]], Iterable[bool]]) – Parameter that defines the temporal subset. Can be a collection of timestamps, a collection of timestamp indices. It is possible to also provide a callable that maps a list of timestamps to a sequence of booleans, which determine if a given timestamp is included in the subset or not.

Return type:

EOPatch

plot(feature, *, times=None, channels=None, channel_names=None, rgb=None, backend='matplotlib', config=None, **kwargs)

Plots an EOPatch feature.

Parameters:

• feature (Feature) – A feature in the EOPatch.

• times (list[int] | slice | None) – A list or a slice of indices on temporal axis to be used for plotting. If not provided all indices will be used.

• channels (list[int] | slice | None) – A list or a slice of indices on channels axis to be used for plotting. If not provided all indices will be used.

• channel_names (list[str] | None) – Names of channels of the last dimension in the given raster feature.

• rgb (tuple[int, int, int] | None) – If provided, it should be a list of 3 indices of RGB channels to be plotted. It will plot only RGB images with these channels. This only works for raster features with spatial dimension.

• backend (str | PlotBackend) – A type of plotting backend.

• config (PlotConfig | None) – A configuration object with advanced plotting parameters.

• kwargs (Any) – Parameters that are specific to a specified plotting backend.

Returns:

A plot object that depends on the backend used.

Return type:

object