# tfl.configs.CalibratedLatticeConfig

<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#L397-L506) |

Config for calibrated lattice model.

    tfl.configs.CalibratedLatticeConfig(
        feature_configs=None,
        interpolation='hypercube',
        parameterization='all_vertices',
        num_terms=2,
        regularizer_configs=None,
        output_min=None,
        output_max=None,
        output_calibration=False,
        output_calibration_num_keypoints=10,
        output_initialization='quantiles',
        output_calibration_input_keypoints_type='fixed',
        random_seed=0
    )

### Used in the notebooks

| Used in the tutorials |
|---|
| - [Shape Constraints with Tensorflow Lattice](https://www.tensorflow.org/lattice/tutorials/shape_constraints) - [Shape Constraints for Ethics with Tensorflow Lattice](https://www.tensorflow.org/lattice/tutorials/shape_constraints_for_ethics) - [TF Lattice Premade Models](https://www.tensorflow.org/lattice/tutorials/premade_models) |

A calibrated lattice model applies piecewise-linear and categorical
calibration on the input feature, followed by a lattice model and an
optional output piecewise-linear calibration.

#### Example:

    model_config = tfl.configs.CalibratedLatticeConfig(
        feature_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 ||
|---|---|
| `feature_configs` | A list of [`tfl.configs.FeatureConfig`](https://www.tensorflow.org/lattice/api_docs/python/tfl/configs/FeatureConfig) instances that specify configurations for each feature. If a configuration is not provided for a feature, a default configuration will be used. |
| `interpolation` | One of 'hypercube' or 'simplex' interpolation. For a d-dimensional lattice, 'hypercube' interpolates 2\^d parameters, whereas 'simplex' uses d+1 parameters and thus scales better. For details see [`tfl.lattice_lib.evaluate_with_simplex_interpolation`](https://www.tensorflow.org/lattice/api_docs/python/tfl/lattice_lib/evaluate_with_simplex_interpolation) and [`tfl.lattice_lib.evaluate_with_hypercube_interpolation`](https://www.tensorflow.org/lattice/api_docs/python/tfl/lattice_lib/evaluate_with_hypercube_interpolation). |
| `parameterization` | The parameterization of the lattice function class to use. A lattice function is uniquely determined by specifying its value on every lattice vertex. A parameterization scheme is a mapping from a vector of parameters to a multidimensional array of lattice vertex values. It can be one of: <br /> - String `'all_vertices'`: This is the "traditional" parameterization that keeps one scalar parameter per lattice vertex where the mapping is essentially the identity map. With this scheme, the number of parameters scales exponentially with the number of inputs to the lattice. The underlying lattice used will be a [`tfl.layers.Lattice`](https://www.tensorflow.org/lattice/api_docs/python/tfl/layers/Lattice) layer. - String `'kronecker_factored'`: With this parameterization, for each lattice input i we keep a collection of `num_terms` vectors each having `feature_configs[0].lattice_size` entries (note that all features must have the same lattice size). To obtain the tensor of lattice vertex values, for `t=1,2,...,num_terms` we compute the outer product of the `t'th` vector in each collection, multiply by a per-term scale, and sum the resulting tensors. Finally, we add a single shared bias parameter to each entry in the sum. With this scheme, the number of parameters grows linearly with `len(feature_configs)` (assuming lattice sizes and `num_terms` are held constant). Currently, only monotonicity shape constraint and bound constraint are supported for this scheme. Regularization is not currently supported. The underlying lattice used will be a [`tfl.layers.KroneckerFactoredLattice`](https://www.tensorflow.org/lattice/api_docs/python/tfl/layers/KroneckerFactoredLattice) layer. |
| `num_terms` | The number of terms in a lattice using `'kronecker_factored'` parameterization. Ignored if parameterization is set to `'all_vertices'`. |
| `regularizer_configs` | A list of [`tfl.configs.RegularizerConfig`](https://www.tensorflow.org/lattice/api_docs/python/tfl/configs/RegularizerConfig) instances that apply global regularization. |
| `output_min` | Lower bound constraint on the output of the model. |
| `output_max` | Upper bound constraint on the output of the model. |
| `output_calibration` | If a piecewise-linear calibration should be used on the output of the lattice. |
| `output_calibration_num_keypoints` | Number of keypoints to use for the output piecewise-linear calibration. |
| `output_initialization` | The initial values to setup for the output of the model. When using output calibration, these values are used to initialize the output keypoints of the output piecewise-linear calibration. Otherwise the lattice parameters will be setup to form a linear function in the range of output_initialization. It can be one of: - String `'quantiles'`: Output is initliazed to label quantiles, if possible. - String `'uniform'`: Output is initliazed uniformly in label range. - A list of numbers: To be used for initialization of the output lattice or output calibrator. |
| `output_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. |
| `random_seed` | Random seed to use for initialization of a lattice with `'kronecker_factored'` parameterization. Ignored if parameterization is set to `'all_vertices'`. |

## 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.

### `feature_config_by_name`

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

    feature_config_by_name(
        feature_name
    )

Returns existing or default FeatureConfig with the given name.

### `from_config`

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

    @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.