EllipticFourierAnalysis#

class ktch.harmonic.EllipticFourierAnalysis(n_harmonics: int = 20, n_dim: int = 2, registration: str | None = 'auto', scale: bool = True, scale_method: str | None = None, align_parameter: bool = True, reflect: bool = False, return_transform: bool = False, n_jobs: int | None = None, verbose: int = 0, norm: bool = True, norm_method: str | None = None, return_orientation_scale: bool = False)[source]#

Elliptic Fourier Analysis (EFA)

Parameters:

n_harmonics: int, default=20

Number of harmonics

n_dim: int, default=2

Dimension of the codomain (number of components on the curve). Any positive integer is supported for the raw expansion (registration=None). Arc-length parameterization is computed automatically only for n_dim in (2, 3) (spatial shape coordinates). For n_dim=1 or n_dim>3 the codomain is treated as non-shape data, so the parameter t is required and must be supplied explicitly (e.g. derived from the corresponding shape); it is not inferred from the codomain values.

registration{“auto”, None, “first_order”, “moment”}, default=”auto”

Shape-registration method. "auto" (default) registers 2D/3D shape data with "first_order" and leaves other dimensions unregistered (None). None returns raw coefficients. "first_order" uses the 1st-harmonic ellipse; "moment" uses the inertia tensor of all coefficients. Registration applies to 2D/3D shape data only. registration must be None for``n_dim`` not in (2, 3).

scalebool, default=True

Whether registration removes size. False keeps size. Only used when registration != None. (scale=False is currently implemented for "moment" only.)

scale_methodstr or None, default=None

Size measure when scale=True; one of "semi_major_axis", "ellipse_area", "centroid_size", or None. None resolves to the method’s default ("first_order": 2D "semi_major_axis", 3D "ellipse_area"; "moment": "centroid_size"). "semi_major_axis" and "ellipse_area" require registration="first_order"; "centroid_size" requires registration="moment".

align_parameterbool, default=True

Whether to align the parameter domain (phase) in "first_order". Only True is implemented (it is always applied); False raises NotImplementedError.

reflectbool, default=False

Whether to also remove reflection (chirality). Honored by "moment". For "first_order" only reflect=False (orientation preserved) is implemented; reflect=True raises NotImplementedError.

return_transformbool, default=False

Append the registration parameters as extra output columns. Currently only for "first_order" with n_dim in (2, 3); other methods raise NotImplementedError.

2D: Appends [psi, scale] to the end of the coefficient vector.
3D: Appends [alpha, beta, gamma, phi, scale] to the end.

n_jobs: int, default=None

The number of jobs to run in parallel. None means 1 unless in a joblib.parallel_backend context. -1 means using all processors.

verbose: int, default=0

The verbosity level.

normbool, default=True

Deprecated alias. True maps to registration="first_order", False to registration=None. Use registration instead.

norm_method{None, “area”, “semi_major_axis”}, default=None

Deprecated alias for scale_method ("area" -> "ellipse_area"). When None the dimension-appropriate convention is used: "semi_major_axis" for 2D and "area" for 3D.

"area": Scale by sqrt(pi * a1 * b1) where a1 and b1 are the semi-major and semi-minor axis lengths of the 1st harmonic ellipse (Godefroy et al. 2012).
"semi_major_axis": Scale by the semi-major axis length a1 of the 1st harmonic ellipse (Kuhl & Giardina 1982).

return_orientation_scalebool, default=False

Deprecated alias for return_transform producing identical output (requires registration != None).

Notes

EFA is widely applied for outline shape analysis in two-dimensional space [Kuhl_Giardina_1982].

\[\begin{split}\begin{align} x(l) &= \frac{a_0}{2} + \sum_{i=1}^{n} \left[ a_i \cos\left(\frac{2\pi i t}{T}\right) + b_i \sin\left(\frac{2\pi i t}{T}\right) \right]\\ y(l) &= \frac{c_0}{2} + \sum_{i=1}^{n} \left[ c_i \cos\left(\frac{2\pi i t}{T}\right) + d_i \sin\left(\frac{2\pi i t}{T}\right) \right]\\ \end{align}\end{split}\]

EFA is also applied for a closed curve in the three-dimensional space (e.g., [Lestrel_1997], [Lestrel_et_al_1997], and [Godefroy_et_al_2012]).

For 3D data (n_dim=3), "first_order" registration follows Godefroy et al. (2012) §3.1: rescaling by the 1st harmonic ellipse area, reorientation using ZXZ Euler angles, phase shift, and direction correction.

When return_transform=True with registered data, extra values are appended to the output:

2D: [psi, scale] where psi is the orientation angle and scale is the normalization factor.
3D: [alpha, beta, gamma, phi, scale] where (alpha, beta, gamma) are ZXZ Euler angles (in radians) of the 1st harmonic ellipse orientation, phi is the phase angle, and scale is the normalization factor.

The scale value depends on scale_method: sqrt(pi * a1 * b1) for "ellipse_area", or a1 for "semi_major_axis".

The legacy parameters norm / norm_method / return_orientation_scale remain as deprecated aliases of registration / scale_method / return_transform.

References

[Kuhl_Giardina_1982]

Kuhl, F.P., Giardina, C.R. (1982) Elliptic Fourier features of a closed contour. Comput. Graph. Image Process. 18: 236–258. https://doi.org/10.1016/0146-664X(82)90034-X

[Lestrel_1997]

Lestrel, P.E., 1997. Introduction and overview of Fourier descriptors, in: Fourier Descriptors and Their Applications in Biology. Cambridge University Press, pp. 22–44. https://doi.org/10.1017/cbo9780511529870.003

[Lestrel_et_al_1997]

Lestrel, P.E., Read, D.W., Wolfe, C., 1997. Size and shape of the rabbit orbit: 3-D Fourier descriptors, in: Lestrel, P.E. (Ed.), Fourier Descriptors and Their Applications in Biology. Cambridge University Press, pp. 359–378. https://doi.org/10.1017/cbo9780511529870.017

[Godefroy_et_al_2012]

Godefroy, J.E., Bornert, F., Gros, C.I., Constantinesco, A., 2012. Elliptical Fourier descriptors for contours in three dimensions: A new tool for morphometrical analysis in biology. C. R. Biol. 335, 205–213. https://doi.org/10.1016/j.crvi.2011.12.004

fit(X, y=None)[source]#

Fit the model (no-op for stateless transformer).

Parameters:

Xignored
yignored

Returns:

self

fit_transform(X, y=None, t=None)[source]#

Fit and transform in a single step.

Overridden to support metadata routing of t.

Parameters:

Xlist of array-like of shape (n_coords_i, n_dim): Coordinate values of n_samples.
yignored
tlist of array-like, optional: Per-sample parameterization. Passed to transform.

Returns:

X_transformedndarray of shape (n_samples, n_features_out)

get_feature_names_out(input_features: None | npt.ArrayLike = None) → np.ndarray[source]#

Get output feature names.

Parameters:

input_featuresignored

Returns:

feature_names_outndarray of str objects: Transformed feature names.

get_metadata_routing()#

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest: A MetadataRequest encapsulating routing information.

get_params(deep=True)#

Get parameters for this estimator.

Parameters:

deepbool, default=True: If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict: Parameter names mapped to their values.

inverse_transform(X_transformed, t_num=100, as_frame=False)[source]#

Inverse analysis of elliptic Fourier analysis.

Parameters:

X_transformedarray-like of shape (n_samples, n_features)

Elliptic Fourier coefficients. Accepted lengths per sample:

2D: 4*(n_harmonics+1) or 4*(n_harmonics+1)+2 (psi, scale).

3D: 6*(n_harmonics+1) or 6*(n_harmonics+1)+5 (alpha, beta, gamma, phi, scale).

Orientation/scale columns, if present, are ignored for reconstruction.

t_numint, default = 100

Number of coordinate values.

as_framebool, default = False

If True, return pd.DataFrame.

Returns:

X_coordsarray-like of shape (n_samples, t_num, n_dim) or pd.DataFrame: Coordinate values reconstructed from the elliptic Fourier coefficients.

Configure whether metadata should be requested to be passed to the inverse_transform method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to inverse_transform if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to inverse_transform.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

X_transformedstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for X_transformed parameter in inverse_transform.
as_framestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for as_frame parameter in inverse_transform.
t_numstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for t_num parameter in inverse_transform.

Returns:

selfobject: The updated object.

set_output(*, transform=None)#

Set output container.

Refer to the user guide for more details and Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

“default”: Default output format of a transformer
“pandas”: DataFrame output
“polars”: Polars output
None: Transform configuration is unchanged

Added in version 1.4: “polars” option was added.

Returns:

selfestimator instance: Estimator instance.

set_params(**params)#

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict: Estimator parameters.

Returns:

selfestimator instance: Estimator instance.

set_transform_request(*, t: bool | None | str = '$UNCHANGED$') → EllipticFourierAnalysis#

Configure whether metadata should be requested to be passed to the transform method.

The options for each parameter are:

True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to transform.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:

tstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for t parameter in transform.

Returns:

selfobject: The updated object.

transform(X: list[npt.ArrayLike] | npt.ArrayLike, t: npt.ArrayLike = None) → npt.ArrayLike[source]#

Elliptic Fourier Analysis.

Parameters:

X{list of array-like, array-like} of shape (n_samples, n_coords, n_dim): Coordinate values of n_samples. The i-th array-like of shape (n_coords_i, n_dim) represents coordinate values of the i-th sample.
tlist of array-like of shape (n_coords_i,), optional: Parameters indicating the position on the outline of n_samples. The i-th element corresponds to each coordinate value in the i-th element of X. If None, arc-length parameterization is computed automatically.

Returns:

X_transformedndarray of shape (n_samples, n_features_out)

Elliptic Fourier coefficients.

For a general codomain dimension n_dim=D with norm=False the layout is, per axis, [cos_0..cos_n, sin_0..sin_n] concatenated over the D axes, giving length 2 * D * (n_harmonics + 1). The 2D/3D cases below are special cases of this layout (with letter names a, b, c, d, ...).

2D (return_orientation_scale=False): [a_0..a_n, b_0..b_n, c_0..c_n, d_0..d_n] length = 4 * (n_harmonics + 1).
2D (return_orientation_scale=True): Same as above with [psi, scale] appended (length +2).
3D (return_orientation_scale=False): [a_0..a_n, b_0..b_n, c_0..c_n, d_0..d_n, e_0..e_n, f_0..f_n] length = 6 * (n_harmonics + 1).
3D (return_orientation_scale=True): Same as above with [alpha, beta, gamma, phi, scale] appended (length +5).