Premium Primitive Examples¶

Examples by type

Geospatial Primitives
NLP Primitives
Date of Birth Primitives
Time Primitives
Phone Number Primitives
ZIP Code Primitives
Numeric Primitives
Miscellaneous Data Types

In [1]:

from datetime import datetime
import numpy as np
import pandas as pd

Geospatial Primitives¶

LatLong variables store a tuple containing the Latitude and Longitude of a point on the globe. These primitives transform that location (e.g. what country is it in) and can do comparions between multiple LatLong variables (e.g. distance between them).

CityBlockDistance¶

Calculates the distance between points in a city road grid.

In [2]:

from featuretools.primitives import CityblockDistance

cityblock_distance = CityblockDistance()
DC = (38, -77)
Boston = (43, -71)
NYC = (40, -74)
cityblock_distance([DC, DC], [NYC, Boston])  # DC -> NYC, DC -> Boston

Out[2]:

0    301.518836
1    672.088624
dtype: float64

PathLength¶

Determines the length of a path defined by a series of coordinates.

In [3]:

from featuretools.primitives import PathLength

path_length_km = PathLength(unit='kilometers')
path_length_km([(41.881832, -87.623177), (38.6270, -90.1994), (39.0997, -94.5786)])

Out[3]:

805.5203180792812

LatLongToCity¶

Determines city/town corresponding to given Latitude and Longitude coordinates.

In [4]:

from featuretools.primitives import LatLongToCity

latlong_to_city = LatLongToCity()
latlong_to_city([(51.52, -0.17), (9.93, 76.25), (37.38, -122.08), (np.nan, np.nan)])

Out[4]:

0        Bayswater
1           Cochin
2    Mountain View
3             None
Name: results, dtype: object

Natural Language Processing Primitives¶

NLP primitives can apply various natural language processing techniques to text data.

PolarityScore¶

Calculates the polarity of a text on a scale from -1 (negative) to 1 (positive)

In [5]:

from featuretools.primitives import PolarityScore

x = ['He loves dogs', 'She hates cats', 'There is a dog', '']
polarity_score = PolarityScore()
polarity_score(x)

Out[5]:

0    0.677
1   -0.649
2    0.000
3    0.000
dtype: float64

PartOfSpeechCount¶

Calculates the occurences of each different part of speech.

In [6]:

from featuretools.primitives import PartOfSpeechCount

x = ['He was eating cheese', '']
part_of_speech_count = PartOfSpeechCount()
part_of_speech_count(x)

Out[6]:

0     [0.0, 0.0]
1     [0.0, 0.0]
2     [0.0, 0.0]
3     [0.0, 0.0]
4     [0.0, 0.0]
5     [1.0, 0.0]
6     [0.0, 0.0]
7     [0.0, 0.0]
8     [0.0, 0.0]
9     [1.0, 0.0]
10    [0.0, 0.0]
11    [0.0, 0.0]
12    [0.0, 0.0]
13    [1.0, 0.0]
14    [0.0, 0.0]
dtype: object

Date of Birth Primitives¶

These primitives transform DateOfBirth type variables. They use the time of the feature calculation to extrapolate the current age of a person. This is set by using a cutoff time.

Age¶

Calculates the age in years as a floating point number given a date of birth.

In [7]:

from featuretools.primitives import Age

reference_date = pd.to_datetime("01-01-2019")
age = Age()
input_ages = [pd.to_datetime("01-01-2000"),
              pd.to_datetime("05-30-1983"),
              pd.to_datetime("10-17-1997")]
age(input_ages, time=reference_date)

Out[7]:

0    19.013699
1    35.616438
2    21.221918
dtype: float64

There are also primitives to see if a birth date falls within a give age range

AgeOver18¶

Determines whether a person is over 18 years old given their date of birth.

In [8]:

from featuretools.primitives import AgeOver18

over18 = AgeOver18()
over18(input_ages, time=reference_date)

Out[8]:

0    True
1    True
2    True
dtype: bool

AgeUnder65¶

Determines whether a person is under 65 years old given their date of birth.

In [9]:

from featuretools.primitives import AgeUnder65

under65 = AgeUnder65()
under65(input_ages, time=reference_date)

Out[9]:

0    True
1    True
2    True
dtype: bool

Time Primitives¶

Datetime variables store dates or timestamps. These primitives can extract special properties from a Datetime field like if it is a holiday.

DateToHoliday¶

If there is no holiday, it returns NaN. Currently only works for the United States and Canada with dates between 1950 and 2100.

In [10]:

from featuretools.primitives import DateToHoliday

date_to_holiday = DateToHoliday()
dates = pd.Series([datetime(2016, 1, 1),
         datetime(2016, 2, 27),
         datetime(2017, 5, 29, 10, 30, 5),
         datetime(2018, 7, 4)])
date_to_holiday(dates)

Out[10]:

array(["New Year's Day", nan, 'Memorial Day', 'Independence Day'],
      dtype=object)

NUniqueDaysOfCalendarYear¶

Determines the number of unique calendar days.

In [11]:

from featuretools.primitives import NUniqueDaysOfCalendarYear

n_unique_days_of_calendar_year = NUniqueDaysOfCalendarYear()
times = [datetime(2019, 2, 1),
         datetime(2019, 2, 1),
         datetime(2018, 2, 1),
         datetime(2019, 1, 1)]
n_unique_days_of_calendar_year(times)

Out[11]:

Phone Number Primitives¶

The PhoneNumber variable stores phone numbers. These primitives can transformations on the phone numbers to extract metadata like country or area code that are general enough for a model to use

PhoneNumberToCountry¶

Determines the country of a phone number.

In [12]:

from featuretools.primitives import PhoneNumberToCountry

phone_number_to_country = PhoneNumberToCountry()
phone_number_to_country(['+55 85 5555555', '+81 55-555-5555', '+1-541-754-3010',])

Out[12]:

0    BR
1    JP
2    US
dtype: object

ZIP Code Primitives¶

These primitives can bring in various metadata about a zip code (like geographic or economic information).

ZIPCodeToState¶

Extracts the state from a ZIPCode.

In [13]:

from featuretools.primitives import ZIPCodeToState

zipcode_to_state = ZIPCodeToState()
zipcode_to_state(['60622', '94120', '02111-1253'])

Out[13]:

0    IL
1    CA
2    MA
dtype: object

ZIPCodeToHouseholdIncome¶

Determines the median household income for a ZIP Code.

In [14]:

from featuretools.primitives import ZIPCodeToHouseholdIncome

zipcode_to_household_income = ZIPCodeToHouseholdIncome()
zipcode_to_household_income(["82838", "02116", "02116-3899"])

Out[14]:

array([ 59000., 103422., 103422.])

Numeric Primitives¶

The premium primitives have additional nmumeric primitives that add new mathematical transformations and aggregations that aren't present in the open-source library. They are frequently useful in time-series analysis

NumPeaks¶

Determines the number of peaks in a list of numbers.

In [15]:

from featuretools.primitives import NumPeaks

num_peaks = NumPeaks()
num_peaks([-5, 0, 10, 0, 10, -5, -4, -5, 10, 0])

Out[15]:

NumZeroCrossings¶

Determines the number of times a list crosses 0.

In [16]:

from featuretools.primitives import NumZeroCrossings

num_zero_crossings = NumZeroCrossings()
num_zero_crossings([1, -1, 2, -2, 3, -3])

Out[16]:

Correlation¶

Computes the correlation between two columns of values.

In [17]:

from featuretools.primitives import Correlation

correlation = Correlation()
array_1 = [1, 4, 6, 7]
array_2 = [1, 5, 9, 7]
correlation(array_1, array_2)

Out[17]:

0.9221388919541468

CountOutsideRange¶

Determines the number of values that fall outside a certain range.

In [18]:

from featuretools.primitives import CountOutsideRange

count_outside_range = CountOutsideRange(lower=1.5, upper=3.6)
count_outside_range([1, 2, 3, 4, 5])

Out[18]:

Miscellaneous Data Types¶

Other variable types include FullName, EmailAddress, URL, CountryCode, SubRegionCode, FilePath

FullNameToLastName¶

Determines the first name from a person's name.

In [19]:

from featuretools.primitives import FullNameToLastName

full_name_to_last_name = FullNameToLastName()
names = ['Woolf Spector', 'Oliva y Ocana, Dona. Fermina',
         'Ware, Mr. Frederick', 'Peter, Michael J', 'Mr. Brown']
full_name_to_last_name(names)

Out[19]:

0          Spector
1    Oliva y Ocana
2             Ware
3            Peter
4            Brown
Name: last_name, dtype: object

IsFreeEmailDomain¶

Determines if an email address is from a free email domain.

In [20]:

from featuretools.primitives import IsFreeEmailDomain

is_free_email_domain = IsFreeEmailDomain()
is_free_email_domain(['name@gmail.com', 'name@featuretools.com'])

Out[20]:

array([ True, False])

URLToDomain¶

Determines the domain of a url.

In [21]:

from featuretools.primitives import URLToDomain

url_to_domain = URLToDomain()
urls =  ['https://play.google.com', 'http://www.google.co.in', 'www.facebook.com']
url_to_domain(urls)

Out[21]:

0    play.google.com
1       google.co.in
2       facebook.com
dtype: object

CountryCodeToIncome¶

Transforms a 2-digit or 3-digit ISO-3166-1 country code into Gross National Income (GNI) per capita.

In [22]:

from featuretools.primitives import CountryCodeToIncome

country_code_to_income = CountryCodeToIncome()
country_code_to_income(['USA', 'AM', 'EC'])

Out[22]:

array([58270.,  3990.,  5920.])

SubRegionCodeToMedianHouseholdIncome¶

Determines the median household income of a US sub-region.

In [23]:

from featuretools.primitives import SubRegionCodeToMedianHouseholdIncome

sub_region_code_to_median_household_income = SubRegionCodeToMedianHouseholdIncome()
subregions = ["US-AL", "US-IA", "US-VT", "US-DC", "US-MI", "US-NY"]
sub_region_code_to_median_household_income(subregions)

Out[23]:

array([51113, 63481, 63805, 83382, 57700, 62447])

FileExtension¶

Determines the extension of a filepath.

In [24]:

from featuretools.primitives import FileExtension

file_extension = FileExtension()
file_extension(['doc.txt', '~/documents/data.json', 'file'])

Out[24]:

0     .txt
1    .json
2      NaN
dtype: object