# tfl.conditional_pwl_calibration.pwl_calibration_fn

<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/conditional_pwl_calibration.py#L269-L495) |

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`](https://www.tensorflow.org/lattice/api_docs/python/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)`.

<br />

<br />

| ## Input shape ||
|---|---|
| `inputs` should be one of: <br /> - `(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)`. ||

<br />

<br />

<br />

<br />

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

<br />

<br />

<br />

<br />

| ## Returns ||
|---|---|
| If `return_derived_parameters = False`: <br /> - 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. ||

<br />