6. Formulate Use Case

Why Create a Use Case?¶

Creating a Use Case in FeatureByte, while optional, offers significant benefits. It not only defines the goal and application of your prediction model but also helps organize your training data and improve post-deployment feature monitoring.

Plus, for FeatureByte Enterprise users, it's used by FeatureByte Copilot to suggest features tailored to your use cases.

We'll create one Use Case for our Grocery Dataset: In-Store Prediction of Customer Spending on a given Product Group next 2 Weeks.

We will first establish a Target, define a Context and then link the Use Case with the Context and Target.

In [1]:

import featurebyte as fb

# Set your profile to the tutorial environment
fb.use_profile("tutorial")

catalog_name = "Grocery Dataset Tutorial"
catalog = fb.Catalog.activate(catalog_name)

import featurebyte as fb # Set your profile to the tutorial environment fb.use_profile("tutorial") catalog_name = "Grocery Dataset Tutorial" catalog = fb.Catalog.activate(catalog_name)

10:43:22 | WARNING  | Service endpoint is inaccessible: http://featurebyte-server:8088/
10:43:22 | INFO     | Using profile: tutorial
10:43:22 | INFO     | Using configuration file at: /Users/gxav/.featurebyte/config.yaml
10:43:22 | INFO     | Active profile: tutorial (https://tutorials.featurebyte.com/api/v1)
10:43:23 | INFO     | SDK version: 2.0.1.dev67
10:43:23 | INFO     | No catalog activated.
10:43:23 | INFO     | Catalog activated: Grocery Dataset Tutorial
16:06:14 | INFO     | Using configuration file at: /Users/gxav/.featurebyte/config.yaml
16:06:14 | INFO     | Active profile: tutorial (https://tutorials.featurebyte.com/api/v1)
16:06:14 | WARNING  | Remote SDK version (1.1.0.dev7) is different from local (1.1.0.dev1). Update local SDK to avoid unexpected behavior.
16:06:14 | INFO     | No catalog activated.
16:06:14 | INFO     | Catalog activated: Grocery Dataset Tutorial

Creating a Target¶

We will work with INVOICEITEMS which is the table indicating the details of each invoice. For convenience, "GroceryCustomerGuid", representing the customer entity, is already added to the view of INVOICEITEMS. We will also join "GROCERYPRODUCT" to populate the "ProductGroup" column representing the productgroup entity.

In [2]:

# Get view from GROCERYPRODUCT dimension table.
groceryproduct_view = catalog.get_view("GROCERYPRODUCT")
# Get view from INVOICEITEMS item table.
invoiceitems_view = catalog.get_view("INVOICEITEMS")
# Join GROCERYPRODUCT view to INVOICEITEMS view.
invoiceitems_view = invoiceitems_view.join(groceryproduct_view, rsuffix="")

# Get view from GROCERYPRODUCT dimension table. groceryproduct_view = catalog.get_view("GROCERYPRODUCT") # Get view from INVOICEITEMS item table. invoiceitems_view = catalog.get_view("INVOICEITEMS") # Join GROCERYPRODUCT view to INVOICEITEMS view. invoiceitems_view = invoiceitems_view.join(groceryproduct_view, rsuffix="")

The target is a sum of the TotalCost column in next 14d per customer (GroceryCustomerGuid) and productgroup (ProductGroup).

In [3]:

target = invoiceitems_view\
    .groupby(['GroceryCustomerGuid', 'ProductGroup'])\
    .forward_aggregate(
        "TotalCost", method="sum",
        target_name="CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks",
        window='14d',
        fill_value=0
    )

target = invoiceitems_view\ .groupby(['GroceryCustomerGuid', 'ProductGroup'])\ .forward_aggregate( "TotalCost", method="sum", target_name="CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks", window='14d', fill_value=0 )

In order for a target (or a feature) to be recorded in catalog, we need to save it:

In [4]:

target.save()

target.save()

Also we will update description of the target.

In [5]:

target.update_description(
    "Sum of Total spent by the customer for a given product group over the next 14d period."
)

target.update_description( "Sum of Total spent by the customer for a given product group over the next 14d period." )

Target is created. We can check target's definition file, which provides explicit outline of all operations for declaration of the target. For example this definition includes implicit operations like all cleaning operations inherited from the table.

In [6]:

target.definition

target.definition

Out[6]:

# Generated by SDK version: 2.0.1.dev119
from bson import ObjectId
from featurebyte import DimensionTable
from featurebyte import ItemTable


# item_table name: "INVOICEITEMS", event_table name: "GROCERYINVOICE"
item_table = ItemTable.get_by_id(ObjectId("676235f7375a850179e42f8e"))
item_view = item_table.get_view(
    event_suffix=None,
    view_mode="manual",
    drop_column_names=["record_available_at"],
    column_cleaning_operations=[],
    event_drop_column_names=["record_available_at"],
    event_column_cleaning_operations=[],
    event_join_column_names=["Timestamp", "GroceryCustomerGuid", "tz_offset"],
)

# dimension_table name: "GROCERYPRODUCT"
dimension_table = DimensionTable.get_by_id(ObjectId("676235f9375a850179e42f8f"))
dimension_view = dimension_table.get_view(
    view_mode="manual", drop_column_names=[], column_cleaning_operations=[]
)
joined_view = item_view.join(
    dimension_view, on="GroceryProductGuid", how="left", rsuffix="", rprefix=""
)
target = joined_view.groupby(
    by_keys=["GroceryCustomerGuid", "ProductGroup"], category=None
).forward_aggregate(
    value_column="TotalCost",
    method="sum",
    window="14d",
    target_name="CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks",
    skip_fill_na=True,
    offset=None,
)
target_1 = target.copy()
target_1[target.isnull()] = 0
target_1.name = "CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks"
output = target_1
output.save(_id=ObjectId("676236cc1572fa7b62bc8fb7"))

Creating a Context¶

A Context defines the scope and circumstances in which features are expected to be served.

Let's describe the Context for our use case:

• Context Name: In-Store Customer Engagement with ProductGroup
• Primary Entity: customer, productgroup
• Description: Evaluate future customer engagement with ProductGroup during its visit in the store to improve its shopping experience.

In [7]:

fb.Context.create(
    name="In-Store Customer Engagement with ProductGroup",
    primary_entity=["customer", "productgroup"],
    description="Evaluate future customer engagement with ProductGroup during its visit in the store to improve its shopping experience."
)

fb.Context.create( name="In-Store Customer Engagement with ProductGroup", primary_entity=["customer", "productgroup"], description="Evaluate future customer engagement with ProductGroup during its visit in the store to improve its shopping experience." )

Out[7]:

Context

name	In-Store Customer Engagement with ProductGroup
created_at	2024-12-18 02:43:25
updated_at	None
description	Evaluate future customer engagement with ProductGroup during its visit in the store to improve its shopping experience.
author	None
primary_entities	name serving_names catalog_name 0 productgroup [PRODUCTGROUP] Grocery Dataset Tutorial 1 customer [GROCERYCUSTOMERGUID] Grocery Dataset Tutorial
default_eda_table	None
default_preview_table	None
associated_use_cases	[]

Creating a Use Case¶

Let's link our Use Case with the Context and Target.

In [8]:

fb.UseCase.create(
    name="In-Store Prediction of Customer Spending on a given Product Group next 2 Weeks",
    context_name="In-Store Customer Engagement with ProductGroup",
    target_name="CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks",
    description="Predict the expenditure of customer on a specific product group within a two-week period starting from the time of its visit in the store. This use case will help improve customer shopping experience."
)

fb.UseCase.create( name="In-Store Prediction of Customer Spending on a given Product Group next 2 Weeks", context_name="In-Store Customer Engagement with ProductGroup", target_name="CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks", description="Predict the expenditure of customer on a specific product group within a two-week period starting from the time of its visit in the store. This use case will help improve customer shopping experience." )

Out[8]:

Use Case

name	In-Store Prediction of Customer Spending on a given Product Group next 2 Weeks
created_at	2024-12-18 02:43:25
updated_at	None
description	Predict the expenditure of customer on a specific product group within a two-week period starting from the time of its visit in the store. This use case will help improve customer shopping experience.
author	None
primary_entities	name serving_names catalog_name 0 productgroup [PRODUCTGROUP] Grocery Dataset Tutorial 1 customer [GROCERYCUSTOMERGUID] Grocery Dataset Tutorial
context_name	In-Store Customer Engagement with ProductGroup
target_name	CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_2_weeks
default_eda_table	None
default_preview_table	None

Listing targets, contexts and use cases in the catalog¶

In [9]:

catalog.list_targets()

catalog.list_targets()

Out[9]:

	id	name	dtype	entities	created_at
0	676236cc1572fa7b62bc8fb7	CUSTOMER_x_PRODUCTGROUP_Sum_of_TotalCost_next_...	FLOAT	[customer, productgroup]	2024-12-18T02:43:24.605000

In [10]:

catalog.list_contexts()

catalog.list_contexts()

Out[10]:

	id	name	primary_entity_ids	description
0	676236cc1572fa7b62bc8fb9	In-Store Customer Engagement with ProductGroup	[67623636619b916027485d94, 67623637619b9160274...	Evaluate future customer engagement with Produ...

In [11]:

catalog.list_use_cases()

catalog.list_use_cases()

Out[11]:

	id	name	default_preview_table_name	default_eda_table_name	description
0	676236cd1572fa7b62bc8fbb	In-Store Prediction of Customer Spending on a ...	[]	[]	Predict the expenditure of customer on a speci...

Concepts discussed in this tutorial¶

• More about feature definition file

SDK reference for¶

• Target
• Context
• Use Case
• View.groupby()
• GroupBy.forward_aggregate()
• Aggregation functions
• Target.definition