RaupModel#

class ktch.coiling.RaupModel(r0: float = 1.0, estimator: str = 'ml_2d', n_jobs: int | None = None, verbose: int = 0)[source]#

Raup’s model.

Raup’s logarithmic shell coiling model [Raup_1965] [Raup_1966]. inverse_transform is the generative map Phi: (w_r, t_r, d_r, delta_r, gamma_r) -> form. transform estimates the parameters from lateral and umbilical measurements (ml_2d) or, from a structured surface (surface).

Parameters:

r0float, default = 1.0: Initial tube radius (scale) used for generation.
estimator{“ml_2d”, “surface”}, default = “ml_2d”: Estimation method used by transform. "ml_2d" fits the lateral (d, f) series and combines it with d_r = c / (c + b). "surface" fits the model directly to a structured surface panel (the coordinate output of inverse_transform), recovering the aperture orientation (delta_r, gamma_r) as well. It is consistent with inverse_transform (transform(inverse_transform(params)) ~= params).
n_jobsint, optional: Number of jobs for the per-specimen estimation in transform.
verboseint, default = 0: Verbosity level.

References

[Raup_1965]

Raup, D.M., Michelson, A., 1965. Theoretical Morphology of the Coiled Shell. Science 147, 1294–1295.

[Raup_1966]

Raup, D.M., 1966. Geometric analysis of shell coiling: general problems. Journal of Paleontology 40, 1178–1190.

fit(X, y=None)[source]#: No-op (stateless). Returns self.

fit_transform(X, y=None, c=None, b=None, aperture=None)[source]#

Fit and transform in one step.

Overridden to support metadata routing of c, b, aperture.

get_feature_names_out(input_features=None) → ndarray[source]#: Parameter names (w_r, t_r, d_r, delta_r, gamma_r).

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, aperture=None, as_frame=False)[source]#

Generate shell surfaces from Raup’s model parameters.

Parameters:

X_transformedarray-like of shape (n_samples, 5) or (5,): Rows of (w_r, t_r, d_r, delta_r, gamma_r). A 3-column input (w_r, t_r, d_r) is also accepted, with orientation defaulted to 0.
theta_range, phi_rangearray-like, optional: Sampling grids. See raup().
apertureNone: Aperture shape; only the circular default is supported.
as_framebool, default = False: If True, return a long-format pandas.DataFrame.

Returns:

Xndarray of shape (n_samples, n_theta, n_phi, 3) or pd.DataFrame

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.
aperturestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for aperture 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.
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.

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.

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:

aperturestr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for aperture parameter in transform.
bstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for b parameter in transform.
cstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED: Metadata routing for c parameter in transform.

Returns:

selfobject: The updated object.

transform(X, c=None, b=None, aperture=None)[source]#

Estimate Raup parameters from measured shells.

For estimator="ml_2d", fit the lateral (d, f) series and combine with d_r = c / (c + b). For estimator="surface", fit the model directly to a structured surface.

Parameters:

Xlist of array-like, ndarray, or DataFrame: The input panel; its encoding depends on estimator. For "ml_2d", a per-specimen panel of (n_points_i, 2) lateral digitizing points (d, f). For "surface", a panel of (n_theta, n_phi, 3) structured surfaces.
c, barray-like of shape (n_samples,): Per-specimen umbilical measurements (axis-to-inner-margin distance and aperture width) giving d_r = c / (c + b). Required by "ml_2d" and ignored by "surface".
apertureNone: Aperture shape.

Returns:

X_transformedndarray of shape (n_samples, 5): Estimated (w_r, t_r, d_r, delta_r, gamma_r). The "ml_2d" estimator returns zeros for the orientation columns; the "surface" estimator recovers them.