refactor: module layout

CHANGELOG.md

@@ -7,6 +7,20 @@ This project adheres to [Semantic Versioning](https://semver.org/) and uses
 
 Going forward, this file is updated automatically by `cz bump` on each release.
 
+## Unreleased
+
+### Refactor
+
+- Reorganized the `pretab` package by representation taxonomy: spline and functional
+  expansions now live under `pretab.expansion`, numeric and categorical encoders under
+  `pretab.encoding`, kernel approximations under `pretab.kernel_approximation`, language
+  embeddings under `pretab.embedding`, and supporting utilities under `pretab.preprocessing`.
+  `pretab.transformers` remains the stable, flat public import for every transformer class;
+  no class was renamed and no public behavior changed.
+- Restructured the representations documentation and API reference to match the new
+  taxonomy, adding dedicated pages for kernel approximation, embeddings, and preprocessing
+  utilities.
+
 ## v1.0.0rc2 (2026-08-21)
 
 ### Fix

README.md

@@ -88,10 +88,12 @@ print({k: v.shape for k, v in X.items()})
 
 ## Available Transformers
 
-PreTab groups its transformers into three families. Each one follows the standard `fit` /
-`transform` API and is importable from `pretab.transformers`.
+PreTab groups its transformers by representation taxonomy. Each one follows the standard
+`fit` / `transform` API and is importable from `pretab.transformers` (the stable, flat public
+import); advanced users can also reach them through the namespace shown per table
+(`pretab.expansion.spline`, `pretab.expansion.functional`, and so on).
 
-### Splines
+### Spline expansions
 
 | Transformer                        | Basis                                 | Best for                               |
 | ----------------------------------- | -------------------------------------- | ---------------------------------------- |
@@ -104,7 +106,7 @@ PreTab groups its transformers into three families. Each one follows the standar
 | `TensorProductSplineTransformer`    | Tensor-product spline (multivariate)  | Smooth interactions across 2+ features |
 | `ThinPlateSplineTransformer`        | Thin-plate spline (multivariate)      | Smooth surfaces across 2+ features     |
 
-### Feature maps
+### Functional expansions
 
 | Transformer                        | Basis                                   | Best for                              |
 | ------------------------------------ | ------------------------------------------ | ---------------------------------------- |
@@ -113,15 +115,26 @@ PreTab groups its transformers into three families. Each one follows the standar
 | `SigmoidExpansionTransformer`        | Sigmoid basis                           | Smooth saturating features            |
 | `TanhExpansionTransformer`           | Tanh basis                              | Zero-centered saturating features     |
 | `FourierFeatureTransformer`          | Sine/cosine basis                       | Periodic or cyclic numerical effects  |
+
+### Kernel approximation
+
+| Transformer                        | Basis                                   | Best for                              |
+| ------------------------------------ | ------------------------------------------ | ---------------------------------------- |
 | `RandomFourierFeaturesTransformer`   | Random Fourier features (multivariate)  | Scalable RBF-kernel approximation     |
 | `NystroemFeaturesTransformer`        | Nystroem kernel map (multivariate)      | Landmark-based kernel approximation   |
 
-### Encoding and binning
+### Numerical encoding
 
 | Transformer                    | Method                                  | Best for                              |
 | ------------------------------- | ------------------------------------------ | ---------------------------------------- |
 | `PLETransformer`                | Piecewise-linear encoding (supervised)  | Strong numerical encoding for models  |
 | `NumericBinningTransformer`     | Uniform/quantile binning, tree-driven   | Discretizing numerical columns        |
+| `PeriodicEncodingTransformer`   | Sine/cosine cyclic encoding             | Values that wrap around a known period |
+
+### Categorical encoding and embeddings
+
+| Transformer                    | Method                                  | Best for                              |
+| ------------------------------- | ------------------------------------------ | ---------------------------------------- |
 | `ContinuousOrdinalTransformer`  | Integer (ordinal) encoding              | Compact codes for categoricals        |
 | `LanguageEmbeddingTransformer`  | Pretrained language embeddings          | High-cardinality, semantic columns    |
 
@@ -131,7 +144,9 @@ PreTab groups its transformers into three families. Each one follows the standar
 > **Note:** Inside the `Preprocessor` you select these by short name, for example `"ple"`,
 > `"rbf"`, `"one-hot"`, `"pretrained"`. See
 > [Representations](https://pretab.readthedocs.io/en/latest/representations/overview.html) for
-> the full catalogue and [comparison table](https://pretab.readthedocs.io/en/latest/representations/comparison_table.html).
+> the full catalogue, including exact input/output shapes and per-parameter effects, and the
+> [comparison table](https://pretab.readthedocs.io/en/latest/representations/comparison_table.html)
+> to filter by capability.
 
 ## 📚 Documentation
 

docs/api/representations.rst

@@ -7,8 +7,8 @@ view, see the :doc:`comparison table <../representations/comparison_table>`.
 
 .. currentmodule:: pretab.transformers
 
-Splines
--------
+Spline expansions
+------------------
 
 .. autosummary::
    :toctree: _autosummary
@@ -20,11 +20,23 @@ Splines
    CubicRegressionSplineTransformer
    NaturalCubicSplineTransformer
    PSplineTransformer
+
+Canonical import: ``pretab.expansion.spline``.
+
+Multivariate splines
+---------------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :nosignatures:
+
    TensorProductSplineTransformer
    ThinPlateSplineTransformer
 
-Feature maps
-------------
+Canonical import: ``pretab.expansion.spline.multivariate``.
+
+Functional expansions
+----------------------
 
 .. autosummary::
    :toctree: _autosummary
@@ -35,33 +47,59 @@ Feature maps
    SigmoidExpansionTransformer
    TanhExpansionTransformer
    FourierFeatureTransformer
-   PeriodicEncodingTransformer
+
+Canonical import: ``pretab.expansion.functional``.
+
+Kernel approximation
+----------------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :nosignatures:
+
    RandomFourierFeaturesTransformer
    NystroemFeaturesTransformer
 
-Binning and PLE
----------------
+Canonical import: ``pretab.kernel_approximation``.
+
+Numerical encoding
+--------------------
 
 .. autosummary::
    :toctree: _autosummary
    :nosignatures:
 
    NumericBinningTransformer
    PLETransformer
+   PeriodicEncodingTransformer
+
+Canonical import: ``pretab.encoding.numerical``.
 
-Categorical
------------
+Categorical encoding
+-----------------------
 
 .. autosummary::
    :toctree: _autosummary
    :nosignatures:
 
    ContinuousOrdinalTransformer
    OneHotFromOrdinalTransformer
+
+Canonical import: ``pretab.encoding.categorical``.
+
+Embeddings
+------------
+
+.. autosummary::
+   :toctree: _autosummary
+   :nosignatures:
+
    LanguageEmbeddingTransformer
 
-Utility transformers
---------------------
+Canonical import: ``pretab.embedding``.
+
+Preprocessing utilities
+--------------------------
 
 .. autosummary::
    :toctree: _autosummary
@@ -70,3 +108,6 @@ Utility transformers
    MissingStateIndicator
    NoTransformer
    ToFloatTransformer
+
+Canonical import: ``pretab.preprocessing``.
+

docs/homepage.md

@@ -120,7 +120,7 @@ See PreTab lift a linear model, baseline vs. PreTab.
 :::{grid-item-card} Representations
 :link: representations/overview
 :link-type: doc
-The full catalogue of splines, feature maps, and encoders.
+The full catalogue of spline and functional expansions, kernel approximations, and encoders.
 :::
 
 :::{grid-item-card} API reference

docs/index.rst

@@ -33,10 +33,13 @@
    representations/overview
    representations/comparison_table
    representations/choosing_a_method
-   representations/splines
-   representations/feature_maps
-   representations/binning_and_ple
-   representations/categorical
+   representations/spline_expansions
+   representations/functional_expansions
+   representations/kernel_approximation
+   representations/numerical_encoding
+   representations/categorical_encoding
+   representations/embeddings
+   representations/preprocessing_utilities
    representations/references
 
 .. toctree::