convert_excel_date, convert_matlab_date for Polars

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 ## [Unreleased]
+-  [ENH] Added a `convert_excel_date` method for polars - Issue #1352
 
 -  [ENH] `xlsx_cells` function now supports polars - Issue #1352
 -  [ENH] `xlsx_table` function now supports polars - Issue #1352

janitor/functions/convert_date.py

@@ -1,24 +1,22 @@
-import datetime as dt
-from typing import Hashable
+from typing import Hashable, Union
 
 import pandas as pd
 import pandas_flavor as pf
-from pandas.api.types import is_numeric_dtype
 from pandas.errors import OutOfBoundsDatetime
 
-from janitor.utils import deprecated_alias
+from janitor.utils import deprecated_alias, refactored_function
 
 
 @pf.register_dataframe_method
-@deprecated_alias(column="column_name")
+@deprecated_alias(column="column_names")
 def convert_excel_date(
-    df: pd.DataFrame, column_name: Hashable
+    df: pd.DataFrame, column_names: Union[Hashable, list]
 ) -> pd.DataFrame:
     """Convert Excel's serial date format into Python datetime format.
 
-    This method mutates the original DataFrame.
+    This method does not mutate the original DataFrame.
 
-    Implementation is also from
+    Implementation is based on
     [Stack Overflow](https://stackoverflow.com/questions/38454403/convert-excel-style-date-with-pandas).
 
     Examples:
@@ -38,40 +36,36 @@ def convert_excel_date(
 
     Args:
         df: A pandas DataFrame.
-        column_name: A column name.
-
-    Raises:
-        ValueError: If there are non numeric values in the column.
+        column_names: A column name, or a list of column names.
 
     Returns:
         A pandas DataFrame with corrected dates.
     """  # noqa: E501
 
-    if not is_numeric_dtype(df[column_name]):
-        raise ValueError(
-            "There are non-numeric values in the column. "
-            "All values must be numeric."
+    if not isinstance(column_names, list):
+        column_names = [column_names]
+    # https://stackoverflow.com/a/65460255/7175713
+    dictionary = {
+        column_name: pd.to_datetime(
+            df[column_name], unit="D", origin="1899-12-30"
         )
+        for column_name in column_names
+    }
 
-    df[column_name] = pd.TimedeltaIndex(
-        df[column_name], unit="d"
-    ) + dt.datetime(
-        1899, 12, 30
-    )  # noqa: W503
-    return df
+    return df.assign(**dictionary)
 
 
 @pf.register_dataframe_method
-@deprecated_alias(column="column_name")
+@deprecated_alias(column="column_names")
 def convert_matlab_date(
-    df: pd.DataFrame, column_name: Hashable
+    df: pd.DataFrame, column_names: Union[Hashable, list]
 ) -> pd.DataFrame:
     """Convert Matlab's serial date number into Python datetime format.
 
-    Implementation is also from
+    Implementation is based on
     [Stack Overflow](https://stackoverflow.com/questions/13965740/converting-matlabs-datenum-format-to-python).
 
-    This method mutates the original DataFrame.
+    This method does not mutate the original DataFrame.
 
     Examples:
         >>> import pandas as pd
@@ -84,29 +78,38 @@ def convert_matlab_date(
         2  737124.498500
         3  737124.000000
         >>> df.convert_matlab_date('date')
-                                date
-        0 2018-03-06 00:00:00.000000
-        1 2018-03-05 19:34:50.563200
-        2 2018-03-05 11:57:50.399999
-        3 2018-03-05 00:00:00.000000
+                                   date
+        0 2018-03-06 00:00:00.000000000
+        1 2018-03-05 19:34:50.563199671
+        2 2018-03-05 11:57:50.399998876
+        3 2018-03-05 00:00:00.000000000
 
     Args:
         df: A pandas DataFrame.
-        column_name: A column name.
+        column_names: A column name, or a list of column names.
 
     Returns:
         A pandas DataFrame with corrected dates.
     """  # noqa: E501
-    days = pd.Series([dt.timedelta(v % 1) for v in df[column_name]])
-    df[column_name] = (
-        df[column_name].astype(int).apply(dt.datetime.fromordinal)
-        + days
-        - dt.timedelta(days=366)
-    )
-    return df
+    # https://stackoverflow.com/a/49135037/7175713
+    if not isinstance(column_names, list):
+        column_names = [column_names]
+    dictionary = {
+        column_name: pd.to_datetime(df[column_name] - 719529, unit="D")
+        for column_name in column_names
+    }
 
+    return df.assign(**dictionary)
 
+
+@pf.register_dataframe_method
 @pf.register_dataframe_method
+@refactored_function(
+    message=(
+        "This function will be deprecated in a 1.x release. "
+        "Please use `pd.to_datetime` instead."
+    )
+)
 @deprecated_alias(column="column_name")
 def convert_unix_date(df: pd.DataFrame, column_name: Hashable) -> pd.DataFrame:
     """Convert unix epoch time into Python datetime format.
@@ -116,6 +119,11 @@ def convert_unix_date(df: pd.DataFrame, column_name: Hashable) -> pd.DataFrame:
 
     This method mutates the original DataFrame.
 
+    !!!note
+
+        This function will be deprecated in a 1.x release.
+        Please use `pd.to_datetime` instead.
+
     Examples:
         >>> import pandas as pd
         >>> import janitor

janitor/polars/__init__.py

@@ -257,3 +257,96 @@ def clean_names(
             enforce_string=enforce_string,
             truncate_limit=truncate_limit,
         )
+
+    def convert_excel_date(self) -> pl.Expr:
+        """
+        Convert Excel's serial date format into Python datetime format.
+
+        Inspiration is from
+        [Stack Overflow](https://stackoverflow.com/questions/38454403/convert-excel-style-date-with-pandas).
+
+        Examples:
+            >>> import polars as pl
+            >>> import janitor.polars
+            >>> df = pl.DataFrame({"date": [39690, 39690, 37118]})
+            >>> df
+            shape: (3, 1)
+            ┌───────┐
+            │ date  │
+            │ ---   │
+            │ i64   │
+            ╞═══════╡
+            │ 39690 │
+            │ 39690 │
+            │ 37118 │
+            └───────┘
+            >>> expression = pl.col('date').janitor.convert_excel_date().alias('date_')
+            >>> df.with_columns(expression)
+            shape: (3, 2)
+            ┌───────┬────────────┐
+            │ date  ┆ date_      │
+            │ ---   ┆ ---        │
+            │ i64   ┆ date       │
+            ╞═══════╪════════════╡
+            │ 39690 ┆ 2008-08-30 │
+            │ 39690 ┆ 2008-08-30 │
+            │ 37118 ┆ 2001-08-15 │
+            └───────┴────────────┘
+
+        !!! info "New in version 0.28.0"
+
+        Returns:
+            A polars Expression.
+        """  # noqa: E501
+        expression = pl.duration(days=self._expr)
+        expression += pl.date(year=1899, month=12, day=30)
+        return expression
+
+    def convert_matlab_date(self) -> pl.Expr:
+        """
+        Convert Matlab's serial date number into Python datetime format.
+
+        Implementation is from
+        [Stack Overflow](https://stackoverflow.com/questions/13965740/converting-matlabs-datenum-format-to-python).
+
+
+        Examples:
+            >>> import polars as pl
+            >>> import janitor.polars
+            >>> df = pl.DataFrame({"date": [737125.0, 737124.815863, 737124.4985, 737124]})
+            >>> df
+            shape: (4, 1)
+            ┌───────────────┐
+            │ date          │
+            │ ---           │
+            │ f64           │
+            ╞═══════════════╡
+            │ 737125.0      │
+            │ 737124.815863 │
+            │ 737124.4985   │
+            │ 737124.0      │
+            └───────────────┘
+            >>> expression = pl.col('date').janitor.convert_matlab_date().alias('date_')
+            >>> df.with_columns(expression)
+            shape: (4, 2)
+            ┌───────────────┬─────────────────────────┐
+            │ date          ┆ date_                   │
+            │ ---           ┆ ---                     │
+            │ f64           ┆ datetime[μs]            │
+            ╞═══════════════╪═════════════════════════╡
+            │ 737125.0      ┆ 2018-03-06 00:00:00     │
+            │ 737124.815863 ┆ 2018-03-05 19:34:50.563 │
+            │ 737124.4985   ┆ 2018-03-05 11:57:50.399 │
+            │ 737124.0      ┆ 2018-03-05 00:00:00     │
+            └───────────────┴─────────────────────────┘
+
+        !!! info "New in version 0.28.0"
+
+        Returns:
+            A polars Expression.
+        """  # noqa: E501
+        # https://stackoverflow.com/questions/13965740/converting-matlabs-datenum-format-to-python
+        expression = self._expr.sub(719529).mul(86_400_000)
+        expression = pl.duration(milliseconds=expression)
+        expression += pl.datetime(year=1970, month=1, day=1)
+        return expression

tests/functions/test_convert_excel_date.py

@@ -18,15 +18,3 @@ def test_convert_excel_date():
     )
 
     assert df["hire_date"].dtype == "M8[ns]"
-
-
-@pytest.mark.functions
-def test_convert_excel_date_with_string_data():
-    """Raises ValueError if values of column are not numeric"""
-    df = pd.read_excel(
-        Path(pytest.EXAMPLES_DIR) / "notebooks" / "dirty_data.xlsx",
-        engine="openpyxl",
-    ).clean_names()
-
-    with pytest.raises(ValueError):
-        df.convert_excel_date("certification")

tests/polars/functions/test_convert_excel_date_polars.py

@@ -0,0 +1,11 @@
+import polars as pl
+
+import janitor.polars  # noqa: F401
+
+
+def test_convert_excel_date():
+    df = pl.DataFrame({"dates": [42580.3333333333]})
+
+    expression = pl.col("dates").janitor.convert_excel_date().alias("dd")
+    expression = df.with_columns(expression).get_column("dd")
+    assert expression.dtype.is_temporal() is True

tests/polars/functions/test_convert_matlab_date_polars.py

@@ -0,0 +1,20 @@
+import polars as pl
+
+import janitor.polars  # noqa: F401
+
+
+def test_convert_matlab_date():
+    df = pl.DataFrame(
+        {
+            "dates": [
+                733_301.0,
+                729_159.0,
+                734_471.0,
+                737_299.563_296_356_5,
+                737_300.000_000_000_0,
+            ]
+        }
+    )
+    expression = pl.col("dates").janitor.convert_matlab_date().alias("dd")
+    expression = df.with_columns(expression).get_column("dd")
+    assert expression.dtype.is_temporal() is True