refactor docstrings module

feature_engine/encoding/_docstrings.py → feature_engine/_docstrings/init_parameters.py

@@ -1,4 +1,21 @@
-_variables_docstring = """variables: list, default=None
+_variables_numerical_docstring = """variables: list, default=None
+        The list of numerical variables to transform. If None, the transformer will
+        automatically find and select all numerical variables.
+    """.rstrip()
+
+_drop_original_docstring = """drop_original: bool, default=False
+        If True, the original variables to transform will be dropped from the dataframe.
+    """.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 learning
+        parameters or performing the transformation.
+        """.rstrip()
+
+# used in categorical encoders
+_variables_categorical_docstring = """variables: list, default=None
         The list of categorical variables that will be encoded. If None, the
         encoder will find and transform all variables of type object or categorical by
         default. You can also make the transformer accept numerical variables, see the
@@ -19,7 +36,3 @@
         error. If 'ignore', then unseen categories will be set as NaN and a warning will
         be raised instead.
     """.rstrip()
-
-_transform_docstring = """transform:
-        Encode the categories to numbers.
-    """.rstrip()

feature_engine/_docstrings/methods.py

@@ -36,3 +36,8 @@
 _inverse_transform_docstring = """inverse_transform:
         Convert the data back to the original representation.
         """.rstrip()
+
+# used in categorical encoders
+_transform_encoders_docstring = """transform:
+        Encode the categories to numbers.
+    """.rstrip()

feature_engine/creation/combine_with_reference_feature.py

@@ -5,14 +5,14 @@
 from sklearn.utils import deprecated
 from sklearn.utils.validation import check_is_fitted
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _missing_values_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_not_learn_docstring,
     _fit_transform_docstring,

feature_engine/creation/cyclical.py

@@ -4,15 +4,15 @@
 import pandas as pd
 from sklearn.utils import deprecated
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _variables_numerical_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _variables_numerical_docstring,
+)
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (

feature_engine/creation/cyclical_features.py

@@ -4,15 +4,15 @@
 import pandas as pd
 from sklearn.utils.validation import check_is_fitted
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _variables_numerical_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _variables_numerical_docstring,
+)
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (

feature_engine/creation/math_features.py

@@ -3,14 +3,14 @@
 import pandas as pd
 from sklearn.utils.validation import check_is_fitted
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _missing_values_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_not_learn_docstring,
     _fit_transform_docstring,

feature_engine/creation/mathematical_combination.py

@@ -5,14 +5,14 @@
 from sklearn.utils import deprecated
 from sklearn.utils.validation import check_is_fitted
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _missing_values_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_not_learn_docstring,
     _fit_transform_docstring,

feature_engine/creation/relative_features.py

@@ -3,15 +3,15 @@
 import pandas as pd
 from sklearn.utils.validation import check_is_fitted
 
-from feature_engine._docstrings.class_inputs import (
-    _drop_original_docstring,
-    _missing_values_docstring,
-    _variables_numerical_docstring,
-)
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _drop_original_docstring,
+    _missing_values_docstring,
+    _variables_numerical_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_not_learn_docstring,
     _fit_transform_docstring,

feature_engine/discretisation/decision_tree.py

@@ -8,12 +8,12 @@
 from sklearn.tree import DecisionTreeClassifier, DecisionTreeRegressor
 from sklearn.utils.multiclass import check_classification_targets, type_of_target
 
-from feature_engine._docstrings.class_inputs import _variables_numerical_docstring
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import _variables_numerical_docstring
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (

feature_engine/discretisation/equal_frequency.py

@@ -5,12 +5,12 @@
 
 import pandas as pd
 
-from feature_engine._docstrings.class_inputs import _variables_numerical_docstring
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import _variables_numerical_docstring
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (

feature_engine/discretisation/equal_width.py

@@ -5,12 +5,12 @@
 
 import pandas as pd
 
-from feature_engine._docstrings.class_inputs import _variables_numerical_docstring
 from feature_engine._docstrings.fit_attributes import (
     _feature_names_in_docstring,
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import _variables_numerical_docstring
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (

feature_engine/encoding/base_encoder.py

@@ -5,6 +5,11 @@
 from sklearn.base import BaseEstimator, TransformerMixin
 from sklearn.utils.validation import check_is_fitted
 
+from feature_engine._docstrings.init_parameters import (
+    _ignore_format_docstring,
+    _unseen_docstring,
+    _variables_categorical_docstring,
+)
 from feature_engine._docstrings.methods import _get_feature_names_out_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine._variable_handling.init_parameter_checks import (
@@ -19,19 +24,14 @@
     _check_X_matches_training_df,
     check_X,
 )
-from feature_engine.encoding._docstrings import (
-    _ignore_format_docstring,
-    _unseen_docstring,
-    _variables_docstring,
-)
 from feature_engine.encoding._helper_functions import check_parameter_unseen
 from feature_engine.get_feature_names_out import _get_feature_names_out
 from feature_engine.tags import _return_tags
 
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
 )
 class CategoricalInitMixin:
     """Shared initialization parameters across transformers.
@@ -61,7 +61,7 @@ def __init__(
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
     unseen=_unseen_docstring,
 )
 class CategoricalInitExpandedMixin(CategoricalInitMixin):
@@ -90,7 +90,7 @@ def __init__(
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
 )
 class CategoricalMethodsMixin(BaseEstimator, TransformerMixin):
     """Shared methods across categorical transformers.

feature_engine/encoding/count_frequency.py

@@ -11,18 +11,18 @@
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _ignore_format_docstring,
+    _unseen_docstring,
+    _variables_categorical_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_transform_docstring,
     _inverse_transform_docstring,
+    _transform_encoders_docstring,
 )
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine.dataframe_checks import check_X
-from feature_engine.encoding._docstrings import (
-    _ignore_format_docstring,
-    _transform_docstring,
-    _unseen_docstring,
-    _variables_docstring,
-)
 from feature_engine.encoding._helper_functions import check_parameter_unseen
 from feature_engine.encoding.base_encoder import (
     CategoricalInitMixin,
@@ -37,13 +37,13 @@
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
     unseen=_unseen_docstring,
     variables_=_variables_attribute_docstring,
     feature_names_in_=_feature_names_in_docstring,
     n_features_in_=_n_features_in_docstring,
     fit_transform=_fit_transform_docstring,
-    transform=_transform_docstring,
+    transform=_transform_encoders_docstring,
     inverse_transform=_inverse_transform_docstring,
 )
 class CountFrequencyEncoder(CategoricalInitMixin, CategoricalMethodsMixin):

feature_engine/encoding/decision_tree.py

@@ -12,14 +12,14 @@
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _ignore_format_docstring,
+    _variables_categorical_docstring,
+)
 from feature_engine._docstrings.methods import _fit_transform_docstring
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine.dataframe_checks import check_X_y
 from feature_engine.discretisation import DecisionTreeDiscretiser
-from feature_engine.encoding._docstrings import (
-    _ignore_format_docstring,
-    _variables_docstring,
-)
 from feature_engine.encoding.base_encoder import (
     CategoricalInitMixin,
     CategoricalMethodsMixin,
@@ -30,7 +30,7 @@
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
     variables_=_variables_attribute_docstring,
     feature_names_in_=_feature_names_in_docstring,
     n_features_in_=_n_features_in_docstring,

feature_engine/encoding/mean_encoding.py

@@ -10,18 +10,18 @@
     _n_features_in_docstring,
     _variables_attribute_docstring,
 )
+from feature_engine._docstrings.init_parameters import (
+    _ignore_format_docstring,
+    _unseen_docstring,
+    _variables_categorical_docstring,
+)
 from feature_engine._docstrings.methods import (
     _fit_transform_docstring,
     _inverse_transform_docstring,
+    _transform_encoders_docstring,
 )
 from feature_engine._docstrings.substitute import Substitution
 from feature_engine.dataframe_checks import check_X_y
-from feature_engine.encoding._docstrings import (
-    _ignore_format_docstring,
-    _transform_docstring,
-    _unseen_docstring,
-    _variables_docstring,
-)
 from feature_engine.encoding.base_encoder import (
     CategoricalInitExpandedMixin,
     CategoricalMethodsMixin,
@@ -30,13 +30,13 @@
 
 @Substitution(
     ignore_format=_ignore_format_docstring,
-    variables=_variables_docstring,
+    variables=_variables_categorical_docstring,
     unseen=_unseen_docstring,
     variables_=_variables_attribute_docstring,
     feature_names_in_=_feature_names_in_docstring,
     n_features_in_=_n_features_in_docstring,
     fit_transform=_fit_transform_docstring,
-    transform=_transform_docstring,
+    transform=_transform_encoders_docstring,
     inverse_transform=_inverse_transform_docstring,
 )
 class MeanEncoder(CategoricalInitExpandedMixin, CategoricalMethodsMixin):