Feature Columns

    Overview

    Feature columns are used to specify how Tensors received from the input function should be combined and transformed before entering the model. A feature column can be a plain mapping to some input column (e.g. column_numeric() for a column of numerical data), or a transformation of other feature columns (e.g. column_crossed() to define a new column as the cross of two other feature columns).

    The following feature columns are available:

    Feature ColumnDescription
    column_categorical_with_vocabulary_list()Construct a Categorical Column with In-Memory Vocabulary.
    column_categorical_with_vocabulary_file()Construct a Categorical Column with a Vocabulary File.
    column_categorical_with_identity()Construct a Categorical Column that Returns Identity Values.
    column_categorical_with_hash_bucket()Represents Sparse Feature where IDs are set by Hashing.
    column_categorical_weighted()Construct a Weighted Categorical Column.
    column_indicator()Represents Multi-Hot Representation of Given Categorical Column.
    column_numeric()Construct a Real-Valued Column.
    column_embedding()Construct a Dense Column.
    column_crossed()Construct a Crossed Column.
    column_bucketized()Construct a Bucketized Column.

    Some typical mappings of R data types to feature column are:

    Data TypeFeature Column
    Numericcolumn_numeric()
    Factorcolumn_categorical_with_identity()
    Charactercolumn_categorical_with_hash_bucket()

    We’ll use the flights dataset from the nycflights13 package to explore how feature columns can be constructed. The flights dataset records airline on-time data for all flights departing NYC in 2013.

    library(nycflights13)
    print(flights)
    > print(flights)
    # A tibble: 336,776 x 19
        year month   day dep_time sched_dep_time dep_delay arr_time sched_arr_time arr_delay carrier flight tailnum origin  dest air_time
       <int> <int> <int>    <int>          <int>     <dbl>    <int>          <int>     <dbl>   <chr>  <int>   <chr>  <chr> <chr>    <dbl>
     1  2013     1     1      517            515         2      830            819        11      UA   1545  N14228    EWR   IAH      227
     2  2013     1     1      533            529         4      850            830        20      UA   1714  N24211    LGA   IAH      227
     3  2013     1     1      542            540         2      923            850        33      AA   1141  N619AA    JFK   MIA      160
    # ... with 336,766 more rows, and 4 more variables: distance <dbl>, hour <dbl>, minute <dbl>, time_hour <dttm>

    For example, we can define numeric columns based on the dep_time and dep_delay variables:

    cols <- feature_columns(
      column_numeric("dep_time"),
      column_numeric("dep_delay")
    )

    You can also define multiple feature columns at once.

    cols <- feature_columns(
      column_numeric("dep_time", "dep_delay")
    )

    Pattern Matching

    Often, you will find that you want to generate a number of feature column definitions based on some pattern existing in the names of your data set. tfestimators uses the tidyselect package to make it easy to define feature columns, similar to what you might be familiar with in the dplyr package. You can use the names = argument of feature_columns() function to define a context from which variable names will be selected.

    For example, we can use the ends_with() helper to assert that all columns ending with "time" are numeric columns as follows:

    library(nycflights13)
    
    cols <- feature_columns(names = flights,
      column_numeric(ends_with("time"))
    )

    The names parameter can either be a character vector with the names as-is, or any named R object.

    If the code you are using to compose columns is more complicated, or if you need to save references to columns for use in column embeddings you can also establish a scope for given set of column names using the with_columns() function:

    cols <- with_columns(flights, {
      feature_columns(
        column_numeric(ends_with("time"))
      )
    })

    You can also use an alternate syntax of the form (pattern) ~ (column), which can add clarity when longer pattern rules are used, as it separates the matching rule from the column definition:

    cols <- with_columns(flights, {
      feature_columns(
        ends_with("time") ~ column_numeric(),
      )
    })

    Available pattern matching operators include:

    OperatorDescription
    starts_with()Starts with a prefix
    ends_with()Ends with a suffix
    contains()Contains a literal string
    matches()Matches a regular expression
    one_of()Included in character vector
    everything()All columns

    See help("select_helpers", package = "tidyselect") for full information on the set of helpers made available by the tidyselect package.