API

pyEulerCurves module

class pyEulerCurves.ECC_from_bitmap(*args: Any, **kwargs: Any)

Bases: TransformerMixin, BaseEstimator

Transformer that computes the Euler Characteristic Curve (ECC) from a bitmap image using cubical complexes.

This transformer is compatible with scikit-learn pipelines and interprets the input as a binary or grayscale bitmap, computing the ECC based on connected components formed by cubical cells (voxels or pixels).

Parameters:

  • periodic_boundary (bool or list of bool, default=False) – Specifies whether to use periodic boundary conditions in each spatial dimension. If a list is provided, it must match the number of dimensions of the bitmap.

  • workers (int, default=1) – Number of parallel workers to use for computing local contributions.

n_features_

Number of features (flattened bitmap size) seen during fit.

Type:

int

contributions_list

List of local Euler characteristic contributions computed from the bitmap.

Type:

list of np.ndarray

number_of_simplices

Estimated total number of cells (0D to top-dimensional) in the cubical complex.

Type:

int

Initialize the ECC_from_bitmap transformer.

Parameters:

  • periodic_boundary (bool or list of bool, default=False) – Whether to apply periodic boundary conditions in each dimension.

  • workers (int, default=1) – Number of parallel workers.

fit(X, y=None)

Fit the transformer to the input bitmap.

Parameters:

  • X ({array-like, sparse matrix}, shape (n_samples, n_features)) – The training input samples, typically flattened bitmap arrays.

  • y (None) – Ignored. This parameter exists for compatibility with scikit-learn pipelines.

Returns:

self – Fitted transformer.

Return type:

object

transform(X)

Compute the Euler Characteristic Curve (ECC) from bitmap images.

Parameters:

X ({array-like, sparse matrix}, shape (n_samples, n_features)) – Flattened input bitmaps. Each row is treated as a bitmap image.

Returns:

ecc – A list of [filtration_value, Euler_characteristic] pairs representing the ECC computed from the bitmap.

Return type:

list of [float, int]

class pyEulerCurves.ECC_from_pointcloud(*args: Any, **kwargs: Any)

Bases: TransformerMixin, BaseEstimator

Transformer that computes Euler Characteristic Curves (ECCs) from a point cloud using Vietoris-Rips or Alpha filtrations.

This transformer is compatible with scikit-learn pipelines and computes local contributions to the Euler characteristic, assembling them into a global ECC.

Parameters:

  • epsilon (float, default=0) – Threshold parameter for Vietoris-Rips filtration. Controls the scale at which simplices are created.

  • max_dimension (int, default=-1) – Maximum homology dimension to consider. If set to -1, all dimensions are used.

  • workers (int, default=1) – Number of worker processes to use in parallel computation.

  • complex_type ({'VR', 'alpha'}, default='VR') – Type of simplicial complex used for ECC computation. Use β€˜VR’ for Vietoris-Rips and β€˜alpha’ for Alpha complex.

  • dbg (bool, default=False) – If True, enables debug output for internal steps.

  • measure_times (bool, default=False) – If True, records timing information for different steps of the computation.

n_features_

Number of features seen during fit.

Type:

int

contributions_list

Local Euler characteristic contributions for each sample.

Type:

list of np.ndarray

num_simplices_list

Number of simplices used in each ECC computation.

Type:

list of int

largest_dimension_list

Largest homology dimension computed for each point cloud.

Type:

list of int

times

If measure_times is True, contains the durations of computations.

Type:

list of float

num_simplices

Total number of simplices over all samples.

Type:

int

Initialize the ECC_from_pointcloud transformer.

Parameters:

  • epsilon (float, default=0) – Vietoris-Rips filtration scale parameter.

  • max_dimension (int, default=-1) – Maximum homology dimension to consider.

  • workers (int, default=1) – Number of parallel workers.

  • complex_type ({'VR', 'alpha'}, default='VR') – Type of simplicial complex used to compute ECCs. Choose β€˜VR’ for Vietoris-Rips or β€˜alpha’ for Alpha complex.

  • dbg (bool, default=False) – Enable debug output.

  • measure_times (bool, default=False) – Enable timing measurement.

fit(X, y=None)

Fit the transformer on input data X.

Parameters:

  • X ({array-like, sparse matrix}, shape (n_samples, n_features)) – The training input samples.

  • y (None) – Ignored. This parameter exists for compatibility with scikit-learn pipelines.

Returns:

self – Fitted transformer.

Return type:

object

transform(X)

Compute the Euler Characteristic Curve (ECC) for the given point cloud(s).

Parameters:

X ({array-like, sparse matrix}, shape (n_samples, n_features)) – The input point cloud data. Each row corresponds to a single point cloud.

Returns:

ecc – A list of [filtration_value, Euler_characteristic] pairs representing the Euler Characteristic Curve computed from the entire dataset.

Return type:

list of [float, int]

pyEulerCurves.difference_ECC(ecc1, ecc2, max_f)

Compute the L1 distance between two Euler Characteristic Curves (ECCs) up to a maximum filtration value.

Parameters:

  • ecc1 (list of [float, int]) – First ECC as a list of [filtration, EC].

  • ecc2 (list of [float, int]) – Second ECC as a list of [filtration, EC].

  • max_f (float) – The maximum filtration value to consider.

Returns:

difference – The total L1 distance between the two ECCs over [0, max_f].

Return type:

float

pyEulerCurves.plot_euler_curve(e_list, this_ax=None, with_lines=False, **kwargs)

Plot an Euler Characteristic Curve (ECC).

Parameters:

  • e_list (list of [float, int]) – The ECC to plot, as a list of [filtration, Euler characteristic] pairs.

  • this_ax (matplotlib.axes.Axes, optional) – Axes object to draw the plot onto. If None, uses current Axes.

  • with_lines (bool, default=False) – If True, draws step-style horizontal and vertical lines between points.

  • **kwargs (dict) – Additional keyword arguments passed to matplotlib scatter.

Returns:

this_ax – The matplotlib axes containing the plot.

Return type:

matplotlib.axes.Axes