tfl.configs.CalibratedLatticeEnsembleConfig

View source on GitHub

Class CalibratedLatticeEnsembleConfig

Config for calibrated lattice model.

Used in the notebooks

Used in the tutorials

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

The ensemble structure can be one of the following and set via the lattice flag:

  • Expliclit list of list of features specifying features used in each submodel.
  • A random arrangement (also called Random Tiny Lattices, or RTL).
  • Crystals growing algorithm: This algorithm first constructs a prefitting model to assess pairwise interactions between features, and then uses those estimates to construct a final model that puts interacting features in the same lattice. For details see "Fast and flexible monotonic functions with ensembles of lattices", Advances in Neural Information Processing Systems, 2016.

Examples:

Creating a random ensemble (RTL) model:

model_config = tfl.configs.CalibratedLatticeEnsembleConfig(
    num_lattices=6,  # number of lattices
    lattice_rank=5,  # number of features in each lattice
    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)

To create a Crystals model, you will need to provide a prefitting_input_fn to the estimator constructor. This input_fn is used to train the prefitting model, as described above. The prefitting model does not need to be fully trained, so a few epochs should be enough.

model_config = tfl.configs.CalibratedLatticeEnsembleConfig(
    lattices='crystals',  # feature arrangement method
    num_lattices=6,  # number of lattices
    lattice_rank=5,  # number of features in each lattice
    feature_configs=[...],
)
feature_analysis_input_fn = create_input_fn(num_epochs=1, ...)
prefitting_input_fn = create_input_fn(num_epochs=5, ...)
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
    prefitting_input_fn=prefitting_input_fn)
estimator.train(input_fn=train_input_fn)

__init__

View source

__init__(
    feature_configs=None,
    lattices='random',
    num_lattices=None,
    lattice_rank=None,
    separate_calibrators=True,
    regularizer_configs=None,
    output_min=None,
    output_max=None,
    output_calibration=False,
    output_calibration_num_keypoint=10,
    output_initialization='quantiles',
    fix_ensemble_for_2d_constraints=True,
    random_seed=0
)

Initializes a CalibratedLatticeEnsembleConfig instance.

Args:

  • feature_configs: A list of 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.
  • lattices: Should be one of the following:
    • String 'random' indicating that the features in each lattice should be selected randomly
    • String 'crystals' to use a heuristic to construct the lattice ensemble based on pairwise feature interactions
    • An explicit list of list of feature names to be used in each lattice in the ensemble.
  • num_lattices: Number of lattices in the ensemble. Must be provided if lattices are not explicitly provided.
  • lattice_rank: Number of features in each lattice. Must be provided if lattices are not explicitly provided.
  • separate_calibrators: If features should be separately calibrated for each lattice in the ensemble.
  • regularizer_configs: A list of 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_keypoint: 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 initliaze 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.
  • fix_ensemble_for_2d_constraints: A boolean indicating whether to add missing features to some lattices to resolve potential 2d constraint violations which require lattices from ensemble to either contain both constrained features or none of them, e.g. trapezoid trust constraint requires a lattice that has the "conditional" feature to include the "main" feature. Note that this might increase the final lattice rank.
  • random_seed: Random seed to use for randomized lattices.

Methods

feature_config_by_name

View source

feature_config_by_name(feature_name)

Returns existing or default FeatureConfig with the given name.

regularizer_config_by_name

View source

regularizer_config_by_name(regularizer_name)

Returns existing or default RegularizerConfig with the given name.