test_time_series.py

#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#    http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
from datetime import datetime

import numpy as np
import pandas as pd

from pyspark import pandas as ps
from pyspark.testing.pandasutils import PandasOnSparkTestCase
from pyspark.testing.sqlutils import SQLTestUtils


# This file contains test cases for 'Time series-related'
# https://spark.apache.org/docs/latest/api/python/reference/pyspark.pandas/frame.html#time-series-related
class FrameTimeSeriesMixin:
    def test_shift(self):
        pdf = pd.DataFrame(
            {
                "Col1": [10, 20, 15, 30, 45],
                "Col2": [13, 23, 18, 33, 48],
                "Col3": [17, 27, 22, 37, 52],
            },
            index=np.random.rand(5),
        )
        psdf = ps.from_pandas(pdf)

        self.assert_eq(pdf.shift(3), psdf.shift(3))
        self.assert_eq(pdf.shift().shift(-1), psdf.shift().shift(-1))
        self.assert_eq(pdf.shift().sum().astype(int), psdf.shift().sum())

        # Need the expected result since pandas 0.23 does not support `fill_value` argument.
        pdf1 = pd.DataFrame(
            {"Col1": [0, 0, 0, 10, 20], "Col2": [0, 0, 0, 13, 23], "Col3": [0, 0, 0, 17, 27]},
            index=pdf.index,
        )
        self.assert_eq(pdf1, psdf.shift(periods=3, fill_value=0))
        msg = "should be an int"
        with self.assertRaisesRegex(TypeError, msg):
            psdf.shift(1.5)

        # multi-index columns
        columns = pd.MultiIndex.from_tuples([("x", "Col1"), ("x", "Col2"), ("y", "Col3")])
        pdf.columns = columns
        psdf.columns = columns
        self.assert_eq(pdf.shift(3), psdf.shift(3))
        self.assert_eq(pdf.shift().shift(-1), psdf.shift().shift(-1))
        self.assert_eq(pdf.shift(0), psdf.shift(0))

    def test_shift_axis(self):
        # SPARK-46160: shift with axis parameter
        pdf = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]})
        psdf = ps.from_pandas(pdf)

        # Test axis=0 (explicit, should match default behavior)
        self.assert_eq(pdf.shift(axis=0).sort_index(), psdf.shift(axis=0).sort_index())

        # Test axis=1 (shift across columns)
        self.assert_eq(pdf.shift(axis=1).sort_index(), psdf.shift(axis=1).sort_index())

        # Test axis='index' and axis='columns'
        self.assert_eq(pdf.shift(axis="index").sort_index(), psdf.shift(axis="index").sort_index())
        self.assert_eq(
            pdf.shift(axis="columns").sort_index(), psdf.shift(axis="columns").sort_index()
        )

        # Test various periods with axis=1
        for periods in [1, -1, 2, -2, 0]:
            self.assert_eq(
                pdf.shift(periods=periods, axis=1).sort_index(),
                psdf.shift(periods=periods, axis=1).sort_index(),
            )

        # Test fill_value with axis=1
        self.assert_eq(
            pdf.shift(periods=1, fill_value=0, axis=1).sort_index(),
            psdf.shift(periods=1, fill_value=0, axis=1).sort_index(),
        )

        # Test with single column DataFrame
        pdf_single = pd.DataFrame({"A": [1, 2, 3]})
        psdf_single = ps.from_pandas(pdf_single)
        self.assert_eq(
            pdf_single.shift(axis=1).sort_index(),
            psdf_single.shift(axis=1).sort_index(),
        )

        # Test with NaN values
        pdf_nan = pd.DataFrame({"A": [1, np.nan, 3], "B": [4, 3, np.nan]})
        psdf_nan = ps.from_pandas(pdf_nan)
        self.assert_eq(
            pdf_nan.shift(axis=1).sort_index(),
            psdf_nan.shift(axis=1).sort_index(),
        )

        # Test with multi-index columns
        columns = pd.MultiIndex.from_tuples([("x", "A"), ("x", "B"), ("y", "C")])
        pdf.columns = columns
        psdf.columns = columns
        self.assert_eq(pdf.shift(axis=1).sort_index(), psdf.shift(axis=1).sort_index())

        # Test with large dataset to ensure UDF path is used (>1000 rows)
        rng = np.random.RandomState(42)
        pdf_large = pd.DataFrame({"A": rng.rand(1500), "B": rng.rand(1500), "C": rng.rand(1500)})
        psdf_large = ps.from_pandas(pdf_large)
        self.assert_eq(
            pdf_large.shift(axis=1).sort_index(),
            psdf_large.shift(axis=1).sort_index(),
        )

        # Test fill_value on UDF path (large dataset)
        self.assert_eq(
            pdf_large.shift(periods=1, fill_value=0, axis=1).sort_index(),
            psdf_large.shift(periods=1, fill_value=0, axis=1).sort_index(),
        )

        # Test periods larger than number of columns (should produce all NaN)
        self.assert_eq(
            pdf.shift(periods=5, axis=1).sort_index(),
            psdf.shift(periods=5, axis=1).sort_index(),
        )

        # Test with mixed numeric types (int + float)
        pdf_mixed = pd.DataFrame({"A": [1, 2, 3], "B": [4.0, 5.0, 6.0], "C": [7, 8, 9]})
        psdf_mixed = ps.from_pandas(pdf_mixed)
        self.assert_eq(
            pdf_mixed.shift(axis=1).sort_index(),
            psdf_mixed.shift(axis=1).sort_index(),
        )

        # Test with empty DataFrame
        pdf_empty = pd.DataFrame({"A": pd.Series([], dtype="float64")})
        psdf_empty = ps.from_pandas(pdf_empty)
        self.assert_eq(
            pdf_empty.shift(axis=1).sort_index(),
            psdf_empty.shift(axis=1).sort_index(),
        )

        # Test invalid axis value
        with self.assertRaisesRegex(ValueError, "No axis named"):
            psdf.shift(axis=2)

    def test_first_valid_index(self):
        pdf = pd.DataFrame(
            {"a": [None, 2, 3, 2], "b": [None, 2.0, 3.0, 1.0], "c": [None, 200, 400, 200]},
            index=["Q", "W", "E", "R"],
        )
        psdf = ps.from_pandas(pdf)
        self.assert_eq(pdf.first_valid_index(), psdf.first_valid_index())
        self.assert_eq(pdf[[]].first_valid_index(), psdf[[]].first_valid_index())

        # MultiIndex columns
        pdf.columns = pd.MultiIndex.from_tuples([("a", "x"), ("b", "y"), ("c", "z")])
        psdf = ps.from_pandas(pdf)
        self.assert_eq(pdf.first_valid_index(), psdf.first_valid_index())

        # Empty DataFrame
        pdf = pd.Series([]).to_frame()
        psdf = ps.Series([]).to_frame()
        self.assert_eq(pdf.first_valid_index(), psdf.first_valid_index())

        pdf = pd.DataFrame(
            {"a": [None, 2, 3, 2], "b": [None, 2.0, 3.0, 1.0], "c": [None, 200, 400, 200]},
            index=[
                datetime(2021, 1, 1),
                datetime(2021, 2, 1),
                datetime(2021, 3, 1),
                datetime(2021, 4, 1),
            ],
        )
        psdf = ps.from_pandas(pdf)
        self.assert_eq(pdf.first_valid_index(), psdf.first_valid_index())

    def test_last_valid_index(self):
        pdf = pd.DataFrame(
            {"a": [1, 2, 3, None], "b": [1.0, 2.0, 3.0, None], "c": [100, 200, 400, None]},
            index=["Q", "W", "E", "R"],
        )
        psdf = ps.from_pandas(pdf)
        self.assert_eq(pdf.last_valid_index(), psdf.last_valid_index())
        self.assert_eq(pdf[[]].last_valid_index(), psdf[[]].last_valid_index())

        # MultiIndex columns
        pdf.columns = pd.MultiIndex.from_tuples([("a", "x"), ("b", "y"), ("c", "z")])
        psdf = ps.from_pandas(pdf)
        self.assert_eq(pdf.last_valid_index(), psdf.last_valid_index())

        # Empty DataFrame
        pdf = pd.Series([]).to_frame()
        psdf = ps.Series([]).to_frame()
        self.assert_eq(pdf.last_valid_index(), psdf.last_valid_index())

    def test_to_datetime(self):
        pdf = pd.DataFrame(
            {"year": [2015, 2016], "month": [2, 3], "day": [4, 5]}, index=np.random.rand(2)
        )
        psdf = ps.from_pandas(pdf)

        self.assert_eq(pd.to_datetime(pdf), ps.to_datetime(psdf))


class FrameTimeSeriesTests(
    FrameTimeSeriesMixin,
    PandasOnSparkTestCase,
    SQLTestUtils,
):
    pass


if __name__ == "__main__":
    from pyspark.testing import main

    main()