Polar metrics¶

Module for computing polar metrics, that are derived from a time wheel legend, projecting the values of a timeseries to angles in the interval [0, 2pi].

stmetrics.polar.angle(timeseries, nodata=-9999)¶

Angle - The main angle of the closed shape created by the polar visualization. If two angle are the same, the first one is presented.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return angle:	The main angle of time series.

stmetrics.polar.area_q1(timeseries, nodata=-9999)¶

Area of the closed shape over the first quadrant.

Parameters:	timeseries (numpy.ndarra) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area_q1:	Area of polygon that covers quadrant 1.

stmetrics.polar.area_q2(timeseries, nodata=-9999)¶

Area_Q2 - Area of the closed shape over the second quadrant.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area_q2:	Area of polygon that covers quadrant 2.

stmetrics.polar.area_q3(timeseries, nodata=-9999)¶

Area of the closed shape over the thrid quadrant.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area_q3:	Area of polygon that covers quadrant 3.

stmetrics.polar.area_q4(timeseries, nodata=-9999)¶

Area of the closed shape over the fourth quadrant.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area_q4:	Area of polygon that covers quadrant 4.

stmetrics.polar.area_season(timeseries, nodata=-9999)¶

Partial area of the shape, proportional to some quadrant of the polar representation.

This metric returns the area of the polygon on each quadrant.

area2—-area1 | | area3—-area4

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area:	The area of the time series that intersected each quadrant that represents a season.

stmetrics.polar.area_ts(timeseries, nodata=-9999)¶

Area - Area of the closed shape.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Return area_ts:	Area of polygon.

stmetrics.polar.csi(timeseries, nodata=-9999)¶

Cell Shape Index - This is a dimensionless quantitative measure of morphology, that characterize the standard deviation of an object from a circle.

Return shape_index:
Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
	Quantitative measure of morphology.

Note

Rational of this metric:

After polar transformation time series usually have a round shape, which can be releate do cell in some cases. That’s why cell shape index is available here.

stmetrics.polar.ecc_metric(timeseries, nodata=-9999)¶

Return values close to 0 if the shape is a circle and 1 if the shape is similar to a line.

Return eccentricity:
Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
	Eccentricity of time series after polar transformation.

stmetrics.polar.get_seasons(x, y)¶

This function polygons that represents the four season of a year. They are used to compute the metric area_season.

Returns tuple of polygons:
Parameters:	x (numpy.array) – x-coordinate in polar space. y (numpy.array) – y-coordinate in polar space.
	Quadrant polygons

stmetrics.polar.gyration_radius(timeseries, nodata=-9999)¶

Gyration_radius - Equals the average distance between each point inside the shape and the shape’s centroid.

Return gyration_radius:
Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
	Average distance between each point inside the shape and the shape’s centroid.

stmetrics.polar.polar_balance(timeseries, nodata=-9999)¶

Polar_balance - The standard deviation of the areas per season, considering the 4 seasons.

Return polar_balance:
Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
	Standard deviation of the areas per season.

stmetrics.polar.polar_plot(timeseries, nodata=-9999)¶

This function create a plot of time series in polar space.

Parameters:	timeseries (numpy.ndarray) – Time series. nodata (int) – nodata of the time series. Default is -9999.
Returns plot:	Plot of time series in polar space.

stmetrics.polar.symmetric_distance(time_series_1, time_series_2, nodata=-9999)¶

This function computes the difference between two time series in the polar space.

Parameters:	timeseries1 – Time series. timeseries2 – Time series. nodata (int) – nodata of the time series. Default is -9999.
Returns dist:	Distance between two time series.

stmetrics.polar.ts_polar(timeseries, funcs=['all'], nodata=-9999, show=False)¶

This function compute 9 polar metrics:

Area - Area of the closed shape.
Angle - The main angle of the closed shape created after transformation.
Area_q1 - Partial area of the shape, proportional to quadrant 1 of the polar representation.
Area_q2 - Partial area of the shape, proportional to quadrant 2 of the polar representation.
Area_q3 - Partial area of the shape, proportional to quadrant 3 of the polar representation.
Area_q4 - Partial area of the shape, proportional to quadrant 4 of the polar representation.
Polar_balance - The standard deviation of the areas per season, considering the 4 seasons.
Eccenticity - Return values close to 0 if the shape is a circle and 1 if the shape is similar to a line.
Gyration_radius - Equals the average distance between each point inside the shape and the shape’s centroid.
CSI - This is a dimensionless quantitative measure of morphology, that characterize the standard deviation of an object from a circle.

To visualize the time series on polar space use: ts_polar(timeseries, show=True)

Returns out_metrics:
Parameters:	timeseries (numpy.ndarray) – Time series. nodata (boolean) – nodata of the time series. Default is -9999. show – This inform that the polar plot must be presented.
	Dictionary with polar metrics values.

Tip

Check the original publication of the metrics: Körting, Thales & Câmara, Gilberto & Fonseca, Leila. (2013). Land Cover Detection Using Temporal Features Based On Polar Representation.