Using Label Transforms

In this guide, we will demonstrate how to use the transforms that are available on LabelTimes. Each transform will return a copy of the label times. This is useful for trying out multiple transforms in different settings without having to recalculate the labels. As a result, we could see which labels give a better performance in less time.

Generate Labels

Let’s start by generating labels on a mock dataset of transactions. Each label is defined as the total spent by a customer given one hour of transactions.

[1]:
from composeml import datasets, LabelMaker, LabelTimes

def total_spent(df):
    return df['amount'].sum()

label_maker = LabelMaker(
    labeling_function=total_spent,
    target_entity='customer_id',
    time_index='transaction_time',
    window_size='1h',
)

labels = label_maker.search(
    datasets.transactions(),
    num_examples_per_instance=10,
    minimum_data='2h',
    gap='2min',
    verbose=True,
)
Elapsed: 00:00 | Remaining: 00:00 | Progress: 100%|██████████| customer_id: 50/50

To get an idea on how the labels looks, we preview the data frame.

[2]:
labels.head()
[2]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 65.11
1 1 2014-01-02 17:48:20 101.08
2 1 2014-01-03 15:43:34 16.78
3 1 2014-01-05 11:48:10 108.16
4 1 2014-01-06 09:56:58 48.33

Threshold on Labels

LabelTimes.threshold() will create binary labels by testing if label values are above a threshold. In this example, a threshold is applied to determine which customers spent over 100.

[3]:
labels.threshold(100).head()
[3]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 False
1 1 2014-01-02 17:48:20 True
2 1 2014-01-03 15:43:34 False
3 1 2014-01-05 11:48:10 True
4 1 2014-01-06 09:56:58 False

Lead Labels Times

LabelTimes.apply_lead() will shift the label time earlier. This is useful for training a model to predict in advance. In this example, a one hour lead is applied to the label times.

[4]:
labels.apply_lead('1h').head()
[4]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 04:13:51 65.11
1 1 2014-01-02 16:48:20 101.08
2 1 2014-01-03 14:43:34 16.78
3 1 2014-01-05 10:48:10 108.16
4 1 2014-01-06 08:56:58 48.33

Bin Labels

LabelTimes.bin() will bin the labels into discrete intervals. There are two types of bins. Bins could either be based on values or quantiles. Additionally, the widths of the bins could either be defined by the user or divided equally. The following examples will go through each type.

Value Based

To use bins based on values, quantiles should be set to False which is the default value.

Equal Width

To group values into bins of equal width, set bins as a scalar value. In this example, the total spent is grouped into bins of equal width.

[5]:
labels.bin(4, quantiles=False).head()
[5]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 (50.975, 85.17]
1 1 2014-01-02 17:48:20 (85.17, 119.365]
2 1 2014-01-03 15:43:34 (16.643, 50.975]
3 1 2014-01-05 11:48:10 (85.17, 119.365]
4 1 2014-01-06 09:56:58 (16.643, 50.975]

Custom Widths

To group values into bins of custom widths, set bins as an array of values to define edges. In this example, the total spent is grouped into bins of custom widths.

[6]:
inf = float('inf')
edges = [-inf, 34, 50, 67, inf]
labels.bin(edges, quantiles=False,).head()
[6]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 (50.0, 67.0]
1 1 2014-01-02 17:48:20 (67.0, inf]
2 1 2014-01-03 15:43:34 (-inf, 34.0]
3 1 2014-01-05 11:48:10 (67.0, inf]
4 1 2014-01-06 09:56:58 (34.0, 50.0]

Quantile Based

To use bins based on quantiles, quantiles should be set to True.

Equal Width

To group values into quantile bins of equal width, set bins to the number of quantiles as a scalar value (e.g. 4 for quartiles, 10 for deciles, etc.). In this example, the total spent is grouped into bins based on the quartiles.

[7]:
labels.bin(4, quantiles=True).head()
[7]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 (49.805, 73.89]
1 1 2014-01-02 17:48:20 (100.982, 153.56]
2 1 2014-01-03 15:43:34 (16.779, 49.805]
3 1 2014-01-05 11:48:10 (100.982, 153.56]
4 1 2014-01-06 09:56:58 (16.779, 49.805]

To verify quartile values, we could check the descriptive statistics.

[8]:
stats = labels.total_spent.describe()
stats = stats.round(3).to_string()
print(stats)
count     50.000
mean      77.041
std       39.911
min       16.780
25%       49.805
50%       73.890
75%      100.982
max      153.560

Custom Widths

To group values into quantile bins of custom widths, set bins as an array of quantiles. In this example, the total spent is grouped into quantile bins of custom widths.

[9]:
quantiles = [0, .34, .5, .67, 1]
labels.bin(quantiles, quantiles=True).head()
[9]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 (63.446, 73.89]
1 1 2014-01-02 17:48:20 (87.639, 153.56]
2 1 2014-01-03 15:43:34 (16.779, 63.446]
3 1 2014-01-05 11:48:10 (87.639, 153.56]
4 1 2014-01-06 09:56:58 (16.779, 63.446]

Label Bins

To assign bins with custom labels, set labels to the array of values. The number of labels need to match the number of bins. In this example, the total spent is grouped into bins with custom labels.

[10]:
values = ['low', 'medium', 'high']
labels.bin(3, labels=values).head()
[10]:
customer_id cutoff_time total_spent
label_id
0 1 2014-01-01 05:13:51 medium
1 1 2014-01-02 17:48:20 medium
2 1 2014-01-03 15:43:34 low
3 1 2014-01-05 11:48:10 high
4 1 2014-01-06 09:56:58 low

Describe Labels

LabelTimes.describe() will print out the distribution with the settings and transforms that were used to make the labels. This is useful as a reference for understanding how the labels were generated from raw data. Also, the label distribution is helpful for determining if we have imbalanced labels. In this examlpe, a description of the labels is printed after transforming the labels into discrete values.

[11]:
labels.threshold(100).describe()
Label Distribution
------------------
False     36
True      14
Total:    50


Settings
--------
gap                          2min
minimum_data                   2h
num_examples_per_instance      10
window_size                    1h


Transforms
----------
1. threshold
  - value:    100