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

Input shape

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

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

Returns

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: The calibrated output as a tensor with shape (batch_size, units). The deltas between the keypoints x's with shape (batch_size, units, # keypoints - 1). 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.