tfl.configs.FeatureConfig

Per-feature configuration for TFL canned estimators.

tfl.configs.FeatureConfig(
    name,
    is_missing_name=None,
    default_value=None,
    lattice_size=2,
    monotonicity='none',
    unimodality='none',
    reflects_trust_in=None,
    dominates=None,
    pwl_calibration_always_monotonic=False,
    pwl_calibration_convexity=0,
    pwl_calibration_num_keypoints=10,
    pwl_calibration_input_keypoints='quantiles',
    pwl_calibration_input_keypoints_type='fixed',
    pwl_calibration_clip_min=None,
    pwl_calibration_clip_max=None,
    pwl_calibration_clamp_min=False,
    pwl_calibration_clamp_max=False,
    num_buckets=0,
    vocabulary_list=None,
    regularizer_configs=None
)

Used in the notebooks

Used in the tutorials

A feature can either be numerical or categorical. Numeric features will be calibrated using a piecewise-linear function with the given number of keypoints. Categorical features should have num_buckets > 0 and the vocabulary_list represent their categories. Several of the config fields can be filled in automatically based on the FeatureColumns used by the model but can also be provided explicitly. See __init__ args comments for details.

Currently only one dimensional feature are supported.

Examples:

feature_columns = [
    tf.feature_column.numeric_column.numeric_column(
        'age', default_value=-1),
    tf.feature_column.numeric_column.categorical_column_with_vocabulary_list(
        'thal', vocabulary_list=['normal', 'fixed', 'reversible']),
    ...
]

model_config = tfl.configs.CalibratedLatticeConfig(
    feature_configs=[
        tfl.configs.FeatureConfig(
            name='age',
            lattice_size=3,
            # Monotonically increasing.
            monotonicity='increasing',
            # Per feature regularization.
            regularizer_configs=[
                tfl.configs.RegularizerConfig(name='calib_hessian', l2=1e-4),
            ],
        ),
        tfl.configs.FeatureConfig(
            name='thal',
            # Partial monotonicity:
            # output(normal) <= output(fixed)
            # output(normal) <= output(reversible)
            monotonicity=[('normal', 'fixed'), ('normal', 'reversible')],
        ),
    ],
    # Global regularizers
    regularizer_configs=[...])
feature_analysis_input_fn = create_input_fn(num_epochs=1, ...)
train_input_fn = create_input_fn(num_epochs=100, ...)
estimator = tfl.estimators.CannedClassifier(
    feature_columns=feature_columns,
    model_config=model_config,
    feature_analysis_input_fn=feature_analysis_input_fn)
estimator.train(input_fn=train_input_fn)

name The name of the feature, which should match the name of a given FeatureColumn or a key in the input feature dict.
is_missing_name The name of a FeatureColumn or key in the input feature dict that indicates missing-ness of the main feature.
default_value [Automatically filled in from FeatureColumns] If set, this value in the input value represents missing. For numeric features, the output will be imputed. If default_value is provided for a categocial features, it would corresponds to the last bucket counted in num_buckets.
lattice_size The number of lattice verticies to be used along the axis for this feature.
monotonicity

  • For numeric features, specifies if the model output should be monotonic in this feature, using 'increasing' or 1 to indicate increasing monotonicity, 'decreasing' or -1 to indicate decreasing monotonicity, and 'none' or 0 to indicate no monotonicity constraints. - For categorical features, a list of (category_a, category_b) pairs from the vocabulary list indicating that with other features fixed, model output for category_b should be greater than or equal to category_a. If no vocabulary list is specified, we assume implcit vocabulary in the range [0, num_buckets - 1].
unimodality For numeric features specifies if the model output should be unimodal in corresponding feature, using 'valley' or 1 to indicate that function first decreases then increases, using 'peak' or -1 to indicate that funciton first increases then decreases, using 'none' or 0 to indicate no unimodality constraints. Not used for categorical features.
reflects_trust_in None or a list of tfl.configs.TrustConfig instances.
dominates None or a list of tfl.configs.DominanceConfig instances.
pwl_calibration_always_monotonic Specifies if the piecewise-linear calibration should always be monotonic regardless of the specified end-to-end model output monotonicity with respect to this feature.
pwl_calibration_convexity Spefices the convexity constraints of the calibrators for numeric features. Convexity is indicated by 'convex' or 1, concavity is indicated by 'concave' or -1, 'none' or 0 indicates no convexity/concavity constraints. Does not affect categorical features. Concavity together with increasing monotonicity as well as convexity together with decreasing monotonicity results in diminishing return constraints.
pwl_calibration_num_keypoints Number of keypoints to use for piecewise-linear calibration.
pwl_calibration_input_keypoints Indicates what should be used for the input keypoints of the piecewise-linear calibration. It can be one of:
  • String 'quantiles': Input keypoints are set to feature quantiles.
  • String 'uniform': Input keypoints are uniformly spaced in feature range.
  • A list of numbers: Explicitly specifies the keypoints.
pwl_calibration_input_keypoints_type One of "fixed" or "learned_interior". If "learned_interior", keypoints are initialized to the values in pwl_calibration_input_keypoints but then allowed to vary during training, with the exception of the first and last keypoint location which are fixed. Convexity can only be imposed with "fixed".
pwl_calibration_clip_min Input values are lower clipped by this value.
pwl_calibration_clip_max Input values are upper clipped by this value.
pwl_calibration_clamp_min for monotonic calibrators ensures that the minimum value in calibration output is reached.
pwl_calibration_clamp_max for monotonic calibrators ensures that the maximum value in calibration output is reached.
num_buckets [Automatically filled in from FeatureColumns] Number of categories for a categorical feature. Out-of-vocabulary and missing/default value should be counted into num_buckets (last buckets).
vocabulary_list [Automatically filled in from FeatureColumns] The input vocabulary of the feature.
regularizer_configs None or a list of per-feature tfl.configs.RegularizerConfig instances.

Methods

deserialize_nested_configs

View source

@classmethod
deserialize_nested_configs(
    config, custom_objects=None
)

Returns a deserialized configuration dictionary.

from_config

View source

@classmethod
from_config(
    config, custom_objects=None
)

get_config

View source

get_config()

Returns a configuration dictionary.

regularizer_config_by_name

View source

regularizer_config_by_name(
    regularizer_name
)

Returns existing or default RegularizerConfig with the given name.