[MNT] Deprecate LogCpTransformer in favour of LogTransformer with C parameter

README.md

@@ -119,7 +119,6 @@ Please share your story by answering 1 quick question
 
 ### Variable Transformation methods
 * LogTransformer
-* LogCpTransformer
 * ReciprocalTransformer
 * ArcsinTransformer
 * PowerTransformer

docs/api_doc/transformation/LogCpTransformer.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 LogCpTransformer
 ================
 

docs/api_doc/transformation/index.rst

@@ -10,7 +10,6 @@ mathematical transformations.
    :maxdepth: 1
 
    LogTransformer
-   LogCpTransformer
    ReciprocalTransformer
    ArcsinTransformer
    ArcSinhTransformer

docs/index.rst

@@ -237,7 +237,6 @@ We normally use variance stabilising transformations to make the data meet the a
 like ANOVA, and machine learning models, like linear regression. Feature-engine supports the following transformations:
 
 - :doc:`api_doc/transformation/LogTransformer`: performs logarithmic transformation of numerical variables
-- :doc:`api_doc/transformation/LogCpTransformer`: performs logarithmic transformation after adding a constant value
 - :doc:`api_doc/transformation/ReciprocalTransformer`: performs reciprocal transformation of numerical variables
 - :doc:`api_doc/transformation/PowerTransformer`: performs power transformation of numerical variables
 - :doc:`api_doc/transformation/BoxCoxTransformer`: performs Box-Cox transformation of numerical variables

docs/user_guide/transformation/LogCpTransformer.rst

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _log_cp:
 
 .. currentmodule:: feature_engine.transformation
@@ -13,6 +15,12 @@ positive values.
 adding a constant to move distributions towards positive values. For more details about
 the logarithm transformation, check out the :ref:`LogTransformer()'s user Guide <log_transformer>`.
 
+.. warning::
+
+    :class:`LogCpTransformer()` was deprecated in version 2.0.0 and will be removed in
+    version 2.1.0. Use ``LogTransformer(C="auto")`` instead, which reproduces
+    :class:`LogCpTransformer()`'s default behavior exactly.
+
 Defining C
 ----------
 

docs/user_guide/transformation/LogTransformer.rst

@@ -28,9 +28,7 @@ LogTransformer
 
 .. note::
 
-    Note that the logarithm can only be applied to positive values. Thus, if the variable contains 0 or negative values, this transformer will return an error.
-
-To transform non-positive variables you can add a constant to shift the data points towards positive values. You can do this by using :class:`LogCpTransformer()`.
+    The logarithm can only be applied to positive values; if the variable contains 0 or negative values, the transformer will raise an error. To avoid this, add a constant to the variables by using the `C` parameter (more details below).
 
 .. attention::
 
@@ -161,6 +159,64 @@ In the following plots we see histograms showing the variables in their original
     Following the transformations with scatter plots and residual analysis of the regression models helps understand if the transformations are useful in our regression analysis.
 
 
+Transforming non-positive variables with C
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:class:`LogTransformer()` can also transform variables that contain zero or
+negative values, by adding a constant ``C`` before applying the logarithm,
+i.e. ``log(x + C)``.
+
+Let's load the diabetes dataset that comes with scikit-learn, which contains
+variables with negative values:
+
+.. code:: python
+
+    from sklearn.datasets import load_diabetes
+    from sklearn.model_selection import train_test_split
+    from feature_engine.transformation import LogTransformer
+
+    # Load dataset
+    X, y = load_diabetes(return_X_y=True, as_frame=True)
+
+    # Separate into train and test sets
+    X_train, X_test, y_train, y_test = train_test_split(
+        X, y, test_size=0.3, random_state=0)
+
+Let's set up :class:`LogTransformer()` with ``C="auto"``, so it automatically
+finds the constant needed to shift each variable's distribution to positive
+values before applying the logarithm:
+
+.. code:: python
+
+    logt = LogTransformer(variables=["bmi", "s3"], C="auto")
+    logt.fit(X_train)
+
+We can inspect the constant values that will be added to each variable in the
+``C_`` attribute:
+
+.. code:: python
+
+    logt.C_
+
+Since these variables are not strictly positive, the transformer found the
+minimum value needed to make their values positive:
+
+.. code:: python
+
+    {'bmi': 1.0848862355291056, 's3': 1.102307050517416}
+
+We can now transform the data:
+
+.. code:: python
+
+    train_t = logt.transform(X_train)
+    test_t = logt.transform(X_test)
+
+You can also pass a fixed constant to all variables (``C=5``), or a dictionary
+mapping each variable to its own constant (``C={"bmi": 2, "s3": 3}``), the same
+way you would with the deprecated :class:`LogCpTransformer()`.
+
+
 Additional resources
 --------------------
 

docs/user_guide/transformation/PowerTransformer.rst

@@ -74,7 +74,6 @@ Other transformers
 Feature-engine also provides the following power transformers:
 
 - :class:`LogTransformer`
-- :class:`LogCpTransformer`
 - :class:`ReciprocalTransformer`
 - :class:`ArcsinTransformer`
 

docs/user_guide/transformation/index.rst

@@ -24,18 +24,17 @@ See the following illustration:
 Supported transformations
 -------------------------
 
-================================ ================================================ ============================================================================================= ====================
-Transformer                      Description                                      Suitable for                                                                                  Limitations
-================================ ================================================ ============================================================================================= ====================
-:class:`LogTransformer()`        Applies natural or decimal logarithm.            Positive continuous variables with right skew.                                                Not valid for x<=0
-:class:`LogCpTransformer()`      Applies logarithm after adding a constant value. Continuous variables with a right skew.                                                       None
-:class:`ReciprocalTransformer()` Applies the reciprocal transformation: 1/x.      Variables representing ratios or proportions, like tons per acre.                             Not defined for x=0
-:class:`ArcsinTransformer()`     Applies the arcsin square root transformation.   Probabilities or proportion variables with values between 0 and 1.                            0<= x <= 1
-:class:`ArcSinhTransformer()`    Applies the inverse hyperbolic sine function.    Similar to log but retaining zero values in a variable.                                       None
-:class:`PowerTransformer()`      Applies any power transformation x = x**n.       Square root is suitable for count variables. Other powers vary.                               None
-:class:`BoxCoxTransformer()`     Applies the Box-Cox transformation.              Positive continuous variables when the optimal transformation is unknown.                     Not defined for x<=0
-:class:`YeoJohnsonTransformer()` Applies the Yeo-Johnson transformation.          Continuous variables with zero or negative values when the optimal transformation is unknown. None
-================================ ================================================ ============================================================================================= ====================
+================================ ===================================================================== ============================================================================================= ======================================================
+Transformer                      Description                                                           Suitable for                                                                                  Limitations
+================================ ===================================================================== ============================================================================================= ======================================================
+:class:`LogTransformer()`        Applies natural or decimal logarithm, optionally adding a constant C. Positive continuous variables with right skew.                                                Not valid for x<=0 unless C is used to shift the data.
+:class:`ReciprocalTransformer()` Applies the reciprocal transformation: 1/x.                           Variables representing ratios or proportions, like tons per acre.                             Not defined for x=0
+:class:`ArcsinTransformer()`     Applies the arcsin square root transformation.                        Probabilities or proportion variables with values between 0 and 1.                            0<= x <= 1
+:class:`ArcSinhTransformer()`    Applies the inverse hyperbolic sine function.                         Similar to log but retaining zero values in a variable.                                       None
+:class:`PowerTransformer()`      Applies any power transformation x = x**n.                            Square root is suitable for count variables. Other powers vary.                               None
+:class:`BoxCoxTransformer()`     Applies the Box-Cox transformation.                                   Positive continuous variables when the optimal transformation is unknown.                     Not defined for x<=0
+:class:`YeoJohnsonTransformer()` Applies the Yeo-Johnson transformation.                               Continuous variables with zero or negative values when the optimal transformation is unknown. None
+================================ ===================================================================== ============================================================================================= ======================================================
 
 .. note::
 
@@ -49,7 +48,6 @@ Transformers
    :maxdepth: 1
 
    LogTransformer
-   LogCpTransformer
    ReciprocalTransformer
    ArcsinTransformer
    ArcSinhTransformer