Add Expanding Primitives (#2343)

*  Add ExpandingCount, ExpandingMin, ExpandingMean, ExpandingMax, ExpandingSTD, and ExpandingTrend primitives

Author: sbadithe

docs/source/api_reference.rst

@@ -286,6 +286,12 @@ Time Series Transform Primitives
 .. autosummary::
     :toctree: generated/
 
+    ExpandingCount
+    ExpandingMax
+    ExpandingMean
+    ExpandingMin
+    ExpandingSTD
+    ExpandingTrend
     Lag
     RollingCount
     RollingMax

docs/source/release_notes.rst

@@ -6,14 +6,15 @@ Release Notes
 Future Release
 ==============
     * Enhancements
+        * Add ``ExpandingCount``, ``ExpandingMin``, ``ExpandingMean``, ``ExpandingMax``, ``ExpandingSTD``, and ``ExpandingTrend`` primitives (:pr:`2343`)
     * Fixes
     * Changes
     * Documentation Changes
     * Testing Changes
         * Fix version comparison in ``test_holiday_out_of_range`` (:pr:`2382`)
 
     Thanks to the following people for contributing to this release:
-    :user:`thehomebrewnerd`
+    :user:`sbadithe`, :user:`thehomebrewnerd`
 
 v1.18.0 Nov 15, 2022
 ====================

featuretools/primitives/standard/transform/time_series/__init__.py

@@ -23,3 +23,11 @@
 from featuretools.primitives.standard.transform.time_series.rolling_trend import (
     RollingTrend,
 )
+from featuretools.primitives.standard.transform.time_series.expanding import (
+    ExpandingCount,
+    ExpandingMax,
+    ExpandingMean,
+    ExpandingMin,
+    ExpandingSTD,
+    ExpandingTrend,
+)

featuretools/primitives/standard/transform/time_series/expanding/__init__.py

@@ -0,0 +1,18 @@
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_count import (
+    ExpandingCount,
+)
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_max import (
+    ExpandingMax,
+)
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_mean import (
+    ExpandingMean,
+)
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_min import (
+    ExpandingMin,
+)
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_std import (
+    ExpandingSTD,
+)
+from featuretools.primitives.standard.transform.time_series.expanding.expanding_trend import (
+    ExpandingTrend,
+)

featuretools/primitives/standard/transform/time_series/expanding/expanding_count.py

@@ -0,0 +1,75 @@
+import numpy as np
+from woodwork.column_schema import ColumnSchema
+from woodwork.logical_types import Datetime, IntegerNullable
+
+from featuretools.primitives.base.transform_primitive_base import TransformPrimitive
+from featuretools.primitives.standard.transform.time_series.utils import (
+    _apply_gap_for_expanding_primitives,
+)
+
+
+class ExpandingCount(TransformPrimitive):
+    """Computes the expanding count of events over a given window.
+
+    Description:
+        Given a list of datetimes, returns an expanding count starting
+        at the row `gap` rows away from the current row. An expanding
+        primitive calculates the value of a primitive for a given time
+        with all the data available up to the corresponding point in time.
+
+        Input datetimes should be monotonic.
+
+    Args:
+        gap (int, optional): Specifies a gap backwards from each instance before the
+            usable data begins. Corresponds to number of rows. Defaults to 1.
+        min_periods (int, optional): Minimum number of observations required for performing calculations
+            over the window. Defaults to 1.
+
+
+    Examples:
+        >>> import pandas as pd
+        >>> expanding_count = ExpandingCount()
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_count(times).tolist()
+        [nan, 1.0, 2.0, 3.0, 4.0]
+
+        We can also control the gap before the expanding calculation.
+
+        >>> import pandas as pd
+        >>> expanding_count = ExpandingCount(gap=0)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_count(times).tolist()
+        [1.0, 2.0, 3.0, 4.0, 5.0]
+
+        We can also control the minimum number of periods required for the rolling calculation.
+
+        >>> import pandas as pd
+        >>> expanding_count = ExpandingCount(min_periods=3)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_count(times).tolist()
+        [nan, nan, nan, 3.0, 4.0]
+    """
+
+    name = "expanding_count"
+    input_types = [ColumnSchema(logical_type=Datetime, semantic_tags={"time_index"})]
+    return_type = ColumnSchema(logical_type=IntegerNullable, semantic_tags={"numeric"})
+    uses_full_dataframe = True
+
+    def __init__(self, gap=1, min_periods=1):
+        self.gap = gap
+        self.min_periods = min_periods
+
+    def get_function(self):
+        def expanding_count(datetime_series):
+            datetime_series = _apply_gap_for_expanding_primitives(
+                datetime_series,
+                self.gap,
+            )
+            count_series = datetime_series.expanding(
+                min_periods=self.min_periods,
+            ).count()
+            num_nans = self.gap + self.min_periods - 1
+            count_series[range(num_nans)] = np.nan
+            return count_series
+
+        return expanding_count

featuretools/primitives/standard/transform/time_series/expanding/expanding_max.py

@@ -0,0 +1,71 @@
+import pandas as pd
+from woodwork.column_schema import ColumnSchema
+from woodwork.logical_types import Datetime
+
+from featuretools.primitives.base.transform_primitive_base import TransformPrimitive
+from featuretools.primitives.standard.transform.time_series.utils import (
+    _apply_gap_for_expanding_primitives,
+)
+
+
+class ExpandingMax(TransformPrimitive):
+    """Computes the expanding maximum of events over a given window.
+
+    Description:
+        Given a list of datetimes, returns an expanding maximum starting
+        at the row `gap` rows away from the current row. An expanding
+        primitive calculates the value of a primitive for a given time
+        with all the data available up to the corresponding point in time.
+
+        Input datetimes should be monotonic.
+
+    Args:
+        gap (int, optional): Specifies a gap backwards from each instance before the
+            usable data begins. Corresponds to number of rows. Defaults to 1.
+        min_periods (int, optional): Minimum number of observations required for performing calculations
+            over the window. Defaults to 1.
+
+
+    Examples:
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMax()
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [2, 4, 6, 7, 2]).tolist()
+        [nan, 2.0, 4.0, 6.0, 7.0]
+
+        We can also control the gap before the expanding calculation.
+
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMax(gap=0)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [2, 4, 6, 7, 2]).tolist()
+        [2.0, 4.0, 6.0, 7.0, 7.0]
+
+        We can also control the minimum number of periods required for the rolling calculation.
+
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMax(min_periods=3)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [2, 4, 6, 7, 2]).tolist()
+        [nan, nan, nan, 6.0, 7.0]
+    """
+
+    name = "expanding_max"
+    input_types = [
+        ColumnSchema(logical_type=Datetime, semantic_tags={"time_index"}),
+        ColumnSchema(semantic_tags={"numeric"}),
+    ]
+    return_type = ColumnSchema(semantic_tags={"numeric"})
+    uses_full_dataframe = True
+
+    def __init__(self, gap=1, min_periods=1):
+        self.gap = gap
+        self.min_periods = min_periods
+
+    def get_function(self):
+        def expanding_max(datetime, numeric):
+            x = pd.Series(numeric.values, index=datetime)
+            x = _apply_gap_for_expanding_primitives(x, self.gap)
+            return x.expanding(min_periods=self.min_periods).max().values
+
+        return expanding_max

featuretools/primitives/standard/transform/time_series/expanding/expanding_mean.py

@@ -0,0 +1,71 @@
+import pandas as pd
+from woodwork.column_schema import ColumnSchema
+from woodwork.logical_types import Datetime, Double
+
+from featuretools.primitives.base.transform_primitive_base import TransformPrimitive
+from featuretools.primitives.standard.transform.time_series.utils import (
+    _apply_gap_for_expanding_primitives,
+)
+
+
+class ExpandingMean(TransformPrimitive):
+    """Computes the expanding mean of events over a given window.
+
+    Description:
+        Given a list of datetimes, returns an expanding mean starting
+        at the row `gap` rows away from the current row. An expanding
+        primitive calculates the value of a primitive for a given time
+        with all the data available up to the corresponding point in time.
+
+        Input datetimes should be monotonic.
+
+    Args:
+        gap (int, optional): Specifies a gap backwards from each instance before the
+            usable data begins. Corresponds to number of rows. Defaults to 1.
+        min_periods (int, optional): Minimum number of observations required for performing calculations
+            over the window. Defaults to 1.
+
+
+    Examples:
+        >>> import pandas as pd
+        >>> expanding_mean = ExpandingMean()
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_mean(times, [5, 4, 3, 2, 1]).tolist()
+        [nan, 5.0, 4.5, 4.0, 3.5]
+
+        We can also control the gap before the expanding calculation.
+
+        >>> import pandas as pd
+        >>> expanding_mean = ExpandingMean(gap=0)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_mean(times, [5, 4, 3, 2, 1]).tolist()
+        [5.0, 4.5, 4.0, 3.5, 3.0]
+
+        We can also control the minimum number of periods required for the rolling calculation.
+
+        >>> import pandas as pd
+        >>> expanding_mean = ExpandingMean(min_periods=3)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_mean(times, [5, 4, 3, 2, 1]).tolist()
+        [nan, nan, nan, 4.0, 3.5]
+    """
+
+    name = "expanding_mean"
+    input_types = [
+        ColumnSchema(logical_type=Datetime, semantic_tags={"time_index"}),
+        ColumnSchema(semantic_tags={"numeric"}),
+    ]
+    return_type = ColumnSchema(logical_type=Double, semantic_tags={"numeric"})
+    uses_full_dataframe = True
+
+    def __init__(self, gap=1, min_periods=1):
+        self.gap = gap
+        self.min_periods = min_periods
+
+    def get_function(self):
+        def expanding_mean(datetime, numeric):
+            x = pd.Series(numeric.values, index=datetime)
+            x = _apply_gap_for_expanding_primitives(x, self.gap)
+            return x.expanding(min_periods=self.min_periods).mean().values
+
+        return expanding_mean

featuretools/primitives/standard/transform/time_series/expanding/expanding_min.py

@@ -0,0 +1,70 @@
+import pandas as pd
+from woodwork.column_schema import ColumnSchema
+from woodwork.logical_types import Datetime
+
+from featuretools.primitives.base.transform_primitive_base import TransformPrimitive
+from featuretools.primitives.standard.transform.time_series.utils import (
+    _apply_gap_for_expanding_primitives,
+)
+
+
+class ExpandingMin(TransformPrimitive):
+    """Computes the expanding minimum of events over a given window.
+
+    Description:
+        Given a list of datetimes, returns an expanding minimum starting
+        at the row `gap` rows away from the current row. An expanding
+        primitive calculates the value of a primitive for a given time
+        with all the data available up to the corresponding point in time.
+
+        Input datetimes should be monotonic.
+
+    Args:
+        gap (int, optional): Specifies a gap backwards from each instance before the
+            usable data begins. Corresponds to number of rows. Defaults to 1.
+        min_periods (int, optional): Minimum number of observations required for performing calculations
+            over the window. Defaults to 1.
+
+    Examples:
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMin()
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [5, 4, 3, 2, 1]).tolist()
+        [nan, 5.0, 4.0, 3.0, 2.0]
+
+        We can also control the gap before the expanding calculation.
+
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMin(gap=0)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [5, 4, 3, 2, 1]).tolist()
+        [5.0, 4.0, 3.0, 2.0, 1.0]
+
+        We can also control the minimum number of periods required for the rolling calculation.
+
+        >>> import pandas as pd
+        >>> expanding_min = ExpandingMin(min_periods=3)
+        >>> times = pd.date_range(start='2019-01-01', freq='1min', periods=5)
+        >>> expanding_min(times, [5, 4, 3, 2, 1]).tolist()
+        [nan, nan, nan, 3.0, 2.0]
+    """
+
+    name = "expanding_min"
+    input_types = [
+        ColumnSchema(logical_type=Datetime, semantic_tags={"time_index"}),
+        ColumnSchema(semantic_tags={"numeric"}),
+    ]
+    return_type = ColumnSchema(semantic_tags={"numeric"})
+    uses_full_dataframe = True
+
+    def __init__(self, gap=1, min_periods=1):
+        self.gap = gap
+        self.min_periods = min_periods
+
+    def get_function(self):
+        def expanding_min(datetime, numeric):
+            x = pd.Series(numeric.values, index=datetime)
+            x = _apply_gap_for_expanding_primitives(x, self.gap)
+            return x.expanding(min_periods=self.min_periods).min().values
+
+        return expanding_min