2.4. ECTResult

ECTResult class provides a fast way to manipulate ECT matrices while also maintaining properties of being a numpy array.

class ect.results.ECTResult(matrix, directions, thresholds)[source]

A numpy ndarray subclass that carries Euler Characteristic Transform (ECT) metadata and plotting capabilities.

This class acts like a regular matrix but includes: - Visualization methods for ECT and ECC plots - Metadata about directions and thresholds used in the transform - Support for both dense and compressed (CSR) representations

Parameters:

matrix (np.ndarray) – ECT matrix data.
directions – Direction metadata (angles or vectors).
thresholds – Threshold values used for the transform.

Notes

Use plot() to visualize the ECT matrix.
Use dist() to compute distances between ECT results.
Supports loading/saving in compressed format via save_npz() and load_npz().

property has_csr

Check if the ECTResult instance has compressed sparse row (CSR) data attached.

Returns:: True if CSR fields (row_ptr, col_idx, data) are present, False otherwise.
Return type:: bool

classmethod from_csr(row_ptr, col_idx, data, directions, thresholds, dtype=<class 'numpy.int32'>)[source]

Create an ECTResult instance from compressed sparse row (CSR) data.

Parameters:

row_ptr (np.ndarray) – CSR row pointer array.
col_idx (np.ndarray) – CSR column indices array.
data (np.ndarray) – CSR data array (jump values).
directions – Direction metadata (angles or vectors).
thresholds – Threshold values used for the transform.
dtype – Data type for the dense matrix (default: np.int32).

Returns:

Instance with dense matrix and attached CSR fields.

Return type:

ECTResult

to_dense()[source]

Convert the ECTResult from CSR format to a dense matrix.

Returns:: Dense matrix representation of the ECTResult.
Return type:: np.ndarray

save_npz(path)[source]

Save the ECTResult in compressed .npz format, including CSR data and metadata.

Parameters:: path (str) – File path to save the .npz file.

Notes

If CSR data is not present, it is computed from the dense matrix.
Metadata (thresholds, dtype) is included for reproducibility.

classmethod load_npz(path, directions)[source]

Load an ECTResult from a compressed .npz file, restoring CSR data and metadata.

Parameters:

path (str) – File path to load the .npz file from.
directions – Direction metadata to attach to the result.

Returns:

Instance with dense matrix, CSR fields, and metadata.

Return type:

ECTResult

plot(ax=None)[source]

Plot the ECT matrix, handling both 2D and 3D direction cases.

Parameters:: ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, uses current axes.
Returns:: The axes object with the plot.
Return type:: matplotlib.axes.Axes

Notes

For 2D, directions are shown as angles; for 3D, as indices.
Uses color mesh and labels for visualization.

smooth()[source]

Calculate the Smooth Euler Characteristic Transform (SECT) from the ECT matrix.

Returns:: New instance containing the SECT matrix, directions, and thresholds.
Return type:: ECTResult

Notes

The SECT is computed by centering each direction’s values and taking the cumulative sum across thresholds.

dist(other, metric='cityblock', **kwargs)[source]

Compute distance to another ECTResult or list of ECTResults.

Parameters:

other – Another ECTResult object or list of ECTResult objects
metric – Distance metric to use. Can be: - String: any metric supported by scipy.spatial.distance (e.g., ‘euclidean’, ‘cityblock’, ‘chebyshev’, ‘cosine’, etc.) - Callable: a custom distance function that takes two 1D arrays and returns a scalar distance. The function should have signature: func(u, v) -> float
**kwargs – Additional keyword arguments passed to the metric function (e.g., p=3 for minkowski distance, w=weights for weighted metrics)

Returns:

Single distance if other is an ECTResult, array of distances if other is a list.

Return type:

float or np.ndarray

Raises:

ValueError – If the shapes of the ECTResults don’t match.

Examples

>>> # Built-in metrics
>>> dist1 = ect1.dist(ect2, metric='euclidean')
>>> dist2 = ect1.dist(ect2, metric='minkowski', p=3)

>>> # Custom distance function
>>> def my_distance(u, v):
...     return np.sum(np.abs(u - v) ** 0.5)
>>> dist3 = ect1.dist(ect2, metric=my_distance)

>>> # Batch distances with custom function
>>> dists = ect1.dist([ect2, ect3, ect4], metric=my_distance)