refactor variable handling module for narwahls

docs/user_guide/variable_handling/check_all_variables.rst

@@ -89,4 +89,48 @@ Below we see the error message:
 
 .. code:: python
 
-    KeyError: 'Some of the variables are not in the dataframe.'
+    KeyError: 'Some of the variables are not in the dataframe.'
+
+With polars
+-----------
+
+:class:`check_all_variables()` works in the same way with a polars dataframe.
+Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import check_all_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+    checked_vars = check_all_variables(X, ["num_var_1", "cat_var1", "date1"])
+
+    checked_vars
+
+The output is the list of variable names passed to the function:
+
+.. code:: python
+
+    ['num_var_1', 'cat_var1', 'date1']

docs/user_guide/variable_handling/check_categorical_variables.rst

@@ -89,4 +89,54 @@ Below we see the error message:
 .. code:: python
 
     TypeError: Some of the variables are not categorical. Please cast them as object
-    or categorical before using this transformer.
+    or categorical before using this transformer.
+
+With polars
+-----------
+
+:class:`check_categorical_variables()` works in the same way with a polars dataframe.
+Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import check_categorical_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+    var_cat = check_categorical_variables(X, ["cat_var1", "date3"])
+
+    var_cat
+
+Both variables are of type string and hence, will be in the resulting list:
+
+.. code:: python
+
+    ['cat_var1', 'date3']
+
+.. note::
+
+    Polars has no separate "object" dtype the way pandas does - its `String` dtype
+    is the only way to represent free-form text, so it is accepted here as
+    categorical, alongside `Categorical` and `Enum` columns.

docs/user_guide/variable_handling/check_datetime_variables.rst

@@ -92,3 +92,54 @@ Below the error message:
 .. code:: python
 
     TypeError: Some of the variables are not or cannot be parsed as datetime.
+
+With polars
+-----------
+
+:class:`check_datetime_variables()` works in the same way with a polars dataframe.
+Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import check_datetime_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+    var_date = check_datetime_variables(X, ["date2", "date3"])
+
+    var_date
+
+In this case, both variables, if they can be parsed as datetime, will be in the
+resulting list:
+
+.. code:: python
+
+    ['date2', 'date3']
+
+.. note::
+
+    `date3` here is an ISO-8601 string, which polars (via narwhals) can parse.
+    Pandas' flexible, dateutil-backed date-string guessing recognises additional
+    formats that polars does not - see the note in :class:`find_datetime_variables()`.

docs/user_guide/variable_handling/check_numerical_variables.rst

@@ -67,3 +67,32 @@ Below we see the error message:
 
     TypeError: Some of the variables are not numerical. Please cast them as numerical
     before using this transformer.
+
+With polars
+-----------
+
+:class:`check_numerical_variables()` works in the same way with a polars dataframe:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime
+    from feature_engine.variable_handling import check_numerical_variables
+
+    df = pl.DataFrame({
+        "Name": ["tom", "nick", "krish", "jack"],
+        "City": ["London", "Manchester", "Liverpool", "Bristol"],
+        "Age": [20, 21, 19, 18],
+        "Marks": [0.9, 0.8, 0.7, 0.6],
+        "dob": [datetime(2020, 2, 24, 0, i) for i in range(4)],
+    })
+
+    var_num = check_numerical_variables(df, ['Age', 'Marks'])
+
+    var_num
+
+If the variables are numerical, the function returns their names in a list:
+
+.. code:: python
+
+    ['Age', 'Marks']

docs/user_guide/variable_handling/find_all_variables.rst

@@ -125,4 +125,68 @@ However, this command returns an empty list:
         X[[ 'date1', 'date2', 'date3']],
         exclude_datetime=True,
         return_empty=True,
-    )
+    )
+
+With polars
+-----------
+
+:class:`find_all_variables()` works in the same way with a polars dataframe.
+Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import find_all_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+    vars_all = find_all_variables(X)
+
+    vars_all
+
+We see the variable names in the list below:
+
+.. code:: python
+
+    ['num_var_1',
+     'num_var_2',
+     'num_var_3',
+     'num_var_4',
+     'cat_var1',
+     'cat_var2',
+     'date1',
+     'date2',
+     'date3']
+
+And, as with pandas, we can exclude the datetime variables:
+
+.. code:: python
+
+    vars_all = find_all_variables(X, exclude_datetime=True)
+
+    vars_all
+
+.. code:: python
+
+    ['num_var_1', 'num_var_2', 'num_var_3', 'num_var_4', 'cat_var1', 'cat_var2']

docs/user_guide/variable_handling/find_categorical_and_numerical_variables.rst

@@ -126,4 +126,50 @@ To return empty lists instead, we set `return_empty` to `True`:
     find_categorical_and_numerical_variables(
         X[[ 'date1', 'date2', 'date3']],
         return_empty = True
-    )
+    )
+
+With polars
+-----------
+
+:class:`find_categorical_and_numerical_variables()` works in the same way with a
+polars dataframe. Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import find_categorical_and_numerical_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+    var_cat, var_num = find_categorical_and_numerical_variables(X)
+
+    var_cat, var_num
+
+Below we see the names of the categorical variables, followed by the names of the
+numerical variables:
+
+.. code:: python
+
+    (['cat_var1', 'cat_var2'],
+     ['num_var_1', 'num_var_2', 'num_var_3', 'num_var_4'])

docs/user_guide/variable_handling/find_categorical_variables.rst

@@ -90,3 +90,59 @@ To return an empty list instead of the error we need to set `return_empty` to `T
 follows: `find_categorical_variables(X[colnames], return_empty=True)`.
 
 The previous command returns an empty list: `[]`.
+
+With polars
+-----------
+
+:class:`find_categorical_variables()` works in the same way with a polars dataframe.
+Let's create an equivalent toy dataset:
+
+.. code:: python
+
+    import polars as pl
+    from datetime import datetime, timedelta
+    from sklearn.datasets import make_classification
+    from feature_engine.variable_handling import find_categorical_variables
+
+    X, y = make_classification(
+        n_samples=1000,
+        n_features=4,
+        n_redundant=1,
+        n_clusters_per_class=1,
+        weights=[0.50],
+        class_sep=2,
+        random_state=1,
+    )
+
+    colnames = [f"num_var_{i+1}" for i in range(4)]
+    X = pl.DataFrame(X, schema=colnames)
+
+    X = X.with_columns(
+        pl.lit("Hello").alias("cat_var1"),
+        pl.lit("Bye").alias("cat_var2"),
+        pl.Series("date1", [datetime(2020, 2, 24) + timedelta(minutes=i) for i in range(1000)]),
+        pl.Series("date2", [datetime(2021, 9, 29) + timedelta(hours=i) for i in range(1000)]),
+        pl.lit("2020-02-24").alias("date3"),
+    )
+
+Now let's find the categorical variables:
+
+.. code:: python
+
+    var_cat = find_categorical_variables(X)
+
+    var_cat
+
+We see the variable names in the list below:
+
+.. code:: python
+
+    ['cat_var1', 'cat_var2']
+
+.. note::
+
+    Unlike for pandas, `date3` above is a plain ISO-8601 string column, which polars
+    (via narwhals) *can* auto-detect as a datetime candidate, so it is still correctly
+    excluded here. Only pandas' flexible, dateutil-backed date-string guessing (formats
+    like "24-Feb-2020" or "02/24/20") has no polars equivalent - see the note in
+    :class:`find_datetime_variables()`.