plaid.pipelines.plaid_blocks
============================

.. py:module:: plaid.pipelines.plaid_blocks

.. autoapi-nested-parse::

   Custom meta-estimators for applying feature-wise and target-wise transformations.

   Includes:

   - PlaidTransformedTargetRegressor: transforms the target before fitting.

   - PlaidColumnTransformer: applies transformers to feature subsets like ColumnTransformer.



Attributes
----------

.. autoapisummary::

   plaid.pipelines.plaid_blocks.Self


Classes
-------

.. autoapisummary::

   plaid.pipelines.plaid_blocks.ColumnTransformer
   plaid.pipelines.plaid_blocks.TransformedTargetRegressor


Module Contents
---------------

.. py:data:: Self

.. py:class:: ColumnTransformer(plaid_transformers: list[tuple[str, Union[sklearn.base.TransformerMixin, sklearn.pipeline.Pipeline]]])

   Bases: :py:obj:`sklearn.compose.ColumnTransformer`


   Custom column-wise transformer for PLAID-style datasets.

   Similar to scikit-learn's `ColumnTransformer`, this class applies a list
   of transformer blocks to subsets of features, defined by their feature
   identifiers. Additionally, it preserves a set of remainder features that
   bypass transformation.

   :param plaid_transformers: A list of tuples
                              (name, transformer), where each `transformer` is a TransformerMixin.

   .. note:: At fit, it is checked that `plaid_transformers` share no in_features_identifiers and no out_features_identifiers.


   .. py:attribute:: plaid_transformers


   .. py:method:: fit(dataset: plaid.Dataset, _y=None) -> Self

      Fits all transformers on their corresponding feature subsets.

      :param dataset: A `Dataset` object or a list of samples.
      :param y: Ignored. Present for API compatibility.

      :returns: The fitted PlaidColumnTransformer.
      :rtype: self



   .. py:method:: transform(dataset: plaid.Dataset) -> plaid.Dataset

      Applies fitted transformers to feature subsets and merges results.

      :param dataset: A `Dataset` object or a list of samples.

      :returns: A new `Dataset` with transformed feature blocks, including
                untransformed remainder features.
      :rtype: Dataset



   .. py:method:: fit_transform(dataset: plaid.Dataset, y=None) -> plaid.Dataset

      Fits all transformers and returns the combined transformed dataset.

      :param dataset: A `Dataset` object or a list of samples.
      :param y: Ignored. Present for API compatibility.

      :returns: A new `Dataset` with transformed features.
      :rtype: Dataset



   .. py:method:: inverse_transform(dataset: plaid.Dataset) -> plaid.Dataset

      Applies fitted inverse transformers to feature subsets and merges results.

      :param dataset: A `Dataset` object or a list of samples.

      :returns: A new `Dataset` with inverse transformed feature blocks, including
                untransformed remainder features.
      :rtype: Dataset



.. py:class:: TransformedTargetRegressor(regressor: Union[sklearn.base.RegressorMixin, sklearn.pipeline.Pipeline], transformer: Union[sklearn.base.TransformerMixin, sklearn.pipeline.Pipeline])

   Bases: :py:obj:`sklearn.base.RegressorMixin`, :py:obj:`sklearn.base.BaseEstimator`


   Meta-estimator that transforms the target before fit and inverses it at predict.

   This regressor is compatible with custom `Dataset` objects and supports
   complex targets, including scalars and fields. It wraps a base regressor
   and a transformer that is responsible for preprocessing the target space.

   :param regressor: A regressor implementing `fit` and `predict`, following the scikit-learn API.
   :param transformer: A transformer implementing `fit`, `transform`, and `inverse_transform`.
                       Applied to the dataset before fitting the regressor.


   .. py:attribute:: regressor


   .. py:attribute:: transformer


   .. py:method:: fit(dataset: plaid.Dataset, _y=None) -> Self

      Fits the transformer and the regressor on the transformed dataset.

      :param dataset: A `Dataset` object or a list of sample dictionaries.
                      Input training data.
      :param y: Ignored. Present for API compatibility.

      :returns: The fitted estimator.
      :rtype: self



   .. py:method:: predict(dataset: plaid.Dataset) -> plaid.Dataset

      Predicts target values using the fitted regressor, then applies the inverse transformation.

      :param dataset: A `Dataset` object or a list of sample dictionaries.
                      Input data to predict on.

      :returns: A `Dataset` containing the inverse-transformed predictions.
      :rtype: Dataset



   .. py:method:: score(dataset_X: plaid.Dataset, dataset_y: plaid.Dataset = None) -> float

      Computes a normalized root mean squared error (RMSE) score on the transformed targets.

      The score is defined as `1 - avg(relative RMSE)` over all target features in the
      `transformer` input features identifiers. The error computation depends on the feature type:
      - For "scalar" features: RMSE normalized by squared reference value.
      - For "field" features: RMSE normalized by field size and max-norm of the reference.

      :param dataset_X: A `Dataset` object or a list of samples.
                        Input features used for prediction.
      :param dataset_y: A `Dataset` object or list, optional.
                        Ground-truth targets. If `None`, `dataset_X` is used for both input and reference.

      :returns: A score between `-inf` and `1`. A perfect prediction yields a score of `1.0`.
      :rtype: float

      :raises ValueError: If an unknown feature type is encountered.