eolearn.core.utils.parsing

A module implementing the FeatureParser class that simplifies specifying features.

class eolearn.core.utils.parsing.FeatureParser(features, allowed_feature_types=Ellipsis)[source]

Bases: object

Class for parsing a variety of feature specifications into a streamlined format.

This class takes care of parsing multiple inputs that specify features and includes some additional options:

  • Fix allowed types, which raises an appropriate exception if a forbidden type is detected.

  • Parsing directly or parsing over an EOPatch. If an EOPatch object is provided the parser fails if a specified feature is missing from the EOPatch. Because EOPatch objects are usually provided to EOTasks at runtime, the parser preprocesses and validates the input feature specifications at initialization to ensure exceptions at an appropriate point.

  • The user can provide ellipsis … as a way to specify all features. When combined with a feature type it is understood as all features of a given type. When using … an EOPatch must be provided when parsing features, except when used only for BBOX and TIMESTAMPS features.

  • The parser can output pairs (feature_type, feature_name) or triples (feature_type, old_name, new_name), which come in hand in many cases. If the user does not provide an explicit new name, the old_name and new_name are equal.

The main input formats are as follows:

  1. Ellipsis … signify that all features of all types should be parsed.

  2. Input representing a single feature, where the first element is a FeatureType element and the other (or two for renaming) is a string.

  3. Dictionary mapping feature_type keys to sequences of feature names. Feature names are either a sequence of strings, pairs of shape (old_name, new_name) or …. Example:

    {
    FeatureType.DATA: [
        ('S2-BANDS', 'INTERPOLATED_S2_BANDS'),
        ('L8-BANDS', 'INTERPOLATED_L8_BANDS'),
        'NDVI',
        'NDWI',
    },
    FeatureType.MASK: ...
}

  4. Sequences of elements, each describing a feature. When describing all features of a given feature type use (feature_type, …). For specific features one can use (feature_type, feature_name) or even (feature_type, old_name, new_name) for renaming.

    [
    (FeatureType.DATA, 'BANDS'),
    (FeatureType.MASK, 'CLOUD_MASK', 'NEW_CLOUD_MASK'),
]

Outputs of the FeatureParser are:

  • For get_features a list of pairs (feature_type, feature_name).

  • For get_renamed_features a list of triples (feature_type, old_name, new_name).

Parameters:

  • features (FeaturesSpecification) – A collection of features in one of the supported formats

  • allowed_feature_types (Iterable[FeatureType] | Callable[[FeatureType], bool] | EllipsisType) – Makes sure that only features of these feature types will be returned, otherwise an error is raised

Raises:

ValueError

get_feature_specifications()[source]

Returns the feature specifications in a more streamlined fashion.

Requests for all features, e.g. (FeatureType.DATA, …), are returned directly.

Return type:

list[tuple[eolearn.core.constants.FeatureType, str | ellipsis]]

get_features(eopatch=None)[source]

Returns a list of (feature_type, feature_name) pairs.

For features that specify renaming, the new name of the feature is ignored.

If eopatch is provided, the method checks that the EOPatch contains all the specified data and processes requests for all features, e.g. (FeatureType.DATA, …), by listing all available features of given type.

If eopatch is not provided the method fails if an all-feature request is in the specification.

Parameters:

eopatch (EOPatch | None) –

Return type:

list[Feature]

get_renamed_features(eopatch=None)[source]

Returns a list of (feature_type, old_name, new_name) triples.

For features without a specified renaming the new name is equal to the old one.

If eopatch is provided, the method checks that the EOPatch contains all the specified data and processes requests for all features, e.g. (FeatureType.DATA, …), by listing all available features of given type. In these cases the returned old_name and new_name are equal.

If eopatch is not provided the method fails if an all-feature request is in the specification.

Parameters:

eopatch (EOPatch | None) –

Return type:

list[tuple[FeatureType, str, str]]

eolearn.core.utils.parsing.parse_feature(feature, eopatch=None, allowed_feature_types=Ellipsis)[source]

Parses input describing a single feature into a (feature_type, feature_name) pair.

See FeatureParser for viable inputs.

Parameters:

  • feature (SingleFeatureSpec) –

  • eopatch (EOPatch | None) –

  • allowed_feature_types (EllipsisType | Iterable[FeatureType] | Callable[[FeatureType], bool]) –

Return type:

Feature

eolearn.core.utils.parsing.parse_renamed_feature(feature, eopatch=None, allowed_feature_types=Ellipsis)[source]

Parses input describing a single feature into a (feature_type, old_name, new_name) triple.

See FeatureParser for viable inputs.

Parameters:

  • feature (SingleFeatureSpec) –

  • eopatch (EOPatch | None) –

  • allowed_feature_types (EllipsisType | Iterable[FeatureType] | Callable[[FeatureType], bool]) –

Return type:

tuple[FeatureType, str, str]

eolearn.core.utils.parsing.parse_features(features, eopatch=None, allowed_feature_types=Ellipsis)[source]

Parses input describing features into a list of (feature_type, feature_name) pairs.

See FeatureParser for viable inputs.

Parameters:

  • features (FeaturesSpecification) –

  • eopatch (EOPatch | None) –

  • allowed_feature_types (EllipsisType | Iterable[FeatureType] | Callable[[FeatureType], bool]) –

Return type:

list[Feature]

eolearn.core.utils.parsing.parse_renamed_features(features, eopatch=None, allowed_feature_types=Ellipsis)[source]

Parses input describing features into a list of (feature_type, old_name, new_name) triples.

See FeatureParser for viable inputs.

Parameters:

  • features (FeaturesSpecification) –

  • eopatch (EOPatch | None) –

  • allowed_feature_types (EllipsisType | Iterable[FeatureType] | Callable[[FeatureType], bool]) –

Return type:

list[tuple[FeatureType, str, str]]