tfl.conditional_pwl_calibration.pwl_calibration_fn

Calibrates inputs using derived parameters (kernels).

@tf.function
tfl.conditional_pwl_calibration.pwl_calibration_fn(
    inputs: tf.Tensor,
    keypoint_input_parameters: Optional[tf.Tensor],
    keypoint_output_parameters: tf.Tensor,
    keypoint_input_min: float = 0.0,
    keypoint_input_max: float = 1.0,
    keypoint_output_min: float = 0.0,
    keypoint_output_max: float = 1.0,
    units: int = 1,
    monotonicity: str = 'none',
    clamp_min: bool = False,
    clamp_max: bool = False,
    is_cyclic: bool = False,
    missing_input_value: Optional[float] = None,
    missing_output_value: Optional[float] = None,
    return_derived_parameters: bool = False
) -> Union[tf.Tensor, Tuple[tf.Tensor, tf.Tensor, tf.Tensor]]

pwl_calibration_fn is similar to tfl.layers.PWLCalibration with the key difference that the keypoints are decided by the given parameters instead of learnable weights belonging to a layer. These parameters can be one of:

  • constants,
  • trainable variables,
  • outputs from other TF modules.

Shapes:

The last dimension of keypoint_input_parameters (input_param_size) and keypoint_output_parameters (output_param_size) depend on the number of keypoints used by the calibrator. We follow the relationships that

  • input_param_size = # keypoints - 2, as the leftmost and rightmost keypoints are given.

  • output_param_size = # keypoints initially, and we then modify it by

    1. if cyclic calibrator: output_param_size -= 1,
    2. if clamp_min: output_param_size -= 1,
    3. if clamp_max: output_param_size -= 1,
    4. if need to learn how to impute missing: output_param_size += 1.

The final shapes need to be broadcast friendly with (batch_size, units, 1):

  • keypoint_input_parameters: (1 or batch_size, 1 or units, input_param_size).
  • keypoint_output_parameters: (1 or batch_size, 1 or units, output_param_size).

inputs should be one of:

  • (batch_size, 1) if units == 1.
  • (batch_size, 1) or (batch_size, units) if units > 1. The former will be broadcast to match units.

keypoint_input_parameters should be one of:

  • None if only the leftmost and the rightmost keypoints are required.
  • (1, input_param_size).
  • (batch_size, input_param_size).
  • (1, 1, input_param_size).
  • (batch_size, 1, input_param_size).
  • (1, units, input_param_size).
  • (batch_size, units, input_param_size).

keypoint_output_parameters should be one of:

  • (1, output_param_size).
  • (batch_size, output_param_size).
  • (1, 1, output_param_size).
  • (batch_size, 1, output_param_size).
  • (1, units, output_param_size).
  • (batch_size, units, output_param_size).

inputs inputs to the calibration fn.
keypoint_input_parameters parameters for keypoint x's of calibration fn.
keypoint_output_parameters parameters for keypoint y's of calibration fn.
keypoint_input_min the leftmost keypoint.
keypoint_input_max the rightmost keypoint.
keypoint_output_min lower bound of the fn output.
keypoint_output_max upper bound of the fn output.
units number of parallel calibrations on one input.
monotonicity none or increasing. Whether the calibration is monotonic.
clamp_min only applies when monotonicity == increasing. Whether to clamp the LHS keypoint to the calibration keypoint_output_min.
clamp_max only applies when monotonicity == increasing. Whether to clamp the RHS keypoint to the calibration keypoint_output_max.
is_cyclic only applies when monotonicity == none. Whether the LHS and the RHS keypoints have the same calibration output.
missing_input_value if set, use as the value indicating a missing input.
missing_output_value if set, use as the output for missing_input_value.
return_derived_parameters if True, return the derived kernel parameters used for interpolation.

If return_derived_parameters = False:

  • The calibrated output as a tensor with shape (batch_size, units).

If return_derived_parameters == True:

  • A tuple of three elements:

    1. The calibrated output as a tensor with shape (batch_size, units).

    2. The deltas between the keypoints x's with shape (batch_size, units, # keypoints - 1).

    3. The initial value and the deltas between the keypoints y's, with shape shape (batch_size, units, # keypoints). Apply cumsum will reconstruct the y values.