Feature primitives

Feature primitives are the building blocks of Featuretools. They define individual computations that can be applied to raw datasets to create new features. Because a primitive only constrains the input and output data types, they can be applied across datasets and can stack to create new calculations.

Why primitives?

The space of potential functions that humans use to create a feature is expansive. By breaking common feature engineering calculations down into primitive components, we are able to capture the underlying structure of the features humans create today.

A primitive only constrains the input and output data types. This means they can be used to transfer calculations known in one domain to another. Consider a feature which is often calculated by data scientists for transactional or event logs data: average time between events. This feature is incredibly valuable in predicting fraudulent behavior or future customer engagement.

DFS achieves the same feature by stacking two primitives "time_since_previous" and "mean"

In [1]: feature_defs = ft.dfs(entityset=es,
   ...:                       target_entity="customers",
   ...:                       agg_primitives=["mean"],
   ...:                       trans_primitives=["time_since_previous"],
   ...:                       features_only=True)
   ...: 

In [2]: feature_defs
Out[2]: 
[<Feature: zip_code>,
 <Feature: MEAN(transactions.amount)>,
 <Feature: MEAN(sessions.time_since_previous_by_customer_id)>,
 <Feature: MEAN(sessions.MEAN(transactions.amount))>]

Note

When dfs is called with features_only=True, only feature definitions are returned as output. By default this parameter is set to False. This parameter is used quickly inspect the feature definitions before the spending time calculating the feature matrix.

A second advantage of primitives is that they can be used to quickly enumerate many interesting features in a parameterized way. This is used by Deep Feature Synthesis to get several different ways of summarizing the time since the previous event.

In [3]: feature_matrix, feature_defs = ft.dfs(entityset=es,
   ...:                                       target_entity="customers",
   ...:                                       agg_primitives=["mean", "max", "min", "std", "skew"],
   ...:                                       trans_primitives=["time_since_previous"])
   ...: 

In [4]: feature_matrix[["MEAN(sessions.time_since_previous_by_customer_id)",
   ...:                 "MAX(sessions.time_since_previous_by_customer_id)",
   ...:                 "MIN(sessions.time_since_previous_by_customer_id)",
   ...:                 "STD(sessions.time_since_previous_by_customer_id)",
   ...:                 "SKEW(sessions.time_since_previous_by_customer_id)"]]
   ...: 
Out[4]: 
             MEAN(sessions.time_since_previous_by_customer_id)  MAX(sessions.time_since_previous_by_customer_id)  MIN(sessions.time_since_previous_by_customer_id)  STD(sessions.time_since_previous_by_customer_id)  SKEW(sessions.time_since_previous_by_customer_id)
customer_id                                                                                                                                                                                                                                                            
1                                                  3502.777778                                            7670.0                                            1040.0                                       1849.029943                                                NaN
2                                                  2655.714286                                            7085.0                                             910.0                                       2167.930924                                                NaN
3                                                  6971.250000                                           11245.0                                            1430.0                                       4260.940881                                                NaN
4                                                  2405.000000                                            7605.0                                             910.0                                       2213.274884                                                NaN
5                                                  9316.666667                                           15860.0                                            3705.0                                       5005.797195                                                NaN

Aggregation vs Transform Primitive

In the example above, we use two types of primitives.

Aggregation primitives: These primitives take related instances as an input and output a single value. They are applied across a parent-child relationship in an entity set. E.g: "count", "sum", "avg_time_between".

Transform primitives: These primitives take one or more variables from an entity as an input and output a new variable for that entity. They are applied to a single entity. E.g: "hour", "time_since_previous", "absolute".

For a DataFrame that lists and describes each built-in primitive in Featuretools, call ft.list_primitives().

In [5]: ft.list_primitives().head(5)
Out[5]: 
            name         type                                        description
0          count  aggregation              Counts the number of non null values.
1            std  aggregation  Finds the standard deviation of a numeric feat...
2            all  aggregation                     Test if all values are 'True'.
3           last  aggregation                            Returns the last value.
4  n_most_common  aggregation  Finds the N most common elements in a categori...

Defining Custom Primitives

The library of primitives in Featuretools is constantly expanding. Users can define their own primitive using the APIs below. To define a primitive, a user will

  • Specify the type of primitive Aggregation or Transform
  • Define the input and output data types
  • Write a function in python to do the calculation
  • Annotate with attributes to constrain how it is applied

Once a primitive is defined, it can stack with existing primitives to generate complex patterns. This enables primitives known to be important for one domain to automatically be transfered to another.

Simple Custom Primitives

In [6]: from featuretools.primitives import make_agg_primitive, make_trans_primitive

In [7]: from featuretools.variable_types import Text, Numeric

In [8]: def absolute(column):
   ...:     return abs(column)
   ...: 

In [9]: Absolute = make_trans_primitive(function=absolute,
   ...:                                 input_types=[Numeric],
   ...:                                 return_type=Numeric)
   ...: 

Above we created a new transform primitive that can be used with Deep Feature Synthesis using make_trans_primitive and a python function we defined. Additionally, we annotated the input data types that the primitive can be applied to and the data type it returns.

Similarly, we can make a new aggregation primitive using make_agg_primitive.

In [10]: def maximum(column):
   ....:     return max(column)
   ....: 

In [11]: Maximum = make_agg_primitive(function=maximum,
   ....:                           input_types=[Numeric],
   ....:                           return_type=Numeric)
   ....: 

Because we defined an aggregation primitive, the function takes in a list of values but only returns one.

Now that we’ve defined two primitives, we can use them with the dfs function as if they were built-in primitives.

In [12]: feature_matrix, feature_defs = ft.dfs(entityset=es,
   ....:                                       target_entity="sessions",
   ....:                                       agg_primitives=[Maximum],
   ....:                                       trans_primitives=[Absolute],
   ....:                                       max_depth=2)
   ....: 

In [13]: feature_matrix[["customers.MAXIMUM(transactions.amount)", "MAXIMUM(transactions.ABSOLUTE(amount))"]].head(5)
Out[13]: 
            customers.MAXIMUM(transactions.amount)  MAXIMUM(transactions.ABSOLUTE(amount))
session_id                                                                                
1                                           149.95                                  147.23
2                                           149.95                                  148.14
3                                           148.17                                  141.66
4                                           147.73                                  147.73
5                                           149.15                                  124.29

Word Count Example

Here we define a function, word_count, which counts the number of words in each row of an input and returns a list of the counts.

In [14]: def word_count(column):
   ....:     '''
   ....:     Counts the number of words in each row of the column. Returns a list
   ....:     of the counts for each row.
   ....:     '''
   ....:     word_counts = []
   ....:     for value in column:
   ....:         words = value.split(None)
   ....:         word_counts.append(len(words))
   ....:     return word_counts
   ....: 

Next, we need to create a custom primitive from the word_count function.

In [15]: WordCount = make_trans_primitive(function=word_count,
   ....:                                  input_types=[Text],
   ....:                                  return_type=Numeric)
   ....: 

Since WordCount is a transform primitive, we need to add it to the list of transform primitives DFS can use when generating features.

In [16]: feature_matrix, features = ft.dfs(entityset=es,
   ....:                                   target_entity="sessions",
   ....:                                   agg_primitives=["sum", "mean", "std"],
   ....:                                   trans_primitives=[WordCount])
   ....: 

In [17]: feature_matrix[["customers.WORD_COUNT(favorite_quote)", "STD(log.WORD_COUNT(comments))", "SUM(log.WORD_COUNT(comments))", "MEAN(log.WORD_COUNT(comments))"]]
Out[17]: 
    customers.WORD_COUNT(favorite_quote)  STD(log.WORD_COUNT(comments))  SUM(log.WORD_COUNT(comments))  MEAN(log.WORD_COUNT(comments))
id                                                                                                                                    
0                                      9                     483.381423                           2500                             500
1                                      9                     505.501236                           1732                             433
2                                      9                       0.000000                            246                             246
3                                      6                     625.000000                           1256                             628
4                                      6                       0.000000                              9                               3
5                                     12                      14.000000                             68                              34

By adding some aggregation primitives as well, Deep Feature Synthesis was able to make four new features from one new primitive.

Multiple Input Types

If a primitive requires multiple features as input, input_types has multiple elements, eg [Numeric, Numeric] would mean the primitive requires two Numeric features as input. Below is an example of a primitive that has multiple input features.

In [18]: from featuretools.variable_types import Datetime, Timedelta, Variable

In [19]: import pandas as pd

In [20]: def mean_sunday(numeric, datetime):
   ....:     '''
   ....:     Finds the mean of non-null values of a feature that occurred on Sundays
   ....:     '''
   ....:     days = pd.DatetimeIndex(datetime).weekday.values
   ....:     df = pd.DataFrame({'numeric': numeric, 'time': days})
   ....:     return df[df['time'] == 6]['numeric'].mean()
   ....: 

In [21]: MeanSunday = make_agg_primitive(function=mean_sunday,
   ....:                                  input_types=[Numeric, Datetime],
   ....:                                  return_type=Numeric)
   ....: 

In [22]: feature_matrix, features = ft.dfs(entityset=es,
   ....:                                   target_entity="sessions",
   ....:                                   agg_primitives=[MeanSunday],
   ....:                                   trans_primitives=[],
   ....:                                   max_depth=1)
   ....: 

In [23]: feature_matrix[["MEAN_SUNDAY(log.value, datetime)", "MEAN_SUNDAY(log.value_2, datetime)"]]
Out[23]: 
    MEAN_SUNDAY(log.value, datetime)  MEAN_SUNDAY(log.value_2, datetime)
id                                                                      
0                                NaN                                 NaN
1                                NaN                                 NaN
2                                NaN                                 NaN
3                                2.5                                 1.0
4                                7.0                                 3.0
5                                NaN                                 NaN