te_schemas.results

Result schemas for Trends.Earth analysis outputs.

This module defines the data structures for representing analysis results, including raster outputs, JSON data, and file references. These schemas are used for serialization/deserialization when communicating with the Trends.Earth API and for storing job results.

Classes:: Band: Metadata for a single raster band. Raster: A single-file raster layer. TiledRaster: A multi-file tiled raster layer. RasterResults: Results containing raster layers (primary result type). JsonResults: Results containing only JSON data. FileResults: Results referencing file outputs. CloudResults: Results from cloud processing. URI: Universal resource identifier for file locations. Etag: File hash for integrity verification.
Enums:: DataType: Pixel data types (Int16, Float32, etc.). RasterType: Single file vs tiled raster. RasterFileType: GeoTiff or COG format. ResultType: Type discriminator for result classes.

class te_schemas.results.Band

Metadata for a single band in a raster file.

Attributes:: name: Human-readable band name (e.g., “SDG 15.3.1 Indicator - Baseline”). metadata: Dictionary of additional band metadata. no_data_value: Value representing no data (default: -32768). activated: Whether the band should be processed (default: True). add_to_map: Whether the band should be displayed in the map (default: True).

__init__(name, metadata, no_data_value=-32768, activated=True, add_to_map=True)

Parameters:

name (str)
metadata (dict)
no_data_value (int | float)
activated (bool | None)
add_to_map (bool | None)

Return type:

None

activated: bool | None = True

add_to_map: bool | None = True

metadata: dict

name: str

no_data_value: int | float = -32768

class te_schemas.results.CloudResults

CloudResults(name: ‘str’, bands: ‘typing.List[Band]’, urls: ‘typing.List[Url]’, data_path: ‘typing.Optional[typing.Union[VSIPath, LocalPath]]’ = None, other_paths: ‘typing.Optional[typing.List[typing.Union[VSIPath, LocalPath]]]’ = <factory>, data: ‘typing.Optional[dict]’ = <factory>, type: ‘ResultType’ = <ResultType.CLOUD_RESULTS: ‘CloudResults’>)

class Meta

unknown = 'exclude'

__init__(name, bands, urls, data_path=None, other_paths=<factory>, data=<factory>, type=ResultType.CLOUD_RESULTS)

Parameters:

name (str)
bands (List[Band])
urls (List[Annotated[str, Url]])
data_path (Annotated[PurePosixPath, <fields.VSIPathField(dump_default=<marshmallow.missing>, attribute=None, validate=<PathValidator(regex=re.compile('/vsi(s3)|(gs)'), error='String does not match expected pattern.')>, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.'})>] | Annotated[Path, LocalPathField] | None)
other_paths (List[Annotated[PurePosixPath, <fields.VSIPathField(dump_default=<marshmallow.missing>, attribute=None, validate=<PathValidator(regex=re.compile('/vsi(s3)|(gs)'), error='String does not match expected pattern.')>, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.'})>] | Annotated[Path, LocalPathField]] | None)
data (dict | None)
type (ResultType)

Return type:

None

bands: List[Band]

data: dict | None

data_path: LocalPathField] | None = None

name: str

other_paths: LocalPathField]] | None

type: ResultType = 'CloudResults'

urls: List[Annotated[str, Url]]

class te_schemas.results.DataType

BYTE = 'Byte'

FLOAT32 = 'Float32'

FLOAT64 = 'Float64'

INT16 = 'Int16'

INT32 = 'Int32'

UINT16 = 'UInt16'

UINT32 = 'UInt32'

class te_schemas.results.EmptyResults

EmptyResults(name: ‘typing.Optional[str]’ = None, data_path: ‘typing.Optional[typing.Union[VSIPath, LocalPath]]’ = None, type: ‘ResultType’ = <ResultType.EMPTY_RESULTS: ‘EmptyResults’>)

class Meta

unknown = 'exclude'

__init__(name=None, data_path=None, type=ResultType.EMPTY_RESULTS)

Parameters:

name (str | None)
data_path (Annotated[PurePosixPath, <fields.VSIPathField(dump_default=<marshmallow.missing>, attribute=None, validate=<PathValidator(regex=re.compile('/vsi(s3)|(gs)'), error='String does not match expected pattern.')>, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.'})>] | Annotated[Path, LocalPathField] | None)
type (ResultType)

Return type:

None

data_path: LocalPathField] | None = None

name: str | None = None

type: ResultType = 'EmptyResults'

class te_schemas.results.Etag

Etag(hash: ‘str’, type: ‘EtagType’)

__init__(hash, type)

Parameters:

hash (str)
type (EtagType)

Return type:

None

property decoded_hash

hash: str

type: EtagType

class te_schemas.results.EtagType

AWS_MD5 = 'AWS MD5 Etag'

AWS_MULTIPART = 'AWS Multipart Etag'

GCS_CRC32C = 'GCS CRC32C Etag'

GCS_MD5 = 'GCS MD5 Etag'

class te_schemas.results.FileResults

FileResults(name: ‘str’, uri: ‘URI’ = None, other_uris: ‘typing.List[URI]’ = <factory>, data: ‘typing.Optional[dict]’ = <factory>, type: ‘ResultType’ = <ResultType.FILE_RESULTS: ‘FileResults’>)

class Meta

unknown = 'exclude'

__init__(name, uri=None, other_uris=<factory>, data=<factory>, type=ResultType.FILE_RESULTS)

Parameters:

name (str)
uri (URI)
other_uris (List[URI])
data (dict | None)
type (ResultType)

Return type:

None

get_all_uris()

Return a list of all URI objects associated with this file result.

Mirrors the interface provided by RasterResults so that downstream code can treat different result types uniformly. The primary archive or file (self.uri) is returned first (if set), followed by any auxiliary URIs in other_uris.

update_uris(job_path)

data: dict | None

name: str

other_uris: List[URI]

type: ResultType = 'FileResults'

uri: URI = None

class te_schemas.results.JsonResults

Results containing only JSON data without raster outputs.

Used for analysis jobs that produce statistics or reports without generating new raster files (e.g., sdg-15-3-1-stats script).

Attributes:: name: Human-readable result name. data: Dictionary containing all result data (statistics, reports, etc.). type: Must be ResultType.JSON_RESULTS.

class Meta

unknown = 'exclude'

__init__(name, data, type=ResultType.JSON_RESULTS)

Parameters:

name (str)
data (dict)
type (ResultType)

Return type:

None

data: dict

name: str

type: ResultType = 'JsonResults'

class te_schemas.results.LocalPathField

class te_schemas.results.PathValidator

class te_schemas.results.Raster

A single-file raster layer.

Represents a GeoTIFF or COG file containing one or more bands.

Attributes:: uri: URI pointing to the raster file (S3, GCS, or local path). bands: List of Band metadata for each band in the file. datatype: Pixel data type (e.g., Int16, Float32). filetype: File format (GeoTiff or COG). extent: Optional bounding box as (minx, miny, maxx, maxy). type: Must be RasterType.ONE_FILE_RASTER.

__init__(uri, bands, datatype, filetype, extent=None, type=RasterType.ONE_FILE_RASTER)

Parameters:

uri (URI)
bands (List[Band])
datatype (DataType)
filetype (RasterFileType)
extent (Tuple[float, float, float, float] | None)
type (RasterType)

Return type:

None

bands: List[Band]

datatype: DataType

extent: Tuple[float, float, float, float] | None = None

filetype: RasterFileType

type: RasterType = 'One file raster'

uri: URI

class te_schemas.results.RasterFileType

COG = 'COG'

GEOTIFF = 'GeoTiff'

class te_schemas.results.RasterResults

Results containing one or more raster layers.

The primary result type for land degradation analysis jobs. Contains raster data organized by data type (e.g., Int16, Float32) along with optional metadata and summary statistics.

Attributes:

name: Human-readable result name (e.g., “SDG 15.3.1 Indicator”). rasters: Dict mapping data type keys to Raster or TiledRaster objects. uri: Optional URI to a combined VRT or TIF linking all rasters. data: Optional dict containing additional result data (e.g., summaries). type: Must be ResultType.RASTER_RESULTS.

Example:

Typical structure after serialization:

{
    "name": "SDG 15.3.1 Indicator",
    "type": "RasterResults",
    "rasters": {
        "Int16": {
            "uri": {...},
            "bands": [...],
            "datatype": "Int16",
            "filetype": "GeoTiff",
            "type": "One file raster"
        }
    },
    "data": {"report": {"summary": {...}}}
}

__init__(name, rasters, uri=None, data=<factory>, type=ResultType.RASTER_RESULTS)

Parameters:

name (str)
rasters (Dict[str, Raster | TiledRaster])
uri (URI | None)
data (dict | None)
type (ResultType)

Return type:

None

combine(other): Merge with another RasterResults with matching bands

get_all_uris()

get_band_uris()

get_bands()

get_extents()

get_main_uris()

has_tiled_raster()

update_uris(job_path)

data: dict | None

name: str

rasters: Dict[str, Raster | TiledRaster]

type: ResultType = 'RasterResults'

uri: URI | None = None

class te_schemas.results.RasterType

ONE_FILE_RASTER = 'One file raster'

TILED_RASTER = 'Tiled raster'

class te_schemas.results.ResultType

ANALYSIS_RESULTS = 'AnalysisResults'

CLOUD_RESULTS = 'CloudResults'

EMPTY_RESULTS = 'EmptyResults'

FILE_RESULTS = 'FileResults'

JSON_RESULTS = 'JsonResults'

RASTER_RESULTS = 'RasterResults'

TIME_SERIES_TABLE = 'TimeSeriesTable'

VECTOR_RESULTS = 'VectorResults'

class te_schemas.results.TiledRaster

A tiled raster composed of multiple files.

Used for large rasters that are split across multiple GeoTIFF tiles, typically with a VRT file linking them together.

Attributes:: tile_uris: List of URIs pointing to individual tile files. bands: List of Band metadata for the raster. datatype: Pixel data type (e.g., Int16, Float32). filetype: File format (GeoTiff or COG). uri: Optional URI to a VRT file linking all tiles. extents: Optional list of (minx, miny, maxx, maxy) bounding boxes. type: Must be RasterType.TILED_RASTER.

__init__(tile_uris, bands, datatype, filetype, uri=None, extents=<factory>, type=RasterType.TILED_RASTER)

Parameters:

tile_uris (List[URI])
bands (List[Band])
datatype (DataType)
filetype (RasterFileType)
uri (URI | None)
extents (List[Tuple[float, float, float, float]] | None)
type (RasterType)

Return type:

None

bands: List[Band]

datatype: DataType

extents: List[Tuple[float, float, float, float]] | None

filetype: RasterFileType

tile_uris: List[URI]

type: RasterType = 'Tiled raster'

uri: URI | None = None

class te_schemas.results.TimeSeriesTableResult

TimeSeriesTableResult(name: ‘str’, table: ‘typing.List[dict]’, type: ‘ResultType’ = <ResultType.TIME_SERIES_TABLE: ‘TimeSeriesTable’>)

class Meta

unknown = 'exclude'

__init__(name, table, type=ResultType.TIME_SERIES_TABLE)

Parameters:

name (str)
table (List[dict])
type (ResultType)

Return type:

None

name: str

table: List[dict]

type: ResultType = 'TimeSeriesTable'

class te_schemas.results.URI

URI(uri: ‘typing.Union[Url, VSIPath, LocalPath, None]’, etag: ‘typing.Optional[Etag]’ = None)

class Meta

unknown = 'exclude'

__init__(uri, etag=None)

Parameters:

uri (Annotated[str, Url] | Annotated[PurePosixPath, <fields.VSIPathField(dump_default=<marshmallow.missing>, attribute=None, validate=<PathValidator(regex=re.compile('/vsi(s3)|(gs)'), error='String does not match expected pattern.')>, required=False, load_only=False, dump_only=False, load_default=<marshmallow.missing>, allow_none=False, error_messages={'required': 'Missing data for required field.', 'null': 'Field may not be null.', 'validator_failed': 'Invalid value.'})>] | Annotated[Path, LocalPathField] | None)
etag (Etag | None)

Return type:

None

etag: Etag | None = None

uri: LocalPathField] | None

class te_schemas.results.VSIPathField

class te_schemas.results.Vector

Base class for vector data in VectorResults.

Contains the URI and type discriminator for different vector types. Subclasses can add additional metadata specific to their type.

__init__(uri=None, type=VectorType.GENERIC)

Parameters:

uri (URI | None)
type (VectorType)

Return type:

None

type: VectorType = 'Generic'

uri: URI | None = None

class te_schemas.results.VectorFalsePositive

Vector data for false positive/negative (error recode) results.

Inherits from Vector with type defaulting to ERROR_RECODE.

__init__(uri=None, type=VectorType.ERROR_RECODE)

Parameters:

uri (URI | None)
type (VectorType)

Return type:

None

type: VectorType = 'False positive/negative'

class te_schemas.results.VectorResults

Vector results class for any vector/geojson output.

The vector field contains the vector data and its type discriminator. Use vector.type to determine the category of vector (ERROR_RECODE, GENERIC, etc.).

class Meta

unknown = 'exclude'

__init__(name, vector, extent=None, type=ResultType.VECTOR_RESULTS)

Parameters:

name (str)
vector (Vector)
extent (Tuple[float, float, float, float] | None)
type (ResultType)

Return type:

None

update_uris(job_path)

extent: Tuple[float, float, float, float] | None = None

name: str

type: ResultType = 'VectorResults'

property uri: URI | None: Convenience property to access vector.uri directly.

vector: Vector

class te_schemas.results.VectorType

ERROR_RECODE = 'False positive/negative'

GENERIC = 'Generic'