{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Frequently Asked Questions\n", "\n", "Here we are attempting to answer some commonly asked questions that appear on Github, and Stack Overflow." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import featuretools as ft\n", "import pandas as pd\n", "import numpy as np\n", "import woodwork as ww" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## EntitySet" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I get a list of column names and types in an `EntitySet`?\n", "\n", "After you create your `EntitySet`, you may wish to view the column names. An `EntitySet` contains multiple DataFrames, one for each table in the `EntitySet`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you want to view the underlying Dataframe, you can do the following:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es['transactions'].head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you want view the columns and types for the \"transactions\" DataFrame, you can do the following:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es['transactions'].ww" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### What is the difference between `copy_columns` and `additional_columns`?\n", "The function `normalize_dataframe` creates a new DataFrame and a relationship from unique values of an existing DataFrame. It takes 2 similar arguments:\n", "\n", "- `additional_columns` removes columns from the base DataFrame and moves them to the new DataFrame. \n", "- `copy_columns` keeps the given columns in the base DataFrame, but also copies them to the new DataFrame." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "data = ft.demo.load_mock_customer()\n", "transactions_df = data[\"transactions\"].merge(data[\"sessions\"]).merge(data[\"customers\"])\n", "products_df = data[\"products\"]\n", "\n", "es = ft.EntitySet(id=\"customer_data\")\n", "es = es.add_dataframe(dataframe_name=\"transactions\",\n", " dataframe=transactions_df,\n", " index=\"transaction_id\",\n", " time_index=\"transaction_time\")\n", "\n", "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=products_df,\n", " index=\"product_id\")\n", "\n", "es = es.add_relationship(\"products\", \"product_id\", \"transactions\", \"product_id\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before we normalize to create a new DataFrame, let's look at the base DataFrame" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es['transactions'].head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice the columns `session_id`, `session_start`, `join_date`, `device`, `customer_id`, and `zip_code`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = es.normalize_dataframe(base_dataframe_name=\"transactions\",\n", " new_dataframe_name=\"sessions\",\n", " index=\"session_id\",\n", " make_time_index=\"session_start\",\n", " additional_columns=[\"join_date\"],\n", " copy_columns=[\"device\", \"customer_id\", \"zip_code\",\"session_start\"])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Above, we normalized the columns to create a new DataFrame. \n", "\n", "- For `additional_columns`, the following column `['join_date]` will be removed from the `transactions` DataFrame, and moved to the new `sessions` DataFrame. \n", "\n", "- For `copy_columns`, the following columns `['device', 'customer_id', 'zip_code','session_start']` will be copied from the `transactions` DataFrame to the new `sessions` DataFrame. \n", "\n", "Let's see this in the actual `EntitySet`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es['transactions'].head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice above how `['device', 'customer_id', 'zip_code','session_start']` are still in the `transactions` DataFrame, while `['join_date']` is not. But, they have all been moved to the `sessions` DataFrame, as seen below." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es['sessions'].head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Why did my columns get new semantic tags?\n", "\n", "During the creation of your `EntitySet`, you might be wondering why the semantic tags in your columns change." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "data = ft.demo.load_mock_customer()\n", "transactions_df = data[\"transactions\"].merge(data[\"sessions\"]).merge(data[\"customers\"])\n", "products_df = data[\"products\"]\n", "\n", "es = ft.EntitySet(id=\"customer_data\")\n", "es = es.add_dataframe(dataframe_name=\"transactions\",\n", " dataframe=transactions_df,\n", " index=\"transaction_id\",\n", " time_index=\"transaction_time\")\n", "es.plot()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If a column contains semantic tags, they will appear on the right side of a semicolon in the plot above. Notice how `session_id` and `session_start` do not have any semantic tags currently associated to them.\n", "\n", "Now, let's normalize the transactions DataFrame to create a new DataFrame." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = es.normalize_dataframe(base_dataframe_name=\"transactions\",\n", " new_dataframe_name=\"sessions\",\n", " index=\"session_id\",\n", " make_time_index=\"session_start\",\n", " additional_columns=[\"session_start\"])\n", "es.plot()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `session_id` now has the sematic tag `foreign_key` in the `transactions` DataFrame, and `index` in the new DataFrame, `sessions`. This is the case because when we normalize the DataFrame, we create a new relationship between the `transactions` and `sessions`. There is a one to many relationship between the parent DataFrame, `sessions`, and child DataFrame, `transactions`.\n", "\n", "Therefore, `session_id` has the semantic tag `foreign_key` in `transactions` because it represents an `index` in another DataFrame. There would be a similar effect if we added another DataFrame using `add_dataframe` and `add_relationship`. \n", "\n", "In addition, when we created the new DataFrame, we set `session_start` as the `time_index`. This added the semantic tag `time_index` to the `session_start` column in the new `sessions` DataFrame because it now represents a `time_index`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I update a column's description or metadata?\n", "\n", "You can directly update the description or metadata attributes of the column schema. However, you must specifically use the column schema returned by `DataFrame.ww.columns['col_name']`, **not** `DataFrame.ww['col_name'].ww.schema`. The column schema from `DataFrame.ww.columns['col_name']` is still associated with the EntitySet and propagates any attribute updates, whereas the other does not. As an example, this is how you can update a column's description or metadata:\n", "\n", "```python\n", "column_schema = df.ww.columns['col_name']\n", "column_schema.description = 'my description'\n", "column_schema.metadata.update(key='value')\n", "```\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I combine two or more interesting values?\n", "\n", "You might want to create features that are conditioned on multiple values before they are calculated. This would require the use of `interesting_values`. However, since we are trying to create the feature with multiple conditions, we will need to modify the Dataframe before we create the `EntitySet`.\n", "\n", "Let's look at how you might accomplish this. \n", "\n", "First, let's create our Dataframes." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "data = ft.demo.load_mock_customer()\n", "transactions_df = data[\"transactions\"].merge(data[\"sessions\"]).merge(data[\"customers\"])\n", "products_df = data[\"products\"]" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "transactions_df.head()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "products_df.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now, let's modify our `transactions` Dataframe to create the additional column that represents multiple conditions for our feature." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "transactions_df['product_id_device'] = transactions_df['product_id'].astype(str) + ' and ' + transactions_df['device']" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Here, we created a new column called `product_id_device`, which just combines the `product_id` column, and the `device` column.\n", "\n", "Now let's create our `EntitySet`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.EntitySet(id=\"customer_data\")\n", "es = es.add_dataframe(dataframe_name=\"transactions\",\n", " dataframe=transactions_df,\n", " index=\"transaction_id\",\n", " time_index=\"transaction_time\",\n", " logical_types={\"product_id\": ww.logical_types.Categorical,\n", " \"product_id_device\": ww.logical_types.Categorical,\n", " \"zip_code\": ww.logical_types.PostalCode})\n", "\n", "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=products_df,\n", " index=\"product_id\")\n", "\n", "es = es.normalize_dataframe(base_dataframe_name=\"transactions\",\n", " new_dataframe_name=\"sessions\",\n", " index=\"session_id\",\n", " additional_columns=[\"device\", \"product_id_device\", \"customer_id\"])\n", "\n", "es = es.normalize_dataframe(base_dataframe_name=\"sessions\",\n", " new_dataframe_name=\"customers\",\n", " index=\"customer_id\")\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now, we are ready to add our interesting values. \n", "\n", "First, let's view our options for what the interesting values could be." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "interesting_values = transactions_df['product_id_device'].unique().tolist()\n", "interesting_values" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you wanted to, you could pick a subset of these, and the `where` features created would only use those conditions. In our example, we will use all the possible interesting values.\n", "\n", "Here, we set all of these values as our interesting values for this specific DataFrame and column. If we wanted to, we could make interesting values in the same way for more than one column, but we will just stick with this one for this example." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "values = {'product_id_device': interesting_values}\n", "es.add_interesting_values(dataframe_name='sessions', values=values)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can run DFS." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[\"count\"],\n", " where_primitives=[\"count\"],\n", " trans_primitives=[])\n", "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To better understand the `where` clause features, let's examine one of those features. \n", "The feature `COUNT(sessions WHERE product_id_device = 5 and tablet)`, tells us how many sessions the customer purchased `product_id` 5 while on a tablet. Notice how the feature depends on multiple conditions **(product_id = 5 & device = tablet)**." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix[[\"COUNT(sessions WHERE product_id_device = 5 and tablet)\"]]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Can I create an `EntitySet` using Dask or Koalas dataframes? (BETA)\n", "\n", "Support for Dask EntitySets and Koalas EntitySets is still in Beta - if you encounter any errors using either of these approaches, please let us know by creating a [new issue on Github](https://github.com/alteryx/featuretools/issues).\n", "\n", "Yes! Featuretools supports creating an `EntitySet` from Dask dataframes or from Koalas dataframes. You can simply follow the same process you would when creating an `EntitySet` from pandas dataframes.\n", "\n", "There are some limitations to be aware of when using Dask or Koalas dataframes. When creating a `DataFrame`, type inference can significantly slow down the runtime compared to pandas DataFrames, so users are encouraged to specify logical types for all columns during creation. Also, other quality checks are not performed, such as checking for unique index values. An `EntitySet` must be created entirely of one type of DataFrame (Dask, Koalas, or pandas) - you cannot mix pandas DataFrames, Dask DataFrames, and Koalas DataFrames with each other in the same `EntitySet`.\n", "\n", "For more information on creating an `EntitySet` from Dask dataframes or from Koalas dataframes, see the [Using Dask EntitySets](../guides/using_dask_entitysets.rst) and the [Using Koalas EntitySets](../guides/using_koalas_entitysets.rst) guides." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## DFS" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Why is DFS not creating aggregation features?\n", "You may have created your `EntitySet`, and then applied DFS to create features. However, you may be puzzled as to why no aggregation features were created. \n", "\n", "- **This is most likely because you have a single DataFrame in your EntitySet, and DFS is not capable of creating aggregation features with fewer than 2 DataFrames. Featuretools looks for a relationship, and aggregates based on that relationship.**\n", "\n", "Let's look at a simple example." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "data = ft.demo.load_mock_customer()\n", "transactions_df = data[\"transactions\"].merge(data[\"sessions\"]).merge(data[\"customers\"])\n", "\n", "es = ft.EntitySet(id=\"customer_data\")\n", "es = es.add_dataframe(dataframe_name=\"transactions\",\n", " dataframe=transactions_df,\n", " index=\"transaction_id\")\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how we only have 1 DataFrame in our `EntitySet`. If we try to create aggregation features on this `EntitySet`, it will not be possible because DFS needs 2 DataFrames to generate aggregation features. " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(entityset=es, target_dataframe_name=\"transactions\")\n", "feature_defs" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "None of the above features are aggregation features. To fix this issue, you can add another DataFrame to your `EntitySet`.\n", "\n", "**Solution #1 - You can add new DataFrame if you have additional data.**" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "products_df = data[\"products\"]\n", "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=products_df,\n", " index=\"product_id\")\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how we now have an additional DataFrame in our `EntitySet`, called `products`.\n", "\n", "**Solution #2 - You can normalize an existing DataFrame.**" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = es.normalize_dataframe(base_dataframe_name=\"transactions\",\n", " new_dataframe_name=\"sessions\",\n", " index=\"session_id\",\n", " make_time_index=\"session_start\",\n", " additional_columns=[\"device\", \"customer_id\", \"zip_code\", \"join_date\"],\n", " copy_columns=[\"session_start\"])\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how we now have an additional DataFrame in our `EntitySet`, called `sessions`. Here, the normalization created a relationship between `transactions` and `sessions`. However, we could have specified a relationship between `transactions` and `products` if we had only used Solution \\#1.\n", "\n", "Now, we can generate aggregation features." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(entityset=es, target_dataframe_name=\"transactions\")\n", "feature_defs[:-10]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "A few of the aggregation features are:\n", "\n", "- ``\n", "- ``\n", "- ``\n", "- ``\n", "- ``" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I speed up the runtime of DFS?\n", "\n", "One issue you may encounter while running `ft.dfs` is slow performance. While Featuretools has generally optimal default settings for calculating features, you may want to speed up performance when you are calculating on a large number of features. \n", "\n", "One quick way to speed up performance is by adjusting the `n_jobs` settings of `ft.dfs` or `ft.calculate_feature_matrix`.\n", "\n", "```python\n", "# setting n_jobs to -1 will use all cores\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " n_jobs=-1)\n", "\n", " \n", "feature_matrix, feature_defs = ft.calculate_feature_matrix(entityset=es,\n", " features=feature_defs,\n", " n_jobs=-1)\n", "```\n", "\n", "\n", "**For more ways to speed up performance, please visit:**\n", "\n", "- [Improving Computational Performance](../guides/performance.ipynb#improving-computational-performance)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I include only certain features when running DFS?\n", "\n", "When using DFS to generate features, you may wish to include only certain features. There are multiple ways that you do this:\n", "\n", "- Use `ignore_columns` to specify columns in a DataFrame that should not be used to create features. It is a dictionary mapping dataframe names to a list of column names to ignore.\n", "\n", "- Use `drop_contains` to drop features that contain any of the strings listed in this parameter.\n", "\n", "- Use `drop_exact` to drop features that exactly match any of the strings listed in this parameter.\n", "\n", "Here is an example of using all three parameters:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " ignore_columns={\n", " \"transactions\": [\"amount\"],\n", " \"customers\": [\"age\", \"gender\", \"birthday\"]\n", " }, # ignore these columns\n", " drop_contains=[\"customers.SUM(\"], # drop features that contain these strings\n", " drop_exact=[\"STD(transactions.quanity)\"]) # drop features that exactly match" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I specify primitives on a per column or per DataFrame basis?\n", "\n", "When using DFS to generate features, you may wish to use only certain features or DataFrames for specific primitives. This can be done through the `primitive_options` parameter. The `primitive_options` parameter is a dictionary that maps a primitive or a tuple of primitives to a dictionary containing options for the primitive(s). A primitive or tuple of primitives can also be mapped to a list of option dictionaries if the primitive(s) \n", "takes multiple inputs. The primitive keys can be the string names of the primitive, the primitive class, or specific instances of the primitive. Each dictionary supplies options for their respective input column. There are multiple ways to control how primitives get applied through these options:\n", "\n", "- Use `ignore_dataframes` to specify DataFrames that should not be used to create features for that primitive. It is a list of DataFrame names to ignore.\n", "\n", "- Use `include_dataframes` to specify the only DataFrames to be included to create features for that primitive. It is a list of DataFrame names to include.\n", "\n", "- Use `ignore_columns` to specify columns in a DataFrame that should not be used to create features for that primitive. It is a dictionary mapping a DataFrame name to a list of column names to ignore.\n", "\n", "- Use `include_columns` to specify the only columns in a DataFrame that should be used to create features for that primitive. It is a dictionary mapping a DataFrame name to a list of column names to include.\n", "\n", "You can also use `primitive_options` to specify which DataFrames or columns you wish to use as groupbys for groupby transformation primitives:\n", "\n", "- Use `ignore_groupby_dataframes` to specify DataFrames that should not be used to get groupbys for that primitive. It is a list of DataFrame names to ignore.\n", "\n", "- Use `include_groupby_dataframes` to specify the only DataFrames that should be used to get groupbys for that primitive. It is a list of DataFrame names to include.\n", "\n", "- Use `ignore_groupby_columns` to specify columns in a DataFrame that should not be used as groupbys for that primitive. It is a dictionary mapping a DataFrame name to a list of column names to ignore.\n", "\n", "- Use `include_groupby_columns` to specify the only columns in a DataFrame that should be used as groupbys for that primitive. It is a dictionary mapping a DataFrame name to a list of column names to include.\n", "\n", "Here is an example of using some of these options:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " primitive_options={\"mode\": {\"ignore_dataframes\": [\"sessions\"],\n", " \"ignore_columns\": {\"products\": [\"brand\"],\n", " \"transactions\": [\"product_id\"]}},\n", " # For mode, ignore the \"sessions\" DataFrame and only include \"brands\" in the\n", " # \"products\" dataframe and \"product_id\" in the \"transactions\" DataFrame\n", " (\"count\", \"mean\"): {\"include_dataframes\": [\"sessions\", \"transactions\"]}\n", " # For count and mean, only include the dataframes \"sessions\" and \"transactions\"\n", " })\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that if options are given for a specific instance of a primitive and for the primitive generally (either by string name or class), the instances with their own options will not use the generic options. For example, in this case:\n", "```\n", "special_mean = Mean()\n", "options = {\n", " special_mean: {'include_dataframes': ['customers']},\n", " 'mean': {'include_dataframes': ['sessions']}\n", "```\n", "the primitive `special_mean` will not use the DataFrame `sessions` because it's options have it only include `customers`. Every other instance of the `Mean` primitive will use the `'mean'` options. \n", "\n", "**For more examples of specifying options for DFS, please visit:**\n", "\n", "- [Specifying Primitive Options](../guides/specifying_primitive_options.rst)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### If I didn't specify the **cutoff_time**, what date will be used for the feature calculations?\n", "\n", "The cutoff time will be set to the current time using `cutoff_time = datetime.now()`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I select a certain amount of past data when calculating features?\n", "\n", "You may encounter a situation when you wish to make prediction using only a certain amount of historical data. You can accomplish this using the `training_window` parameter in `ft.dfs`. When you use the `training_window`, Featuretools will use the historical data between the `cutoff_time` and `cutoff_time - training_window`.\n", "\n", "In order to make the calculation, Featuretools will check the time in the `time_index` column of the `target_dataframe`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "es['customers'].ww.time_index" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Our target_dataframe has a `time_index`, which is needed for the `training_window` calculation. Here, we are creating a cutoff time DataFrame so that we can have a unique training window for each customer." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cutoff_times = pd.DataFrame()\n", "cutoff_times['customer_id'] = [1, 2, 3, 1]\n", "cutoff_times['time'] = pd.to_datetime(['2014-1-1 04:00', '2014-1-1 05:00', '2014-1-1 06:00', '2014-1-1 08:00'])\n", "cutoff_times['label'] = [True, True, False, True]\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " cutoff_time=cutoff_times,\n", " cutoff_time_in_index=True,\n", " training_window=\"1 hour\")\n", "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Above, we ran DFS with `training_window` argument of `1 hour` to create features that only used customer data collected in the last hour (from the cutoff time we provided)." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I apply DFS to a single table?\n", "\n", "You can run DFS on a single table. Featuretools will be able to generate features for your data, but only transform features.\n", "\n", "For example:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "transactions_df = ft.demo.load_mock_customer(return_single_table=True)\n", "\n", "es = ft.EntitySet(id=\"customer_data\")\n", "es = es.add_dataframe(dataframe_name=\"transactions\",\n", " dataframe=transactions_df,\n", " index=\"transaction_id\",\n", " time_index=\"transaction_time\")\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es, \n", " target_dataframe_name=\"transactions\", \n", " trans_primitives=['time_since', 'day', 'is_weekend', \n", " 'cum_min', 'minute', 'weekday',\n", " 'percentile', 'year', 'week',\n", " 'cum_mean'])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Before we examine the output, let's look at our original single table." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "transactions_df.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can look at the transformations that Featuretools was able to apply to this single DataFrame to create feature matrix." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I prevent label leakage with DFS?\n", "\n", "One concern you might have with using DFS is about label leakage. You want to make sure that labels in your data aren't used incorrectly to create features and the feature matrix.\n", "\n", "**Featuretools is particularly focused on helping users avoid label leakage.**\n", "\n", "There are two ways to prevent label leakage depending on if your data has timestamps or not.\n", "\n", "#### 1. Data without timestamps\n", "In the case where you do not have timestamps, you can create one `EntitySet` using only the training data and then run `ft.dfs`. This will create a feature matrix using only the training data, but also return a list of feature definitions. Next, you can create an `EntitySet` using the test data and recalculate the same features by calling `ft.calculate_feature_matrix` with the list of feature definitions from before. \n", "\n", "Here is what that flow would look like:\n", "\n", "First, let's create our training data." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "train_data = pd.DataFrame({\"customer_id\": [1, 2, 3, 4, 5],\n", " \"age\": [40, 50, 10, 20, 30],\n", " \"gender\": [\"m\", \"f\", \"m\", \"f\", \"f\"],\n", " \"signup_date\": pd.date_range('2014-01-01 01:41:50', periods=5, freq='25min'),\n", " \"labels\": [True, False, True, False, True]})\n", "train_data.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now, we can create an entityset for our training data." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es_train_data = ft.EntitySet(id=\"customer_train_data\")\n", "es_train_data = es_train_data.add_dataframe(dataframe_name=\"customers\",\n", " dataframe=train_data,\n", " index=\"customer_id\")\n", "es_train_data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Next, we are ready to create our features, and feature matrix for the training data. We don't want Featuretools to use the labels column to build new features, so we will use the ``ignore_columns`` option to exclude it. This would also remove the labels column from the feature matrix, so we will tell DFS to include it as a seed feature." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "labels_feature = ft.Feature(es_train_data['customers'].ww['labels'])\n", "feature_matrix_train, feature_defs = ft.dfs(entityset=es_train_data, \n", " target_dataframe_name=\"customers\",\n", " ignore_columns={\"customers\": [\"labels\"]},\n", " seed_features=[labels_feature])\n", "feature_matrix_train" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We will also encode our feature matrix to make machine learning compatible features. " ] }, { "cell_type": "code", "execution_count": null, "metadata": { "scrolled": true }, "outputs": [], "source": [ "feature_matrix_train_enc, features_enc = ft.encode_features(feature_matrix_train, feature_defs)\n", "feature_matrix_train_enc.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how the whole feature matrix only includes numeric and boolean values now." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can use the feature definitions to calculate our feature matrix for the test data, and avoid label leakage." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "test_train = pd.DataFrame({\"customer_id\": [6, 7, 8, 9, 10],\n", " \"age\": [20, 25, 55, 22, 35],\n", " \"gender\": [\"f\", \"m\", \"m\", \"m\", \"m\"],\n", " \"signup_date\": pd.date_range('2014-01-01 01:41:50', periods=5, freq='25min'),\n", " \"labels\": [True, False, False, True, True]})\n", "\n", "es_test_data = ft.EntitySet(id=\"customer_test_data\")\n", "es_test_data = es_test_data.add_dataframe(dataframe_name=\"customers\",\n", " dataframe=test_train,\n", " index=\"customer_id\",\n", " time_index=\"signup_date\")\n", "\n", "# Use the feature definitions from earlier\n", "feature_matrix_enc_test = ft.calculate_feature_matrix(features=features_enc, \n", " entityset=es_test_data)\n", "\n", "feature_matrix_enc_test.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Check out the [Modeling](frequently_asked_questions.ipynb#Modeling) section for an example of using the encoded matrix with sklearn." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### 2. Data with timestamps\n", "\n", "If your data has timestamps, the best way to prevent label leakage is to use a list of **cutoff times**, which specify the last point in time data is allowed to be used for each row in the resulting feature matrix. To use **cutoff times**, you need to set a time index for each time sensitive DataFrame in your entity set.\n", "\n", "> **Tip: Even if your data doesn’t have time stamps, you could add a column with dummy timestamps that can be used by Featuretools as time index.**\n", "\n", "When you call `ft.dfs`, you can provide a DataFrame of cutoff times like this:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cutoff_times = pd.DataFrame({\"customer_id\": [1, 2, 3, 4, 5],\n", " \"time\": pd.date_range('2014-01-01 01:41:50', periods=5, freq='25min')})\n", "cutoff_times.head()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "train_test_data = pd.DataFrame({\"customer_id\": [1, 2, 3, 4, 5],\n", " \"age\": [20, 25, 55, 22, 35],\n", " \"gender\": [\"f\", \"m\", \"m\", \"m\", \"m\"],\n", " \"signup_date\": pd.date_range('2010-01-01 01:41:50', periods=5, freq='25min')})\n", "\n", "es_train_test_data = ft.EntitySet(id=\"customer_train_test_data\")\n", "es_train_test_data = es_train_test_data.add_dataframe(dataframe_name=\"customers\",\n", " dataframe=train_test_data,\n", " index=\"customer_id\",\n", " time_index=\"signup_date\")\n", "\n", "feature_matrix_train_test, features = ft.dfs(entityset=es_train_test_data,\n", " target_dataframe_name=\"customers\",\n", " cutoff_time=cutoff_times,\n", " cutoff_time_in_index=True)\n", "feature_matrix_train_test.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Above, we have created a feature matrix that uses cutoff times to avoid label leakage. We could also encode this feature matrix using `ft.encode_features`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### What is the difference between passing a primitive object versus a string to DFS? \n", "\n", "There are 2 ways to pass primitives to DFS: the primitive object, or a string of the primitive name. \n", "\n", "We will use the Transform primitive called `TimeSincePrevious` to illustrate the differences.\n", "\n", "First, let's use the string of primitive name." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[],\n", " trans_primitives=[\"time_since_previous\"])\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now, let's use the primitive object." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from featuretools.primitives import TimeSincePrevious\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[],\n", " trans_primitives=[TimeSincePrevious])\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As we can see above, the feature matrix is the same.\n", "\n", "However, if we need to modify controllable parameters in the primitive, we should use the primitive object. \n", "For instance, let's make TimeSincePrevious return units of hours (the default is in seconds)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from featuretools.primitives import TimeSincePrevious\n", "\n", "time_since_previous_in_hours = TimeSincePrevious(unit='hours')\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[],\n", " trans_primitives=[time_since_previous_in_hours])\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Features" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How can I select features based on some attributes (a specific string, an explicit primitive type, a return type, a given depth)?\n", "\n", "You may wish to select a subset of your features based on some attributes. \n", "\n", "Let's say you wanted to select features that had the string `amount` in its name. You can check for this by using the `get_name` function on the feature definitions." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "\n", "feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " features_only=True)\n", "\n", "features_with_amount = []\n", "for x in feature_defs:\n", " if 'amount' in x.get_name():\n", " features_with_amount.append(x)\n", "features_with_amount[0:5]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "You might also want to only select features that are aggregation features." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from featuretools import AggregationFeature\n", "\n", "features_only_aggregations = []\n", "for x in feature_defs:\n", " if type(x) == AggregationFeature:\n", " features_only_aggregations.append(x)\n", "features_only_aggregations[0:5]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Also, you might only want to select features that are calculated at a certain depth. You can do this by using the `get_depth` function. " ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "features_only_depth_2 = []\n", "for x in feature_defs:\n", " if x.get_depth() == 2:\n", " features_only_depth_2.append(x)\n", "features_only_depth_2[0:5]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Finally, you might only want features that return a certain type. You can do this by using the `column_schema` attribute. For more information on working with column schemas, take a look at [Transitioning from Variables to Woodwork](transition_to_ft_v1.0.ipynb)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "features_only_numeric = []\n", "for x in feature_defs:\n", " if 'numeric' in x.column_schema.semantic_tags:\n", " features_only_numeric.append(x)\n", "features_only_numeric[0:5]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Once you have your specific feature list, you can use `ft.calculate_feature_matrix` to generate a feature matrix for only those features.\n", "\n", "For our example, let's use the features with only the string `amount` in its name." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix = ft.calculate_feature_matrix(entityset=es,\n", " features=features_with_amount) # change to your specific feature list\n", "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Above, notice how all the column names for our feature matrix contain the string `amount`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I create **where** features?\n", "\n", "Sometimes, you might want to create features that are conditioned on a second value before it is calculated. This extra filter is called a “where clause”. You can create these features using the using the `interesting_values` of a column.\n", "\n", "If you have categorical columns in your `EntitySet`, you can use `add_interesting_values`. This function will find interesting values for your categorical columns, which can then be used to generate “where” clauses.\n", "\n", "First, let's create our `EntitySet`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can add the interesting values for the categorical column." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es.add_interesting_values()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can run DFS with the `where_primitives` argument to define which primitives to apply with where clauses. In this case, let's use the primitive `count`. For this to work, the primitive `count` must be present in both `agg_primitives` and `where_primitives`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[\"count\"],\n", " where_primitives=[\"count\"],\n", " trans_primitives=[])\n", "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We have now created some useful features. One example of a useful feature is the `COUNT(sessions WHERE device = tablet)`. This feature tells us how many sessions a customer completed on a tablet." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix[[\"COUNT(sessions WHERE device = tablet)\"]]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Primitives" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### What is the difference between the primitive types (Transform, GroupBy Transform, & Aggregation)?\n", "\n", "You might curious to know the difference between the primitive groups.\n", "Let's review the differences between transform, groupby transform, and aggregation primitives.\n", "\n", "First, let's create a simple `EntitySet`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import pandas as pd\n", "import featuretools as ft\n", "\n", "df = pd.DataFrame({\n", " \"id\": [1, 2, 3, 4, 5, 6],\n", " \"time_index\": pd.date_range(\"1/1/2019\", periods=6, freq=\"D\"),\n", " \"group\": [\"a\", \"a\", \"a\", \"a\", \"a\", \"a\"],\n", " \"val\": [5, 1, 10, 20, 6, 23],\n", "})\n", "es = ft.EntitySet()\n", "es = es.add_dataframe(dataframe_name=\"observations\",\n", " dataframe=df,\n", " index=\"id\",\n", " time_index=\"time_index\")\n", "\n", "es = es.normalize_dataframe(base_dataframe_name=\"observations\",\n", " new_dataframe_name=\"groups\",\n", " index=\"group\")\n", "\n", "es.plot()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "After calling `normalize_dataframe`, the column \"group\" has the semantic tag \"foreign_key\" because it identifies another DataFrame. Alternatively, it could be set using the `semantic_tags` parameter when we first call `es.add_dataframe()`.\n", "\n", "#### Transform Primitive\n", "\n", "The cum_sum primitive calculates the running sum in list of numbers." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from featuretools.primitives import CumSum\n", "\n", "cum_sum = CumSum()\n", "cum_sum([1, 2, 3, 4, 5]).tolist()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If we apply it using the `trans_primitives` argument it will calculate it over the entire observations DataFrame like this:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(target_dataframe_name=\"observations\",\n", " entityset=es,\n", " agg_primitives=[],\n", " trans_primitives=[\"cum_sum\"],\n", " groupby_trans_primitives=[])\n", "\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Groupby Transform Primitive\n", "\n", "If we apply it using `groupby_trans_primitives`, then DFS will first group by any foreign key columns before applying the transform primitive. As a result, we get the cumulative sum by group." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(target_dataframe_name=\"observations\",\n", " entityset=es,\n", " agg_primitives=[],\n", " trans_primitives=[],\n", " groupby_trans_primitives=[\"cum_sum\"])\n", "\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Aggregation Primitive\n", "\n", "Finally, there is also the aggregation primitive \"sum\". If we use sum, it will calculate the sum for the group at the cutoff time for each row. Because we didn't specify a cutoff time it will use all the data for each group for each row." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(target_dataframe_name=\"observations\",\n", " entityset=es,\n", " agg_primitives=[\"sum\"],\n", " trans_primitives=[],\n", " cutoff_time_in_index=True,\n", " groupby_trans_primitives=[])\n", "\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If we set the cutoff time of each row to be the time index, then use sum as an aggregation primitive, the result is the same as cum_sum. (Though the order is different in the displayed dataframe)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cutoff_time = df[[\"id\", \"time_index\"]]\n", "cutoff_time" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix, feature_defs = ft.dfs(target_dataframe_name=\"observations\",\n", " entityset=es,\n", " agg_primitives=[\"sum\"],\n", " trans_primitives=[],\n", " groupby_trans_primitives=[],\n", " cutoff_time_in_index=True,\n", " cutoff_time=cutoff_time)\n", "\n", "feature_matrix" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I get a list of all Aggregation and Transform primitives?\n", "\n", "You can do `featuretools.list_primitives()` to get all the primitive in Featuretools. It will return a DataFrame with the names, type, and description of the primitives, and if the primitive can be used with entitysets created from Dask dataframes. You can also visit [primitives.featurelabs.com](https://primitives.featurelabs.com/) to obtain a list of all available primitives." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "df_primitives = ft.list_primitives()\n", "df_primitives.head()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "df_primitives.tail()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### What primitives can I use when creating a feature matrix from a Dask `EntitySet`? (BETA)\n", "\n", "Support for Dask EntitySets is still in Beta - if you encounter any errors using this approach, please let us know by creating a [new issue on Github](https://github.com/alteryx/featuretools/issues).\n", "\n", "When creating a feature matrix from a Dask `EntitySet`, only certain primitives can be used. Computation of certain features is quite expensive in a distributed environment, and as a result only a subset of Featuretools primitives are currently supported when using a Dask `EntitySet`.\n", "\n", "The table returned by `featuretools.list_primitives()` will contain a column labeled `dask_compatible`. Any primitive that has a value of `True` in this column can be used safely when computing a feature matrix from a Dask `EntitySet`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How do I change the units for a TimeSince primitive?\n", "There are a few primitives in Featuretools that make some time-based calculation. These include `TimeSince, TimeSincePrevious, TimeSinceLast, TimeSinceFirst`. \n", "\n", "You can change the units from the default seconds to any valid time unit, by doing the following:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from featuretools.primitives import TimeSince, TimeSincePrevious, TimeSinceLast, TimeSinceFirst\n", "\n", "time_since = TimeSince(unit=\"minutes\")\n", "time_since_previous = TimeSincePrevious(unit=\"hours\")\n", "time_since_last = TimeSinceLast(unit=\"days\")\n", "time_since_first = TimeSinceFirst(unit=\"years\")\n", "\n", "es = ft.demo.load_mock_customer(return_entityset=True)\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " agg_primitives=[time_since_last, time_since_first],\n", " trans_primitives=[time_since, time_since_previous])" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Above, we changed the units to the following:\n", "- minutes for `TimeSince`\n", "- hours for `TimeSincePrevious`\n", "- days for `TimeSinceLast`\n", "- years for `TimeSinceFirst`.\n", "\n", "\n", "Now we can see that our feature matrix contains multiple features where the units for the TimeSince primitives are changed." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "There are now features where time unit is different from the default of seconds, such as `TIME_SINCE_LAST(sessions.session_start, unit=days)`, and `TIME_SINCE_FIRST(sessions.session_start, unit=years)`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Modeling" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How does my train & test data work with Featuretools and sklearn's **train_test_split**?\n", "\n", "You might be wondering how to properly use your train & test data with Featuretools, and sklearn's **train_test_split**. There are a few things you must do to ensure accuracy with this workflow.\n", "\n", "Let's imagine we have a Dataframes for our train data, with the labels." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "train_data = pd.DataFrame({\"customer_id\": [1, 2, 3, 4, 5],\n", " \"age\": [20, 25, 55, 22, 35],\n", " \"gender\": [\"f\", \"m\", \"m\", \"m\", \"m\"],\n", " \"signup_date\": pd.date_range('2010-01-01 01:41:50', periods=5, freq='25min'),\n", " \"labels\": [False, True, True, False, False]})\n", "train_data.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can create our `EntitySet` for the train data, and create our features. To prevent label leakage, we will use cutoff times (see [earlier question](#How-do-I-prevent-label-leakage-with-DFS?))." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es_train_data = ft.EntitySet(id=\"customer_data\")\n", "es_train_data = es_train_data.add_dataframe(dataframe_name=\"customers\",\n", " dataframe=train_data,\n", " index=\"customer_id\")\n", "\n", "cutoff_times = pd.DataFrame({\"customer_id\": [1, 2, 3, 4, 5],\n", " \"time\": pd.date_range('2014-01-01 01:41:50', periods=5, freq='25min')})\n", "\n", "feature_matrix_train, features = ft.dfs(entityset=es_train_data,\n", " target_dataframe_name=\"customers\",\n", " cutoff_time=cutoff_times,\n", " cutoff_time_in_index=True)\n", "feature_matrix_train.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We will also encode our feature matrix to compatible for machine learning algorithms." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix_train_enc, feature_enc = ft.encode_features(feature_matrix_train, features)\n", "feature_matrix_train_enc.head()" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from sklearn.model_selection import train_test_split\n", "\n", "X = feature_matrix_train_enc.drop(['labels'], axis=1)\n", "y = feature_matrix_train_enc['labels']\n", "\n", "X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.25)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now you can use the encoded feature matrix with sklearn's **train_test_split**. This will allow you to train your model, and tune your parameters." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### How are categorical columns encoded when splitting training and testing data?\n", "\n", "You might be wondering what happens when categorical columns are encoded with your training and testing data. You might be curious to know what happens if the train data has a categorical column that is not present in the testing data. \n", "\n", "Let's explore a simple example to see what happens during the encoding process." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "train_data = pd.DataFrame({\n", " \"customer_id\": [1, 2, 3, 4, 5],\n", " \"product_purchased\": [\"coke zero\", \"car\", \"toothpaste\", \"coke zero\", \"car\"],\n", "})\n", "es_train = ft.EntitySet(id=\"customer_data\")\n", "es_train = es_train.add_dataframe(\n", " dataframe_name=\"customers\",\n", " dataframe=train_data,\n", " index=\"customer_id\",\n", " logical_types={'product_purchased': ww.logical_types.Categorical},\n", ")\n", "feature_matrix_train, features = ft.dfs(entityset=es_train, target_dataframe_name='customers')\n", "feature_matrix_train" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "We will use `ft.encode_features` to properly encode the `product_purchased` column." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "feature_matrix_train_encoded, features_encoded = ft.encode_features(feature_matrix_train,\n", " features)\n", "feature_matrix_train_encoded.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now lets imagine we have some test data that has doesn't have one of the categorical values (**toothpaste**). Also, the test data has a value that wasn't present in the train data (**water**)." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "test_data = pd.DataFrame({\"customer_id\": [6, 7, 8, 9, 10],\n", " \"product_purchased\": [\"coke zero\", \"car\", \"coke zero\", \"coke zero\", \"water\"]})\n", "\n", "es_test = ft.EntitySet(id=\"customer_data\")\n", "es_test = es_test.add_dataframe(dataframe_name=\"customers\",\n", " dataframe=test_data,\n", " index=\"customer_id\")\n", "\n", "feature_matrix_test = ft.calculate_feature_matrix(entityset=es_test,\n", " features=features_encoded)\n", "feature_matrix_test.head()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As seen above, we were able to successfully handle the encoding, and deal with the following complications: \n", "- **toothpaste** was present in the training data but not present in the testing data \n", "- **water** was present in the test data but not present in the training data. " ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Errors & Warnings" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Why am I getting this error 'Index is not unique on dataframe'?\n", "You may be trying to create your `EntitySet`, and run into this error. \n", "```python\n", "IndexError: Index column must be unique\n", "```\n", "**This is because each dataframe in your EntitySet needs a unique index.**\n", "\n", "Let's look at a simple example." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "product_df = pd.DataFrame({'id': [1, 2, 3, 4, 4],\n", " 'rating': [3.5, 4.0, 4.5, 1.5, 5.0]})\n", "product_df" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how the `id` column has a duplicate index of `4`. If you try to add this dataframe to the EntitySet, you will run into the following error." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```python\n", "es = ft.EntitySet(id=\"product_data\")\n", "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=product_df,\n", " index=\"id\")\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "```\n", "---------------------------------------------------------------------------\n", "IndexError Traceback (most recent call last)\n", " in \n", " 1 es = ft.EntitySet(id=\"product_data\")\n", "----> 2 es = es.add_dataframe(dataframe_name=\"products\",\n", " 3 dataframe=product_df,\n", " 4 index=\"id\")\n", "\n", "~/Code/featuretools/featuretools/entityset/entityset.py in add_dataframe(self, dataframe, dataframe_name, index, logical_types, semantic_tags, make_index, time_index, secondary_time_index, already_sorted)\n", " 625 index_was_created, index, dataframe = _get_or_create_index(index, make_index, dataframe)\n", " 626 \n", "--> 627 dataframe.ww.init(name=dataframe_name,\n", " 628 index=index,\n", " 629 time_index=time_index,\n", "\n", "/usr/local/Caskroom/miniconda/base/envs/featuretools/lib/python3.8/site-packages/woodwork/table_accessor.py in init(self, index, time_index, logical_types, already_sorted, schema, validate, use_standard_tags, **kwargs)\n", " 94 \"\"\"\n", " 95 if validate:\n", "---> 96 _validate_accessor_params(self._dataframe, index, time_index, logical_types, schema, use_standard_tags)\n", " 97 if schema is not None:\n", " 98 self._schema = schema\n", "\n", "/usr/local/Caskroom/miniconda/base/envs/featuretools/lib/python3.8/site-packages/woodwork/table_accessor.py in _validate_accessor_params(dataframe, index, time_index, logical_types, schema, use_standard_tags)\n", " 877 # We ignore these parameters if a schema is passed\n", " 878 if index is not None:\n", "--> 879 _check_index(dataframe, index)\n", " 880 if logical_types:\n", " 881 _check_logical_types(dataframe.columns, logical_types)\n", "\n", "/usr/local/Caskroom/miniconda/base/envs/featuretools/lib/python3.8/site-packages/woodwork/table_accessor.py in _check_index(dataframe, index)\n", " 903 # User specifies an index that is in the dataframe but not unique\n", " 904 # Does not check for Dask as Dask does not support is_unique\n", "--> 905 raise IndexError('Index column must be unique')\n", " 906 \n", " 907 \n", "\n", "IndexError: Index column must be unique\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "To fix the above error, you can do one of the following solutions:\n", "\n", "**Solution #1 - You can create a unique index on your Dataframe.**" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "product_df = pd.DataFrame({'id': [1, 2, 3, 4, 5],\n", " 'rating': [3.5, 4.0, 4.5, 1.5, 5.0]})\n", "product_df" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Notice how we now have a unique index column called `id`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=product_df,\n", " index=\"id\")\n", "es" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As seen above, we can now create our DataFrame for our `EntitySet` without an error by creating a unique index in our Dataframe.\n", "\n", "**Solution #2 - Set make_index to True in your call to add_dataframe to create a new index on that data**\n", "- `make_index` creates a unique index for each row by just looking at what number the row is, in relation to all the other rows." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "product_df = pd.DataFrame({'id': [1, 2, 3, 4, 4],\n", " 'rating': [3.5, 4.0, 4.5, 1.5, 5.0]})\n", "\n", "es = ft.EntitySet(id=\"product_data\")\n", "es = es.add_dataframe(dataframe_name=\"products\",\n", " dataframe=product_df,\n", " index=\"product_id\",\n", " make_index=True)\n", "\n", "es['products']" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As seen above, we created our dataframe for our `EntitySet` without an error using the `make_index` argument." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Why am I getting the following warning 'Using training_window but last_time_index is not set'?\n", "\n", "If you are using a training window, and you haven't set a `last_time_index` for your dataframe, you will get this warning.\n", "The training window attribute in Featuretools limits the amount of past data that can be used while calculating a particular feature vector.\n", "\n", "You can add the `last_time_index` to all dataframes automatically by calling `your_entityset.add_last_time_indexes()` after you create your `EntitySet`. This will remove the warning." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "es = ft.demo.load_mock_customer(return_entityset=True)\n", "es.add_last_time_indexes()" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now we can run DFS without getting the warning." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "cutoff_times = pd.DataFrame()\n", "cutoff_times['customer_id'] = [1, 2, 3, 1]\n", "cutoff_times['time'] = pd.to_datetime(['2014-1-1 04:00', '2014-1-1 05:00', '2014-1-1 06:00', '2014-1-1 08:00'])\n", "cutoff_times['label'] = [True, True, False, True]\n", "\n", "feature_matrix, feature_defs = ft.dfs(entityset=es,\n", " target_dataframe_name=\"customers\",\n", " cutoff_time=cutoff_times,\n", " cutoff_time_in_index=True,\n", " training_window=\"1 hour\")" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### last_time_index vs. time_index\n", "\n", "- The `time_index` is when the instance was first known.\n", "- The `last_time_index` is when the instance appears for the last time.\n", "- For example, a customer’s session has multiple transactions which can happen at different points in time. If we are trying to count the number of sessions a user has in a given time period, we often want to count all the sessions that had any transaction during the training window. To accomplish this, we need to not only know when a session starts (**time_index**), but also when it ends (**last_time_index**). The last time that an instance appears in the data is stored as the `last_time_index` of a dataframe. \n", "- Once the last_time_index has been set, Featuretools will check to see if the last_time_index is after the start of the training window. That, combined with the cutoff time, allows DFS to discover which data is relevant for a given training window." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Why am I getting errors with Featuretools on [Google Colab](https://colab.research.google.com/)?\n", "\n", "[Google Colab](https://colab.research.google.com/), by default, has Featuretools `0.4.1` installed. You may run into issues following our newest guides, or latest documentation while using an older version of Featuretools. Therefore, we suggest you upgrade to the latest featuretools version by doing the following in your notebook in Google Colab:\n", "```shell\n", "!pip install -U featuretools\n", "```\n", "\n", "You may need to Restart the runtime by doing **Runtime** -> **Restart Runtime**.\n", "You can check latest Featuretools version by doing following:\n", "```python\n", "import featuretools as ft\n", "print(ft.__version__)\n", "```\n", "You should see a version greater than `0.4.1`" ] } ], "metadata": { "file_extension": ".py", "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.8.2" }, "mimetype": "text/x-python", "name": "python", "npconvert_exporter": "python", "pygments_lexer": "ipython3", "version": 3 }, "nbformat": 4, "nbformat_minor": 2 }