<br />

|---|
| [![](https://www.tensorflow.org/images/GitHub-Mark-32px.png) View source on GitHub](https://github.com/tensorflow/lattice/blob/v2.1.1/tensorflow_lattice/python/configs.py#L690-L840) |

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 |
|---|
| - [Shape Constraints with Tensorflow Lattice](https://www.tensorflow.org/lattice/tutorials/shape_constraints) - [TF Lattice Premade Models](https://www.tensorflow.org/lattice/tutorials/premade_models) - [TF Lattice Aggregate Function Models](https://www.tensorflow.org/lattice/tutorials/aggregate_function_models) - [Shape Constraints for Ethics with Tensorflow Lattice](https://www.tensorflow.org/lattice/tutorials/shape_constraints_for_ethics) |

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)

<br />

<br />

<br />

| ## Args ||
|---|---|
| `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` | <br /> - 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`](https://www.tensorflow.org/lattice/api_docs/python/tfl/configs/TrustConfig) instances. |
| `dominates` | None or a list of [`tfl.configs.DominanceConfig`](https://www.tensorflow.org/lattice/api_docs/python/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`](https://www.tensorflow.org/lattice/api_docs/python/tfl/configs/RegularizerConfig) instances. |

## Methods

### `deserialize_nested_configs`

[View source](https://github.com/tensorflow/lattice/blob/v2.1.1/tensorflow_lattice/python/configs.py#L124-L158)

    @classmethod
    deserialize_nested_configs(
        config, custom_objects=None
    )

Returns a deserialized configuration dictionary.

### `from_config`

[View source](https://github.com/tensorflow/lattice/blob/v2.1.1/tensorflow_lattice/python/configs.py#L837-L840)

    @classmethod
    from_config(
        config, custom_objects=None
    )

### `get_config`

[View source](https://github.com/tensorflow/lattice/blob/v2.1.1/tensorflow_lattice/python/configs.py#L93-L122)

    get_config()

Returns a configuration dictionary.

### `regularizer_config_by_name`

[View source](https://github.com/tensorflow/lattice/blob/v2.1.1/tensorflow_lattice/python/configs.py#L179-L188)

    regularizer_config_by_name(
        regularizer_name
    )

Returns existing or default RegularizerConfig with the given name.