create docstring functionality to share common params and methods

feature_engine/creation/_docstring.py

@@ -0,0 +1,14 @@
+_drop_original_docstring = """drop_original: bool, default=False
+        If True, the original variables will be dropped from the dataframe after
+        creating the features.
+    """.rstrip()
+
+_missing_values_docstring = """missing_values: string, default='raise'
+        Indicates if missing values should be ignored or raised. If 'raise' the
+        transformer will return an error if the the datasets to `fit` or `transform`
+        contain missing values. If 'ignore', missing data will be ignored when creating
+        the features.
+        """
+_transform_docstring = """transform:
+        Create and add the new features.
+    """.rstrip()

feature_engine/creation/combine_with_reference_feature.py

@@ -4,16 +4,35 @@
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_is_fitted
 
+from feature_engine.creation._docstring import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+    _transform_docstring,
+)
 from feature_engine.dataframe_checks import (
     _check_contains_inf,
     _check_contains_na,
     _check_input_matches_training_df,
     _is_dataframe,
 )
+from feature_engine.docstrings import (
+    Substitution,
+    _fit_not_learn_docstring,
+    _fit_transform_docstring,
+    _n_features_in_docstring,
+)
 from feature_engine.validation import _return_tags
 from feature_engine.variable_manipulation import _find_or_check_numerical_variables
 
 
+@Substitution(
+    missing_values=_missing_values_docstring,
+    drop_original=_drop_original_docstring,
+    n_features_in_=_n_features_in_docstring,
+    fit=_fit_not_learn_docstring,
+    transform=_transform_docstring,
+    fit_transform=_fit_transform_docstring,
+)
 class CombineWithReferenceFeature(BaseEstimator, TransformerMixin):
     """
     CombineWithReferenceFeature() applies basic mathematical operations between a group
@@ -42,9 +61,9 @@ class CombineWithReferenceFeature(BaseEstimator, TransformerMixin):
     operations: list, default=['sub']
         The list of basic mathematical operations to be used in the transformation.
 
-        If None, all of ['sub', 'div','add','mul'] will be performed. Alternatively,
+        If None, all of ['sub', 'div', 'add', 'mul'] will be performed. Alternatively,
         you can enter a list of operations to carry out. Each operation should
-        be a string and must be one of the elements in `['sub', 'div','add', 'mul']`.
+        be a string and must be one of the elements in `['sub', 'div', 'add', 'mul']`.
 
         Each operation will result in a new variable that will be added to the
         transformed dataset.
@@ -59,29 +78,21 @@ class CombineWithReferenceFeature(BaseEstimator, TransformerMixin):
         If `new_variable_names` is None, the transformer will assign an arbitrary name
         to the features. The name will be var + operation + ref_var.
 
-    missing_values: string, default='ignore'
-        Indicates if missing values should be ignored or raised. If 'ignore', the
-        transformer will ignore missing data when transforming the data. If 'raise' the
-        transformer will return an error if the training or the datasets to transform
-        contain missing values.
+    {missing_values}
 
-    drop_original: bool, default=False
-        If True, the original variables will be dropped from the dataframe
-        after their combination.
+    {drop_original}
 
     Attributes
     ----------
-    n_features_in_:
-        The number of features in the train set used in fit.
+    {n_features_in_}
 
     Methods
     -------
-    fit:
-        This transformer does not learn parameters.
-    transform:
-        Combine the variables with the mathematical operations.
-    fit_transform:
-        Fit to the data, then transform it.
+    {fit}
+
+    {transform}
+
+    {fit_transform}
 
     Notes
     -----

feature_engine/creation/cyclical.py

@@ -4,9 +4,28 @@
 import pandas as pd
 
 from feature_engine.base_transformers import BaseNumericalTransformer
+from feature_engine.creation._docstring import (
+    _drop_original_docstring,
+    _transform_docstring,
+)
+from feature_engine.docstrings import (
+    Substitution,
+    _fit_transform_docstring,
+    _n_features_in_docstring,
+    _variables_attribute_docstring,
+    _variables_numerical_docstring,
+)
 from feature_engine.variable_manipulation import _check_input_parameter_variables
 
 
+@Substitution(
+    variables=_variables_numerical_docstring,
+    drop_original=_drop_original_docstring,
+    variables_=_variables_attribute_docstring,
+    n_features_in_=_n_features_in_docstring,
+    transform=_transform_docstring,
+    fit_transform=_fit_transform_docstring,
+)
 class CyclicalTransformer(BaseNumericalTransformer):
     """
     The CyclicalTransformer() applies cyclical transformations to numerical
@@ -27,39 +46,32 @@ class CyclicalTransformer(BaseNumericalTransformer):
 
     Parameters
     ----------
-    variables: list, default=None
-        The list of numerical variables to transform. If None, the transformer will
-        automatically find and select all numerical variables.
+    {variables}
 
     max_values: dict, default=None
         A dictionary with the maximum value of each variable to transform. Useful when
         the maximum value is not present in the dataset. If None, the transformer will
         automatically find the maximum value of each variable.
 
-    drop_original: bool, default=False
-        If True, the original variables to transform will be dropped from the dataframe.
+    {drop_original}
 
     Attributes
     ----------
     max_values_:
         The maximum value of the cyclical feature.
 
-    variables_:
-        The group of variables that will be transformed.
-
-    n_features_in_:
-        The number of features in the train set used in fit.
+    {variables_}
 
+    {n_features_in_}
 
     Methods
     -------
     fit:
         Learns the maximum values of the cyclical features.
-    transform:
-        Applies the cyclical transformation.
-    fit_transform:
-        Fit to data, then transform it.
 
+    {transform}
+
+    {fit_transform}
 
     References
     ----------

feature_engine/creation/mathematical_combination.py

@@ -4,16 +4,35 @@
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_is_fitted
 
+from feature_engine.creation._docstring import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+    _transform_docstring,
+)
 from feature_engine.dataframe_checks import (
     _check_contains_inf,
     _check_contains_na,
     _check_input_matches_training_df,
     _is_dataframe,
 )
+from feature_engine.docstrings import (
+    Substitution,
+    _fit_not_learn_docstring,
+    _fit_transform_docstring,
+    _n_features_in_docstring,
+)
 from feature_engine.validation import _return_tags
 from feature_engine.variable_manipulation import _find_or_check_numerical_variables
 
 
+@Substitution(
+    missing_values=_missing_values_docstring,
+    drop_original=_drop_original_docstring,
+    n_features_in_=_n_features_in_docstring,
+    fit=_fit_not_learn_docstring,
+    transform=_transform_docstring,
+    fit_transform=_fit_transform_docstring,
+)
 class MathematicalCombination(BaseEstimator, TransformerMixin):
     """
     MathematicalCombination() applies basic mathematical operations to multiple
@@ -55,11 +74,9 @@ class MathematicalCombination(BaseEstimator, TransformerMixin):
         to the newly created features starting by the name of the mathematical
         operation, followed by the variables combined separated by -.
 
-    missing_values: string, default='raise'
-        Indicates if missing values should be ignored or raised. If 'raise' the
-        transformer will return an error if the the datasets to `fit` or `transform`
-        contain missing values. If 'ignore', missing data will be ignored when
-        performing the calculations.
+    {missing_values}
+
+    {drop_original}
 
     Attributes
     ----------
@@ -70,17 +87,15 @@ class MathematicalCombination(BaseEstimator, TransformerMixin):
         List with the mathematical operations to be applied to the
         `variables_to_combine`.
 
-    n_features_in_:
-        The number of features in the train set used in fit.
+    {n_features_in_}
 
     Methods
     -------
-    fit:
-        This transformer does not learn parameters.
-    transform:
-        Combine the variables with the mathematical operations.
-    fit_transform:
-        Fit to the data, then transform it.
+    {fit}
+
+    {transform}
+
+    {fit_transform}
 
     Notes
     -----

feature_engine/datetime/datetime.py

@@ -18,12 +18,23 @@
     FEATURES_SUFFIXES,
     FEATURES_SUPPORTED,
 )
+from feature_engine.docstrings import (
+    Substitution,
+    _fit_not_learn_docstring,
+    _fit_transform_docstring,
+    _n_features_in_docstring,
+)
 from feature_engine.variable_manipulation import (
     _check_input_parameter_variables,
     _find_or_check_datetime_variables,
 )
 
 
+@Substitution(
+    n_features_in_=_n_features_in_docstring,
+    fit=_fit_not_learn_docstring,
+    fit_transform=_fit_transform_docstring,
+)
 class DatetimeFeatures(BaseEstimator, TransformerMixin):
     """
     DatetimeFeatures extracts date and time features from datetime variables, adding
@@ -103,17 +114,16 @@ class DatetimeFeatures(BaseEstimator, TransformerMixin):
     features_to_extract_:
         The date and time features that will be extracted from each variable.
 
-    n_features_in_:
-        The number of features in the train set used in fit.
+    {n_features_in_}
 
     Methods
     -------
-    fit:
-        This transformer does not learn parameters.
+    {fit}
+
     transform:
         Add the date and time features.
-    fit_transform:
-        Fit to the data, then transform it.
+
+    {fit_transform}
 
     See also
     --------
@@ -130,7 +140,6 @@ def __init__(
         dayfirst: bool = False,
         yearfirst: bool = False,
         utc: Union[None, bool] = None,
-
     ) -> None:
 
         if features_to_extract:
@@ -162,10 +171,7 @@ def __init__(
             )
 
         if utc is not None and not isinstance(utc, bool):
-            raise ValueError(
-                "utc takes only booleans or None. "
-                f"Got {utc} instead."
-            )
+            raise ValueError("utc takes only booleans or None. " f"Got {utc} instead.")
 
         self.variables = _check_input_parameter_variables(variables)
         self.drop_original = drop_original
@@ -244,8 +250,10 @@ def transform(self, X: pd.DataFrame) -> pd.DataFrame:
         datetime_df = pd.concat(
             [
                 pd.to_datetime(
-                    X[variable], dayfirst=self.dayfirst,
-                    yearfirst=self.yearfirst, utc=self.utc
+                    X[variable],
+                    dayfirst=self.dayfirst,
+                    yearfirst=self.yearfirst,
+                    utc=self.utc,
                 )
                 for variable in self.variables_
             ],
@@ -255,9 +263,9 @@ def transform(self, X: pd.DataFrame) -> pd.DataFrame:
         non_dt_columns = datetime_df.columns[~datetime_df.apply(is_datetime)].tolist()
         if non_dt_columns:
             raise ValueError(
-                "ValueError: variable(s) " +
-                (len(non_dt_columns) * '{} ').format(*non_dt_columns) +
-                "could not be converted to datetime. Try setting utc=True"
+                "ValueError: variable(s) "
+                + (len(non_dt_columns) * "{} ").format(*non_dt_columns)
+                + "could not be converted to datetime. Try setting utc=True"
             )
 
         # create new features