eolearn.core.utils.parsing

A module implementing the FeatureParser class that simplifies specifying features.

class eolearn.core.utils.parsing.FeatureParser(features, allowed_feature_types=None)[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 timestamp 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, either FeatureType.BBOX, FeatureType.TIMESTAMP or a tuple 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 . For feature types with no names (BBox and timestamps) one should use None in place of the sequence. Example:

    {
        FeatureType.DATA: [
            ('S2-BANDS', 'INTERPOLATED_S2_BANDS'),
            ('L8-BANDS', 'INTERPOLATED_L8_BANDS'),
            'NDVI',
            'NDWI',
        },
        FeatureType.MASK: ...
        FeatureType.BBOX: None
    }
    
  4. Sequences of elements, each describing a feature. For elements describing a feature type it is understood as (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'),
        FeatureType.BBOX
    ]
    

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 (Union[dict, Sequence]) – A collection of features in one of the supported formats

  • allowed_feature_types (Optional[Iterable[FeatureType]]) – 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, object]]

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 (Optional[EOPatch]) –

Return type

List[Tuple[FeatureType, Optional[str]]]

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 (Optional[EOPatch]) –

Return type

List[Union[Tuple[FeatureType, str, str], Tuple[FeatureType, None, None]]]

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

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

See FeatureParser for viable inputs.

Parameters
  • eopatch (Optional[EOPatch]) –

  • allowed_feature_types (Optional[Iterable[FeatureType]]) –

Return type

Tuple[FeatureType, Optional[str]]

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

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

See FeatureParser for viable inputs.

Parameters
  • eopatch (Optional[EOPatch]) –

  • allowed_feature_types (Optional[Iterable[FeatureType]]) –

Return type

Union[Tuple[FeatureType, str, str], Tuple[FeatureType, None, None]]

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

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

See FeatureParser for viable inputs.

Parameters
  • eopatch (Optional[EOPatch]) –

  • allowed_feature_types (Optional[Iterable[FeatureType]]) –

Return type

List[Tuple[FeatureType, Optional[str]]]

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

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

See FeatureParser for viable inputs.

Parameters
  • eopatch (Optional[EOPatch]) –

  • allowed_feature_types (Optional[Iterable[FeatureType]]) –

Return type

List[Union[Tuple[FeatureType, str, str], Tuple[FeatureType, None, None]]]