API reference

sitsfeats.feats

The single entry point. Dispatches on the input type: a NumPy array returns a Features, or an xarray cube returns an xarray.Dataset (see Working with data cubes).

Extract time-series metrics (features) from satellite image data.

A single entry point that dispatches on the type of data:

• numpy.ndarray - each row is a time series. Returns a Features with a stacked (n_series, n_metrics) array and the column names.

• xarray.DataArray / Dataset - a labelled data cube. Returns an xarray.Dataset with one variable per metric, preserving spatial coordinates and attributes (chunked/Dask cubes are processed lazily). This path requires the optional xarray dependency and accepts a dim keyword naming the time dimension (default "time").

Parameters:

Name	Type	Description	Default
data	ndarray | DataArray | Dataset	Time-series data - a 2-D array (rows are series) or an xarray cube.	required
metrics	list[str]	Metric names.	required
**kwargs	str	Forwarded to the input-specific handler (e.g. dim for an xarray cube). Passing keywords for a numpy.ndarray input is meaningless and raises an error.	{}

Returns:

Type	Description
Features | Dataset	Features | xarray.Dataset: A Features for an array input, or an
Features | Dataset	xarray.Dataset for an xarray cube.

Raises:

Type	Description
NotImplementedError	If a metric is not available.
TypeError	If data is not a numpy.ndarray or an xarray object.

sitsfeats.Features

Bases: NamedTuple

Result of a feature extraction over a plain array.

Attributes:

Name	Type	Description
data	ndarray	Stacked metrics with shape (n_series, n_metrics). Column j holds the metric named names[j].
names	list[str]	Metric names, in column order.

data instance-attribute

Stacked metrics with shape (n_series, n_metrics).

names instance-attribute

Metric names, in column order.

__array__(dtype=None)

Expose the stacked matrix to np.asarray.

Parameters:

Name	Type	Description	Default
dtype	dtype | None	The dtype of the returned array.	None

Returns:

Type	Description
ndarray	np.ndarray: The stacked matrix as a numpy array.

to_dict()

Return the metrics as a {name: column} mapping.

Returns:

Type	Description
dict[str, ndarray]	dict[str, np.ndarray]: A dictionary with metric names as keys and the corresponding columns as values.

sitsfeats.metrics

List the available metrics, with their family and a short description.

Parameters:

Name	Type	Description	Default
group	str | None	If given, restrict the result to this family (e.g. "basic" or "polar").	None

Returns:

Name	Type	Description
MetricTable	MetricTable	A table of MetricInfo records, sorted by name.

Example

from sitsfeats import metrics metrics() name group description abs_sum basic Sum of absolute values ... metrics(group="polar").names ['angle', 'area_q1', ...]

sitsfeats.registry.MetricTable

Bases: Sequence

An immutable, dependency-free table of MetricInfo records.

Behaves as a sequence of records (iterate, index, len, in) and renders as an aligned table in the terminal and as an HTML table in Jupyter.

Use names to get the bare metric names (e.g., to pass to sitsfeats.feats), or to_dict / to_pandas to export.

__slots__ = ('_records',) class-attribute instance-attribute

Tuple of MetricInfo records.

names property

Get the metric names, in table order.

Returns:

Type	Description
list[str]	list[str]: The metric names, in table order.

__getitem__(index)

Get a record by index.

Parameters:

Name	Type	Description	Default
index	int	Index of the record.	required

Returns:

Name	Type	Description
MetricInfo	MetricInfo	The MetricInfo record at the given index.

__init__(records)

Initialize the metric table.

Parameters:

Name	Type	Description	Default
records	Sequence[MetricInfo]	Sequence of MetricInfo records.	required

__len__()

Get the number of records in the table.

Returns:

Name	Type	Description
int	int	The number of records in the table.

__repr__()

Return a string representation of the metric table.

Returns:

Name	Type	Description
str	str	A string representation of the metric table.

to_dict()

Return the metric records as a list of dictionaries.

Returns:

Type	Description
list[dict[str, str]]	list[dict[str, str]]: The metric records as a list of dictionaries.

to_pandas()

Metric records as a pandas DataFrame.

Returns:

Type	Description
DataFrame	pandas.DataFrame: The metric records as a pandas DataFrame.

sitsfeats.registry.MetricInfo

Bases: NamedTuple

Metadata for a single metric.

description instance-attribute

One-line summary of what the metric computes.

group instance-attribute

Metric family, e.g. "basic" or "polar".

name instance-attribute

Metric name.

sitsfeats.registry.MetricsRegistry

Registry of available metrics, keyed by name.

exists(name, raise_error=False) classmethod

Check if a given metric exists.

Parameters:

Name	Type	Description	Default
name	str	Metric name.	required
raise_error	bool	Raise instead of returning False when the metric is unknown.	False

Returns:

Name	Type	Description
bool	bool	Whether the metric exists.

group(name) classmethod

Return the family of a registered metric.

Parameters:

Name	Type	Description	Default
name	str	Metric name.	required

Returns:

Name	Type	Description
str	str	The family of the given metric.

info(name) classmethod

Return the full MetricInfo record for a registered metric.

Parameters:

Name	Type	Description	Default
name	str	Metric name.	required

Returns:

Name	Type	Description
MetricInfo	MetricInfo	The MetricInfo record for the given metric.

names() classmethod

List the names of all registered metrics.

register(name, group, description) classmethod

Register a metric.

Parameters:

Name	Type	Description	Default
name	str	Metric name.	required
group	str	Metric family (e.g. "basic").	required
description	str	One-line summary.	required