SphericalHarmonicAnalysis#

class ktch.harmonic.SphericalHarmonicAnalysis(n_harmonics=10, n_jobs=None, verbose=0)[source]#

Spherical Harmonic (SPHARM) Analysis

Parameters:
n_harmonics: int, default=10

Number of harmonics to use ($l_mathrm{max}$).

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.

Notes

[Ritche_Kemp_1999], [Shen_etal_2009]

\[\begin{align} \mathbf{p}(\theta, \phi) = \sum_{l=0}^{L} \sum_{m=-l}^l \left( c_l^m Y_l^m(\theta, \phi) \right) \end{align}\]

, where \(Y_l^m(\theta, \phi)\) are spherical harmonics:

\[\begin{align} Y_l^m(\theta, \phi) = \sqrt{\frac{2l+1}{4\pi}\frac{(l-m)!}{(l+m)!}} P_l^m(\cos(\theta)) e^{im\phi} \end{align}\]

, where \(P_n^m(x)\) are associated Legendre polynomials:

\[\begin{align} P_n^m(x) = (-1)^m (1-x^2)^{\frac{m}{2}} \frac{d^m}{dx^m} P_n(x) \end{align}\]

, where \(P_n(x)\) are Legendre polynomials, which are solutions of Legendre’s differential equation;

\[(1-x^2)\frac{d^2 y}{dx^2} -2x \frac{dy}{dx} + n(n+1)y = 0.\]

References

[Ritche_Kemp_1999]

Ritchie, D.W., Kemp, G.J.L. (1999) Fast computation, rotation, and comparison of low resolution spherical harmonic molecular surfaces. J. Comput. Chem. 20: 383–395.

[Shen_etal_2009]

Shen, L., Farid, H., McPeek, M.A. (2009) Modeling three-dimensional morphological structures using spherical harmonics. Evolution (N. Y). 63: 1003–1016.

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

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

Parameters:
Xignored
yignored
Returns:
self
fit_transform(X, y=None, theta_phi=None)[source]#

Fit and transform in a single step.

Overridden to support metadata routing of theta_phi.

Parameters:
Xlist of array-like of shape (n_coords_i, 3)

Coordinate values of n_samples.

yignored
theta_philist of array-like of shape (n_coords_i, 2)

Surface parameterization of n_samples.

Returns:
X_transformedndarray of shape (n_samples, n_coefficients)
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, theta_range=None, phi_range=None, l_max=None)[source]#

Reconstruct surfaces from SPHARM coefficients.

Parameters:
X_transformedarray-like of shape (n_samples, n_coefficients)

SPHARM coefficients.

theta_rangearray-like of shape (n_theta,), optional

Polar angle values (colatitude). Defaults to np.linspace(0, pi, 90).

phi_rangearray-like of shape (n_phi,), optional

Azimuthal angle values. Defaults to np.linspace(0, 2*pi, 180).

l_maxint, optional

Maximum degree of harmonics to use. Defaults to self.n_harmonics.

Returns:
X_coordsndarray of shape (n_samples, n_theta, n_phi, 3)

Reconstructed surface coordinates.

set_inverse_transform_request(*, X_transformed: bool | None | str = '$UNCHANGED$', l_max: bool | None | str = '$UNCHANGED$', phi_range: bool | None | str = '$UNCHANGED$', theta_range: bool | None | str = '$UNCHANGED$') → SphericalHarmonicAnalysis#

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.

l_maxstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for l_max parameter in inverse_transform.

phi_rangestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for phi_range parameter in inverse_transform.

theta_rangestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for theta_range parameter in inverse_transform.

Returns:
selfobject

The updated object.

set_output(*, transform=None)#

Set output container.

See 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(*, theta_phi: bool | None | str = '$UNCHANGED$') → SphericalHarmonicAnalysis#

Configure whether metadata should be requested to be passed to the 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 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:
theta_phistr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for theta_phi parameter in transform.

Returns:
selfobject

The updated object.

transform(X, theta_phi=None)[source]#

Compute SPHARM coefficients.

Parameters:
X: list of array-like

Coordinate values of n_samples. The i-th array-like whose shape (n_coords_i, 3) represents 3D coordinate values of the i-th sample .

theta_phi: list of array-like of shape (n_coords, 2)

Surface parameter of n_samples. The i-th array-like of theta and phi values whose shape is (n_coords_i, 2).

Returns:
X_transformed: array-like of shape (n_samples, n_coefficients)

Returns the array-like of SPHARM coefficients.